Skip to content

Latest commit

 

History

History
3263 lines (2663 loc) · 141 KB

changelog.rst

File metadata and controls

3263 lines (2663 loc) · 141 KB

Changelog

Changes in Version 4.0.1

Issues Resolved

Version 4.0.1 fixes a number of bugs:

  • Fixed a bug that prevented :meth:`bson.json_util.loads` from decoding a document with a non-string "$regex" field (PYTHON-3028).
  • Fixed a bug where a client may select a hidden/ghost or not yet initialized replica set member leading to unexpected "connection pool paused" errors (PYTHON-3027).

See the PyMongo 4.0.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 4.0

Warning

PyMongo 4.0 drops support for Python 2.7, 3.4, and 3.5.

Warning

PyMongo 4.0 drops support for MongoDB 2.6, 3.0, 3.2, and 3.4.

PyMongo 4.0 brings a number of improvements as well as some backward breaking changes. For example, all APIs deprecated in PyMongo 3.X have been removed. Be sure to read the changes listed below and the :doc:`migrate-to-pymongo4` before upgrading from PyMongo 3.x.

Breaking Changes in 4.0

Notable improvements

Issues Resolved

See the PyMongo 4.0 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.12.0

Warning

PyMongo 3.12.0 deprecates support for Python 2.7, 3.4 and 3.5. These Python versions will not be supported by PyMongo 4.

Warning

PyMongo now allows insertion of documents with keys that include dots ('.') or start with dollar signs ('$').

  • PyMongoCrypt 1.1.0 or later is now required for client side field level encryption support.
  • Iterating over :class:`gridfs.grid_file.GridOut` now moves through the file line by line instead of chunk by chunk, and does not restart at the top for subsequent iterations on the same object. Call seek(0) to reset the iterator.

Notable improvements

Bug fixes

  • Fixed a bug that could cause the driver to deadlock during automatic client side field level encryption (PYTHON-2472).
  • Fixed a potential deadlock when garbage collecting an unclosed exhaust :class:`~pymongo.cursor.Cursor`.
  • Fixed an bug where using gevent.Timeout to timeout an operation could lead to a deadlock.
  • Fixed the following bug with Atlas Data Lake. When closing cursors, pymongo now sends killCursors with the namespace returned the cursor's initial command response.
  • Fixed a bug in :class:`~pymongo.cursor.RawBatchCursor` that caused it to return an empty bytestring when the cursor contained no results. It now raises :exc:`StopIteration` instead.

Deprecations

Issues Resolved

See the PyMongo 3.12.0 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.11.3

Issues Resolved

Version 3.11.3 fixes a bug that prevented PyMongo from retrying writes after a writeConcernError on MongoDB 4.4+ (PYTHON-2452)

See the PyMongo 3.11.3 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.11.2

Issues Resolved

Version 3.11.2 includes a number of bugfixes. Highlights include:

See the PyMongo 3.11.2 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.11.1

Version 3.11.1 adds support for Python 3.9 and includes a number of bugfixes. Highlights include:

Issues Resolved

See the PyMongo 3.11.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.11.0

Version 3.11 adds support for MongoDB 4.4 and includes a number of bug fixes. Highlights include:

Deprecations:

Unavoidable breaking changes:

Issues Resolved

See the PyMongo 3.11.0 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.10.1

Version 3.10.1 fixes the following issues discovered since the release of 3.10.0:

Issues Resolved

See the PyMongo 3.10.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.10.0

Version 3.10 includes a number of improvements and bug fixes. Highlights include:

  • Support for Client-Side Field Level Encryption with MongoDB 4.2. See :doc:`examples/encryption` for examples.
  • Support for Python 3.8.
  • Added :attr:`pymongo.client_session.ClientSession.in_transaction`.
  • Do not hold the Topology lock while creating connections in a MongoClient's background thread. This change fixes a bug where application operations would block while the background thread ensures that all server pools have minPoolSize connections.
  • Fix a UnicodeDecodeError bug when coercing a PyMongoError with a non-ascii error message to unicode on Python 2.
  • Fix an edge case bug where PyMongo could exceed the server's maxMessageSizeBytes when generating a compressed bulk write command.

Issues Resolved

See the PyMongo 3.10 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.9.0

Version 3.9 adds support for MongoDB 4.2. Highlights include:

Unavoidable breaking changes:

  • Applications that use MongoDB with the MMAPv1 storage engine must now explicitly disable retryable writes via the connection string (e.g. MongoClient("mongodb://my.mongodb.cluster/db?retryWrites=false")) or the :class:`~pymongo.mongo_client.MongoClient` constructor's keyword argument (e.g. MongoClient("mongodb://my.mongodb.cluster/db", retryWrites=False)) to avoid running into :class:`~pymongo.errors.OperationFailure` exceptions during write operations. The MMAPv1 storage engine is deprecated and does not support retryable writes which are now turned on by default.
  • In order to ensure that the connectTimeoutMS URI option is honored when connecting to clusters with a mongodb+srv:// connection string, the minimum required version of the optional dnspython dependency has been bumped to 1.16.0. This is a breaking change for applications that use PyMongo's SRV support with a version of dnspython older than 1.16.0.

Issues Resolved

See the PyMongo 3.9 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.8.0

Warning

PyMongo no longer supports Python 2.6. RHEL 6 users should install Python 2.7 or newer from Red Hat Software Collections. CentOS 6 users should install Python 2.7 or newer from SCL

Warning

PyMongo no longer supports PyPy3 versions older than 3.5. Users must upgrade to PyPy3.5+.

Unavoidable breaking changes:

  • In order to follow the ObjectID Spec version 0.2, an ObjectId's 3-byte machine identifier and 2-byte process id have been replaced with a single 5-byte random value generated per process. This is a breaking change for any application that attempts to interpret those bytes.

Issues Resolved

See the PyMongo 3.8 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.7.2

Version 3.7.2 fixes a few issues discovered since the release of 3.7.1.

Issues Resolved

See the PyMongo 3.7.2 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.7.1

Version 3.7.1 fixes a few issues discovered since the release of 3.7.0.

  • Calling :meth:`~pymongo.database.Database.authenticate` more than once with the same credentials results in OperationFailure.
  • Authentication fails when SCRAM-SHA-1 is used to authenticate users with only MONGODB-CR credentials.
  • A millisecond rounding problem when decoding datetimes in the pure Python BSON decoder on 32 bit systems and AWS lambda.

Issues Resolved

See the PyMongo 3.7.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.7.0

Version 3.7 adds support for MongoDB 4.0. Highlights include:

Deprecations:

Unavoidable breaking changes:

  • Commands that fail with server error codes 10107, 13435, 13436, 11600, 11602, 189, 91 (NotMaster, NotMasterNoSlaveOk, NotMasterOrSecondary, InterruptedAtShutdown, InterruptedDueToReplStateChange, PrimarySteppedDown, ShutdownInProgress respectively) now always raise :class:`~pymongo.errors.NotMasterError` instead of :class:`~pymongo.errors.OperationFailure`.
  • :meth:`~pymongo.collection.Collection.parallel_scan` no longer uses an implicit session. Explicit sessions are still supported.
  • Unacknowledged writes (w=0) with an explicit session parameter now raise a client side error. Since PyMongo does not wait for a response for an unacknowledged write, two unacknowledged writes run serially by the client may be executed simultaneously on the server. However, the server requires a single session must not be used simultaneously by more than one operation. Therefore explicit sessions cannot support unacknowledged writes. Unacknowledged writes without a session parameter are still supported.

Issues Resolved

See the PyMongo 3.7 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.6.1

Version 3.6.1 fixes bugs reported since the release of 3.6.0:

Issues Resolved

See the PyMongo 3.6.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.6.0

Version 3.6 adds support for MongoDB 3.6, drops support for CPython 3.3 (PyPy3 is still supported), and drops support for MongoDB versions older than 2.6. If connecting to a MongoDB 2.4 server or older, PyMongo now throws a :exc:`~pymongo.errors.ConfigurationError`.

Highlights include:

Deprecations:

Unavoidable breaking changes:

Issues Resolved

See the PyMongo 3.6 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.5.1

Version 3.5.1 fixes bugs reported since the release of 3.5.0:

Issues Resolved

See the PyMongo 3.5.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.5

Version 3.5 implements a number of improvements and bug fixes:

Highlights include:

Changes and Deprecations:

Issues Resolved

See the PyMongo 3.5 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.4

Version 3.4 implements the new server features introduced in MongoDB 3.4 and a whole lot more:

Highlights include:

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+.

Since 3.4rc0, the max staleness option has been renamed from maxStalenessMS to maxStalenessSeconds, its smallest value has changed from twice heartbeatFrequencyMS to 90 seconds, and its default value has changed from None or 0 to -1.

Issues Resolved

See the PyMongo 3.4 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.3.1

Version 3.3.1 fixes a memory leak when decoding elements inside of a :class:`~bson.raw_bson.RawBSONDocument`.

Issues Resolved

See the PyMongo 3.3.1 release notes in Jira for the list of resolved issues in this release.

Changes in Version 3.3

Version 3.3 adds the following major new features:

  • C extensions support on big endian systems.
  • Kerberos authentication support on Windows using WinKerberos.
  • A new ssl_clrfile option to support certificate revocation lists.
  • A new ssl_pem_passphrase option to support encrypted key files.
  • Support for publishing server discovery and monitoring events. See :mod:`~pymongo.monitoring` for details.
  • New connection pool options minPoolSize and maxIdleTimeMS.
  • New heartbeatFrequencyMS option controls the rate at which background monitoring threads re-check servers. Default is once every 10 seconds.

Warning

PyMongo 3.3 drops support for MongoDB versions older than 2.4. It also drops support for python 3.2 (pypy3 continues to be supported).

Issues Resolved

See the PyMongo 3.3 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.2.2

Version 3.2.2 fixes a few issues reported since the release of 3.2.1, including a fix for using the connect option in the MongoDB URI and support for setting the batch size for a query to 1 when using MongoDB 3.2+.

Issues Resolved

See the PyMongo 3.2.2 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.2.1

Version 3.2.1 fixes a few issues reported since the release of 3.2, including running the mapreduce command twice when calling the :meth:`~pymongo.collection.Collection.inline_map_reduce` method and a :exc:`TypeError` being raised when calling :meth:`~gridfs.GridFSBucket.download_to_stream`. This release also improves error messaging around BSON decoding.

Issues Resolved

See the PyMongo 3.2.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.2

Version 3.2 implements the new server features introduced in MongoDB 3.2.

Highlights include:

Note

Certain :class:`~pymongo.mongo_client.MongoClient` properties now block until a connection is established or raise :exc:`~pymongo.errors.ServerSelectionTimeoutError` if no server is available. See :class:`~pymongo.mongo_client.MongoClient` for details.

Issues Resolved

See the PyMongo 3.2 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.1.1

Version 3.1.1 fixes a few issues reported since the release of 3.1, including a regression in error handling for oversize command documents and interrupt handling issues in the C extensions.

Issues Resolved

See the PyMongo 3.1.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.1

Version 3.1 implements a few new features and fixes bugs reported since the release of 3.0.3.

Highlights include:

Changes in internal classes

The private PeriodicExecutor class no longer takes a condition_class option, and the private thread_util.Event class is removed.

Issues Resolved

See the PyMongo 3.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.0.3

Version 3.0.3 fixes issues reported since the release of 3.0.2, including a feature breaking bug in the GSSAPI implementation.

Issues Resolved

See the PyMongo 3.0.3 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.0.2

Version 3.0.2 fixes issues reported since the release of 3.0.1, most importantly a bug that could route operations to replica set members that are not in primary or secondary state when using :class:`~pymongo.read_preferences.PrimaryPreferred` or :class:`~pymongo.read_preferences.Nearest`. It is a recommended upgrade for all users of PyMongo 3.0.x.

Issues Resolved

See the PyMongo 3.0.2 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.0.1

Version 3.0.1 fixes issues reported since the release of 3.0, most importantly a bug in GridFS.delete that could prevent file chunks from actually being deleted.

Issues Resolved

See the PyMongo 3.0.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 3.0

PyMongo 3.0 is a partial rewrite of PyMongo bringing a large number of improvements:

  • A unified client class. MongoClient is the one and only client class for connecting to a standalone mongod, replica set, or sharded cluster. Migrating from a standalone, to a replica set, to a sharded cluster can be accomplished with only a simple URI change.
  • MongoClient is much more responsive to configuration changes in your MongoDB deployment. All connected servers are monitored in a non-blocking manner. Slow to respond or down servers no longer block server discovery, reducing application startup time and time to respond to new or reconfigured servers and replica set failovers.
  • A unified CRUD API. All official MongoDB drivers now implement a standard CRUD API allowing polyglot developers to move from language to language with ease.
  • Single source support for Python 2.x and 3.x. PyMongo no longer relies on 2to3 to support Python 3.
  • A rewritten pure Python BSON implementation, improving performance with pypy and cpython deployments without support for C extensions.
  • Better support for greenlet based async frameworks including eventlet.
  • Immutable client, database, and collection classes, avoiding a host of thread safety issues in client applications.

PyMongo 3.0 brings a large number of API changes. Be sure to read the changes listed below before upgrading from PyMongo 2.x.

Warning

PyMongo no longer supports Python 2.4, 2.5, or 3.1. If you must use PyMongo with these versions of Python the 2.x branch of PyMongo will be minimally supported for some time.

SONManipulator changes

The :class:`~pymongo.son_manipulator.SONManipulator` API has limitations as a technique for transforming your data. Instead, it is more flexible and straightforward to transform outgoing documents in your own code before passing them to PyMongo, and transform incoming documents after receiving them from PyMongo.

Thus the :meth:`~pymongo.database.Database.add_son_manipulator` method is deprecated. PyMongo 3's new CRUD API does not apply SON manipulators to documents passed to :meth:`~pymongo.collection.Collection.bulk_write`, :meth:`~pymongo.collection.Collection.insert_one`, :meth:`~pymongo.collection.Collection.insert_many`, :meth:`~pymongo.collection.Collection.update_one`, or :meth:`~pymongo.collection.Collection.update_many`. SON manipulators are not applied to documents returned by the new methods :meth:`~pymongo.collection.Collection.find_one_and_delete`, :meth:`~pymongo.collection.Collection.find_one_and_replace`, and :meth:`~pymongo.collection.Collection.find_one_and_update`.

SSL/TLS changes

When ssl is True the ssl_cert_reqs option now defaults to :attr:`ssl.CERT_REQUIRED` if not provided. PyMongo will attempt to load OS provided CA certificates to verify the server, raising :exc:`~pymongo.errors.ConfigurationError` if it cannot.

Gevent Support

In previous versions, PyMongo supported Gevent in two modes: you could call gevent.monkey.patch_socket() and pass use_greenlets=True to :class:`~pymongo.mongo_client.MongoClient`, or you could simply call gevent.monkey.patch_all() and omit the use_greenlets argument.

In PyMongo 3.0, the use_greenlets option is gone. To use PyMongo with Gevent simply call gevent.monkey.patch_all().

For more information, see :doc:`PyMongo's Gevent documentation <examples/gevent>`.

:class:`~pymongo.mongo_client.MongoClient` changes

:class:`~pymongo.mongo_client.MongoClient` is now the one and only client class for a standalone server, mongos, or replica set. It includes the functionality that had been split into MongoReplicaSetClient: it can connect to a replica set, discover all its members, and monitor the set for stepdowns, elections, and reconfigs. :class:`~pymongo.mongo_client.MongoClient` now also supports the full :class:`~pymongo.read_preferences.ReadPreference` API.

The obsolete classes MasterSlaveConnection, Connection, and ReplicaSetConnection are removed.

The :class:`~pymongo.mongo_client.MongoClient` constructor no longer blocks while connecting to the server or servers, and it no longer raises :class:`~pymongo.errors.ConnectionFailure` if they are unavailable, nor :class:`~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.

Therefore the alive method is removed since it no longer provides meaningful information; even if the client is disconnected, it may discover a server in time to fulfill the next operation.

In PyMongo 2.x, :class:`~pymongo.mongo_client.MongoClient` accepted a list of standalone MongoDB servers and used the first it could connect to:

MongoClient(['host1.com:27017', 'host2.com:27017'])

A list of multiple standalones is no longer supported; if multiple servers are listed they must be members of the same replica set, or mongoses in the same sharded cluster.

The behavior for a list of mongoses is changed from "high availability" to "load balancing". Before, the client connected to the lowest-latency mongos in the list, and used it until a network error prompted it to re-evaluate all mongoses' latencies and reconnect to one of them. In PyMongo 3, the client monitors its network latency to all the mongoses continuously, and distributes operations evenly among those with the lowest latency. See :ref:`mongos-load-balancing` for more information.

The client methods start_request, in_request, and end_request are removed, and so is the auto_start_request option. 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 :ref:`read preference <secondary-reads>` of PRIMARY.

Support for the slaveOk (or slave_okay), safe, and network_timeout options has been removed. Use :attr:`~pymongo.read_preferences.ReadPreference.SECONDARY_PREFERRED` instead of slave_okay. Accept the default write concern, acknowledged writes, instead of setting safe=True. Use socketTimeoutMS in place of network_timeout (note that network_timeout was in seconds, where as socketTimeoutMS is milliseconds).

The max_pool_size option has been removed. It is replaced by the maxPoolSize MongoDB URI option. maxPoolSize is now a supported URI option in PyMongo and can be passed as a keyword argument.

The copy_database method is removed, see the :doc:`copy_database examples </examples/copydb>` for alternatives.

The disconnect method is removed. Use :meth:`~pymongo.mongo_client.MongoClient.close` instead.

The get_document_class method is removed. Use :attr:`~pymongo.mongo_client.MongoClient.codec_options` instead.

The get_lasterror_options, set_lasterror_options, and unset_lasterror_options methods are removed. Write concern options can be passed to :class:`~pymongo.mongo_client.MongoClient` as keyword arguments or MongoDB URI options.

The :meth:`~pymongo.mongo_client.MongoClient.get_database` method is added for getting a Database instance with its options configured differently than the MongoClient's.

The following read-only attributes have been added:

The following attributes are now read-only:

The following attributes have been removed:

The following attributes have been renamed:

:class:`~pymongo.cursor.Cursor` changes

The conn_id property is renamed to :attr:`~pymongo.cursor.Cursor.address`.

Cursor management changes

:class:`~pymongo.cursor_manager.CursorManager` and :meth:`~pymongo.mongo_client.MongoClient.set_cursor_manager` are no longer deprecated. If you subclass :class:`~pymongo.cursor_manager.CursorManager` your implementation of :meth:`~pymongo.cursor_manager.CursorManager.close` must now take a second parameter, address. The BatchCursorManager class is removed.

The second parameter to :meth:`~pymongo.mongo_client.MongoClient.close_cursor` is renamed from _conn_id to address. :meth:`~pymongo.mongo_client.MongoClient.kill_cursors` now accepts an address parameter.

:class:`~pymongo.database.Database` changes

The connection property is renamed to :attr:`~pymongo.database.Database.client`.

The following read-only attributes have been added:

The following attributes are now read-only:

Use :meth:`~pymongo.mongo_client.MongoClient.get_database` for getting a Database instance with its options configured differently than the MongoClient's.

The following attributes have been removed:

The following methods have been added:

The following methods have been changed:

The following methods have been deprecated:

The following methods have been removed:

The get_lasterror_options, set_lasterror_options, and unset_lasterror_options methods have been removed. Use :class:`~pymongo.write_concern.WriteConcern` with :meth:`~pymongo.mongo_client.MongoClient.get_database` instead.

:class:`~pymongo.collection.Collection` changes

The following read-only attributes have been added:

The following attributes are now read-only:

Use :meth:`~pymongo.database.Database.get_collection` or :meth:`~pymongo.collection.Collection.with_options` for getting a Collection instance with its options configured differently than the Database's.

The following attributes have been removed:

The following methods have been added:

The following methods have changed:

The following methods are deprecated:

The following methods have been removed:

The get_lasterror_options, set_lasterror_options, and unset_lasterror_options methods have been removed. Use :class:`~pymongo.write_concern.WriteConcern` with :meth:`~pymongo.collection.Collection.with_options` instead.

Changes to :meth:`~pymongo.collection.Collection.find` and :meth:`~pymongo.collection.Collection.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:

The following find/find_one options have been removed:

The following find/find_one options are deprecated:

  • manipulate

The following renames need special handling.

  • timeout -> no_cursor_timeout - The default for timeout was True. The default for no_cursor_timeout is False. If you were previously passing False for timeout you must pass True for no_cursor_timeout to keep the previous behavior.

:mod:`~pymongo.errors` changes

The exception classes UnsupportedOption and TimeoutError are deleted.

:mod:`~gridfs` changes

Since PyMongo 1.6, methods open and close of :class:`~gridfs.GridFS` raised an UnsupportedAPI exception, as did the entire GridFile class. The unsupported methods, the class, and the exception are all deleted.

:mod:`~bson` changes

The compile_re option is removed from all methods that accepted it in :mod:`~bson` and :mod:`~bson.json_util`. Additionally, it is removed from :meth:`~pymongo.collection.Collection.find`, :meth:`~pymongo.collection.Collection.find_one`, :meth:`~pymongo.collection.Collection.aggregate`, :meth:`~pymongo.database.Database.command`, and so on. PyMongo now always represents BSON regular expressions as :class:`~bson.regex.Regex` objects. This prevents errors for incompatible patterns, see PYTHON-500. Use :meth:`~bson.regex.Regex.try_compile` to attempt to convert from a BSON regular expression to a Python regular expression object.

PyMongo now decodes the int64 BSON type to :class:`~bson.int64.Int64`, a trivial wrapper around long (in python 2.x) or int (in python 3.x). This allows BSON int64 to be round tripped without losing type information in python 3. Note that if you store a python long (or a python int larger than 4 bytes) it will be returned from PyMongo as :class:`~bson.int64.Int64`.

The as_class, tz_aware, and uuid_subtype options are removed from all BSON encoding and decoding methods. Use :class:`~bson.codec_options.CodecOptions` to configure these options. The APIs affected are:

This is a breaking change for any application that uses the BSON API directly and changes any of the named parameter defaults. No changes are required for applications that use the default values for these options. The behavior remains the same.

Issues Resolved

See the PyMongo 3.0 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.9.5

Version 2.9.5 works around ssl module deprecations in Python 3.6, and expected future ssl module deprecations. It also fixes bugs found since the release of 2.9.4.

Issues Resolved

See the PyMongo 2.9.5 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.9.4

Version 2.9.4 fixes issues reported since the release of 2.9.3.

Issues Resolved

See the PyMongo 2.9.4 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.9.3

Version 2.9.3 fixes a few issues reported since the release of 2.9.2 including thread safety issues in :meth:`~pymongo.collection.Collection.ensure_index`, :meth:`~pymongo.collection.Collection.drop_index`, and :meth:`~pymongo.collection.Collection.drop_indexes`.

Issues Resolved

See the PyMongo 2.9.3 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.9.2

Version 2.9.2 restores Python 3.1 support, which was broken in PyMongo 2.8. It improves an error message when decoding BSON as well as fixes a couple other issues including :meth:`~pymongo.collection.Collection.aggregate` ignoring :attr:`~pymongo.collection.Collection.codec_options` and :meth:`~pymongo.database.Database.command` raising a superfluous DeprecationWarning.

Issues Resolved

See the PyMongo 2.9.2 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.9.1

Version 2.9.1 fixes two interrupt handling issues in the C extensions and adapts a test case for a behavior change in MongoDB 3.2.

Issues Resolved

See the PyMongo 2.9.1 release notes in JIRA for the list of resolved issues in this release.

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 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.

:class:`~pymongo.mongo_client.MongoClient`:
:class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient`:
:class:`~pymongo.database.Database`:
:class:`~pymongo.collection.Collection`:

Warning

In previous versions of PyMongo, changing the value of :attr:`~pymongo.mongo_client.MongoClient.document_class` changed the behavior of all existing instances of :class:`~pymongo.collection.Collection`:

>>> coll = client.test.test
>>> coll.find_one()
{u'_id': ObjectId('5579dc7cfba5220cc14d9a18')}
>>> from bson.son import SON
>>> client.document_class = SON
>>> coll.find_one()
SON([(u'_id', ObjectId('5579dc7cfba5220cc14d9a18'))])

The document_class setting is now configurable at the client, database, collection, and per-operation level. This required breaking the existing behavior. To change the document class per operation in a forward compatible way use :meth:`~pymongo.collection.Collection.with_options`:

>>> coll.find_one()
{u'_id': ObjectId('5579dc7cfba5220cc14d9a18')}
>>> from bson.codec_options import CodecOptions
>>> coll.with_options(CodecOptions(SON)).find_one()
SON([(u'_id', ObjectId('5579dc7cfba5220cc14d9a18'))])

Issues Resolved

See the PyMongo 2.9 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.8.1

Version 2.8.1 fixes a number of issues reported since the release of PyMongo 2.8. It is a recommended upgrade for all users of PyMongo 2.x.

Issues Resolved

See the PyMongo 2.8.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.8

Version 2.8 is a major release that provides full support for MongoDB 3.0 and fixes a number of bugs.

Special thanks to Don Mitchell, Ximing, Can Zhang, Sergey Azovskov, and Heewa Barfchin for their contributions to this release.

Highlights include:

Note

There are a number of deprecations in this release for features that will be removed in PyMongo 3.0. These include:

The JSON format for :class:`~bson.timestamp.Timestamp` has changed from '{"t": <int>, "i": <int>}' to '{"$timestamp": {"t": <int>, "i": <int>}}'. This new format will be decoded to an instance of :class:`~bson.timestamp.Timestamp`. The old format will continue to be decoded to a python dict as before. Encoding to the old format is no longer supported as it was never correct and loses type information.

Issues Resolved

See the PyMongo 2.8 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.7.2

Version 2.7.2 includes fixes for upsert reporting in the bulk API for MongoDB versions previous to 2.6, a regression in how son manipulators are applied in :meth:`~pymongo.collection.Collection.insert`, a few obscure connection pool semaphore leaks, and a few other minor issues. See the list of issues resolved for full details.

Issues Resolved

See the PyMongo 2.7.2 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.7.1

Version 2.7.1 fixes a number of issues reported since the release of 2.7, most importantly a fix for creating indexes and manipulating users through mongos versions older than 2.4.0.

Issues Resolved

See the PyMongo 2.7.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.7

PyMongo 2.7 is a major release with a large number of new features and bug fixes. Highlights include:

Breaking changes

Version 2.7 drops support for replica sets running MongoDB versions older than 1.6.2.

Issues Resolved

See the PyMongo 2.7 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.6.3

Version 2.6.3 fixes issues reported since the release of 2.6.2, most importantly a semaphore leak when a connection to the server fails.

Issues Resolved

See the PyMongo 2.6.3 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.6.2

Version 2.6.2 fixes a :exc:`TypeError` problem when max_pool_size=None is used in Python 3.

Issues Resolved

See the PyMongo 2.6.2 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.6.1

Version 2.6.1 fixes a reference leak in the :meth:`~pymongo.collection.Collection.insert` method.

Issues Resolved

See the PyMongo 2.6.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.6

Version 2.6 includes some frequently requested improvements and adds support for some early MongoDB 2.6 features.

Special thanks go to Justin Patrin for his work on the connection pool in this release.

Important new features:

Warning

SIGNIFICANT BEHAVIOR CHANGE in 2.6. Previously, max_pool_size would limit only the idle sockets the pool would hold onto, not the number of open sockets. The default has also changed, from 10 to 100. If you pass a value for max_pool_size make sure it is large enough for the expected load. (Sockets are only opened when needed, so there is no cost to having a max_pool_size larger than necessary. Err towards a larger value.) If your application accepts the default, continue to do so.

See :ref:`connection-pooling` for more information.

Issues Resolved

See the PyMongo 2.6 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.5.2

Version 2.5.2 fixes a NULL pointer dereference issue when decoding an invalid :class:`~bson.dbref.DBRef`.

Issues Resolved

See the PyMongo 2.5.2 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.5.1

Version 2.5.1 is a minor release that fixes issues discovered after the release of 2.5. Most importantly, this release addresses some race conditions in replica set monitoring.

Issues Resolved

See the PyMongo 2.5.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.5

Version 2.5 includes changes to support new features in MongoDB 2.4.

Important new features:

Note

:meth:`~pymongo.database.Database.authenticate` now raises a subclass of :class:`~pymongo.errors.PyMongoError` if authentication fails due to invalid credentials or configuration issues.

Issues Resolved

See the PyMongo 2.5 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.4.2

Version 2.4.2 is a minor release that fixes issues discovered after the release of 2.4.1. Most importantly, PyMongo will no longer select a replica set member for read operations that is not in primary or secondary state.

Issues Resolved

See the PyMongo 2.4.2 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.4.1

Version 2.4.1 is a minor release that fixes issues discovered after the release of 2.4. Most importantly, this release fixes a regression using :meth:`~pymongo.collection.Collection.aggregate`, and possibly other commands, with mongos.

Issues Resolved

See the PyMongo 2.4.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.4

Version 2.4 includes a few important new features and a large number of bug fixes.

Important new features:

Issues Resolved

See the PyMongo 2.4 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.3

Version 2.3 adds support for new features and behavior changes in MongoDB 2.2.

Important New Features:

Warning

Starting with MongoDB 2.2 the getLastError command requires authentication when the server's authentication features are enabled. Changes to PyMongo were required to support this behavior change. Users of authentication must upgrade to PyMongo 2.3 (or newer) for "safe" write operations to function correctly.

Issues Resolved

See the PyMongo 2.3 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.2.1

Version 2.2.1 is a minor release that fixes issues discovered after the release of 2.2. Most importantly, this release fixes an incompatibility with mod_wsgi 2.x that could cause connections to leak. Users of mod_wsgi 2.x are strongly encouraged to upgrade from PyMongo 2.2.

Issues Resolved

See the PyMongo 2.2.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.2

Version 2.2 adds a few more frequently requested features and fixes a number of bugs.

Special thanks go to Alex Grönholm for his contributions to Python 3 support and maintaining the original pymongo3 port. Christoph Simon, Wouter Bolsterlee, Mike O'Brien, and Chris Tompkinson also contributed to this release.

Important New Features:

Warning

A number of methods and method parameters that were deprecated in PyMongo 1.9 or older versions have been removed in this release. The full list of changes can be found in the following JIRA ticket:

https://jira.mongodb.org/browse/PYTHON-305

BSON module aliases from the pymongo package that were deprecated in PyMongo 1.9 have also been removed in this release. See the following JIRA ticket for details:

https://jira.mongodb.org/browse/PYTHON-304

As a result of this cleanup some minor code changes may be required to use this release.

Issues Resolved

See the PyMongo 2.2 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.1.1

Version 2.1.1 is a minor release that fixes a few issues discovered after the release of 2.1. You can now use :class:`~pymongo.replica_set_connection.ReplicaSetConnection` to run inline map reduce commands on secondaries. See :meth:`~pymongo.collection.Collection.inline_map_reduce` for details.

Special thanks go to Samuel Clay and Ross Lawley for their contributions to this release.

Issues Resolved

See the PyMongo 2.1.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.1

Version 2.1 adds a few frequently requested features and includes the usual round of bug fixes and improvements.

Special thanks go to Alexey Borzenkov, Dan Crosta, Kostya Rybnikov, Flavio Percoco Premoli, Jonas Haag, and Jesse Davis for their contributions to this release.

Important New Features:

Issues Resolved

See the PyMongo 2.1 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 2.0.1

Version 2.0.1 fixes a regression in :class:`~gridfs.grid_file.GridIn` when writing pre-chunked strings. Thanks go to Alexey Borzenkov for reporting the issue and submitting a patch.

Issues Resolved

  • PYTHON-271: Regression in GridFS leads to serious loss of data.

Changes in Version 2.0

Version 2.0 adds a large number of features and fixes a number of issues.

Special thanks go to James Murty, Abhay Vardhan, David Pisoni, Ryan Smith-Roberts, Andrew Pendleton, Mher Movsisyan, Reed O'Brien, Michael Schurter, Josip Delic and Jonas Haag for their contributions to this release.

Important New Features:

  • PyMongo now performs automatic per-socket database authentication. You no longer have to re-authenticate for each new thread or after a replica set failover. Authentication credentials are cached by the driver until the application calls :meth:`~pymongo.database.Database.logout`.
  • slave_okay can be set independently at the connection, database, collection or query level. Each level will inherit the slave_okay setting from the previous level and each level can override the previous level's setting.
  • safe and getLastError options (e.g. w, wtimeout, etc.) can be set independently at the connection, database, collection or query level. Each level will inherit settings from the previous level and each level can override the previous level's setting.
  • PyMongo now supports the await_data and partial cursor flags. If the await_data flag is set on a tailable cursor the server will block for some extra time waiting for more data to return. The partial flag tells a mongos to return partial data for a query if not all shards are available.
  • :meth:`~pymongo.collection.Collection.map_reduce` will accept a dict or instance of :class:`~bson.son.SON` as the out parameter.
  • The URI parser has been moved into its own module and can be used directly by application code.
  • AutoReconnect exception now provides information about the error that actually occured instead of a generic failure message.
  • A number of new helper methods have been added with options for setting and unsetting cursor flags, re-indexing a collection, fsync and locking a server, and getting the server's current operations.

API changes:

  • If only one host:port pair is specified :class:`~pymongo.connection.Connection` will make a direct connection to only that host. Please note that slave_okay must be True in order to query from a secondary.
  • If more than one host:port pair is specified or the replicaset option is used PyMongo will treat the specified host:port pair(s) as a seed list and connect using replica set behavior.

Issues Resolved

See the PyMongo 2.0 release notes in JIRA for the list of resolved issues in this release.

Changes in Version 1.11

Version 1.11 adds a few new features and fixes a few more bugs.

New Features:

API changes:

  • :meth:`~pymongo.database.Database.validate_collection` now returns a dict instead of a string. This change was required to deal with an API change on the server. This method also now takes the optional scandata and full parameters. See the documentation for more details.

Warning

The pool_size, auto_start_request, and timeout parameters for :class:`~pymongo.connection.Connection` have been completely removed in this release. They were deprecated in pymongo-1.4 and have had no effect since then. Please make sure that your code doesn't currently pass these parameters when creating a Connection instance.

Issues resolved

  • PYTHON-241: Support setting slaveok at the cursor level.
  • PYTHON-240: Queries can sometimes permanently fail after a replica set fail over.
  • PYTHON-238: error after few million requests
  • PYTHON-237: Basic IPv6 support.
  • PYTHON-236: Restore option to specify pool size in Connection.
  • PYTHON-212: pymongo does not recover after stale config
  • PYTHON-138: Find method for GridFS

Changes in Version 1.10.1

Version 1.10.1 is primarily a bugfix release. It fixes a regression in version 1.10 that broke pickling of ObjectIds. A number of other bugs have been fixed as well.

There are two behavior changes to be aware of:

Issues resolved

  • PYTHON-234: Fix setup.py to raise exception if any when building extensions
  • PYTHON-233: Add information to build and test with extensions on windows
  • PYTHON-232: Traceback when hashing a DBRef instance
  • PYTHON-231: Traceback when pickling a DBRef instance
  • PYTHON-230: Pickled ObjectIds are not compatible between pymongo 1.9 and 1.10
  • PYTHON-228: Cannot pickle bson.ObjectId
  • PYTHON-227: Traceback when calling find() on system.js
  • PYTHON-216: MasterSlaveConnection is missing disconnect() method
  • PYTHON-186: When storing integers, type is selected according to value instead of type
  • PYTHON-173: as_class option is not propogated by Cursor.clone
  • PYTHON-113: Redunducy in MasterSlaveConnection

Changes in Version 1.10

Version 1.10 includes changes to support new features in MongoDB 1.8.x. Highlights include a modified map/reduce API including an inline map/reduce helper method, a new find_and_modify helper, and the ability to query the server for the maximum BSON document size it supports.

Warning

MongoDB versions greater than 1.7.4 no longer generate temporary collections for map/reduce results. An output collection name must be provided and the output will replace any existing output collection with the same name. :meth:`~pymongo.collection.Collection.map_reduce` now requires the out parameter.

Issues resolved

  • PYTHON-225: :class:`~pymongo.objectid.ObjectId` class definition should use __slots__.
  • PYTHON-223: Documentation fix.
  • PYTHON-220: Documentation fix.
  • PYTHON-219: KeyError in :meth:`~pymongo.collection.Collection.find_and_modify`
  • PYTHON-213: Query server for maximum BSON document size.
  • PYTHON-208: Fix :class:`~pymongo.connection.Connection` __repr__.
  • PYTHON-207: Changes to Map/Reduce API.
  • PYTHON-205: Accept slaveOk in the URI to match the URI docs.
  • PYTHON-203: When slave_okay=True and we only specify one host don't autodetect other set members.
  • PYTHON-194: Show size when whining about a document being too large.
  • PYTHON-184: Raise :class:`~pymongo.errors.DuplicateKeyError` for duplicate keys in capped collections.
  • PYTHON-178: Don't segfault when trying to encode a recursive data structure.
  • PYTHON-177: Don't segfault when decoding dicts with broken iterators.
  • PYTHON-172: Fix a typo.
  • PYTHON-170: Add :meth:`~pymongo.collection.Collection.find_and_modify`.
  • PYTHON-169: Support deepcopy of DBRef.
  • PYTHON-167: Duplicate of PYTHON-166.
  • PYTHON-166: Fixes a concurrency issue.
  • PYTHON-158: Add code and err string to db assertion messages.

Changes in Version 1.9

Version 1.9 adds a new package to the PyMongo distribution, :mod:`bson`. :mod:`bson` contains all of the BSON encoding and decoding logic, and the BSON types that were formerly in the :mod:`pymongo` package. The following modules have been renamed:

In addition, the following exception classes have been renamed:

The above exceptions now inherit from :class:`bson.errors.BSONError` rather than :class:`pymongo.errors.PyMongoError`.

Note

All of the renamed modules and exceptions above have aliases created with the old names, so these changes should not break existing code. The old names will eventually be deprecated and then removed, so users should begin migrating towards the new names now.

Warning

The change to the exception hierarchy mentioned above is possibly breaking. If your code is catching :class:`~pymongo.errors.PyMongoError`, then the exceptions raised by :mod:`bson` will not be caught, even though they would have been caught previously. Before upgrading, it is recommended that users check for any cases like this.

Changes in Version 1.8.1

Changes in Version 1.8

Version 1.8 adds support for connecting to replica sets, specifying per-operation values for w and wtimeout, and decoding to timezone-aware datetimes.

Changes in Version 1.7

Version 1.7 is a recommended upgrade for all PyMongo users. The full release notes are below, and some more in depth discussion of the highlights is here.

Changes in Version 1.6

The biggest change in version 1.6 is a complete re-implementation of :mod:`gridfs` with a lot of improvements over the old implementation. There are many details and examples of using the new API in this blog post. The old API has been removed in this version, so existing code will need to be modified before upgrading to 1.6.

Changes in Version 1.5.2

  • fixed response handling to ignore unknown response flags in queries.
  • handle server versions containing '-pre-'.

Changes in Version 1.5.1

Changes in Version 1.5

Changes in Version 1.4

Perhaps the most important change in version 1.4 is that we have decided to no longer support Python 2.3. The most immediate reason for this is to allow some improvements to connection pooling. This will also allow us to use some new (as in Python 2.4 ;) idioms and will help begin the path towards supporting Python 3.0. If you need to use Python 2.3 you should consider using version 1.3 of this driver, although that will no longer be actively supported.

Other changes:

Changes in Version 1.3

Changes in Version 1.2.1

Changes in Version 1.2

Changes in Version 1.1.2

Changes in Version 1.1.1

Changes in Version 1.1

Changes in Version 1.0

Changes in Version 0.16

Changes in Version 0.15.2

  • documentation changes only

Changes in Version 0.15.1

Changes in Version 0.15

Changes in Version 0.14.2

  • minor bugfixes

Changes in Version 0.14.1

Changes in Version 0.14

Changes in Version 0.13

Changes in Version 0.12

Changes in Version 0.11.3

  • don't allow NULL bytes in string encoder
  • fixes for Python 2.3

Changes in Version 0.11.2

Changes in Version 0.11.1

  • fix for connection pooling under Python 2.5

Changes in Version 0.11

  • better build failure detection
  • driver support for selecting fields in sub-documents
  • disallow insertion of invalid key names
  • added timeout parameter for :meth:`~pymongo.connection.Connection`

Changes in Version 0.10.3

Changes in Version 0.10.2

Changes in Version 0.10.1

Changes in Version 0.10

Changes in Version 0.9.7

.. toctree::
   :hidden:

   python3
   examples/gevent