PYTHON-1317 Deprecate legacy bulk write api.

Use Collection.bulk_write() in documentation examples.
Move deprecated bulk tests to test_legacy_api.

doc/changelog.rst

@@ -47,6 +47,10 @@ Changes and Deprecations:
   and disabling it is not recommended, see `does TCP keepalive time affect
   MongoDB Deployments?
   <https://docs.mongodb.com/manual/faq/diagnostics/#does-tcp-keepalive-time-affect-mongodb-deployments>`_
+- Deprecated :meth:`~pymongo.collection.Collection.initialize_ordered_bulk_op`,
+  :meth:`~pymongo.collection.Collection.initialize_unordered_bulk_op`, and
+  :class:`~pymongo.bulk.BulkOperationBuilder`. Use
+  :meth:`~pymongo.collection.Collection.bulk_write` instead.
 - Deprecated :const:`~bson.json_util.STRICT_JSON_OPTIONS`. Use
   :const:`~bson.json_util.RELAXED_JSON_OPTIONS` or
   :const:`~bson.json_util.CANONICAL_JSON_OPTIONS` instead.

doc/examples/bulk.rst

@@ -47,26 +47,24 @@ Ordered Bulk Write Operations
 .............................
 
 Ordered bulk write operations are batched and sent to the server in the
-order provided for serial execution. The return value is a document
-describing the type and count of operations performed.
+order provided for serial execution. The return value is an instance of
+:class:`~pymongo.results.BulkWriteResult` describing the type and count
+of operations performed.
 
 .. doctest::
   :options: +NORMALIZE_WHITESPACE
 
   >>> from pprint import pprint
-  >>>
-  >>> bulk = db.test.initialize_ordered_bulk_op()
-  >>> # Remove all documents from the previous example.
-  ...
-  >>> bulk.find({}).remove()
-  >>> bulk.insert({'_id': 1})
-  >>> bulk.insert({'_id': 2})
-  >>> bulk.insert({'_id': 3})
-  >>> bulk.find({'_id': 1}).update({'$set': {'foo': 'bar'}})
-  >>> bulk.find({'_id': 4}).upsert().update({'$inc': {'j': 1}})
-  >>> bulk.find({'j': 1}).replace_one({'j': 2})
-  >>> result = bulk.execute()
-  >>> pprint(result)
+  >>> from pymongo import InsertOne, DeleteMany, ReplaceOne, UpdateOne
+  >>> result = db.test.bulk_write([
+  ...     DeleteMany({}),  # Remove all documents from the previous example.
+  ...     InsertOne({'_id': 1}),
+  ...     InsertOne({'_id': 2}),
+  ...     InsertOne({'_id': 3}),
+  ...     UpdateOne({'_id': 1}, {'$set': {'foo': 'bar'}}),
+  ...     UpdateOne({'_id': 4}, {'$inc': {'j': 1}}, upsert=True),
+  ...     ReplaceOne({'j': 1}, {'j': 2})])
+  >>> pprint(result.bulk_api_result)
   {'nInserted': 3,
    'nMatched': 2,
    'nModified': 2,
@@ -91,15 +89,14 @@ the failure.
 .. doctest::
   :options: +NORMALIZE_WHITESPACE
 
+  >>> from pymongo import InsertOne, DeleteOne, ReplaceOne
   >>> from pymongo.errors import BulkWriteError
-  >>> bulk = db.test.initialize_ordered_bulk_op()
-  >>> bulk.find({'j': 2}).replace_one({'i': 5})
-  >>> # Violates the unique key constraint on _id.
-  ...
-  >>> bulk.insert({'_id': 4})
-  >>> bulk.find({'i': 5}).remove_one()
+  >>> requests = [
+  ...     ReplaceOne({'j': 2}, {'i': 5}),
+  ...     InsertOne({'_id': 4}),  # Violates the unique key constraint on _id.
+  ...     DeleteOne({'i': 5})]
   >>> try:
-  ...     bulk.execute()
+  ...     db.test.bulk_write(requests)
   ... except BulkWriteError as bwe:
   ...     pprint(bwe.details)
   ... 
@@ -131,13 +128,13 @@ and fourth operations succeed.
 .. doctest::
   :options: +NORMALIZE_WHITESPACE
 
-  >>> bulk = db.test.initialize_unordered_bulk_op()
-  >>> bulk.insert({'_id': 1})
-  >>> bulk.find({'_id': 2}).remove_one()
-  >>> bulk.insert({'_id': 3})
-  >>> bulk.find({'_id': 4}).replace_one({'i': 1})
+  >>> requests = [
+  ...     InsertOne({'_id': 1}),
+  ...     DeleteOne({'_id': 2}),
+  ...     InsertOne({'_id': 3}),
+  ...     ReplaceOne({'_id': 4}, {'i': 1})]
   >>> try:
-  ...     bulk.execute()
+  ...     db.test.bulk_write(requests, ordered=False)
   ... except BulkWriteError as bwe:
   ...     pprint(bwe.details)
   ... 
@@ -160,22 +157,17 @@ and fourth operations succeed.
 Write Concern
 .............
 
-By default bulk operations are executed with the
+Bulk operations are executed with the
 :attr:`~pymongo.collection.Collection.write_concern` of the collection they
-are executed against. A custom write concern can be passed to the
-:meth:`~pymongo.bulk.BulkOperationBuilder.execute` method. Write concern
-errors (e.g. wtimeout) will be reported after all operations are attempted,
-regardless of execution order.
+are executed against. Write concern errors (e.g. wtimeout) will be reported
+after all operations are attempted, regardless of execution order.
 
 ::
-
-  >>> bulk = db.test.initialize_ordered_bulk_op()
-  >>> bulk.insert({'a': 0})
-  >>> bulk.insert({'a': 1})
-  >>> bulk.insert({'a': 2})
-  >>> bulk.insert({'a': 3})
+  >>> from pymongo import WriteConcern
+  >>> coll = db.get_collection(
+  ...     'test', write_concern=WriteConcern(w=3, wtimeout=1))
   >>> try:
-  ...     bulk.execute({'w': 3, 'wtimeout': 1})
+  ...     coll.bulk_write([InsertOne({'a': i}) for i in range(4)])
   ... except BulkWriteError as bwe:
   ...     pprint(bwe.details)
   ... 

pymongo/bulk.py

@@ -599,14 +599,14 @@ class BulkWriteOperation(object):
 
 
 class BulkOperationBuilder(object):
-    """An interface for executing a batch of write operations.
+    """**DEPRECATED**: An interface for executing a batch of write operations.
     """
 
     __slots__ = '__bulk'
 
     def __init__(self, collection, ordered=True,
                  bypass_document_validation=False):
-        """Initialize a new BulkOperationBuilder instance.
+        """**DEPRECATED**: Initialize a new BulkOperationBuilder instance.
 
         :Parameters:
           - `collection`: A :class:`~pymongo.collection.Collection` instance.
@@ -623,6 +623,10 @@ class BulkOperationBuilder(object):
         .. note:: `bypass_document_validation` requires server version
           **>= 3.2**
 
+        .. versionchanged:: 3.5
+           Deprecated. Use :meth:`~pymongo.collection.Collection.bulk_write`
+           instead.
+
         .. versionchanged:: 3.2
           Added bypass_document_validation support
         """

pymongo/collection.py

@@ -338,7 +338,7 @@ class Collection(common.BaseObject):
                           read_concern or self.read_concern)
 
     def initialize_unordered_bulk_op(self, bypass_document_validation=False):
-        """Initialize an unordered batch of write operations.
+        """**DEPRECATED** - Initialize an unordered batch of write operations.
 
         Operations will be performed on the server in arbitrary order,
         possibly in parallel. All operations will be attempted.
@@ -355,15 +355,21 @@ class Collection(common.BaseObject):
         .. note:: `bypass_document_validation` requires server version
           **>= 3.2**
 
+        .. versionchanged:: 3.5
+           Deprecated. Use :meth:`~pymongo.collection.Collection.bulk_write`
+           instead.
+
         .. versionchanged:: 3.2
-          Added bypass_document_validation support
+           Added bypass_document_validation support
 
         .. versionadded:: 2.7
         """
+        warnings.warn("initialize_unordered_bulk_op is deprecated",
+                      DeprecationWarning, stacklevel=2)
         return BulkOperationBuilder(self, False, bypass_document_validation)
 
     def initialize_ordered_bulk_op(self, bypass_document_validation=False):
-        """Initialize an ordered batch of write operations.
+        """**DEPRECATED** - Initialize an ordered batch of write operations.
 
         Operations will be performed on the server serially, in the
         order provided. If an error occurs all remaining operations
@@ -381,11 +387,17 @@ class Collection(common.BaseObject):
         .. note:: `bypass_document_validation` requires server version
           **>= 3.2**
 
+        .. versionchanged:: 3.5
+           Deprecated. Use :meth:`~pymongo.collection.Collection.bulk_write`
+           instead.
+
         .. versionchanged:: 3.2
-          Added bypass_document_validation support
+           Added bypass_document_validation support
 
         .. versionadded:: 2.7
         """
+        warnings.warn("initialize_ordered_bulk_op is deprecated",
+                      DeprecationWarning, stacklevel=2)
         return BulkOperationBuilder(self, True, bypass_document_validation)
 
     def bulk_write(self, requests, ordered=True,

test/test_collation.py

@@ -101,10 +101,15 @@ class TestCollation(unittest.TestCase):
         cls.client = rs_or_single_client(event_listeners=[cls.listener])
         cls.db = cls.client.pymongo_test
         cls.collation = Collation('en_US')
+        cls.warn_context = warnings.catch_warnings()
+        cls.warn_context.__enter__()
+        warnings.simplefilter("ignore", DeprecationWarning)
 
     @classmethod
     def tearDownClass(cls):
         monitoring._LISTENERS = cls.saved_listeners
+        cls.warn_context.__exit__()
+        cls.warn_context = None
 
     def tearDown(self):
         self.listener.results.clear()
@@ -179,12 +184,10 @@ class TestCollation(unittest.TestCase):
 
     @raisesConfigurationErrorForOldMongoDB
     def test_group(self):
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
-            self.db.test.group('foo', {'foo': {'$gt': 42}}, {},
-                               'function(a, b) { return a; }',
-                               collation=self.collation)
-            self.assertCollationInLastCommand()
+        self.db.test.group('foo', {'foo': {'$gt': 42}}, {},
+                           'function(a, b) { return a; }',
+                           collation=self.collation)
+        self.assertCollationInLastCommand()
 
     @raisesConfigurationErrorForOldMongoDB
     def test_map_reduce(self):