diff --git a/bson/raw_bson.py b/bson/raw_bson.py index 339354d7d..bfe888b6b 100644 --- a/bson/raw_bson.py +++ b/bson/raw_bson.py @@ -28,23 +28,23 @@ Example: Moving a document between different databases/collections >>> client.drop_database('db') >>> client.drop_database('replica_db') >>> db = client.db - >>> result = db.test.insert_many([{'a': 1}, - ... {'b': 1}, - ... {'c': 1}, - ... {'d': 1}]) + >>> result = db.test.insert_many([{'_id': 1, 'a': 1}, + ... {'_id': 2, 'b': 1}, + ... {'_id': 3, 'c': 1}, + ... {'_id': 4, 'd': 1}]) >>> replica_db = client.replica_db >>> for doc in db.test.find(): ... print(f"raw document: {doc.raw}") ... print(f"decoded document: {bson.decode(doc.raw)}") ... result = replica_db.test.insert_one(doc) raw document: b'...' - decoded document: {'_id': ObjectId('...'), 'a': 1} + decoded document: {'_id': 1, 'a': 1} raw document: b'...' - decoded document: {'_id': ObjectId('...'), 'b': 1} + decoded document: {'_id': 2, 'b': 1} raw document: b'...' - decoded document: {'_id': ObjectId('...'), 'c': 1} + decoded document: {'_id': 3, 'c': 1} raw document: b'...' - decoded document: {'_id': ObjectId('...'), 'd': 1} + decoded document: {'_id': 4, 'd': 1} For use cases like moving documents across different databases or writing binary blobs to disk, using raw BSON documents provides better speed and avoids the diff --git a/doc/changelog.rst b/doc/changelog.rst index 5f0ff2330..222750f55 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -1881,7 +1881,9 @@ Changes in Version 2.9 Version 2.9 provides an upgrade path to PyMongo 3.x. Most of the API changes from PyMongo 3.0 have been backported in a backward compatible way, allowing applications to be written against PyMongo >= 2.9, rather then PyMongo 2.x or -PyMongo 3.x. See the :doc:`/migrate-to-pymongo3` for detailed examples. +PyMongo 3.x. See the `PyMongo 3 Migration Guide +`_ for +detailed examples. .. note:: There are a number of new deprecations in this release for features that were removed in PyMongo 3.0. diff --git a/doc/index.rst b/doc/index.rst index 9ef690718..da05bf80a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -34,9 +34,6 @@ everything you need to know to use **PyMongo**. :doc:`migrate-to-pymongo4` A PyMongo 3.x to 4.x migration guide. -:doc:`migrate-to-pymongo3` - A PyMongo 2.x to 3.x migration guide. - :doc:`python3` Frequently asked questions about python 3 support. @@ -123,5 +120,4 @@ Indices and tables changelog python3 migrate-to-pymongo4 - migrate-to-pymongo3 developer/index diff --git a/doc/migrate-to-pymongo3.rst b/doc/migrate-to-pymongo3.rst deleted file mode 100644 index 633d0a7ab..000000000 --- a/doc/migrate-to-pymongo3.rst +++ /dev/null @@ -1,544 +0,0 @@ -PyMongo 3 Migration Guide -========================= - -.. contents:: - -.. testsetup:: - - from pymongo import MongoClient, ReadPreference - client = MongoClient() - collection = client.my_database.my_collection - -PyMongo 3 is a partial rewrite bringing a large number of improvements. It -also brings a number of backward breaking changes. This guide provides a -roadmap for migrating an existing application from PyMongo 2.x to 3.x or -writing libraries that will work with both PyMongo 2.x and 3.x. - -PyMongo 2.9 ------------ - -The first step in any successful migration involves upgrading to, or -requiring, at least PyMongo 2.9. If your project has a -requirements.txt file, add the line "pymongo >= 2.9, < 3.0" until you have -completely migrated to PyMongo 3. Most of the key new -methods and options from PyMongo 3.0 are backported in PyMongo 2.9 making -migration much easier. - -Enable Deprecation Warnings ---------------------------- - -Starting with PyMongo 2.9, :exc:`DeprecationWarning` is raised by most methods -removed in PyMongo 3.0. Make sure you enable runtime warnings to see -where deprecated functions and methods are being used in your application:: - - python -Wd - -Warnings can also be changed to errors:: - - python -Wd -Werror - -.. note:: Not all deprecated features raise :exc:`DeprecationWarning` when - used. For example, the :meth:`~pymongo.collection.Collection.find` options - renamed in PyMongo 3.0 do not raise :exc:`DeprecationWarning` when used in - PyMongo 2.x. See also `Removed features with no migration path`_. - -CRUD API --------- - -Changes to find() and find_one() -................................ - -"spec" renamed "filter" -~~~~~~~~~~~~~~~~~~~~~~~ - -The `spec` option has been renamed to `filter`. Code like this:: - - >>> cursor = collection.find(spec={"a": 1}) - -can be changed to this with PyMongo 2.9 or later: - -.. doctest:: - - >>> cursor = collection.find(filter={"a": 1}) - -or this with any version of PyMongo: - -.. doctest:: - - >>> cursor = collection.find({"a": 1}) - -"fields" renamed "projection" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The `fields` option has been renamed to `projection`. Code like this:: - - >>> cursor = collection.find({"a": 1}, fields={"_id": False}) - -can be changed to this with PyMongo 2.9 or later: - -.. doctest:: - - >>> cursor = collection.find({"a": 1}, projection={"_id": False}) - -or this with any version of PyMongo: - -.. doctest:: - - >>> cursor = collection.find({"a": 1}, {"_id": False}) - -"partial" renamed "allow_partial_results" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The `partial` option has been renamed to `allow_partial_results`. Code like -this:: - - >>> cursor = collection.find({"a": 1}, partial=True) - -can be changed to this with PyMongo 2.9 or later: - -.. doctest:: - - >>> cursor = collection.find({"a": 1}, allow_partial_results=True) - -"timeout" replaced by "no_cursor_timeout" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The `timeout` option has been replaced by `no_cursor_timeout`. Code like this:: - - >>> cursor = collection.find({"a": 1}, timeout=False) - -can be changed to this with PyMongo 2.9 or later: - -.. doctest:: - - >>> cursor = collection.find({"a": 1}, no_cursor_timeout=True) - -"network_timeout" is removed -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The `network_timeout` option has been removed. This option was always the -wrong solution for timing out long running queries and should never be used -in production. Starting with **MongoDB 2.6** you can use the $maxTimeMS query -modifier. Code like this:: - - # Set a 5 second select() timeout. - >>> cursor = collection.find({"a": 1}, network_timeout=5) - -can be changed to this with PyMongo 2.9 or later:: - - # Set a 5 second (5000 millisecond) server side query timeout. - >>> cursor = collection.find({"a": 1}, modifiers={"$maxTimeMS": 5000}) - -or with PyMongo 3.5 or later: - - >>> cursor = collection.find({"a": 1}, max_time_ms=5000) - -or with any version of PyMongo: - -.. doctest:: - - >>> cursor = collection.find({"$query": {"a": 1}, "$maxTimeMS": 5000}) - -.. seealso:: `$maxTimeMS - `_ - -Tailable cursors -~~~~~~~~~~~~~~~~ - -The `tailable` and `await_data` options have been replaced by `cursor_type`. -Code like this:: - - >>> cursor = collection.find({"a": 1}, tailable=True) - >>> cursor = collection.find({"a": 1}, tailable=True, await_data=True) - -can be changed to this with PyMongo 2.9 or later: - -.. doctest:: - - >>> from pymongo import CursorType - >>> cursor = collection.find({"a": 1}, cursor_type=CursorType.TAILABLE) - >>> cursor = collection.find({"a": 1}, cursor_type=CursorType.TAILABLE_AWAIT) - -Other removed options -~~~~~~~~~~~~~~~~~~~~~ - -The `slave_okay`, `read_preference`, `tag_sets`, -and `secondary_acceptable_latency_ms` options have been removed. See the `Read -Preferences`_ section for solutions. - -The aggregate method always returns a cursor -............................................ - -PyMongo 2.6 added an option to return an iterable cursor from -:meth:`~pymongo.collection.Collection.aggregate`. In PyMongo 3 -:meth:`~pymongo.collection.Collection.aggregate` always returns a cursor. Use -the `cursor` option for consistent behavior with PyMongo 2.9 and later: - -.. doctest:: - - >>> for result in collection.aggregate([], cursor={}): - ... pass - -Read Preferences ----------------- - -The "slave_okay" option is removed -.................................. - -The `slave_okay` option is removed from PyMongo's API. The -secondaryPreferred read preference provides the same behavior. -Code like this:: - - >>> client = MongoClient(slave_okay=True) - -can be changed to this with PyMongo 2.9 or newer: - -.. doctest:: - - >>> client = MongoClient(readPreference="secondaryPreferred") - -The "read_preference" attribute is immutable -............................................ - -Code like this:: - - >>> from pymongo import ReadPreference - >>> db = client.my_database - >>> db.read_preference = ReadPreference.SECONDARY - -can be changed to this with PyMongo 2.9 or later: - -.. doctest:: - - >>> db = client.get_database("my_database", - ... read_preference=ReadPreference.SECONDARY) - -Code like this:: - - >>> cursor = collection.find({"a": 1}, - ... read_preference=ReadPreference.SECONDARY) - -can be changed to this with PyMongo 2.9 or later: - -.. doctest:: - - >>> coll2 = collection.with_options(read_preference=ReadPreference.SECONDARY) - >>> cursor = coll2.find({"a": 1}) - -.. seealso:: :meth:`~pymongo.database.Database.get_collection` - -The "tag_sets" option and attribute are removed -............................................... - -The `tag_sets` MongoClient option is removed. The `read_preference` -option can be used instead. Code like this:: - - >>> client = MongoClient( - ... read_preference=ReadPreference.SECONDARY, - ... tag_sets=[{"dc": "ny"}, {"dc": "sf"}]) - -can be changed to this with PyMongo 2.9 or later: - -.. doctest:: - - >>> from pymongo.read_preferences import Secondary - >>> client = MongoClient(read_preference=Secondary([{"dc": "ny"}])) - -To change the tags sets for a Database or Collection, code like this:: - - >>> db = client.my_database - >>> db.read_preference = ReadPreference.SECONDARY - >>> db.tag_sets = [{"dc": "ny"}] - -can be changed to this with PyMongo 2.9 or later: - -.. doctest:: - - >>> db = client.get_database("my_database", - ... read_preference=Secondary([{"dc": "ny"}])) - -Code like this:: - - >>> cursor = collection.find( - ... {"a": 1}, - ... read_preference=ReadPreference.SECONDARY, - ... tag_sets=[{"dc": "ny"}]) - -can be changed to this with PyMongo 2.9 or later: - -.. doctest:: - - >>> from pymongo.read_preferences import Secondary - >>> coll2 = collection.with_options( - ... read_preference=Secondary([{"dc": "ny"}])) - >>> cursor = coll2.find({"a": 1}) - -.. seealso:: :meth:`~pymongo.database.Database.get_collection` - -The "secondary_acceptable_latency_ms" option and attribute are removed -...................................................................... - -PyMongo 2.x supports `secondary_acceptable_latency_ms` as an option to methods -throughout the driver, but mongos only supports a global latency option. -PyMongo 3.x has changed to match the behavior of mongos, allowing migration -from a single server, to a replica set, to a sharded cluster without a -surprising change in server selection behavior. A new option, -`localThresholdMS`, is available through MongoClient and should be used in -place of `secondaryAcceptableLatencyMS`. Code like this:: - - >>> client = MongoClient(readPreference="nearest", - ... secondaryAcceptableLatencyMS=100) - -can be changed to this with PyMongo 2.9 or later: - -.. doctest:: - - >>> client = MongoClient(readPreference="nearest", - ... localThresholdMS=100) - -Write Concern -------------- - -The "safe" option is removed -............................ - -In PyMongo 3 the `safe` option is removed from the entire API. -:class:`~pymongo.mongo_client.MongoClient` has always defaulted to acknowledged -write operations and continues to do so in PyMongo 3. - -The "write_concern" attribute is immutable -.......................................... - -The `write_concern` attribute is immutable in PyMongo 3. Code like this:: - - >>> client = MongoClient() - >>> client.write_concern = {"w": "majority"} - -can be changed to this with any version of PyMongo: - -.. doctest:: - - >>> client = MongoClient(w="majority") - -Code like this:: - - >>> db = client.my_database - >>> db.write_concern = {"w": "majority"} - -can be changed to this with PyMongo 2.9 or later: - -.. doctest:: - - >>> from pymongo import WriteConcern - >>> db = client.get_database("my_database", - ... write_concern=WriteConcern(w="majority")) - -The new CRUD API write methods do not accept write concern options. Code like -this:: - - >>> oid = collection.insert({"a": 2}, w="majority") - -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_one({"a": 2}) - -.. seealso:: :meth:`~pymongo.database.Database.get_collection` - -Codec Options -------------- - -The "document_class" attribute is removed -......................................... - -Code like this:: - - >>> from bson.son import SON - >>> client = MongoClient() - >>> client.document_class = SON - -can be replaced by this in any version of PyMongo: - -.. doctest:: - - >>> from bson.son import SON - >>> client = MongoClient(document_class=SON) - -or to change the `document_class` for a :class:`~pymongo.database.Database` -with PyMongo 2.9 or later: - -.. doctest:: - - >>> from bson.codec_options import CodecOptions - >>> from bson.son import SON - >>> db = client.get_database("my_database", CodecOptions(SON)) - -.. seealso:: :meth:`~pymongo.database.Database.get_collection` and - :meth:`~pymongo.collection.Collection.with_options` - -The "uuid_subtype" option and attribute are removed -................................................... - -Code like this:: - - >>> from bson.binary import JAVA_LEGACY - >>> db = client.my_database - >>> db.uuid_subtype = JAVA_LEGACY - -can be replaced by this with PyMongo 2.9 or later: - -.. doctest:: - - >>> from bson.binary import JAVA_LEGACY - >>> from bson.codec_options import CodecOptions - >>> db = client.get_database("my_database", - ... CodecOptions(uuid_representation=JAVA_LEGACY)) - -.. seealso:: :meth:`~pymongo.database.Database.get_collection` and - :meth:`~pymongo.collection.Collection.with_options` - -MongoClient ------------ - -MongoClient connects asynchronously -................................... - -In PyMongo 3, the :class:`~pymongo.mongo_client.MongoClient` constructor no -longer blocks while connecting to the server or servers, and it no longer -raises :exc:`~pymongo.errors.ConnectionFailure` if they are unavailable, nor -:exc:`~pymongo.errors.ConfigurationError` if the user’s credentials are wrong. -Instead, the constructor returns immediately and launches the connection -process on background threads. The `connect` option is added to control whether -these threads are started immediately, or when the client is first used. - -For consistent behavior in PyMongo 2.x and PyMongo 3.x, code like this:: - - >>> from pymongo.errors import ConnectionFailure - >>> try: - ... client = MongoClient() - ... except ConnectionFailure: - ... print("Server not available") - >>> - -can be changed to this with PyMongo 2.9 or later: - -.. doctest:: - - >>> from pymongo.errors import ConnectionFailure - >>> client = MongoClient(connect=False) - >>> try: - ... client.admin.command("ping") - ... except ConnectionFailure: - ... print("Server not available") - >>> - -Any operation can be used to determine if the server is available. We choose -the "ping" command here because it is cheap and does not require auth, so -it is a simple way to check whether the server is available. - -The max_pool_size parameter is removed -...................................... - -PyMongo 3 replaced the max_pool_size parameter with support for the MongoDB URI -`maxPoolSize` option. Code like this:: - - >>> client = MongoClient(max_pool_size=10) - -can be replaced by this with PyMongo 2.9 or later: - -.. doctest:: - - >>> client = MongoClient(maxPoolSize=10) - >>> client = MongoClient("mongodb://localhost:27017/?maxPoolSize=10") - -The "disconnect" method is removed -.................................. - -Code like this:: - - >>> client.disconnect() - -can be replaced by this with PyMongo 2.9 or later: - -.. doctest:: - - >>> client.close() - -The host and port attributes are removed -........................................ - -Code like this:: - - >>> host = client.host - >>> port = client.port - -can be replaced by this with PyMongo 2.9 or later: - -.. doctest:: - - >>> address = client.address - >>> host, port = address or (None, None) - -BSON ----- - -"as_class", "tz_aware", and "uuid_subtype" are removed -...................................................... - -The `as_class`, `tz_aware`, and `uuid_subtype` parameters have been -removed from the functions provided in :mod:`bson`. Furthermore, the -:func:`~bson.encode` and :func:`~bson.decode` functions have been added -as more performant alternatives to the :meth:`bson.BSON.encode` and -:meth:`bson.BSON.decode` methods. Code like this:: - - >>> from bson import BSON - >>> from bson.son import SON - >>> encoded = BSON.encode({"a": 1}, as_class=SON) - -can be replaced by this in PyMongo 2.9 or later: - -.. doctest:: - - >>> from bson import encode - >>> from bson.codec_options import CodecOptions - >>> from bson.son import SON - >>> encoded = encode({"a": 1}, codec_options=CodecOptions(SON)) - -Removed features with no migration path ---------------------------------------- - -MasterSlaveConnection is removed -................................ - -Master slave deployments are deprecated in MongoDB. Starting with MongoDB 3.0 -a replica set can have up to 50 members and that limit is likely to be -removed in later releases. We recommend migrating to replica sets instead. - -Requests are removed -.................... - -The client methods `start_request`, `in_request`, and `end_request` are -removed. Requests were designed to make read-your-writes consistency more -likely with the w=0 write concern. Additionally, a thread in a request used the -same member for all secondary reads in a replica set. To ensure -read-your-writes consistency in PyMongo 3.0, do not override the default write -concern with w=0, and do not override the default read preference of PRIMARY. - -The "compile_re" option is removed -.................................. - -In PyMongo 3 regular expressions are never compiled to Python match objects. - -The "use_greenlets" option is removed -..................................... - -The `use_greenlets` option was meant to allow use of PyMongo with Gevent -without the use of gevent.monkey.patch_threads(). This option caused a lot -of confusion and made it difficult to support alternative asyncio libraries -like Eventlet. Users of Gevent should use gevent.monkey.patch_all() instead. - -.. seealso:: :doc:`examples/gevent` diff --git a/doc/migrate-to-pymongo4.rst b/doc/migrate-to-pymongo4.rst index c8ac401a1..5acd3a5d1 100644 --- a/doc/migrate-to-pymongo4.rst +++ b/doc/migrate-to-pymongo4.rst @@ -25,7 +25,8 @@ completely migrated to PyMongo 4. Most of the key new methods and options from PyMongo 4.0 are backported in PyMongo 3.12 making migration much easier. .. note:: Users of PyMongo 2.X who wish to upgrade to 4.x must first upgrade - to PyMongo 3.x by following the :doc:`migrate-to-pymongo3`. + to PyMongo 3.x by following the `PyMongo 3 Migration Guide + `_. Python 3.6+ -----------