Version 3.2.1 fixes a few issues reported since the release of 3.2, including running the mapreduce command twice when calling the inline_map_reduce() method and a TypeError being raised when calling download_to_stream(). This release also improves error messaging around BSON decoding.
See the PyMongo 3.2.1 release notes in JIRA for the list of resolved issues in this release.
Version 3.2 implements the new server features introduced in MongoDB 3.2.
Highlights include:
Note
Certain MongoClient properties now block until a connection is established or raise ServerSelectionTimeoutError if no server is available. See MongoClient for details.
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.
See the PyMongo 3.1.1 release notes in JIRA for the list of resolved issues in this release.
Version 3.1 implements a few new features and fixes bugs reported since the release of 3.0.3.
Highlights include:
The private PeriodicExecutor class no longer takes a condition_class option, and the private thread_util.Event class is removed.
See the PyMongo 3.1 release notes in JIRA for the list of resolved issues in this release.
Version 3.0.3 fixes issues reported since the release of 3.0.2, including a feature breaking bug in the GSSAPI implementation.
See the PyMongo 3.0.3 release notes in JIRA for the list of resolved issues in this release.
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 PrimaryPreferred or Nearest. It is a recommended upgrade for all users of PyMongo 3.0.x.
See the PyMongo 3.0.2 release notes in JIRA for the list of resolved issues in this release.
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.
See the PyMongo 3.0.1 release notes in JIRA for the list of resolved issues in this release.
PyMongo 3.0 is a partial rewrite of PyMongo bringing a large number of improvements:
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.
The 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 add_son_manipulator() method is deprecated. PyMongo 3’s new CRUD API does not apply SON manipulators to documents passed to bulk_write(), insert_one(), insert_many(), update_one(), or update_many(). SON manipulators are not applied to documents returned by the new methods find_one_and_delete(), find_one_and_replace(), and find_one_and_update().
When ssl is True the ssl_cert_reqs option now defaults to ssl.CERT_REQUIRED if not provided. PyMongo will attempt to load OS provided CA certificates to verify the server, raising ConfigurationError if it cannot.
In previous versions, PyMongo supported Gevent in two modes: you could call gevent.monkey.patch_socket() and pass use_greenlets=True to 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 PyMongo’s Gevent documentation.
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. MongoClient now also supports the full ReadPreference API.
The obsolete classes MasterSlaveConnection, Connection, and ReplicaSetConnection are removed.
The MongoClient constructor no longer blocks while connecting to the server or servers, and it no longer raises ConnectionFailure if they are unavailable, nor 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, 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 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 read preference of PRIMARY.
Support for the slaveOk (or slave_okay), safe, and network_timeout options has been removed. Use 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 copy_database examples for alternatives.
The disconnect method is removed. Use close() instead.
The get_document_class method is removed. Use codec_options instead.
The get_lasterror_options, set_lasterror_options, and unset_lasterror_options methods are removed. Write concern options can be passed to MongoClient as keyword arguments or MongoDB URI options.
The 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:
CursorManager and set_cursor_manager() are no longer deprecated. If you subclass CursorManager your implementation of close() must now take a second parameter, address. The BatchCursorManager class is removed.
The second parameter to close_cursor() is renamed from _conn_id to address. kill_cursors() now accepts an address parameter.
The connection property is renamed to client.
The following read-only attributes have been added:
The following attributes are now read-only:
Use 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 WriteConcern with get_database() instead.
The following read-only attributes have been added:
The following attributes are now read-only:
Use get_collection() or 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 WriteConcern with with_options() instead.
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.
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:
The following renames need special handling.
Since PyMongo 1.6, methods open and close of GridFS raised an UnsupportedAPI exception, as did the entire GridFile class. The unsupported methods, the class, and the exception are all deleted.
The compile_re option is removed from all methods that accepted it in bson and json_util. Additionally, it is removed from find(), find_one(), aggregate(), command(), and so on. PyMongo now always represents BSON regular expressions as Regex objects. This prevents errors for incompatible patterns, see PYTHON-500. Use 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 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 Int64.
The as_class, tz_aware, and uuid_subtype options are removed from all BSON encoding and decoding methods. Use 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.
See the PyMongo 3.0 release notes in JIRA for the list of resolved issues in this release.
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 aggregate() ignoring codec_options and command() raising a superfluous DeprecationWarning.
See the PyMongo 2.9.2 release notes in JIRA for the list of resolved issues in this release.
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.
See the PyMongo 2.9.1 release notes in JIRA for the list of resolved issues in this release.
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.
Warning
In previous versions of PyMongo, changing the value of document_class changed the behavior of all existing instances of 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 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'))])
See the PyMongo 2.9 release notes in JIRA for the list of resolved issues in this release.
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.
See the PyMongo 2.8.1 release notes in JIRA for the list of resolved issues in this release.
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 Timestamp has changed from ‘{“t”: <int>, “i”: <int>}’ to ‘{“$timestamp”: {“t”: <int>, “i”: <int>}}’. This new format will be decoded to an instance of 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.
See the PyMongo 2.8 release notes in JIRA for the list of resolved issues in this release.
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 insert(), a few obscure connection pool semaphore leaks, and a few other minor issues. See the list of issues resolved for full details.
See the PyMongo 2.7.2 release notes in JIRA for the list of resolved issues in this release.
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.
See the PyMongo 2.7.1 release notes in JIRA for the list of resolved issues in this release.
PyMongo 2.7 is a major release with a large number of new features and bug fixes. Highlights include:
Version 2.7 drops support for replica sets running MongoDB versions older than 1.6.2.
See the PyMongo 2.7 release notes in JIRA for the list of resolved issues in this release.
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.
See the PyMongo 2.6.3 release notes in JIRA for the list of resolved issues in this release.
Version 2.6.2 fixes a TypeError problem when max_pool_size=None is used in Python 3.
See the PyMongo 2.6.2 release notes in JIRA for the list of resolved issues in this release.
Version 2.6.1 fixes a reference leak in the insert() method.
See the PyMongo 2.6.1 release notes in JIRA for the list of resolved issues in this release.
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 How does connection pooling work in PyMongo? for more information.
See the PyMongo 2.6 release notes in JIRA for the list of resolved issues in this release.
Version 2.5.2 fixes a NULL pointer dereference issue when decoding an invalid DBRef.
See the PyMongo 2.5.2 release notes in JIRA for the list of resolved issues in this release.
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.
See the PyMongo 2.5.1 release notes in JIRA for the list of resolved issues in this release.
Version 2.5 includes changes to support new features in MongoDB 2.4.
Important new features:
Note
authenticate() now raises a subclass of PyMongoError if authentication fails due to invalid credentials or configuration issues.
See the PyMongo 2.5 release notes in JIRA for the list of resolved issues in this release.
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.
See the PyMongo 2.4.2 release notes in JIRA for the list of resolved issues in this release.
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 aggregate(), and possibly other commands, with mongos.
See the PyMongo 2.4.1 release notes in JIRA for the list of resolved issues in this release.
Version 2.4 includes a few important new features and a large number of bug fixes.
Important new features:
Warning
The constructors for MongoClient, MongoReplicaSetClient, Connection, and ReplicaSetConnection now raise ConnectionFailure instead of its subclass AutoReconnect if the server is unavailable. Applications that expect to catch AutoReconnect should now catch ConnectionFailure while creating a new connection.
See the PyMongo 2.4 release notes in JIRA for the list of resolved issues in this release.
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.
See the PyMongo 2.3 release notes in JIRA for the list of resolved issues in this release.
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.
See the PyMongo 2.2.1 release notes in JIRA for the list of resolved issues in this release.
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.
See the PyMongo 2.2 release notes in JIRA for the list of resolved issues in this release.
Version 2.1.1 is a minor release that fixes a few issues discovered after the release of 2.1. You can now use ReplicaSetConnection to run inline map reduce commands on secondaries. See inline_map_reduce() for details.
Special thanks go to Samuel Clay and Ross Lawley for their contributions to this release.
See the PyMongo 2.1.1 release notes in JIRA for the list of resolved issues in this release.
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:
See the PyMongo 2.1 release notes in JIRA for the list of resolved issues in this release.
Version 2.0.1 fixes a regression in GridIn when writing pre-chunked strings. Thanks go to Alexey Borzenkov for reporting the issue and submitting a patch.
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:
API changes:
Warning
The default subtype for Binary has changed from OLD_BINARY_SUBTYPE (2) to BINARY_SUBTYPE (0).
See the PyMongo 2.0 release notes in JIRA for the list of resolved issues in this release.
Version 1.11 adds a few new features and fixes a few more bugs.
New Features:
API changes:
Warning
The pool_size, auto_start_request, and timeout parameters for 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.
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:
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. map_reduce() now requires the out parameter.
Version 1.9 adds a new package to the PyMongo distribution, bson. bson contains all of the BSON encoding and decoding logic, and the BSON types that were formerly in the pymongo package. The following modules have been renamed:
- pymongo.bson -> bson
- pymongo._cbson -> bson._cbson and pymongo._cmessage
- pymongo.binary -> bson.binary
- pymongo.code -> bson.code
- pymongo.dbref -> bson.dbref
- pymongo.json_util -> bson.json_util
- pymongo.max_key -> bson.max_key
- pymongo.min_key -> bson.min_key
- pymongo.objectid -> bson.objectid
- pymongo.son -> bson.son
- pymongo.timestamp -> bson.timestamp
- pymongo.tz_util -> bson.tz_util
In addition, the following exception classes have been renamed:
- pymongo.errors.InvalidBSON -> bson.errors.InvalidBSON
- pymongo.errors.InvalidStringData -> bson.errors.InvalidStringData
- pymongo.errors.InvalidDocument -> bson.errors.InvalidDocument
- pymongo.errors.InvalidId -> bson.errors.InvalidId
The above exceptions now inherit from bson.errors.BSONError rather than 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 PyMongoError, then the exceptions raised by 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.
Version 1.8 adds support for connecting to replica sets, specifying per-operation values for w and wtimeout, and decoding to timezone-aware datetimes.
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.
The biggest change in version 1.6 is a complete re-implementation of 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.
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: