PYTHON-1113 - Index collation documentation into API docs.

Luke Lovett · Luke Lovett · commit 0fbdf85f53f9 · 2016-09-07T15:15:15.000-07:00
diff --git a/doc/api/pymongo/collation.rst b/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
diff --git a/doc/api/pymongo/index.rst b/doc/api/pymongo/index.rst
@@ -32,6 +32,7 @@ Sub-modules:
    :maxdepth: 2
 
    database
+   collation
    collection
    command_cursor
    cursor
diff --git a/pymongo/bulk.py b/pymongo/bulk.py
@@ -483,9 +483,11 @@ def execute(self, write_concern):
         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)
diff --git a/pymongo/collation.py b/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``.
diff --git a/pymongo/collection.py b/pymongo/collection.py
@@ -729,8 +729,7 @@ def _update(self, sock_info, criteria, document, upsert=False,
         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 @@ def _delete(
         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 @@ def __create_index(self, keys, index_options):
             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])])
diff --git a/pymongo/pool.py b/pymongo/pool.py
@@ -382,8 +382,7 @@ def command(self, dbname, spec, slave_ok=False,
             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,
diff --git a/test/test_collation.py b/test/test_collation.py
@@ -334,6 +334,11 @@ def test_unacknowledged_write(self):
             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):
