Changelogs » Motor

Motor

2.8

therefore inheriting
`PyMongo 2.7.2's bug fixes <https://jira.mongodb.org/browse/PYTHON/fixforversion/14005>`_
and
`PyMongo 2.8's bug fixes <https://jira.mongodb.org/browse/PYTHON/fixforversion/14223>`_
and `features
<http://api.mongodb.org/python/current/changelog.htmlchanges-in-version-2-8>`_.

Fixes `a connection-pool timeout when waitQueueMultipleMS is set
<https://jira.mongodb.org/browse/MOTOR-62>`_ and `two bugs in replica set
monitoring <https://jira.mongodb.org/browse/MOTOR-61>`_.

The ``copy_database`` method has been removed. It was overly complex and no one
used it, see `MOTOR-56 <https://jira.mongodb.org/browse/MOTOR-56>`_.
You can still use the :meth:`MotorDatabase.command` method directly.
The only scenario not supported is copying a database from one host to
another, if the remote host requires authentication.
For this, use PyMongo's `copy_database`_ method, or, since PyMongo's
``copy_database`` will be removed in a future release too, use the mongo shell.

.. _copy_database: http://api.mongodb.org/python/current/api/pymongo/mongo_client.htmlpymongo.mongo_client.MongoClient.copy_database

.. seealso:: `The "copydb" command <http://docs.mongodb.org/manual/reference/command/copydb/>`_.

2.7

* :meth:`MotorCollection.aggregate` can return a cursor.
* Support for all current MongoDB authentication mechanisms (see PyMongo's
`authentication examples`_).
* A new :meth:`MotorCollection.parallel_scan` method.
* An :doc:`API for bulk writes <examples/bulk>`.
* Support for wire protocol changes in MongoDB 2.6.
* The ability to specify a server-side timeout for operations
with :meth:`~MotorCursor.max_time_ms`.
* A new :meth:`MotorGridFS.find` method for querying GridFS.

.. _authentication examples: http://api.mongodb.org/python/current/examples/authentication.html

Bugfixes
~~~~~~~~

``MotorReplicaSetClient.open`` threw an error if called without a callback.

``MotorCursor.to_list`` `ignored SON manipulators
<https://jira.mongodb.org/browse/MOTOR-8>`_. (Thanks to Eren G├╝ven for the
report and the fix.)

`The full list is in Jira
<https://jira.mongodb.org/browse/MOTOR-23?filter=15038>`_.

2.1

later. Motor continues to support MongoDB 3.0 and later. Motor 2.1 also adds
support for Python 3.8.

Motor now offers experimental support for Windows when it is using the asyncio
event loop. This means it supports Windows exclusively with Python 3, either
integrating with asyncio directly or with Tornado 5 or later: starting in
version 5, Tornado uses the asyncio event loop on Python 3 by default.

Additional changes:

- Support for MongoDB 4.2 sharded transactions. Sharded transactions have
the same API as replica set transactions.
- New method :meth:`~motor.motor_asyncio.AsyncIOMotorClientSession.with_transaction`
to support conveniently running a transaction in a session with automatic
retries and at-most-once semantics.
- Added the ``max_commit_time_ms`` parameter to
:meth:`~motor.motor_asyncio.AsyncIOMotorClientSession.start_transaction`.
- The ``retryWrites`` URI option now defaults to ``True``. Supported write
operations that fail with a retryable error will automatically be retried one
time, with at-most-once semantics.
- Support for retryable reads and the ``retryReads`` URI option which is
enabled by default. See the :class:`~pymongo.mongo_client.MongoClient`
documentation for details. Now that supported operations are retried
automatically and transparently, users should consider adjusting any custom
retry logic to prevent an application from inadvertently retrying for too
long.
- Support zstandard for wire protocol compression.
- Support for periodically polling DNS SRV records to update the mongos proxy
list without having to change client configuration.
- New method :meth:`motor.motor_asyncio.AsyncIOMotorDatabase.aggregate` to
support running database level aggregations.
- Change stream enhancements for MongoDB 4.2:

- Resume tokens can now be accessed from a ``AsyncIOMotorChangeStream`` cursor
using the :attr:`~motor.motor_asyncio.AsyncIOMotorChangeStream.resume_token`
attribute.
- New ``AsyncIOMotorChangeStream`` method
:meth:`~motor.motor_asyncio.AsyncIOMotorChangeStream.try_next` and
attribute :attr:`~motor.motor_asyncio.AsyncIOMotorChangeStream.alive`.
- New parameter ``start_after`` for change stream
:meth:`motor.motor_asyncio.AsyncIOMotorCollection.watch`,
:meth:`motor.motor_asyncio.AsyncIOMotorDatabase.watch`, and
:meth:`motor.motor_asyncio.AsyncIOMotorClient.watch` methods.

- New parameters ``bucket_name``, ``chunk_size_bytes``, ``write_concern``, and
``read_preference`` for :class:`motor.motor_asyncio.AsyncIOMotorGridFSBucket`.

Issues Resolved
~~~~~~~~~~~~~~~

See the `Motor 2.1 release notes in JIRA`_ for the complete list of resolved
issues in this release.

.. _Motor 2.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=11182&version=20187

2.0

including multi-document transactions, and change stream notifications on entire
databases or entire MongoDB servers. It adds support for Python 3.7. This
version of Motor requires PyMongo 3.7 or later.

This is a major release that removes previously deprecated APIs.

To support multi-document transactions, Motor had to make breaking changes to
the session API and release a major version bump. Since this is a major release
it also deletes many helper methods and APIs that had been deprecated over the
time since Motor 1.0, most notably the old CRUD methods ``insert``, ``update``,
``remove``, and ``save``, and the original callback-based API. Read the
:doc:`migrate-to-motor-2` carefully to upgrade your existing Motor application.

Documentation is updated to warn about obsolete TLS versions, see
:doc:`configuration`. Motor is now tested on Travis in addition to MongoDB's
`Evergreen <https://github.com/evergreen-ci/evergreen>`_ system.

Added support for `aiohttp`_ 3.0 and later, and dropped older aiohttp versions.
The aiohttp integration now requires Python 3.5+.

The ``MotorDatabase.add_user`` and ``MotorDatabase.remove_user`` methods are
deleted. Manage user accounts with four database commands: createUser_,
usersInfo_, updateUser_, and dropUser_. You can run any database command with
the :meth:`MotorDatabase.command` method.

.. _createUser: https://docs.mongodb.com/manual/reference/command/createUser/
.. _usersInfo: https://docs.mongodb.com/manual/reference/command/usersInfo/
.. _updateUser: https://docs.mongodb.com/manual/reference/command/updateUser/
.. _dropUser: https://docs.mongodb.com/manual/reference/command/createUser/

The deprecated GridFS classes ``MotorGridFS`` and ``AsyncIOMotorGridFS`` are
deleted in favor of :class:`~motor.motor_tornado.MotorGridFSBucket` and
:class:`~motor.motor_asyncio.AsyncIOMotorGridFSBucket`, which conform to driver
specs for GridFS.

Additional changes:

- New methods for retrieving batches of raw BSON:

- :meth:`MotorCollection.find_raw_batches`
- :meth:`MotorCollection.aggregate_raw_batches`

- Motor adds its name, version, and Tornado's version (if appropriate) to the
client data logged by the MongoDB server when Motor connects, in addition to
the data added by PyMongo.
- Calling :meth:`~MotorCommandCursor.batch_size` on a cursor returned from
:meth:`~MotorCollection.aggregate` no longer raises ``AttributeError``.

1.3.1

-----------

Fix a Python 3.7 compatibility bug caused by importing "async", which is a
keyword in Python 3.7. Drop support for Python 3.4.3 and older.

1.3.0

-----------

Deprecate Motor's old callback-based async API in preparation for removing it in
Motor 2.0. Raise ``DeprecationWarning`` whenever a callback is passed.

See the :doc:`migrate-to-motor-2`.

1.2.5

-----------

Fix a Python 3.7 compatibility bug caused by importing "async", which is a
keyword in Python 3.7. Drop support for Python 3.4.3 and older.

1.2.4

-----------

Fix a Python 3.7 compatibility bug in the :class:`MotorChangeStream` class
returned by :meth:`MotorCollection.watch`. It is now possible to use change
streams in ``async for`` loops in Python 3.7.

1.2.3

-----------

Compatibility with latest Sphinx and document how to use the latest TLS
protocols.

1.2.2

-----------

1.2.1

-----------

An asyncio application that created a Change Stream with
:meth:`MotorCollection.watch` and shut down while the Change Stream was open
would print several errors. I have rewritten :meth:`MotorChangeStream.next`
and some Motor internals to allow clean shutdown with asyncio.

1.2

features. It depends on PyMongo 3.6 or later. Motor continues to support MongoDB
2.6 and later.

Dropped support for Python 2.6 and 3.3. Motor continues to support Python 2.7,
and 3.4+.

Dropped support for Tornado 3. A recent version of Tornado 4 is required.

Dropped support for the `Python 3.5.0 and Python 3.5.1 "async for" protocol
<https://python.org/dev/peps/pep-0492/api-design-and-implementation-revisions>`_.
Motor allows "async for" with cursors in Python 3.5.2 and later.

See the :ref:`Compatibility Matrix <compatibility-matrix>` for the relationships
among Motor, Python, Tornado, and MongoDB versions.

Added support for `aiohttp`_ 2.0 and later, and dropped older aiohttp versions.

Highlights include:

- New method :meth:`MotorCollection.watch` to acquire a Change Stream on a
collection.
- New Session API to support causal consistency, see
:meth:`MotorClient.start_session`.
- Support for array_filters in
:meth:`~MotorCollection.update_one`,
:meth:`~MotorCollection.update_many`,
:meth:`~MotorCollection.find_one_and_update`,
:meth:`~MotorCollection.bulk_write`.
- :meth:`MotorClient.list_databases` and :meth:`MotorClient.list_database_names`.
- Support for mongodb+srv:// URIs. See
:class:`~pymongo.mongo_client.MongoClient` for details.
- Support for retryable writes and the ``retryWrites`` URI option.  See
:class:`~pymongo.mongo_client.MongoClient` for details.

The maximum number of workers in the thread pool can be overridden with an
environment variable, see :doc:`configuration`.

:class:`MotorCollection` accepts codec_options, read_preference, write_concern,
and read_concern arguments. This is rarely needed; you typically create a
:class:`MotorCollection` from a :class:`MotorDatabase`, not by calling its
constructor directly.

Deleted obsolete class ``motor.Op``.

1.2.0

documented, but not enforced in ``setup.py``. PyMongo 3.6 is now an install-time
requirement; thanks to Shane Harvey for the fix.

1.1

---------

Motor depends on PyMongo 3.4 or later. It wraps the latest PyMongo code which
support the new server features introduced in MongoDB 3.4. (It is a coincidence
that the latest MongoDB and PyMongo versions are the same number.)

Highlights include:

- Complete support for MongoDB 3.4:

- Unicode aware string comparison using collations. See :ref:`PyMongo's examples for collation <collation-on-operation>`.
- :class:`MotorCursor` and :class:`MotorGridOutCursor` have a new attribute :meth:`~MotorCursor.collation`.
- Support for the new :class:`~bson.decimal128.Decimal128` BSON type.
- A new maxStalenessSeconds read preference option.
- A username is no longer required for the MONGODB-X509 authentication
mechanism when connected to MongoDB >= 3.4.
- :meth:`~MotorCollection.parallel_scan` supports maxTimeMS.
- :class:`~pymongo.write_concern.WriteConcern` is automatically
applied by all helpers for commands that write to the database when
connected to MongoDB 3.4+. This change affects the following helpers:

- :meth:`MotorClient.drop_database`
- :meth:`MotorDatabase.create_collection`
- :meth:`MotorDatabase.drop_collection`
- :meth:`MotorCollection.aggregate` (when using $out)
- :meth:`MotorCollection.create_indexes`
- :meth:`MotorCollection.create_index`
- :meth:`MotorCollection.drop_indexes`
- :meth:`MotorCollection.drop_indexes`
- :meth:`MotorCollection.drop_index`
- :meth:`MotorCollection.map_reduce` (when output is not
"inline")
- :meth:`MotorCollection.reindex`
- :meth:`MotorCollection.rename`

- Improved support for logging server discovery and monitoring events. See
:mod:`PyMongo's monitoring documentation <pymongo.monitoring>` for examples.
- Support for matching iPAddress subjectAltName values for TLS certificate
verification.
- TLS compression is now explicitly disabled when possible.
- The Server Name Indication (SNI) TLS extension is used when possible.
- PyMongo's `bson` module provides finer control over JSON encoding/decoding
with :class:`~bson.json_util.JSONOptions`.
- Allow :class:`~bson.code.Code` objects to have a scope of ``None``,
signifying no scope. Also allow encoding Code objects with an empty scope
(i.e. ``{}``).

.. warning:: Starting in PyMongo 3.4, :attr:`bson.code.Code.scope` may return
``None``, as the default scope is ``None`` instead of ``{}``.

.. note:: PyMongo 3.4+ attempts to create sockets non-inheritable when possible
(i.e. it sets the close-on-exec flag on socket file descriptors). Support
is limited to a subset of POSIX operating systems (not including Windows) and
the flag usually cannot be set in a single atomic operation. CPython 3.4+
implements `PEP 446`_, creating all file descriptors non-inheritable by
default. Users that require this behavior are encouraged to upgrade to
CPython 3.4+.

.. _PEP 446: https://www.python.org/dev/peps/pep-0446/

1.0

---------

Motor now depends on PyMongo 3.3 and later. The move from PyMongo 2 to 3 brings
a large number of API changes, read the `the PyMongo 3 changelog`_ carefully.

.. _the PyMongo 3 changelog: http://api.mongodb.com/python/current/changelog.htmlchanges-in-version-3-0

:class:`MotorReplicaSetClient` is removed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In Motor 1.0, :class:`MotorClient` is the only class. Connect to a replica set with
a "replicaSet" URI option or parameter::

MotorClient("mongodb://hostname/?replicaSet=my-rs")
MotorClient(host, port, replicaSet="my-rs")

New features
~~~~~~~~~~~~

New classes :class:`~motor.motor_tornado.MotorGridFSBucket` and :class:`~motor.motor_asyncio.AsyncIOMotorGridFSBucket`
conform to the `GridFS API Spec <https://github.com/mongodb/specifications/blob/master/source/gridfs/gridfs-spec.rst>`_
for MongoDB drivers. These classes supersede the old
``MotorGridFS`` and ``AsyncIOMotorGridFS``. See `GridFS`_ changes below,
especially note the **breaking change** in
:class:`~motor.motor_web.GridFSHandler`.

Serve GridFS files over HTTP using `aiohttp`_ and
:class:`~motor.aiohttp.AIOHTTPGridFS`.

.. _aiohttp: https://aiohttp.readthedocs.io/

:class:`MotorClient` changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Removed:

- :meth:`MotorClient.open`; clients have opened themselves automatically on demand
since version 0.2.
- :attr:`MotorClient.seeds`, use :func:`pymongo.uri_parser.parse_uri` on your MongoDB URI.
- :attr:`MotorClient.alive`

Added:

- :attr:`MotorClient.event_listeners`
- :attr:`MotorClient.max_idle_time_ms`
- :attr:`MotorClient.min_pool_size`

Unix domain socket paths must be quoted with :func:`urllib.parse.quote_plus` (or
``urllib.quote_plus`` in Python 2) before they are included in a URI:

.. code-block:: python

path = '/tmp/mongodb-27017.sock'
MotorClient('mongodb://%s' % urllib.parse.quote_plus(path))

:class:`~motor.motor_tornado.MotorCollection` changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Added:

- :meth:`MotorCollection.create_indexes`
- :meth:`MotorCollection.list_indexes`

New ``bypass_document_validation`` parameter for
:meth:`~.MotorCollection.initialize_ordered_bulk_op` and
:meth:`~.MotorCollection.initialize_unordered_bulk_op`.

Changes to :meth:`~motor.motor_tornado.MotorCollection.find` and :meth:`~motor.motor_tornado.MotorCollection.find_one`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following find/find_one options have been renamed:

These renames only affect your code if you passed these as keyword arguments,
like ``find(fields=['fieldname'])``. If you passed only positional parameters these
changes are not significant for your application.

- spec -> filter
- fields -> projection
- partial -> allow_partial_results

The following find/find_one options have been added:

- cursor_type (see :class:`~pymongo.cursor.CursorType` for values)
- oplog_replay
- modifiers

The following find/find_one options have been removed:

- network_timeout (use :meth:`~motor.motor_tornado.MotorCursor.max_time_ms` instead)
- read_preference (use :meth:`~motor.motor_tornado.MotorCollection.with_options`
instead)
- tag_sets (use one of the read preference classes from
:mod:`~pymongo.read_preferences` and
:meth:`~motor.motor_tornado.MotorCollection.with_options` instead)
- secondary_acceptable_latency_ms (use the ``localThresholdMS`` URI option
instead)
- max_scan (use the new ``modifiers`` option instead)
- snapshot (use the new ``modifiers`` option instead)
- tailable (use the new ``cursor_type`` option instead)
- await_data (use the new ``cursor_type`` option instead)
- exhaust (use the new ``cursor_type`` option instead)
- as_class (use :meth:`~motor.motor_tornado.MotorCollection.with_options` with
:class:`~bson.codec_options.CodecOptions` instead)
- compile_re (BSON regular expressions are always decoded to
:class:`~bson.regex.Regex`)

The following find/find_one options are deprecated:

- manipulate

The following renames need special handling.

- timeout -> no_cursor_timeout -
By default, MongoDB closes a cursor after 10 minutes of inactivity. In previous
Motor versions, you disabled the timeout by passing ``timeout=False`` to
:meth:`.MotorCollection.find` or :meth:`.MotorGridFS.find`. The ``timeout``
parameter has been renamed to ``no_cursor_timeout``, it defaults to ``False``,
and you must now pass ``no_cursor_timeout=True`` to disable timeouts.

:class:`~motor.motor_tornado.MotorCursor`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Added:

- :attr:`.MotorCursor.address`
- :meth:`.MotorCursor.max_await_time_ms`

Removed:

- :attr:`.MotorCursor.conn_id`, use :attr:`~.MotorCursor.address`

GridFS
~~~~~~

The old GridFS classes ``MotorGridFS`` and
``AsyncIOMotorGridFS`` are deprecated in favor of
:class:`~motor.motor_tornado.MotorGridFSBucket` and
:class:`~motor.motor_asyncio.AsyncIOMotorGridFSBucket`,
which comply with MongoDB's cross-language driver spec for GridFS.

The old classes are still supported, but will be removed in Motor 2.0.

**BREAKING CHANGE**: The overridable method
:class:`~motor.web.GridFSHandler.get_gridfs_file` of
:class:`~motor.web.GridFSHandler` now takes a
:class:`~motor.motor_tornado.MotorGridFSBucket`, not a
:class:`~motor.motor_tornado.MotorGridFS`.
It also takes an additional ``request`` parameter.

:class:`~motor.motor_tornado.MotorGridOutCursor`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Added:

- :attr:`.MotorGridOutCursor.address`
- :meth:`.MotorGridOutCursor.max_await_time_ms`

Removed:

- :attr:`.MotorGridOutCursor.conn_id`, use :attr:`~.MotorGridOutCursor.address`

:class:`~motor.motor_tornado.MotorGridIn`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

New method :meth:`.MotorGridIn.abort`.

In a Python 3.5 native coroutine, the "async with" statement calls
:meth:`~MotorGridIn.close` automatically::

async def upload():
my_db = MotorClient().test
fs = MotorGridFSBucket(my_db)
async with await fs.new_file() as gridin:
await gridin.write(b'First part\n')
await gridin.write(b'Second part')

gridin is now closed automatically.

:class:`~motor.motor_tornado.MotorGridOut`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:class:`~motor.motor_tornado.MotorGridOut` is now an async iterable, so
reading a chunk at a time is much simpler with a Python 3 native coroutine::

async def read_file(file_id):
fs = motor.motor_tornado.MotorGridFS(db)
gridout = await fs.get(file_id)

async for chunk in gridout:
sys.stdout.write(chunk)

sys.stdout.flush()

Documentation
~~~~~~~~~~~~~

The :doc:`/api-asyncio/index` is now fully documented, side by side with the
:doc:`/api-tornado/index`.

New :doc:`developer-guide` added.

0.7

---------

For asynchronous I/O Motor now uses a thread pool, which is faster and simpler
than the prior implementation with greenlets. It no longer requires the
``greenlet`` package, and now requires the ``futures`` backport package on
Python 2.

This version updates the PyMongo dependency from 2.8.0 to 2.9.x, and wraps
PyMongo 2.9's new APIs.

Most of Motor 1.0's API is now implemented, and APIs that will be removed in
Motor 1.0 are now deprecated and raise warnings.

:class:`MotorClient` changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :class:`~MotorClient.get_database` method is added for getting a :class:`MotorDatabase`
instance with its options configured differently than the MotorClient's.

New read-only attributes:

- :attr:`~MotorClient.codec_options`
- :attr:`~MotorClient.local_threshold_ms`
- :attr:`~MotorClient.max_write_batch_size`

:class:`MotorReplicaSetClient` changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :meth:`~MotorReplicaSetClient.get_database` method is added for getting a
:class:`MotorDatabase` instance with its options configured differently than the
MotorReplicaSetClient's.

New read-only attributes:

- :attr:`~MotorReplicaSetClient.codec_options`
- :attr:`~MotorReplicaSetClient.local_threshold_ms`

:class:`MotorDatabase` changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :meth:`~MotorDatabase.get_collection` method is added for getting a
:class:`MotorCollection` instance with its options configured differently than the
MotorDatabase's.

The ``connection`` property is deprecated in favor of a new read-only attribute
:attr:`~MotorDatabase.client`.

New read-only attribute:

- :attr:`~MotorDatabase.codec_options`

:class:`MotorCollection` changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :meth:`~MotorCollection.with_options` method is added for getting a
:class:`MotorCollection` instance with its options configured differently than this
MotorCollection's.

New read-only attribute:

- :attr:`~MotorCollection.codec_options`

The following methods wrap PyMongo's implementation of the standard `CRUD API Spec`_
for MongoDB Drivers:

- :meth:`~MotorCollection.bulk_write`
- :meth:`~MotorCollection.insert_one`
- :meth:`~MotorCollection.insert_many`
- :meth:`~MotorCollection.update_one`
- :meth:`~MotorCollection.update_many`
- :meth:`~MotorCollection.replace_one`
- :meth:`~MotorCollection.delete_one`
- :meth:`~MotorCollection.delete_many`
- :meth:`~MotorCollection.find_one_and_delete`
- :meth:`~MotorCollection.find_one_and_replace`
- :meth:`~MotorCollection.find_one_and_update`

These new methods do not apply SON Manipulators.

.. _CRUD API Spec: https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst

:doc:`GridFS <api-tornado/gridfs>` changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

New :class:`MotorGridOutCursor` methods:

- :meth:`~MotorGridOutCursor.add_option`
- :meth:`~MotorGridOutCursor.remove_option`
- :meth:`~MotorGridOutCursor.clone`

Added :class:`MotorGridOut` documentation:

- :attr:`~MotorGridOut.aliases`
- :attr:`~MotorGridOut.chunk_size`
- :meth:`~MotorGridOut.close`
- :attr:`~MotorGridOut.content_type`
- :attr:`~MotorGridOut.filename`
- :attr:`~MotorGridOut.length`
- :attr:`~MotorGridOut.md5`
- :attr:`~MotorGridOut.metadata`
- :attr:`~MotorGridOut.name`
- :attr:`~MotorGridOut.upload_date`

Bugfix
~~~~~~

`MOTOR-124 <https://jira.mongodb.org/browse/MOTOR-124>`_: an import deadlock
in Python 2 and Tornado 3 led to an :exc:`~pymongo.errors.AutoReconnect`
exception with some replica sets.

0.6.2

-----------

Fix "from motor import \*" for Python 3.

0.6.1

-----------

Fix source distribution, which hadn't included the "frameworks" submodules.

0.6

---------

This is a bugfix release. Fixing these bugs has introduced tiny API changes that
may affect some programs.

`motor_asyncio` and `motor_tornado` submodules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These modules have been moved from:

- `motor_asyncio.py`
- `motor_tornado.py`

To:

- `motor_asyncio/__init__.py`
- `motor_tornado/__init__.py`

Motor had to make this change in order to omit the `motor_asyncio` submodule
entirely and avoid a spurious :exc:`SyntaxError` being printed when installing in
Python 2. The change should be invisible to application code.

Database and collection names with leading underscores
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A database or collection whose name starts with an underscore can no longer be
accessed as a property::

Now raises AttributeError.
db = MotorClient()._mydatabase
collection = db._mycollection
subcollection = collection._subcollection

Such databases and collections can still be accessed dict-style::

Continues to work the same as previous Motor versions.
db = MotorClient()['_mydatabase']
collection = db['_mycollection']

To ensure a "sub-collection" with a name that includes an underscore is
accessible, Motor collections now allow dict-style access, the same as Motor
clients and databases always have::

New in Motor 0.6
subcollection = collection['_subcollection']

These changes solve problems with iPython code completion and the Python 3
:class:`ABC` abstract base class.

0.5

`MotorClient`:
- `~MotorClient.host`
- `~MotorClient.port`
- `~MotorClient.document_class`
- `~MotorClient.tz_aware`
- `~MotorClient.secondary_acceptable_latency_ms`
- `~MotorClient.tag_sets`
- `~MotorClient.uuid_subtype`
- `~MotorClient.disconnect`
- `~MotorClient.alive`

`MotorReplicaSetClient`:
- `~MotorReplicaSetClient.document_class`
- `~MotorReplicaSetClient.tz_aware`
- `~MotorReplicaSetClient.secondary_acceptable_latency_ms`
- `~MotorReplicaSetClient.tag_sets`
- `~MotorReplicaSetClient.uuid_subtype`
- `~MotorReplicaSetClient.alive`

`MotorDatabase`:
- `~MotorDatabase.secondary_acceptable_latency_ms`
- `~MotorDatabase.tag_sets`
- `~MotorDatabase.uuid_subtype`

`MotorCollection`:
- `~MotorCollection.secondary_acceptable_latency_ms`
- `~MotorCollection.tag_sets`
- `~MotorCollection.uuid_subtype`

Cursor slicing
~~~~~~~~~~~~~~

Cursors can no longer be indexed like ``cursor[n]`` or sliced like
``cursor[start:end]``, see `MOTOR-84 <https://jira.mongodb.org/browse/MOTOR-84>`_.
If you wrote code like this::

cursor = collection.find()[i]
yield cursor.fetch_next
doc = cursor.next_object()

Then instead, write::

cursor = collection.find().skip(i).limit(-1)
yield cursor.fetch_next
doc = cursor.next_object()

The negative limit ensures the server closes the cursor after one result,
saving Motor the work of closing it. See `cursor.limit
<http://docs.mongodb.org/v3.0/reference/method/cursor.limit/>`_.

SSL hostname validation error
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When you use Motor with Tornado and SSL hostname validation fails, Motor used
to raise a :exc:`~pymongo.errors.ConnectionFailure` with a useful messsage like "hostname 'X'
doesn't match 'Y'". The message is now empty and Tornado logs a warning
instead.

Configuring uuid_subtype
~~~~~~~~~~~~~~~~~~~~~~~~

You can now get and set :attr:`~MotorClient.uuid_subtype` on :class:`MotorClient`,
:class:`MotorReplicaSetClient`, and :class:`MotorDatabase` instances, not just on
:class:`MotorCollection`.

0.4.1

-----------

Fix `MOTOR-66 <https://jira.mongodb.org/browse/MOTOR-66>`_, deadlock when
initiating :class:`MotorReplicaSetClient` connection from multiple operations
at once.

0.4

---------

Supports MongoDB 3.0. In particular, supports MongoDB 3.0's new SCRAM-SHA-1
authentication mechanism and updates the implementations of
:meth:`MotorClient.database_names` and :meth:`MotorDatabase.collection_names`.

0.3.3

-----------

Fix `MOTOR-45 <https://jira.mongodb.org/browse/MOTOR-45>`_,
a stack-context leak in domain name resolution that could lead to an infinite
loop and rapid memory leak.

Document Motor's :doc:`requirements` in detail.

0.3.2

-----------

Fix `MOTOR-44 <https://jira.mongodb.org/browse/MOTOR-44>`_,
a socket leak in :class:`MotorClient.copy_database`
and :class:`MotorReplicaSetClient.copy_database`.

0.3.1

-----------

Fix `MOTOR-43 <https://jira.mongodb.org/browse/MOTOR-43>`_,
a TypeError when using :class:`~motor.web.GridFSHandler`
with a timezone-aware :class:`~motor.motor_tornado.MotorClient`.

Fix GridFS examples that hadn't been updated for Motor 0.2's new syntax.

Fix a unittest that hadn't been running.

0.3

---------

No new features.

* Updates PyMongo dependency from 2.7 to 2.7.1,
therefore inheriting `PyMongo 2.7.1's bug fixes
<https://jira.mongodb.org/browse/PYTHON/fixforversion/13823>`_.
* Motor continues to support Python 2.6, 2.7, 3.3, and 3.4,
but now with single-source.
2to3 no longer runs during installation with Python 3.
* ``nosetests`` is no longer required for regular Motor tests.
* Fixes `a mistake in the docstring <https://jira.mongodb.org/browse/MOTOR-34>`_
for aggregate().

0.2.1

-----------

Fixes two bugs:

* `MOTOR-32 <https://jira.mongodb.org/browse/MOTOR-32>`_:
The documentation for :meth:`MotorCursor.close` claimed it immediately
halted execution of :meth:`MotorCursor.each`, but it didn't.
* `MOTOR-33 <https://jira.mongodb.org/browse/MOTOR-33>`_:
An incompletely iterated cursor's ``__del__`` method sometimes got stuck
and cost 100% CPU forever, even though the application was still responsive.

0.2

Old style:
document = yield motor.Op(collection.find_one, {'_id': my_id})

New style:
document = yield collection.find_one({'_id': my_id})

To make this possible, Motor asynchronous methods
(except :meth:`MotorCursor.each`) now return a
:class:`~tornado.concurrent.Future`.

Using Motor with callbacks is still possible: If a callback is passed, it will
be executed with the ``(result, error)`` of the operation, same as in Motor

0.1.2

-----------

Fixes innocuous unittest failures when running against Tornado 3.1.1.

0.1.1

-----------

Fixes issue `MOTOR-12`_ by pinning its PyMongo dependency to PyMongo version
2.5.0 exactly.

Motor relies on some of PyMongo's internal details, so changes to PyMongo can
break Motor, and a change in PyMongo 2.5.1 did. Eventually PyMongo will expose
stable hooks for Motor to use, but for now I changed Motor's dependency from
``PyMongo>=2.4.2`` to ``PyMongo==2.5.0``.

.. _MOTOR-12: https://jira.mongodb.org/browse/MOTOR-12

0.1

gen.engine
def get_some_documents():
cursor = collection.find().sort('_id').limit(2)
cursor.to_list(callback=(yield gen.Callback('key')))
do_something_while_we_wait()
try:
documents = yield motor.WaitOp('key')
print documents
except Exception, e:
print e

The function now becomes::

gen.coroutine
def f():
cursor = collection.find().sort('_id').limit(2)
future = cursor.to_list(2)
do_something_while_we_wait()
try:
documents = yield future
print documents
except Exception, e:
print e

Similarly, a function written like so in the old style::

gen.engine
def get_two_documents_in_parallel(collection):
collection.find_one(
{'_id': 1}, callback=(yield gen.Callback('one')))

collection.find_one(
{'_id': 2}, callback=(yield gen.Callback('two')))

try:
doc_one, doc_two = yield motor.WaitAllOps(['one', 'two'])
print doc_one, doc_two
except Exception, e:
print e

Now becomes::

gen.coroutine
def get_two_documents_in_parallel(collection):
future_0 = collection.find_one({'_id': 1})
future_1 = collection.find_one({'_id': 2})

try:
doc_one, doc_two = yield [future_0, future_1]
print doc_one, doc_two
except Exception, e:
print e


to_list
'''''''

Any calls to :meth:`MotorCursor.to_list` that omitted the ``length``
argument must now include it::

result = yield collection.find().to_list(100)

``None`` is acceptable, meaning "unlimited." Use with caution.

Connection Pooling
''''''''''''''''''

:class:`MotorPool` has been rewritten. It supports the new options
introduced in PyMongo 2.6, and drops all Motor-specific options.

:class:`MotorClient` and :class:`MotorReplicaSetClient` have an option
``max_pool_size``. It used to mean "minimum idle sockets to keep open", but its
meaning has changed to "maximum sockets open per host." Once this limit is
reached, operations will pause waiting for a socket to become available.
Therefore the default has been raised from 10 to 100. If you pass a value for
``max_pool_size`` make sure it's large enough for the expected load. (Sockets
are only opened when needed, so there's no cost to having a ``max_pool_size``
larger than necessary. Err towards a larger value.) If you've been accepting
the default, continue to do so.

``max_pool_size`` is now synonymous with Motor's special ``max_concurrent``
option, so ``max_concurrent`` has been removed.

``max_wait_time`` has been renamed ``waitQueueTimeoutMS`` for consistency with
PyMongo. If you pass ``max_wait_time``, rename it and multiply by 1000.

The :exc:`MotorPoolTimeout` exception is gone; catch PyMongo's
:exc:`~pymongo.errors.ConnectionFailure` instead.

DNS
'''

Motor can take advantage of Tornado 3's `asynchronous resolver interface`_. By
default, Motor still uses blocking DNS, but you can enable non-blocking
lookup with a threaded resolver::

Resolver.configure('tornado.netutil.ThreadedResolver')

Or install `pycares`_ and use the c-ares resolver::

Resolver.configure('tornado.platform.caresresolver.CaresResolver')

MotorCursor.tail
''''''''''''''''

The ``MotorCursor.tail`` method has been removed. It was complex, diverged from
PyMongo's feature set, and encouraged overuse of MongoDB capped collections as
message queues when a purpose-built message queue is more appropriate. An
example of tailing a capped collection is provided instead:
:doc:`examples/tailable-cursors`.

MotorClient.is_locked
'''''''''''''''''''''

``is_locked`` has been removed since calling it from Motor would be
bizarre. If you called ``MotorClient.is_locked`` like::

locked = yield motor.Op(client.is_locked)

you should now do::

result = yield client.admin.current_op()
locked = bool(result.get('fsyncLock', None))

The result is ``True`` only if an administrator has called `fsyncLock`_ on the
mongod. It is unlikely that you have any use for this.

GridFSHandler
'''''''''''''

:meth:`~web.GridFSHandler.get_gridfs_file` now
returns a Future instead of accepting a callback.

.. _Greenlet: http://pypi.python.org/pypi/greenlet/
.. _asynchronous resolver interface: http://www.tornadoweb.org/en/stable/netutil.htmltornado.netutil.Resolver
.. _pycares: https://pypi.python.org/pypi/pycares
.. _fsyncLock: http://docs.mongodb.org/manual/reference/method/db.fsyncLock/

New Features
~~~~~~~~~~~~

The introduction of a :ref:`Futures-based API <changelog-futures>` is the most
pervasive new feature. In addition Motor 0.2 includes new features from