Merge pull request #293 from IlyaSkriblovsky/deprecation-warnings-2

DeprecationWarnings for insert(), update(), remove() and as_class

docs/source/NEWS.rst

@@ -1,13 +1,19 @@
 Changelog
 =========
 
-Release 24.0.0 (2024-09-16)
+Release 24.0.0 (2024-10-01)
 ---------------------------
 
 API Changes
 ^^^^^^^^
 
 - This is the last release that supports Python <3.8 and MongoDB <4.0
+- Collection methods `insert()`, `update()` and `remove()` are deprecated in favor of
+  corresponding `*_one()` and `*_many()` methods. Old methods will be removed in the next release.
+- Collection methods `save()`, `find_and_modify() and `group()` are deprecated and will be removed
+  in the next release.
+- `as_class` argument of `find()`, `find_with_cursor()` and `find_one()` is deprecated and will
+  be removed in the next release.
 
 
 Release UPCOMING (yyyy-mm-dd)

tests/basic/test_queries.py

@@ -13,7 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from bson import BSON, ObjectId
+from bson import BSON, CodecOptions, ObjectId
 from bson.son import SON
 from pymongo.collection import ReturnDocument
 from pymongo.errors import (
@@ -265,13 +265,28 @@ def test_AsClass(self):
         yield self.coll.insert({"x": 42})
 
         doc = yield self.coll.find_one({})
-        self.assertTrue(type(doc) is dict)
+        self.assertIs(type(doc), dict)
 
         class CustomDict(dict):
             pass
 
         doc = yield self.coll.find_one({}, as_class=CustomDict)
-        self.assertTrue(type(doc) is CustomDict)
+        self.assertIs(type(doc), CustomDict)
+
+    @defer.inlineCallbacks
+    def test_AsClassCodecOption(self):
+        yield self.coll.insert({"x": 42})
+
+        doc = yield self.coll.find_one()
+        self.assertIs(type(doc), dict)
+
+        class CustomDict(dict):
+            pass
+
+        doc = yield self.coll.with_options(
+            codec_options=CodecOptions(document_class=CustomDict)
+        ).find_one()
+        self.assertIs(type(doc), CustomDict)
 
     @defer.inlineCallbacks
     def test_FindOneNone(self):

txmongo/collection.py

@@ -448,6 +448,12 @@ def __real_find_with_cursor(
             filter = BSON.encode(filter, codec_options=self.codec_options)
 
         as_class = kwargs.get("as_class")
+        if as_class is not None:
+            warnings.warn(
+                "as_class argument of will be removed in the next version of TxMongo. Please use document_class parameter of codec_options.",
+                DeprecationWarning,
+            )
+
         proto = self._database.connection.getprotocol()
 
         def after_connection(protocol):
@@ -591,6 +597,11 @@ def count(self, filter=None, **kwargs):
 
     @timeout
     def group(self, keys, initial, reduce, condition=None, finalize=None, **kwargs):
+        warnings.warn(
+            "Collection.group() method will be removed in the next version of TxMongo. Please use aggregate() or map_reduce().",
+            DeprecationWarning,
+        )
+
         body = {
             "ns": self._collection_name,
             "initial": initial,
@@ -674,6 +685,11 @@ def insert(self, docs, safe=None, flags=0, **kwargs):
             :class:`Deferred` that fires with single ``_id`` field or a list of
             ``_id`` fields of inserted documents.
         """
+        warnings.warn(
+            "Collection.insert() method will be removed in the next version of TxMongo. Please use insert_one() or insert_many().",
+            DeprecationWarning,
+        )
+
         if isinstance(docs, dict):
             ids = docs.get("_id", ObjectId())
             docs["_id"] = ids
@@ -895,6 +911,10 @@ def update(
             :class:`Deferred` that is called back when request is sent to
             MongoDB or confirmed by MongoDB (depending on selected Write Concern).
         """
+        warnings.warn(
+            "Collection.update() method will be removed in the next version of TxMongo. Please use update_one(), update_many() or replace_one().",
+            DeprecationWarning,
+        )
 
         if not isinstance(spec, dict):
             raise TypeError("TxMongo: spec must be an instance of dict.")
@@ -1071,6 +1091,12 @@ def on_ok(raw_response):
 
     @timeout
     def save(self, doc, safe=None, **kwargs):
+        warnings.warn(
+            "Collection.save() method will be removed in the next version of TxMongo. "
+            "Please use insert_one() or replace_one().",
+            DeprecationWarning,
+        )
+
         if not isinstance(doc, dict):
             raise TypeError(
                 "TxMongo: cannot save objects of type {0}".format(type(doc))
@@ -1083,6 +1109,11 @@ def save(self, doc, safe=None, **kwargs):
 
     @timeout
     def remove(self, spec, safe=None, single=False, flags=0, **kwargs):
+        warnings.warn(
+            "Collection.remove() method will be removed in the next version of TxMongo. Please use delete_one() or delete_many().",
+            DeprecationWarning,
+        )
+
         if isinstance(spec, ObjectId):
             spec = SON(dict(_id=spec))
         if not isinstance(spec, dict):
@@ -1318,6 +1349,12 @@ def on_ok(raw):
 
     @timeout
     def find_and_modify(self, query=None, update=None, upsert=False, **kwargs):
+        warnings.warn(
+            "Collection.find_and_modify() method will be removed in the next version of TxMongo. "
+            "Please use find_one_and_update(), find_one_and_replace() or find_one_and_delete().",
+            DeprecationWarning,
+        )
+
         no_obj_error = "No matching object found"
 
         if not update and not kwargs.get("remove", None):