MOTOR-698 Motor 2 to 3 migration guide (#166)

doc/changelog.rst

@@ -6,12 +6,138 @@ Changelog
 Motor 3.0
 ---------
 
-Motor 3.0 requires PyMongo 4.0+ and Python 3.7+.
-
+Motor 3.0 adds support for PyMongo 4.0+.  It inherits a number
+of improvemnts and breaking API changes from PyMongo 4.0+.
+See :doc:`migrate-to-motor-3` for more information.
 
 Breaking Changes
 ~~~~~~~~~~~~~~~~
-- Prevent use of :class:`~pymongo.database.Database` and :class:`~pymongo.collection.Collection` in boolean expressions.
+- Requires PyMongo 4.0+.
+- Removed support for Python 3.5 and 3.6. Python 3.7+ is now required.
+- Removed the ``socketKeepAlive`` keyword argument to
+  :class:`~motor.motor_tornado.MotorClient`.
+- Removed :meth:`motor.motor_tornado.MotorClient.fsync`,
+  :meth:`motor.motor_tornado.MotorClient.unlock`, and
+  :attr:`motor.motor_tornado.MotorClient.is_locked`.
+- Removed :attr:`motor.motor_tornado.MotorClient.max_bson_size`.
+- Removed :attr:`motor.motor_tornado.MotorClient.max_message_size`.
+- Removed :attr:`motor.motor_tornado.MotorClient.max_write_batch_size`.
+- Removed :attr:`motor.motor_tornado.MotorClient.event_listeners`.
+- Removed :attr:`motor.motor_tornado.MotorClient.max_pool_size`.
+- Removed :attr:`motor.motor_tornado.MotorClient.max_idle_time_ms`.
+- Removed :attr:`motor.motor_tornado.MotorClient.local_threshold_ms`.
+- Removed :attr:`motor.motor_tornado.MotorClient.server_selection_timeout`.
+- Removed :attr:`motor.motor_tornado.MotorClient.retry_writes`.
+- Removed :attr:`motor.motor_tornado.MotorClient.retry_reads`.
+- Removed support for database profiler helpers
+  :meth:`~motor.motor_tornado.MotorDatabase.profiling_level`,
+  :meth:`~motor.motor_tornado.MotorDatabase.set_profiling_level`,
+  and :meth:`~motor.motor_tornado.MotorDatabase.profiling_info`. Instead, users
+  should run the profile command with the
+  :meth:`~motor.motor_tornado.MotorDatabase.command` helper directly.
+- Removed :attr:`pymongo.OFF`, :attr:`pymongo.SLOW_ONLY`, and
+  :attr:`pymongo.ALL`.
+- Removed :meth:`motor.motor_tornado.MotorCollection.map_reduce` and
+  :meth:`motor.motor_tornado.MotorCollection.inline_map_reduce`.
+- Removed the ``useCursor`` option for
+  :meth:`~motor.motor_tornado.MotorCollection.aggregate`.
+- Removed :mod:`pymongo.son_manipulator`,
+  :meth:`motor.motor_tornado.MotorDatabase.add_son_manipulator`,
+  :attr:`motor.motor_tornado.MotorDatabase.outgoing_copying_manipulators`,
+  :attr:`motor.motor_tornado.MotorDatabase.outgoing_manipulators`,
+  :attr:`motor.motor_tornado.MotorDatabase.incoming_copying_manipulators`, and
+  :attr:`motor.motor_tornado.MotorDatabase.incoming_manipulators`.
+- Removed the ``manipulate`` and ``modifiers`` parameters from
+  :meth:`~motor.motor_tornado.MotorCollection.find`,
+  :meth:`~motor.motor_tornado.MotorCollection.find_one`,
+  :meth:`~motor.motor_tornado.MotorCollection.find_raw_batches`, and
+  :meth:`~motor.motor_tornado.MotorCursor`.
+- ``directConnection`` URI option and keyword argument to :class:`~motor.motor_tornado.MotorClient`
+  defaults to ``False`` instead of ``None``, allowing for the automatic
+  discovery of replica sets. This means that if you
+  want a direct connection to a single server you must pass
+  ``directConnection=True`` as a URI option or keyword argument.
+- The ``hint`` option is now required when using ``min`` or ``max`` queries
+  with :meth:`~motor.motor_tornado.MotorCollection.find`.
+- When providing a "mongodb+srv://" URI to
+  :class:`~motor.motor_tornado.MotorClient` constructor you can now use the
+  ``srvServiceName`` URI option to specify your own SRV service name.
+- :class:`~motor.motor_tornado.MotorCollection` and :class:`motor.motor_tornado.MotorDatabase`
+  now raises an error upon evaluating as a Boolean, please use the
+  syntax ``if collection is not None:`` or ``if database is not None:`` as
+  opposed to
+  the previous syntax which was simply ``if collection:`` or ``if database:``.
+  You must now explicitly compare with None.
+- :class:`~motor.motor_tornado.MotorClient` cannot execute any operations
+  after being closed. The previous behavior would simply reconnect. However,
+  now you must create a new instance.
+- Empty projections (eg {} or []) for
+  :meth:`~motor.motor_tornado.MotorCollection.find`, and
+  :meth:`~motor.motor_tornado.MotorCollection.find_one`
+  are passed to the server as-is rather than the previous behavior which
+  substituted in a projection of ``{"_id": 1}``. This means that an empty
+  projection will now return the entire document, not just the ``"_id"`` field.
+- :class:`~motor.motor_tornado.MotorClient` now raises a
+  :exc:`~pymongo.errors.ConfigurationError` when more than one URI is passed
+  into the ``hosts`` argument.
+- :class:`~motor.motor_tornado.MotorClient`` now raises an
+  :exc:`~pymongo.errors.InvalidURI` exception
+  when it encounters unescaped percent signs in username and password when
+  parsing MongoDB URIs.
+- Comparing two :class:`~motor.motor_tornado.MotorClient` instances now
+  uses a set of immutable properties rather than
+  :attr:`~motor.motor_tornado.MotorClient.address` which can change.
+- Removed the `disable_md5` parameter for :class:`~gridfs.GridFSBucket` and
+  :class:`~gridfs.GridFS`. See :ref:`removed-gridfs-checksum` for details.
+- PyMongoCrypt 1.2.0 or later is now required for client side field level
+  encryption support.
+
+Notable improvements
+~~~~~~~~~~~~~~~~~~~~
+
+- Enhanced connection pooling to create connections more efficiently and
+  avoid connection storms.
+- Added the ``maxConnecting`` URI and
+  :class:`~motor.motor_tornado.MotorClient` keyword argument.
+- :class:`~motor.motor_tornado.MotorClient` now accepts a URI and keyword
+  argument `srvMaxHosts` that limits the number of mongos-like hosts a client
+  will connect to. More specifically, when a mongodb+srv:// connection string
+  resolves to more than `srvMaxHosts` number of hosts, the client will randomly
+  choose a `srvMaxHosts` sized subset of hosts.
+- Added :attr:`motor.motor_tornado.MotorClient.options` for read-only access
+  to a client's configuration options.
+- Added support for the ``comment`` parameter to all helpers. For example see
+  :meth:`~motor.motor_tornado.MotorCollection.insert_one`.
+- Added support for the ``let`` parameter to
+  :meth:`~motor.motor_tornado.MotorCollection.update_one`,
+  :meth:`~motor.motor_tornado.MotorCollection.update_many`,
+  :meth:`~motor.motor_tornado.MotorCollection.delete_one`,
+  :meth:`~motor.motor_tornado.MotorCollection.delete_many`,
+  :meth:`~motor.motor_tornado.MotorCollection.replace_one`,
+  :meth:`~motor.motor_tornado.MotorCollection.aggregate`,
+  :meth:`~motor.motor_tornado.MotorCollection.find_one_and_delete`,
+  :meth:`~motor.motor_tornado.MotorCollection.find_one_and_replace`,
+  :meth:`~motor.motor_tornado.MotorCollection.find_one_and_update`,
+  :meth:`~motor.motor_tornado.MotorCollection.find`,
+  :meth:`~motor.motor_tornado.MotorCollection.find_one`,
+  and :meth:`~motor.motor_tornado.MotorCollection.bulk_write`.
+  ``let`` is a map of parameter names and values.
+  Parameters can then be accessed as variables in an aggregate expression
+  context.
+- :meth:`~motor.motor_tornado.MotorCollection.aggregate` now supports
+  $merge and $out executing on secondaries on MongoDB >=5.0.
+  aggregate() now always obeys the collection's :attr:`read_preference` on
+  MongoDB >= 5.0.
+- :meth:`gridfs.grid_file.GridOut.seek` now returns the new position in the file, to
+  conform to the behavior of :meth:`io.IOBase.seek`.
+
+Issues Resolved
+~~~~~~~~~~~~~~~
+
+See the `Motor 3.0 release notes in JIRA`_ for the list of resolved issues
+in this release.
+
+.. _Motor 3.0 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=11182&version=29710
 
 Motor 2.5.1
 -----------
@@ -1123,7 +1249,7 @@ If it's important to test that MongoDB is available before continuing
 your application's startup, use ``IOLoop.run_sync``::
 
     loop = tornado.ioloop.IOLoop.current()
-    client = motor.MotorClient(host, port)
+    client = motor.motor_tornado.MotorClient(host, port)
     try:
         loop.run_sync(client.open)
     except pymongo.errors.ConnectionFailure:

doc/index.rst

@@ -85,6 +85,7 @@ Contents
    examples/index
    changelog
    migrate-to-motor-2
+   migrate-to-motor-3
    developer-guide
    contributors