diff --git a/docs/source/NEWS.rst b/docs/source/NEWS.rst index 95f15ac8..fa10edd0 100644 --- a/docs/source/NEWS.rst +++ b/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) diff --git a/tests/basic/test_queries.py b/tests/basic/test_queries.py index 7d7bbf63..39e77857 100644 --- a/tests/basic/test_queries.py +++ b/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): diff --git a/txmongo/collection.py b/txmongo/collection.py index c21e8a03..329e8857 100644 --- a/txmongo/collection.py +++ b/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):