PYTHON-1113 - Index collation documentation into API docs.

doc/api/pymongo/collation.rst

@@ -0,0 +1,16 @@
+:mod:`collation` -- Tools for working with collations.
+======================================================
+
+.. automodule:: pymongo.collation
+   :synopsis: Tools for working with collations.
+
+   .. autoclass:: pymongo.collation.Collation
+   .. autoclass:: pymongo.collation.CollationStrength
+      :members:
+      :member-order: bysource
+   .. autoclass:: pymongo.collation.CollationAlternate
+      :members:
+      :member-order: bysource
+   .. autoclass:: pymongo.collation.CollationCaseFirst
+      :members:
+      :member-order: bysource

doc/api/pymongo/index.rst

@@ -32,6 +32,7 @@ Sub-modules:
    :maxdepth: 2
 
    database
+   collation
    collection
    command_cursor
    cursor

pymongo/bulk.py

@@ -483,9 +483,11 @@ class _Bulk(object):
         with client._socket_for_writes() as sock_info:
             if sock_info.max_wire_version < 5 and self.uses_collation:
                 raise ConfigurationError(
-                    'Specifying a collation is unsupported with a max wire '
-                    'version of %d.' % (sock_info.max_wire_version,))
+                    'Must be connected to MongoDB 3.4+ to use a collation.')
             if not write_concern.acknowledged:
+                if self.uses_collation:
+                    raise ConfigurationError(
+                        'Collation is unsupported for unacknowledged writes.')
                 self.execute_no_results(sock_info, generator)
             elif sock_info.max_wire_version > 1:
                 return self.execute_command(sock_info, generator, write_concern)

pymongo/collation.py

@@ -14,7 +14,7 @@
 
 """Tools for working with `collations`_.
 
-.. collations: http://userguide.icu-project.org/collation/concepts
+.. _collations: http://userguide.icu-project.org/collation/concepts
 """
 
 from pymongo import common
@@ -95,11 +95,9 @@ class Collation(object):
 
     :Parameters:
       - `locale`: (string) The locale of the collation. This should be a string
-        that identifies an `ICU locale ID`_ exactly. For example, ``en_US``
-        is valid, but ``en_us`` and ``en-US`` are not.
-
-    The following parameters are all optional:
-
+        that identifies an `ICU locale ID` exactly. For example, ``en_US`` is
+        valid, but ``en_us`` and ``en-US`` are not. Consult the MongoDB
+        documentation for a list of supported locales.
       - `caseLevel`: (optional) If ``True``, turn on case sensitivity if
         `strength` is 1 or 2 (case sensitivity is implied if `strength` is
         greater than 2). Defaults to ``False``.

pymongo/collection.py

@@ -729,8 +729,7 @@ class Collection(common.BaseObject):
         if collation is not None:
             if sock_info.max_wire_version < 5:
                 raise ConfigurationError(
-                    'Specifying a collation is unsupported with a max wire '
-                    'version of %d.' % (sock_info.max_wire_version,))
+                    'Must be connected to MongoDB 3.4+ to use collations.')
             elif not acknowledged:
                 raise ConfigurationError(
                     'Collation is unsupported for unacknowledged writes.')
@@ -976,8 +975,7 @@ class Collection(common.BaseObject):
         if collation is not None:
             if sock_info.max_wire_version < 5:
                 raise ConfigurationError(
-                    'Specifying a collation is unsupported with a max wire '
-                    'version of %d.' % (sock_info.max_wire_version,))
+                    'Must be connected to MongoDB 3.4+ to use collations.')
             elif not acknowledged:
                 raise ConfigurationError(
                     'Collation is unsupported for unacknowledged writes.')
@@ -1420,8 +1418,7 @@ class Collection(common.BaseObject):
             if collation is not None:
                 if sock_info.max_wire_version < 5:
                     raise ConfigurationError(
-                        'Specifying a collation is unsupported with a max wire '
-                        'version of %d.' % (sock_info.max_wire_version,))
+                        'Must be connected to MongoDB 3.4+ to use collations.')
                 else:
                     index['collation'] = collation
             cmd = SON([('createIndexes', self.name), ('indexes', [index])])

pymongo/pool.py

@@ -382,8 +382,7 @@ class SocketInfo(object):
             spec['writeConcern'] = write_concern.document
         elif self.max_wire_version < 5 and collation is not None:
             raise ConfigurationError(
-                'Specifying a collation is unsupported with a max wire '
-                'version of %d.' % (self.max_wire_version,))
+                'Must be connected to MongoDB 3.4+ to use a collation.')
         try:
             return command(self.sock, dbname, spec, slave_ok,
                            self.is_mongos, read_preference, codec_options,

test/test_collation.py

@@ -334,6 +334,11 @@ class TestCollation(unittest.TestCase):
             collection.update_one(
                 {'hello': 'world'}, {'$set': {'hello': 'moon'}},
                 collation=self.collation)
+        bulk = collection.initialize_ordered_bulk_op()
+        bulk.find({'hello': 'world'}, collation=self.collation).update_one(
+            {'$set': {'hello': 'moon'}})
+        with self.assertRaises(ConfigurationError):
+            bulk.execute()
 
     @raisesConfigurationErrorForOldMongoDB
     def test_cursor_collation(self):