PYTHON-1320 Remove legacy CRUD methods

bson/regex.py

@@ -53,7 +53,7 @@ def from_native(cls, regex):
           >>> pattern = re.compile('.*')
           >>> regex = Regex.from_native(pattern)
           >>> regex.flags ^= re.UNICODE
-          >>> db.collection.insert({'pattern': regex})
+          >>> db.collection.insert_one({'pattern': regex})
 
         :Parameters:
           - `regex`: A regular expression object from ``re.compile()``.

doc/api/pymongo/collection.rst

@@ -71,8 +71,3 @@
       .. automethod:: initialize_ordered_bulk_op
       .. automethod:: group
       .. automethod:: count
-      .. automethod:: insert(doc_or_docs, manipulate=True, check_keys=True, continue_on_error=False, **kwargs)
-      .. automethod:: save(to_save, manipulate=True, check_keys=True, **kwargs)
-      .. automethod:: update(spec, document, upsert=False, manipulate=False, multi=False, check_keys=True, **kwargs)
-      .. automethod:: remove(spec_or_id=None, multi=True, **kwargs)
-      .. automethod:: find_and_modify

doc/changelog.rst

@@ -30,6 +30,11 @@ Breaking Changes in 4.0
 - Removed :meth:`pymongo.collection.Collection.parallel_scan`.
 - Removed :meth:`pymongo.collection.Collection.ensure_index`.
 - Removed :meth:`pymongo.collection.Collection.reindex`.
+- Removed :meth:`pymongo.collection.Collection.save`
+- Removed :meth:`pymongo.collection.Collection.insert`
+- Removed :meth:`pymongo.collection.Collection.update`
+- Removed :meth:`pymongo.collection.Collection.remove`
+- Removed :meth:`pymongo.collection.Collection.find_and_modify`
 - Removed :meth:`pymongo.mongo_client.MongoClient.close_cursor`. Use
   :meth:`pymongo.cursor.Cursor.close` instead.
 - Removed :meth:`pymongo.mongo_client.MongoClient.kill_cursors`.

doc/compatibility-policy.rst

@@ -24,7 +24,7 @@ warning:
 
 .. code-block:: python
 
-    # "insert.py"
+    # "insert.py" (with PyMongo 3.X)
     from pymongo import MongoClient
 
     client = MongoClient()

doc/faq.rst

@@ -202,6 +202,9 @@ documents that already have an ``_id`` field, added by your application.
 Key order in subdocuments -- why does my query work in the shell but not PyMongo?
 ---------------------------------------------------------------------------------
 
+..
+  Note: We should rework this section now that Python 3.6+ has ordered dict.
+
 .. testsetup:: key-order
 
   from bson.son import SON
@@ -220,9 +223,9 @@ is displayed:
 .. code-block:: javascript
 
   > // mongo shell.
-  > db.collection.insert( { "_id" : 1, "subdocument" : { "b" : 1, "a" : 1 } } )
+  > db.collection.insertOne( { "_id" : 1, "subdocument" : { "b" : 1, "a" : 1 } } )
   WriteResult({ "nInserted" : 1 })
-  > db.collection.find()
+  > db.collection.findOne()
   { "_id" : 1, "subdocument" : { "b" : 1, "a" : 1 } }
 
 PyMongo represents BSON documents as Python dicts by default, and the order

doc/migrate-to-pymongo3.rst

@@ -340,14 +340,14 @@ this::
 
   >>> oid = collection.insert({"a": 2}, w="majority")
 
-can be changed to this with PyMongo 2.9 or later:
+can be changed to this with PyMongo 3 or later:
 
 .. doctest::
 
   >>> from pymongo import WriteConcern
   >>> coll2 = collection.with_options(
   ...     write_concern=WriteConcern(w="majority"))
-  >>> oid = coll2.insert({"a": 2})
+  >>> oid = coll2.insert_one({"a": 2})
 
 .. seealso:: :meth:`~pymongo.database.Database.get_collection`
 

doc/migrate-to-pymongo4.rst

@@ -140,6 +140,103 @@ can be changed to this::
 Collection
 ----------
 
+Collection.insert is removed
+............................
+
+Removed :meth:`pymongo.collection.Collection.insert`. Use
+:meth:`~pymongo.collection.Collection.insert_one` or
+:meth:`~pymongo.collection.Collection.insert_many` instead.
+
+Code like this::
+
+  collection.insert({'doc': 1})
+  collection.insert([{'doc': 2}, {'doc': 3}])
+
+Can be changed to this::
+
+  collection.insert_one({'my': 'document'})
+  collection.insert_many([{'doc': 2}, {'doc': 3}])
+
+Collection.save is removed
+..........................
+
+Removed :meth:`pymongo.collection.Collection.save`. Applications will
+get better performance using :meth:`~pymongo.collection.Collection.insert_one`
+to insert a new document and :meth:`~pymongo.collection.Collection.update_one`
+to update an existing document. Code like this::
+
+  doc = collection.find_one({"_id": "some id"})
+  doc["some field"] = <some value>
+  db.collection.save(doc)
+
+Can be changed to this::
+
+  result = collection.update_one({"_id": "some id"}, {"$set": {"some field": <some value>}})
+
+If performance is not a concern and refactoring is untenable, ``save`` can be
+implemented like so::
+
+  def save(doc):
+      if '_id' in doc:
+          collection.replace_one({'_id': doc['_id']}, doc, upsert=True)
+          return doc['_id']
+      else:
+          res = collection.insert_one(doc)
+          return res.inserted_id
+
+Collection.update is removed
+............................
+
+Removed :meth:`pymongo.collection.Collection.update`. Use
+:meth:`~pymongo.collection.Collection.update_one`
+to update a single document or
+:meth:`~pymongo.collection.Collection.update_many` to update multiple
+documents. Code like this::
+
+  collection.update({}, {'$set': {'a': 1}})
+  collection.update({}, {'$set': {'b': 1}}, multi=True)
+
+Can be changed to this::
+
+  collection.update_one({}, {'$set': {'a': 1}})
+  collection.update_many({}, {'$set': {'b': 1}})
+
+Collection.remove is removed
+............................
+
+Removed :meth:`pymongo.collection.Collection.remove`. Use
+:meth:`~pymongo.collection.Collection.delete_one`
+to delete a single document or
+:meth:`~pymongo.collection.Collection.delete_many` to delete multiple
+documents. Code like this::
+
+  collection.remove({'a': 1}, multi=False)
+  collection.remove({'b': 1})
+
+Can be changed to this::
+
+  collection.delete_one({'a': 1})
+  collection.delete_many({'b': 1})
+
+Collection.find_and_modify is removed
+.....................................
+
+Removed :meth:`pymongo.collection.Collection.find_and_modify`. Use
+:meth:`~pymongo.collection.Collection.find_one_and_update`,
+:meth:`~pymongo.collection.Collection.find_one_and_replace`, or
+:meth:`~pymongo.collection.Collection.find_one_and_delete` instead.
+Code like this::
+
+  updated_doc = collection.find_and_modify({'a': 1}, {'$set': {'b': 1}})
+  replaced_doc = collection.find_and_modify({'b': 1}, {'c': 1})
+  deleted_doc = collection.find_and_modify({'c': 1}, remove=True)
+
+Can be changed to this::
+
+  updated_doc = collection.find_one_and_update({'a': 1}, {'$set': {'b': 1}})
+  replaced_doc = collection.find_one_and_replace({'b': 1}, {'c': 1})
+  deleted_doc = collection.find_one_and_delete({'c': 1})
+
 Collection.ensure_index is removed
 ..................................
 
@@ -152,16 +249,16 @@ to :meth:`~pymongo.collection.Collection.create_index` or
 :meth:`~pymongo.collection.Collection.create_indexes`. Code like this::
 
   def persist(self, document):
-      my_collection.ensure_index('a', unique=True)
-      my_collection.insert_one(document)
+      collection.ensure_index('a', unique=True)
+      collection.insert_one(document)
 
 Can be changed to this::
 
   def persist(self, document):
       if not self.created_index:
-          my_collection.create_index('a', unique=True)
+          collection.create_index('a', unique=True)
           self.created_index = True
-      my_collection.insert_one(document)
+      collection.insert_one(document)
 
 Collection.reindex is removed
 .............................