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.
- Added support for MongoDB 5.0.
- Support for MongoDB Versioned API, see
~pymongo.server_api.ServerApi
. - Support for snapshot reads on secondaries (see
snapshot-reads-ref
). - Support for Azure and GCP KMS providers for client side field level encryption. See the docstring for
~pymongo.mongo_client.MongoClient
,~pymongo.encryption_options.AutoEncryptionOpts
, and~pymongo.encryption
. - Support AWS authentication with temporary credentials when connecting to KMS in client side field level encryption.
- Support for connecting to load balanced MongoDB clusters via the new
loadBalanced
URI option. - Support for creating timeseries collections via the
timeseries
andexpireAfterSeconds
arguments to~pymongo.database.Database.create_collection
. - Added
pymongo.mongo_client.MongoClient.topology_description
. - Added hash support to
~pymongo.mongo_client.MongoClient
,~pymongo.database.Database
and~pymongo.collection.Collection
(PYTHON-2466). - Improved the error message returned by
~pymongo.collection.Collection.insert_many
when supplied with an argument of incorrect type (PYTHON-1690). - Added session and read concern support to
~pymongo.collection.Collection.find_raw_batches
and~pymongo.collection.Collection.aggregate_raw_batches
.
- 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
~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
~pymongo.cursor.RawBatchCursor
that caused it to return an empty bytestring when the cursor contained no results. It now raisesStopIteration
instead.
- Deprecated support for Python 2.7, 3.4 and 3.5.
- Deprecated support for database profiler helpers
~pymongo.database.Database.profiling_level
,~pymongo.database.Database.set_profiling_level
, and~pymongo.database.Database.profiling_info
. Instead, users should run the profile command with the~pymongo.database.Database.command
helper directly. - Deprecated
~pymongo.errors.NotMasterError
. Users should use~pymongo.errors.NotPrimaryError
instead. - Deprecated
~pymongo.ismaster.IsMaster
and~pymongo.ismaster
which will be removed in PyMongo 4.0 and are replaced by~pymongo.hello.Hello
and~pymongo.hello
which provide the same API. - Deprecated the
pymongo.messeage
module. - Deprecated the
ssl_keyfile
andssl_certfile
URI options in favor oftlsCertificateKeyFile
(seeexamples/tls
).
See the PyMongo 3.12.0 release notes in JIRA for the list of resolved issues in this release.
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.
Version 3.11.2 includes a number of bugfixes. Highlights include:
- Fixed a memory leak caused by failing SDAM monitor checks on Python 3 (PYTHON-2433).
- Fixed a regression that changed the string representation of
~pymongo.errors.BulkWriteError
(PYTHON-2438). - Fixed a bug that made it impossible to use
bson.codec_options.CodecOptions.with_options
and~bson.json_util.JSONOptions.with_options
on some early versions of Python 3.4 and Python 3.5 due to a bug in the standard library implementation ofcollections.namedtuple._asdict
(PYTHON-2440). - Fixed a bug that resulted in a
TypeError
exception when a PyOpenSSL socket was configured with a timeout ofNone
(PYTHON-2443).
See the PyMongo 3.11.2 release notes in JIRA for the list of resolved issues in this release.
Version 3.11.1 adds support for Python 3.9 and includes a number of bugfixes. Highlights include:
- Support for Python 3.9.
- Initial support for Azure and GCP KMS providers for client side field level encryption is in beta. See the docstring for
~pymongo.mongo_client.MongoClient
,~pymongo.encryption_options.AutoEncryptionOpts
, and~pymongo.encryption
. Note: Backwards-breaking changes may be made before the final release. - Fixed a bug where the
bson.json_util.JSONOptions
API did not match thebson.codec_options.CodecOptions
API due to the absence of abson.json_util.JSONOptions.with_options
method. This method has now been added. - Fixed a bug which made it impossible to serialize
~pymongo.errors.BulkWriteError
instances usingpickle
. - Fixed a bug wherein PyMongo did not always discard an implicit session after encountering a network error.
- Fixed a bug where connections created in the background were not authenticated.
- Fixed a memory leak in the
bson
module when using a~bson.codec_options.TypeRegistry
.
See the PyMongo 3.11.1 release notes in JIRA for the list of resolved issues in this release.
Version 3.11 adds support for MongoDB 4.4 and includes a number of bug fixes. Highlights include:
- Support for
OCSP
(Online Certificate Status Protocol). - Support for PyOpenSSL as an alternative TLS implementation. PyOpenSSL is required for
OCSP
support. It will also be installed when using the "tls" extra if the version of Python in use is older than 2.7.9. - Support for the
MONGODB-AWS
authentication mechanism. - Support for the
directConnection
URI option and kwarg to~pymongo.mongo_client.MongoClient
. - Support for speculative authentication attempts in connection handshakes which reduces the number of network roundtrips needed to authenticate new connections on MongoDB 4.4+.
- Support for creating collections in multi-document transactions with
~pymongo.database.Database.create_collection
on MongoDB 4.4+. - Added index hinting support to the
~pymongo.collection.Collection.replace_one
,~pymongo.collection.Collection.update_one
,~pymongo.collection.Collection.update_many
,~pymongo.collection.Collection.find_one_and_replace
,~pymongo.collection.Collection.find_one_and_update
,~pymongo.collection.Collection.delete_one
,~pymongo.collection.Collection.delete_many
, and~pymongo.collection.Collection.find_one_and_delete
commands. - Added index hinting support to the
~pymongo.operations.ReplaceOne
,~pymongo.operations.UpdateOne
,~pymongo.operations.UpdateMany
,~pymongo.operations.DeleteOne
, and~pymongo.operations.DeleteMany
bulk operations. - Added support for
bson.binary.UuidRepresentation.UNSPECIFIED
andMongoClient(uuidRepresentation='unspecified')
which will become the default UUID representation starting in PyMongo 4.0. Seehandling-uuid-data-example
for details. - Added the
background
parameter topymongo.database.Database.validate_collection
. For a description of this parameter see the MongoDB documentation for the validate command. - Added the
allow_disk_use
parameters topymongo.collection.Collection.find
. - Added the
hedge
parameter to~pymongo.read_preferences.PrimaryPreferred
,~pymongo.read_preferences.Secondary
,~pymongo.read_preferences.SecondaryPreferred
,~pymongo.read_preferences.Nearest
to support disabling (or explicitly enabling) hedged reads in MongoDB 4.4+. - Fixed a bug in change streams that could cause PyMongo to miss some change documents when resuming a stream that was started without a resume token and whose first batch did not contain any change documents.
- Fixed an bug where using gevent.Timeout to timeout an operation could lead to a deadlock.
Deprecations:
- Deprecated the
oplog_replay
parameter topymongo.collection.Collection.find
. Starting in MongoDB 4.4, the server optimizes queries against the oplog collection without requiring the user to set this flag. - Deprecated
pymongo.collection.Collection.reindex
. Use~pymongo.database.Database.command
to run thereIndex
command instead. - Deprecated
pymongo.mongo_client.MongoClient.fsync
. Use~pymongo.database.Database.command
to run thefsync
command instead. - Deprecated
pymongo.mongo_client.MongoClient.unlock
. Use~pymongo.database.Database.command
to run thefsyncUnlock
command instead. See the documentation for more information. - Deprecated
pymongo.mongo_client.MongoClient.is_locked
. Use~pymongo.database.Database.command
to run thecurrentOp
command instead. See the documentation for more information.
Unavoidable breaking changes:
~gridfs.GridFSBucket
and~gridfs.GridFS
do not support multi-document transactions. Running a GridFS operation in a transaction now always raises the following error:InvalidOperation: GridFS does not support multi-document transactions
See the PyMongo 3.11.0 release notes in JIRA for the list of resolved issues in this release.
Version 3.10.1 fixes the following issues discovered since the release of 3.10.0:
- Fix a TypeError logged to stderr that could be triggered during server maintenance or during
pymongo.mongo_client.MongoClient.close
. - Avoid creating new connections during
pymongo.mongo_client.MongoClient.close
.
See the PyMongo 3.10.1 release notes in JIRA for the list of resolved issues in this release.
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
examples/encryption
for examples. - Support for Python 3.8.
- Added
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.
See the PyMongo 3.10 release notes in JIRA for the list of resolved issues in this release.
Version 3.9 adds support for MongoDB 4.2. Highlights include:
- Support for MongoDB 4.2 sharded transactions. Sharded transactions have the same API as replica set transactions. See
transactions-ref
. - New method
pymongo.client_session.ClientSession.with_transaction
to support conveniently running a transaction in a session with automatic retries and at-most-once semantics. - Initial support for client side field level encryption. See the docstring for
~pymongo.mongo_client.MongoClient
,~pymongo.encryption_options.AutoEncryptionOpts
, and~pymongo.encryption
for details. Note: Support for client side encryption is in beta. Backwards-breaking changes may be made before the final release. - Added the
max_commit_time_ms
parameter to~pymongo.client_session.ClientSession.start_transaction
. Implement the URI options specification in the
~pymongo.mongo_client.MongoClient
constructor. Consequently, there are a number of changes in connection options:- The
tlsInsecure
option has been added. - The
tls
option has been added. The olderssl
option has been retained as an alias to the newtls
option. wTimeout
has been deprecated in favor ofwTimeoutMS
.wTimeoutMS
now overrideswTimeout
if the user provides both.j
has been deprecated in favor ofjournal
.journal
now overridesj
if the user provides both.ssl_cert_reqs
has been deprecated in favor oftlsAllowInvalidCertificates
. Instead ofssl.CERT_NONE
,ssl.CERT_OPTIONAL
andssl.CERT_REQUIRED
, the new option expects a boolean value -True
is equivalent tossl.CERT_NONE
, whileFalse
is equivalent tossl.CERT_REQUIRED
.ssl_match_hostname
has been deprecated in favor oftlsAllowInvalidHostnames
.ssl_ca_certs
has been deprecated in favor oftlsCAFile
.ssl_certfile
has been deprecated in favor oftlsCertificateKeyFile
.ssl_pem_passphrase
has been deprecated in favor oftlsCertificateKeyFilePassword
.waitQueueMultiple
has been deprecated without replacement. This option was a poor solution for putting an upper bound on queuing since it didn't affect queuing in other parts of the driver.
- The
- The
retryWrites
URI option now defaults toTrue
. 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~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
pymongo.database.Database.aggregate
to support running database level aggregations. - Support for publishing Connection Monitoring and Pooling events via the new
~pymongo.monitoring.ConnectionPoolListener
class. See~pymongo.monitoring
for an example. pymongo.collection.Collection.aggregate
andpymongo.database.Database.aggregate
now support the$merge
pipeline stage and use read preference~pymongo.read_preferences.ReadPreference.PRIMARY
if the$out
or$merge
pipeline stages are used.- Support for specifying a pipeline or document in
~pymongo.collection.Collection.update_one
,~pymongo.collection.Collection.update_many
,~pymongo.collection.Collection.find_one_and_update
,~pymongo.operations.UpdateOne
, and~pymongo.operations.UpdateMany
. - New BSON utility functions
~bson.encode
and~bson.decode
~bson.binary.Binary
now supports any bytes-like type that implements the buffer protocol.- Resume tokens can now be accessed from a
ChangeStream
cursor using the~pymongo.change_stream.ChangeStream.resume_token
attribute. - Connections now survive primary step-down when using MongoDB 4.2+. Applications should expect less socket connection turnover during replica set elections.
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~pymongo.mongo_client.MongoClient
constructor's keyword argument (e.g.MongoClient("mongodb://my.mongodb.cluster/db", retryWrites=False)
) to avoid running into~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 amongodb+srv://
connection string, the minimum required version of the optionaldnspython
dependency has been bumped to 1.16.0. This is a breaking change for applications that use PyMongo's SRV support with a version ofdnspython
older than 1.16.0.
See the PyMongo 3.9 release notes in JIRA for the list of resolved issues in this release.
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+.
~bson.objectid.ObjectId
now implements the ObjectID specification version 0.2.- For better performance and to better follow the GridFS spec,
~gridfs.grid_file.GridOut
now uses a single cursor to read all the chunks in the file. Previously, each chunk in the file was queried individually using~pymongo.collection.Collection.find_one
. gridfs.grid_file.GridOut.read
now only checks for extra chunks after reading the entire file. Previously, this method would check for extra chunks on every call.~pymongo.database.Database.current_op
now always uses theDatabase
's~pymongo.database.Database.codec_options
when decoding the command response. Previously the codec_options was only used when the MongoDB server version was <= 3.0.- Undeprecated
~pymongo.mongo_client.MongoClient.get_default_database
and added thedefault
parameter. - TLS Renegotiation is now disabled when possible.
- Custom types can now be directly encoded to, and decoded from MongoDB using the
~bson.codec_options.TypeCodec
and~bson.codec_options.TypeRegistry
APIs. For more information, see thecustom type example <examples/custom_type>
. - Attempting a multi-document transaction on a sharded cluster now raises a
~pymongo.errors.ConfigurationError
. pymongo.cursor.Cursor.distinct
andpymongo.cursor.Cursor.count
now send the Cursor's~pymongo.cursor.Cursor.comment
as the "comment" top-level command option instead of "$comment". Also, note that "comment" must be a string.- Add the
filter
parameter to~pymongo.database.Database.list_collection_names
. - Changes can now be requested from a
ChangeStream
cursor without blocking indefinitely using the newpymongo.change_stream.ChangeStream.try_next
method. - Fixed a reference leak bug when splitting a batched write command based on maxWriteBatchSize or the max message size.
- Deprecated running find queries that set
~pymongo.cursor.Cursor.min
and/or~pymongo.cursor.Cursor.max
but do not also set a~pymongo.cursor.Cursor.hint
of which index to use. The find command is expected to require a~pymongo.cursor.Cursor.hint
when using min/max starting in MongoDB 4.2. - Documented support for the uuidRepresentation URI option, which has been supported since PyMongo 2.7. Valid values are pythonLegacy (the default), javaLegacy, csharpLegacy and standard. New applications should consider setting this to standard for cross language compatibility.
~bson.raw_bson.RawBSONDocument
now validates that thebson_bytes
passed in represent a single bson document. Earlier versions would mistakenly accept multiple bson documents.- Iterating over a
~bson.raw_bson.RawBSONDocument
now maintains the same field order of the underlying raw BSON document. - Applications can now register a custom server selector. For more information see the
server selector example <examples/server_selection>
. - The connection pool now implements a LIFO policy.
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.
See the PyMongo 3.8 release notes in JIRA for the list of resolved issues in this release.
Version 3.7.2 fixes a few issues discovered since the release of 3.7.1.
- Fixed a bug in retryable writes where a previous command's "txnNumber" field could be sent leading to incorrect results.
- Fixed a memory leak of a few bytes on some insert, update, or delete commands when running against MongoDB 3.6+.
- Fixed a bug that caused
pymongo.collection.Collection.ensure_index
to only cache a single index per database. - Updated the documentation examples to use
pymongo.collection.Collection.count_documents
instead ofpymongo.collection.Collection.count
andpymongo.cursor.Cursor.count
.
See the PyMongo 3.7.2 release notes in JIRA for the list of resolved issues in this release.
Version 3.7.1 fixes a few issues discovered since the release of 3.7.0.
- Calling
~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.
See the PyMongo 3.7.1 release notes in JIRA for the list of resolved issues in this release.
Version 3.7 adds support for MongoDB 4.0. Highlights include:
- Support for single replica set multi-document ACID transactions. See
transactions-ref
. - Support for wire protocol compression. See the
~pymongo.mongo_client.MongoClient
documentation for details. - Support for Python 3.7.
- New count methods,
~pymongo.collection.Collection.count_documents
and~pymongo.collection.Collection.estimated_document_count
.~pymongo.collection.Collection.count_documents
is always accurate when used with MongoDB 3.6+, or when used with older standalone or replica set deployments. With older sharded clusters is it always accurate when used with Primary read preference. It can also be used in a transaction, unlike the now deprecatedpymongo.collection.Collection.count
andpymongo.cursor.Cursor.count
methods. - Support for watching changes on all collections in a database using the new
pymongo.database.Database.watch
method. - Support for watching changes on all collections in all databases using the new
pymongo.mongo_client.MongoClient.watch
method. - Support for watching changes starting at a user provided timestamp using the new
start_at_operation_time
parameter for thewatch()
helpers. - Better support for using PyMongo in a FIPS 140-2 environment. Specifically, the following features and changes allow PyMongo to function when MD5 support is disabled in OpenSSL by the FIPS Object Module:
- Support for the
SCRAM-SHA-256 <scram_sha_256>
authentication mechanism. TheGSSAPI <gssapi>
,PLAIN <sasl_plain>
, andMONGODB-X509 <mongodb_x509>
mechanisms can also be used to avoid issues with OpenSSL in FIPS environments. - MD5 checksums are now optional in GridFS. See the disable_md5 option of
~gridfs.GridFS
and~gridfs.GridFSBucket
. ~bson.objectid.ObjectId
machine bytes are now hashed using FNV-1a instead of MD5.
- Support for the
- The
~pymongo.database.Database.list_collection_names
and~pymongo.database.Database.collection_names
methods use the nameOnly option when supported by MongoDB. - The
pymongo.collection.Collection.watch
method now returns an instance of the~pymongo.change_stream.CollectionChangeStream
class which is a subclass of~pymongo.change_stream.ChangeStream
. - SCRAM client and server keys are cached for improved performance, following RFC 5802.
- If not specified, the authSource for the
PLAIN <sasl_plain>
authentication mechanism defaults to $external. - wtimeoutMS is once again supported as a URI option.
- When using unacknowledged write concern and connected to MongoDB server version 3.6 or greater, the bypass_document_validation option is now supported in the following write helpers:
~pymongo.collection.Collection.insert_one
,~pymongo.collection.Collection.replace_one
,~pymongo.collection.Collection.update_one
,~pymongo.collection.Collection.update_many
.
Deprecations:
- Deprecated
pymongo.collection.Collection.count
andpymongo.cursor.Cursor.count
. These two methods use the count command and may or may not be accurate, depending on the options used and connected MongoDB topology. Use~pymongo.collection.Collection.count_documents
instead. - Deprecated the snapshot option of
~pymongo.collection.Collection.find
and~pymongo.collection.Collection.find_one
. The option was deprecated in MongoDB 3.6 and removed in MongoDB 4.0. - Deprecated the max_scan option of
~pymongo.collection.Collection.find
and~pymongo.collection.Collection.find_one
. The option was deprecated in MongoDB 4.0. Use maxTimeMS instead. - Deprecated
~pymongo.mongo_client.MongoClient.close_cursor
. Use~pymongo.cursor.Cursor.close
instead. - Deprecated
~pymongo.mongo_client.MongoClient.database_names
. Use~pymongo.mongo_client.MongoClient.list_database_names
instead. - Deprecated
~pymongo.database.Database.collection_names
. Use~pymongo.database.Database.list_collection_names
instead. - Deprecated
~pymongo.collection.Collection.parallel_scan
. MongoDB 4.2 will remove the parallelCollectionScan command.
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
~pymongo.errors.NotMasterError
instead of~pymongo.errors.OperationFailure
. ~pymongo.collection.Collection.parallel_scan
no longer uses an implicit session. Explicit sessions are still supported.- Unacknowledged writes (
w=0
) with an explicitsession
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 asession
parameter are still supported.
See the PyMongo 3.7 release notes in JIRA for the list of resolved issues in this release.
Version 3.6.1 fixes bugs reported since the release of 3.6.0:
- Fix regression in PyMongo 3.5.0 that causes idle sockets to be closed almost instantly when
maxIdleTimeMS
is set. Idle sockets are now closed aftermaxIdleTimeMS
milliseconds. pymongo.mongo_client.MongoClient.max_idle_time_ms
now returns milliseconds instead of seconds.- Properly import and use the monotonic library for monotonic time when it is installed.
~pymongo.collection.Collection.aggregate
now ignores thebatchSize
argument when running a pipeline with a$out
stage.- Always send handshake metadata for new connections.
See the PyMongo 3.6.1 release notes in JIRA for the list of resolved issues in this release.
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 ~pymongo.errors.ConfigurationError
.
Highlights include:
- Support for change streams. See the
~pymongo.collection.Collection.watch
method for details. - Support for array_filters in
~pymongo.collection.Collection.update_one
,~pymongo.collection.Collection.update_many
,~pymongo.collection.Collection.find_one_and_update
,~pymongo.operations.UpdateOne
, and~pymongo.operations.UpdateMany
. - New Session API, see
~pymongo.mongo_client.MongoClient.start_session
. - New methods
~pymongo.collection.Collection.find_raw_batches
and~pymongo.collection.Collection.aggregate_raw_batches
for use with external libraries that can parse raw batches of BSON data. - New methods
~pymongo.mongo_client.MongoClient.list_databases
and~pymongo.mongo_client.MongoClient.list_database_names
. - New methods
~pymongo.database.Database.list_collections
and~pymongo.database.Database.list_collection_names
. - Support for mongodb+srv:// URIs. See
~pymongo.mongo_client.MongoClient
for details. - Index management helpers (
~pymongo.collection.Collection.create_index
,~pymongo.collection.Collection.create_indexes
,~pymongo.collection.Collection.drop_index
,~pymongo.collection.Collection.drop_indexes
,~pymongo.collection.Collection.reindex
) now support maxTimeMS. - Support for retryable writes and the
retryWrites
URI option. See~pymongo.mongo_client.MongoClient
for details.
Deprecations:
- The useCursor option for
~pymongo.collection.Collection.aggregate
is deprecated. The option was only necessary when upgrading from MongoDB 2.4 to MongoDB 2.6. MongoDB 2.4 is no longer supported. - The
~pymongo.database.Database.add_user
and~pymongo.database.Database.remove_user
methods are deprecated. See the method docstrings for alternatives.
Unavoidable breaking changes:
- Starting in MongoDB 3.6, the deprecated methods
~pymongo.database.Database.authenticate
and~pymongo.database.Database.logout
now invalidate all cursors created prior. Instead of using these methods to change credentials, pass credentials for one user to the~pymongo.mongo_client.MongoClient
at construction time, and either grant access to several databases to one user account, or use a distinct client object for each user. - BSON binary subtype 4 is decoded using RFC-4122 byte order regardless of the UUID representation. This is a change in behavior for applications that use UUID representation
bson.binary.JAVA_LEGACY
orbson.binary.CSHARP_LEGACY
to decode BSON binary subtype 4. Other UUID representations,bson.binary.PYTHON_LEGACY
(the default) andbson.binary.STANDARD
, and the decoding of BSON binary subtype 3 are unchanged.
See the PyMongo 3.6 release notes in JIRA for the list of resolved issues in this release.
Version 3.5.1 fixes bugs reported since the release of 3.5.0:
- Work around socket.getsockopt issue with NetBSD.
pymongo.command_cursor.CommandCursor.close
now closes the cursor synchronously instead of deferring to a background thread.- Fix documentation build warnings with Sphinx 1.6.x.
See the PyMongo 3.5.1 release notes in JIRA for the list of resolved issues in this release.
Version 3.5 implements a number of improvements and bug fixes:
Highlights include:
- Username and password can be passed to
~pymongo.mongo_client.MongoClient
as keyword arguments. Before, the only way to pass them was in the URI. - Increased the performance of using
~bson.raw_bson.RawBSONDocument
. - Increased the performance of
~pymongo.mongo_client.MongoClient.database_names
by using the nameOnly option for listDatabases when available. - Increased the performance of
~pymongo.collection.Collection.bulk_write
by reducing the memory overhead of~pymongo.operations.InsertOne
,~pymongo.operations.DeleteOne
, and~pymongo.operations.DeleteMany
. - Added the collation option to
~pymongo.operations.DeleteOne
,~pymongo.operations.DeleteMany
,~pymongo.operations.ReplaceOne
,~pymongo.operations.UpdateOne
, and~pymongo.operations.UpdateMany
. - Implemented the MongoDB Extended JSON specification.
~bson.decimal128.Decimal128
now works when cdecimal is installed.- PyMongo is now tested against a wider array of operating systems and CPU architectures (including s390x, ARM64, and POWER8).
Changes and Deprecations:
~pymongo.collection.Collection.find
has new options return_key, show_record_id, snapshot, hint, max_time_ms, max_scan, min, max, and comment. Deprecated the option modifiers.- Deprecated
~pymongo.collection.Collection.group
. The group command was deprecated in MongoDB 3.4 and is expected to be removed in MongoDB 3.6. Applications should use~pymongo.collection.Collection.aggregate
with the $group pipeline stage instead. - Deprecated
~pymongo.database.Database.authenticate
. Authenticating multiple users conflicts with support for logical sessions in MongoDB 3.6. To authenticate as multiple users, create multiple instances of~pymongo.mongo_client.MongoClient
. - Deprecated
~pymongo.database.Database.eval
. The eval command was deprecated in MongoDB 3.0 and will be removed in a future server version. - Deprecated
~pymongo.database.SystemJS
. - Deprecated
~pymongo.mongo_client.MongoClient.get_default_database
. Applications should use~pymongo.mongo_client.MongoClient.get_database
without the name parameter instead. - Deprecated the MongoClient option socketKeepAlive. It now defaults to true and disabling it is not recommended, see does TCP keepalive time affect MongoDB Deployments?
- Deprecated
~pymongo.collection.Collection.initialize_ordered_bulk_op
,~pymongo.collection.Collection.initialize_unordered_bulk_op
, and~pymongo.bulk.BulkOperationBuilder
. Use~pymongo.collection.Collection.bulk_write
instead. - Deprecated
~bson.json_util.STRICT_JSON_OPTIONS
. Use~bson.json_util.RELAXED_JSON_OPTIONS
or~bson.json_util.CANONICAL_JSON_OPTIONS
instead. - If a custom
~bson.codec_options.CodecOptions
is passed toRawBSONDocument
, its document_class must beRawBSONDocument
. ~pymongo.collection.Collection.list_indexes
no longer raises OperationFailure when the collection (or database) does not exist on MongoDB >= 3.0. Instead, it returns an empty~pymongo.command_cursor.CommandCursor
to make the behavior consistent across all MongoDB versions.- In Python 3,
~bson.json_util.loads
now automatically decodes JSON $binary with a subtype of 0 intobytes
instead of~bson.binary.Binary
. See the/python3
for more details. ~bson.json_util.loads
now raisesTypeError
orValueError
when parsing JSON type wrappers with values of the wrong type or any extra keys.pymongo.cursor.Cursor.close
andpymongo.mongo_client.MongoClient.close
now kill cursors synchronously instead of deferring to a background thread.~pymongo.uri_parser.parse_uri
now returns the original value of thereadPreference
MongoDB URI option instead of the validated read preference mode.
See the PyMongo 3.5 release notes in JIRA for the list of resolved issues in this release.
Version 3.4 implements the new server features introduced in MongoDB 3.4 and a whole lot more:
Highlights include:
- Complete support for MongoDB 3.4:
- Unicode aware string comparison using
examples/collations
. - Support for the new
~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.
~pymongo.collection.Collection.parallel_scan
supports maxTimeMS.~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:~pymongo.mongo_client.MongoClient.drop_database
~pymongo.database.Database.create_collection
~pymongo.database.Database.drop_collection
~pymongo.collection.Collection.aggregate
(when using $out)~pymongo.collection.Collection.create_indexes
~pymongo.collection.Collection.create_index
~pymongo.collection.Collection.drop_indexes
~pymongo.collection.Collection.drop_indexes
~pymongo.collection.Collection.drop_index
~pymongo.collection.Collection.map_reduce
(when output is not "inline")~pymongo.collection.Collection.reindex
~pymongo.collection.Collection.rename
- Unicode aware string comparison using
- Improved support for logging server discovery and monitoring events. See
~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.
- Finer control over JSON encoding/decoding with
~bson.json_util.JSONOptions
. - Allow
~bson.code.Code
objects to have a scope ofNone
, signifying no scope. Also allow encoding Code objects with an empty scope (i.e.{}
).
Warning
Starting in PyMongo 3.4, 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.
See the PyMongo 3.4 release notes in JIRA for the list of resolved issues in this release.
Version 3.3.1 fixes a memory leak when decoding elements inside of a ~bson.raw_bson.RawBSONDocument
.
See the PyMongo 3.3.1 release notes in Jira for the list of resolved issues in this release.
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
~pymongo.monitoring
for details. - New connection pool options
minPoolSize
andmaxIdleTimeMS
. - 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).
See the PyMongo 3.3 release notes in JIRA for the list of resolved issues in this release.
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+.
See the PyMongo 3.2.2 release notes in JIRA for the list of resolved issues in this release.
Version 3.2.1 fixes a few issues reported since the release of 3.2, including running the mapreduce command twice when calling the ~pymongo.collection.Collection.inline_map_reduce
method and a TypeError
being raised when calling ~gridfs.GridFSBucket.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:
- Full support for MongoDB 3.2 including:
- Support for
~pymongo.read_concern.ReadConcern
~pymongo.write_concern.WriteConcern
is now applied to~pymongo.collection.Collection.find_one_and_replace
,~pymongo.collection.Collection.find_one_and_update
, and~pymongo.collection.Collection.find_one_and_delete
.- Support for the new bypassDocumentValidation option in write helpers.
- Support for
- Support for reading and writing raw BSON with
~bson.raw_bson.RawBSONDocument
Note
Certain ~pymongo.mongo_client.MongoClient
properties now block until a connection is established or raise ~pymongo.errors.ServerSelectionTimeoutError
if no server is available. See ~pymongo.mongo_client.MongoClient
for details.
See the PyMongo 3.2 release notes in JIRA for the list of resolved issues in this release.
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:
- Command monitoring support. See
~pymongo.monitoring
for details. - Configurable error handling for
UnicodeDecodeError
. See the unicode_decode_error_handler option of~bson.codec_options.CodecOptions
. - Optional automatic timezone conversion when decoding BSON datetime. See the tzinfo option of
~bson.codec_options.CodecOptions
. - An implementation of
~gridfs.GridFSBucket
from the new GridFS spec. - Compliance with the new Connection String spec.
- Reduced idle CPU usage in Python 2.
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 ~pymongo.read_preferences.PrimaryPreferred
or ~pymongo.read_preferences.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:
- 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.
The ~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 ~pymongo.database.Database.add_son_manipulator
method is deprecated. PyMongo 3's new CRUD API does not apply SON manipulators to documents passed to ~pymongo.collection.Collection.bulk_write
, ~pymongo.collection.Collection.insert_one
, ~pymongo.collection.Collection.insert_many
, ~pymongo.collection.Collection.update_one
, or ~pymongo.collection.Collection.update_many
. SON manipulators are not applied to documents returned by the new methods ~pymongo.collection.Collection.find_one_and_delete
, ~pymongo.collection.Collection.find_one_and_replace
, and ~pymongo.collection.Collection.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 ~pymongo.errors.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 ~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 PyMongo's Gevent documentation <examples/gevent>
.
~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. ~pymongo.mongo_client.MongoClient
now also supports the full ~pymongo.read_preferences.ReadPreference
API.
The obsolete classes MasterSlaveConnection
, Connection
, and ReplicaSetConnection
are removed.
The ~pymongo.mongo_client.MongoClient
constructor no longer blocks while connecting to the server or servers, and it no longer raises ~pymongo.errors.ConnectionFailure
if they are unavailable, nor ~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, ~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 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 <secondary-reads>
of PRIMARY.
Support for the slaveOk
(or slave_okay
), safe
, and network_timeout
options has been removed. Use ~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 copy_database examples </examples/copydb>
for alternatives.
The disconnect
method is removed. Use ~pymongo.mongo_client.MongoClient.close
instead.
The get_document_class
method is removed. Use ~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 ~pymongo.mongo_client.MongoClient
as keyword arguments or MongoDB URI options.
The ~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:
~pymongo.mongo_client.MongoClient.codec_options
The following attributes are now read-only:
~pymongo.mongo_client.MongoClient.read_preference
~pymongo.mongo_client.MongoClient.write_concern
The following attributes have been removed:
~pymongo.mongo_client.MongoClient.document_class
(use~pymongo.mongo_client.MongoClient.codec_options
instead)~pymongo.mongo_client.MongoClient.host
(use~pymongo.mongo_client.MongoClient.address
instead)~pymongo.mongo_client.MongoClient.min_wire_version
~pymongo.mongo_client.MongoClient.max_wire_version
~pymongo.mongo_client.MongoClient.port
(use~pymongo.mongo_client.MongoClient.address
instead)~pymongo.mongo_client.MongoClient.safe
(use~pymongo.mongo_client.MongoClient.write_concern
instead)~pymongo.mongo_client.MongoClient.slave_okay
(use~pymongo.mongo_client.MongoClient.read_preference
instead)~pymongo.mongo_client.MongoClient.tag_sets
(use~pymongo.mongo_client.MongoClient.read_preference
instead)~pymongo.mongo_client.MongoClient.tz_aware
(use~pymongo.mongo_client.MongoClient.codec_options
instead)
The following attributes have been renamed:
~pymongo.mongo_client.MongoClient.secondary_acceptable_latency_ms
is now~pymongo.mongo_client.MongoClient.local_threshold_ms
and is now read-only.
The conn_id
property is renamed to ~pymongo.cursor.Cursor.address
.
~pymongo.cursor_manager.CursorManager
and ~pymongo.mongo_client.MongoClient.set_cursor_manager
are no longer deprecated. If you subclass ~pymongo.cursor_manager.CursorManager
your implementation of ~pymongo.cursor_manager.CursorManager.close
must now take a second parameter, address. The BatchCursorManager
class is removed.
The second parameter to ~pymongo.mongo_client.MongoClient.close_cursor
is renamed from _conn_id
to address
. ~pymongo.mongo_client.MongoClient.kill_cursors
now accepts an address parameter.
The connection
property is renamed to ~pymongo.database.Database.client
.
The following read-only attributes have been added:
~pymongo.database.Database.codec_options
The following attributes are now read-only:
~pymongo.database.Database.read_preference
~pymongo.database.Database.write_concern
Use ~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:
~pymongo.database.Database.safe
~pymongo.database.Database.secondary_acceptable_latency_ms
~pymongo.database.Database.slave_okay
~pymongo.database.Database.tag_sets
The following methods have been added:
~pymongo.database.Database.get_collection
The following methods have been changed:
~pymongo.database.Database.command
. Support for as_class, uuid_subtype, tag_sets, and secondary_acceptable_latency_ms have been removed. You can instead pass an instance of~bson.codec_options.CodecOptions
as codec_options and an instance of a read preference class from~pymongo.read_preferences
as read_preference. The fields and compile_re options are also removed. The fields options was undocumented and never really worked. Regular expressions are always decoded to~bson.regex.Regex
.
The following methods have been deprecated:
~pymongo.database.Database.add_son_manipulator
The following methods have been removed:
The get_lasterror_options
, set_lasterror_options
, and unset_lasterror_options
methods have been removed. Use ~pymongo.write_concern.WriteConcern
with ~pymongo.mongo_client.MongoClient.get_database
instead.
The following read-only attributes have been added:
~pymongo.collection.Collection.codec_options
The following attributes are now read-only:
~pymongo.collection.Collection.read_preference
~pymongo.collection.Collection.write_concern
Use ~pymongo.database.Database.get_collection
or ~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:
~pymongo.collection.Collection.safe
~pymongo.collection.Collection.secondary_acceptable_latency_ms
~pymongo.collection.Collection.slave_okay
~pymongo.collection.Collection.tag_sets
The following methods have been added:
~pymongo.collection.Collection.bulk_write
~pymongo.collection.Collection.insert_one
~pymongo.collection.Collection.insert_many
~pymongo.collection.Collection.update_one
~pymongo.collection.Collection.update_many
~pymongo.collection.Collection.replace_one
~pymongo.collection.Collection.delete_one
~pymongo.collection.Collection.delete_many
~pymongo.collection.Collection.find_one_and_delete
~pymongo.collection.Collection.find_one_and_replace
~pymongo.collection.Collection.find_one_and_update
~pymongo.collection.Collection.with_options
~pymongo.collection.Collection.create_indexes
~pymongo.collection.Collection.list_indexes
The following methods have changed:
~pymongo.collection.Collection.aggregate
now always returns an instance of~pymongo.command_cursor.CommandCursor
. See the documentation for all options.~pymongo.collection.Collection.count
now optionally takes a filter argument, as well as other options supported by the count command.~pymongo.collection.Collection.distinct
now optionally takes a filter argument.~pymongo.collection.Collection.create_index
no longer caches indexes, therefore the cache_for parameter has been removed. It also no longer supports the bucket_size and drop_dups aliases for bucketSize and dropDups.
The following methods are deprecated:
~pymongo.collection.Collection.save
~pymongo.collection.Collection.insert
~pymongo.collection.Collection.update
~pymongo.collection.Collection.remove
~pymongo.collection.Collection.find_and_modify
~pymongo.collection.Collection.ensure_index
The following methods have been removed:
The get_lasterror_options
, set_lasterror_options
, and unset_lasterror_options
methods have been removed. Use ~pymongo.write_concern.WriteConcern
with ~pymongo.collection.Collection.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.
- spec -> filter
- fields -> projection
- partial -> allow_partial_results
The following find/find_one options have been added:
- cursor_type (see
~pymongo.cursor.CursorType
for values) - oplog_replay
- modifiers
The following find/find_one options have been removed:
- network_timeout (use
~pymongo.cursor.Cursor.max_time_ms
instead) - slave_okay (use one of the read preference classes from
~pymongo.read_preferences
and~pymongo.collection.Collection.with_options
instead) - read_preference (use
~pymongo.collection.Collection.with_options
instead) - tag_sets (use one of the read preference classes from
~pymongo.read_preferences
and~pymongo.collection.Collection.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
~pymongo.collection.Collection.with_options
with~bson.codec_options.CodecOptions
instead) - compile_re (BSON regular expressions are always decoded to
~bson.regex.Regex
)
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.
The exception classes UnsupportedOption
and TimeoutError
are deleted.
Since PyMongo 1.6, methods open
and close
of ~gridfs.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 ~bson.json_util
. Additionally, it is removed from ~pymongo.collection.Collection.find
, ~pymongo.collection.Collection.find_one
, ~pymongo.collection.Collection.aggregate
, ~pymongo.database.Database.command
, and so on. PyMongo now always represents BSON regular expressions as ~bson.regex.Regex
objects. This prevents errors for incompatible patterns, see PYTHON-500. Use ~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 ~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 ~bson.int64.Int64
.
The as_class, tz_aware, and uuid_subtype options are removed from all BSON encoding and decoding methods. Use ~bson.codec_options.CodecOptions
to configure these options. The APIs affected are:
~bson.decode_all
~bson.decode_iter
~bson.decode_file_iter
~bson.BSON.encode
~bson.BSON.decode
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.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.
- Use ssl.SSLContext and ssl.PROTOCOL_TLS_CLIENT when available.
- Fixed a C extensions build issue when the interpreter was built with -std=c99
- Fixed various build issues with MinGW32.
- Fixed a write concern bug in
~pymongo.database.Database.add_user
and~pymongo.database.Database.remove_user
when connected to MongoDB 3.2+ - Fixed various test failures related to changes in gevent, MongoDB, and our CI test environment.
See the PyMongo 2.9.5 release notes in JIRA for the list of resolved issues in this release.
Version 2.9.4 fixes issues reported since the release of 2.9.3.
- Fixed __repr__ for closed instances of
~pymongo.mongo_client.MongoClient
. - Fixed
~pymongo.mongo_replica_set_client.MongoReplicaSetClient
handling of uuidRepresentation. - Fixed building and testing the documentation with python 3.x.
- New documentation for
examples/tls
andatlas
.
See the PyMongo 2.9.4 release notes in JIRA for the list of resolved issues in this release.
Version 2.9.3 fixes a few issues reported since the release of 2.9.2 including thread safety issues in ~pymongo.collection.Collection.ensure_index
, ~pymongo.collection.Collection.drop_index
, and ~pymongo.collection.Collection.drop_indexes
.
See the PyMongo 2.9.3 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 ~pymongo.collection.Collection.aggregate
ignoring ~pymongo.collection.Collection.codec_options
and ~pymongo.database.Database.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 /migrate-to-pymongo3
for detailed examples.
Note
There are a number of new deprecations in this release for features that were removed in PyMongo 3.0.
~pymongo.mongo_client.MongoClient
:~pymongo.mongo_client.MongoClient.host
~pymongo.mongo_client.MongoClient.port
~pymongo.mongo_client.MongoClient.use_greenlets
~pymongo.mongo_client.MongoClient.document_class
~pymongo.mongo_client.MongoClient.tz_aware
~pymongo.mongo_client.MongoClient.secondary_acceptable_latency_ms
~pymongo.mongo_client.MongoClient.tag_sets
~pymongo.mongo_client.MongoClient.uuid_subtype
~pymongo.mongo_client.MongoClient.disconnect
~pymongo.mongo_client.MongoClient.alive
~pymongo.mongo_replica_set_client.MongoReplicaSetClient
:~pymongo.mongo_replica_set_client.MongoReplicaSetClient.use_greenlets
~pymongo.mongo_replica_set_client.MongoReplicaSetClient.document_class
~pymongo.mongo_replica_set_client.MongoReplicaSetClient.tz_aware
~pymongo.mongo_replica_set_client.MongoReplicaSetClient.secondary_acceptable_latency_ms
~pymongo.mongo_replica_set_client.MongoReplicaSetClient.tag_sets
~pymongo.mongo_replica_set_client.MongoReplicaSetClient.uuid_subtype
~pymongo.mongo_replica_set_client.MongoReplicaSetClient.alive
~pymongo.database.Database
:~pymongo.database.Database.secondary_acceptable_latency_ms
~pymongo.database.Database.tag_sets
~pymongo.database.Database.uuid_subtype
~pymongo.collection.Collection
:~pymongo.collection.Collection.secondary_acceptable_latency_ms
~pymongo.collection.Collection.tag_sets
~pymongo.collection.Collection.uuid_subtype
Warning
In previous versions of PyMongo, changing the value of ~pymongo.mongo_client.MongoClient.document_class
changed the behavior of all existing instances of ~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
~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'))])
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:
- Support for the SCRAM-SHA-1 authentication mechanism (new in MongoDB 3.0).
- JSON decoder support for the new $numberLong and $undefined types.
- JSON decoder support for the $date type as an ISO-8601 string.
- Support passing an index name to
~pymongo.cursor.Cursor.hint
. - The
~pymongo.cursor.Cursor.count
method will use a hint if one has been provided through~pymongo.cursor.Cursor.hint
. - A new socketKeepAlive option for the connection pool.
- New generator based BSON decode functions,
~bson.decode_iter
and~bson.decode_file_iter
. - Internal changes to support alternative storage engines like wiredtiger.
Note
There are a number of deprecations in this release for features that will be removed in PyMongo 3.0. These include:
~pymongo.mongo_client.MongoClient.start_request
~pymongo.mongo_client.MongoClient.in_request
~pymongo.mongo_client.MongoClient.end_request
~pymongo.mongo_client.MongoClient.copy_database
~pymongo.database.Database.error
~pymongo.database.Database.last_status
~pymongo.database.Database.previous_error
~pymongo.database.Database.reset_error_history
~pymongo.master_slave_connection.MasterSlaveConnection
The JSON format for ~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 ~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.
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 ~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.
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:
- Full support for MongoDB 2.6.
- A new
bulk write operations API </examples/bulk>
. - Support for server side query timeouts using
~pymongo.cursor.Cursor.max_time_ms
. - Support for writing
~pymongo.collection.Collection.aggregate
output to a collection. - A new
~pymongo.collection.Collection.parallel_scan
helper. ~pymongo.errors.OperationFailure
and its subclasses now include a~pymongo.errors.OperationFailure.details
attribute with complete error details from the server.- A new GridFS
~gridfs.GridFS.find
method that returns a~gridfs.grid_file.GridOutCursor
. - Greatly improved
support for mod_wsgi </examples/mod_wsgi>
when using PyMongo's C extensions. Read Jesse's blog post for details. - Improved C extension support for ARM little endian.
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 ~pymongo.collection.Collection.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:
- The
max_pool_size
option for~pymongo.mongo_client.MongoClient
and~pymongo.mongo_replica_set_client.MongoReplicaSetClient
now actually caps the number of sockets the pool will open concurrently. Once the pool has reached~pymongo.mongo_client.MongoClient.max_pool_size
operations will block waiting for a socket to become available. IfwaitQueueTimeoutMS
is set, an operation that blocks waiting for a socket will raise~pymongo.errors.ConnectionFailure
after the timeout. By defaultwaitQueueTimeoutMS
is not set. Seeconnection-pooling
for more information. - The
~pymongo.collection.Collection.insert
method automatically splits large batches of documents into multiple insert messages based on~pymongo.mongo_client.MongoClient.max_message_size
- Support for the exhaust cursor flag. See
~pymongo.collection.Collection.find
for details and caveats. - Support for the PLAIN and MONGODB-X509 authentication mechanisms. See
the authentication docs </examples/authentication>
for more information. - Support aggregation output as a
~pymongo.cursor.Cursor
. See~pymongo.collection.Collection.aggregate
for details.
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 connection-pooling
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 ~bson.dbref.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:
- Support for
GSSAPI (Kerberos) authentication <gssapi>
. - Support for SSL certificate validation with hostname matching.
- Support for delegated and role based authentication.
- New GEOSPHERE (2dsphere) and HASHED index constants.
Note
~pymongo.database.Database.authenticate
now raises a subclass of ~pymongo.errors.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 ~pymongo.collection.Collection.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:
- New
~pymongo.mongo_client.MongoClient
and~pymongo.mongo_replica_set_client.MongoReplicaSetClient
classes -these connection classes do acknowledged write operations (previously referred to as 'safe' writes) by default.~pymongo.connection.Connection
and~pymongo.replica_set_connection.ReplicaSetConnection
are deprecated but still support the old default fire-and-forget behavior. - A new write concern API implemented as a
~pymongo.collection.Collection.write_concern
attribute on the connection,~pymongo.database.Database
, or~pymongo.collection.Collection
classes. ~pymongo.mongo_client.MongoClient
(and~pymongo.connection.Connection
) now support Unix Domain Sockets.~pymongo.cursor.Cursor
can be copied with functions from thecopy
module.- The
~pymongo.database.Database.set_profiling_level
method now supports a slow_ms option. - The replica set monitor task (used by
~pymongo.mongo_replica_set_client.MongoReplicaSetClient
and~pymongo.replica_set_connection.ReplicaSetConnection
) is a daemon thread once again, meaning you won't have to call~pymongo.mongo_replica_set_client.MongoReplicaSetClient.close
before exiting the python interactive shell.
Warning
The constructors for ~pymongo.mongo_client.MongoClient
, ~pymongo.mongo_replica_set_client.MongoReplicaSetClient
, ~pymongo.connection.Connection
, and ~pymongo.replica_set_connection.ReplicaSetConnection
now raise ~pymongo.errors.ConnectionFailure
instead of its subclass ~pymongo.errors.AutoReconnect
if the server is unavailable. Applications that expect to catch ~pymongo.errors.AutoReconnect
should now catch ~pymongo.errors.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:
- Support for expanded read preferences including directing reads to tagged servers - See
secondary-reads
for more information. - Support for mongos failover.
- A new
~pymongo.collection.Collection.aggregate
method to support MongoDB's new aggregation framework. - Support for legacy Java and C# byte order when encoding and decoding UUIDs.
- Support for connecting directly to an arbiter.
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:
- Support for Python 3 -See the
python3
for more information. - Support for Gevent -See
examples/gevent
for more information. - Improved connection pooling. See PYTHON-287.
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 ~pymongo.replica_set_connection.ReplicaSetConnection
to run inline map reduce commands on secondaries. See ~pymongo.collection.Collection.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:
- ReplicaSetConnection -
~pymongo.replica_set_connection.ReplicaSetConnection
can be used to distribute reads to secondaries in a replica set. It supports automatic failover handling and periodically checks the state of the replica set to handle issues like primary stepdown or secondaries being removed for backup operations. Read preferences are defined through~pymongo.read_preferences.ReadPreference
. - PyMongo supports the new BSON binary subtype 4 for UUIDs. The default subtype to use can be set through
~pymongo.collection.Collection.uuid_subtype
The current default remains~bson.binary.OLD_UUID_SUBTYPE
but will be changed to~bson.binary.UUID_SUBTYPE
in a future release. - The getLastError option 'w' can be set to a string, allowing for options like "majority" available in newer version of MongoDB.
- Added support for the MongoDB URI options socketTimeoutMS and connectTimeoutMS.
- Added support for the ContinueOnError insert flag.
- Added basic SSL support.
- Added basic support for Jython.
- Secondaries can be used for
~pymongo.cursor.Cursor.count
,~pymongo.cursor.Cursor.distinct
,~pymongo.collection.Collection.group
, and querying~gridfs.GridFS
. - Added document_class and tz_aware options to
~pymongo.master_slave_connection.MasterSlaveConnection
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 ~gridfs.grid_file.GridIn
when writing pre-chunked strings. Thanks go to Alexey Borzenkov for reporting the issue and submitting a patch.
- PYTHON-271: Regression in GridFS leads to serious loss of data.
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
~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.
~pymongo.collection.Collection.map_reduce
will accept a dict or instance of~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
~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.
Warning
The default subtype for ~bson.binary.Binary
has changed from ~bson.binary.OLD_BINARY_SUBTYPE
(2) to ~bson.binary.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:
- Basic IPv6 support: pymongo prefers IPv4 but will try IPv6. You can also specify an IPv6 address literal in the host parameter or a MongoDB URI provided it is enclosed in '[' and ']'.
- max_pool_size option: previously pymongo had a hard coded pool size of 10 connections. With this change you can specify a different pool size as a parameter to
~pymongo.connection.Connection
(max_pool_size=<integer>) or in the MongoDB URI (maxPoolSize=<integer>). - Find by metadata in GridFS: You can know specify query fields as keyword parameters for
~gridfs.GridFS.get_version
and~gridfs.GridFS.get_last_version
. - Per-query slave_okay option: slave_okay=True is now a valid keyword argument for
~pymongo.collection.Collection.find
and~pymongo.collection.Collection.find_one
.
API changes:
~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 ~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.
- 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
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:
- If a read slave raises
~pymongo.errors.AutoReconnect
~pymongo.master_slave_connection.MasterSlaveConnection
will now retry the query on each slave until it is successful or all slaves have raised~pymongo.errors.AutoReconnect
. Any other exception will immediately be raised. The order that the slaves are tried is random. Previously the read would be sent to one randomly chosen slave and~pymongo.errors.AutoReconnect
was immediately raised in case of a connection failure. - A Python long is now always BSON encoded as an int64. Previously the encoding was based only on the value of the field and a long with a value less than 2147483648 or greater than -2147483649 would always be BSON encoded as an int32.
- 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
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.
- added
~pymongo.collection.Collection.find_and_modify
. - added
~pymongo.collection.Collection.inline_map_reduce
. - changed
~pymongo.collection.Collection.map_reduce
.
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. ~pymongo.collection.Collection.map_reduce
now requires the out parameter.
- PYTHON-225:
~pymongo.objectid.ObjectId
class definition should use __slots__. - PYTHON-223: Documentation fix.
- PYTHON-220: Documentation fix.
- PYTHON-219: KeyError in
~pymongo.collection.Collection.find_and_modify
- PYTHON-213: Query server for maximum BSON document size.
- PYTHON-208: Fix
~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
~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
~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.
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
andpymongo._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 ~pymongo.errors.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.
- the C extension now shares buffer.c/h with the Ruby driver
bson
no longer raises~pymongo.errors.InvalidName
, all occurrences have been replaced with~bson.errors.InvalidDocument
.- renamed
bson._to_dicts
to~bson.decode_all
. - renamed
~bson.BSON.from_dict
to~bson.BSON.encode
and~bson.BSON.to_dict
to~bson.BSON.decode
. - added
~pymongo.cursor.Cursor.batch_size
. - allow updating (some) file metadata after a
~gridfs.grid_file.GridIn
instance has been closed. - performance improvements for reading from GridFS.
- special cased slice with the same start and stop to return an empty cursor.
- allow writing
unicode
to GridFS if anencoding
attribute has been specified for the file. - added
gridfs.GridFS.get_version
. - scope variables for
~bson.code.Code
can now be specified as keyword arguments. - added
~gridfs.grid_file.GridOut.readline
to~gridfs.grid_file.GridOut
. - make a best effort to transparently auto-reconnect if a
~pymongo.connection.Connection
has been idle for a while. - added
~pymongo.database.SystemJS.list
to~pymongo.database.SystemJS
. - added file_document argument to
~gridfs.grid_file.GridOut
to allow initializing from an existing file document. - raise
~pymongo.errors.TimeoutError
even if thegetLastError
command was run manually and not through "safe" mode. - added
uuid
support to~bson.json_util
.
- fixed a typo in the C extension that could cause safe-mode operations to report a failure (
SystemError
) even when none occurred. - added a
__ne__
implementation to any class where we define__eq__
.
Version 1.8 adds support for connecting to replica sets, specifying per-operation values for w and wtimeout, and decoding to timezone-aware datetimes.
- fixed a reference leak in the C extension when decoding a
~bson.dbref.DBRef
. - added support for w, wtimeout, and fsync (and any other options for getLastError) to "safe mode" operations.
- added
~pymongo.connection.Connection.nodes
property. - added a maximum pool size of 10 sockets.
- added support for replica sets.
- DEPRECATED
~pymongo.connection.Connection.from_uri
and~pymongo.connection.Connection.paired
, both are supplanted by extended functionality in~pymongo.connection.Connection
. - added tz aware support for datetimes in
~bson.objectid.ObjectId
,~bson.timestamp.Timestamp
and~bson.json_util
methods. - added
~pymongo.collection.Collection.drop
helper. - reuse the socket used for finding the master when a
~pymongo.connection.Connection
is first created. - added support for
~bson.min_key.MinKey
,~bson.max_key.MaxKey
and~bson.timestamp.Timestamp
to~bson.json_util
. - added support for decoding datetimes as aware (UTC) - it is highly recommended to enable this by setting the tz_aware parameter to
~pymongo.connection.Connection
toTrue
. - added network_timeout option for individual calls to
~pymongo.collection.Collection.find
and~pymongo.collection.Collection.find_one
. - added
~gridfs.GridFS.exists
to check if a file exists in GridFS. - added support for additional keys in
~bson.dbref.DBRef
instances. - added
~pymongo.errors.OperationFailure.code
attribute to~pymongo.errors.OperationFailure
exceptions. - fixed serialization of int and float subclasses in the C extension.
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.
- no longer attempt to build the C extension on big-endian systems.
- added
~bson.min_key.MinKey
and~bson.max_key.MaxKey
. - use unsigned for
~bson.timestamp.Timestamp
in BSON encoder/decoder. - support
True
as"ok"
in command responses, in addition to1.0
- necessary for server versions >= 1.5.X - BREAKING change to
~pymongo.collection.Collection.index_information
to add support for querying unique status and other index information. - added
~pymongo.connection.Connection.document_class
, to specify class for returned documents. - added as_class argument for
~pymongo.collection.Collection.find
, and in the BSON decoder. - added support for creating
~bson.timestamp.Timestamp
instances using a~datetime.datetime
. - allow dropTarget argument for
~pymongo.collection.Collection.rename
. - handle aware
~datetime.datetime
instances, by converting to UTC. - added support for
~pymongo.cursor.Cursor.max_scan
. - raise
~gridfs.errors.FileExists
exception when creating a duplicate GridFS file. - use y2038 for time handling in the C extension - eliminates 2038 problems when extension is installed.
- added sort parameter to
~pymongo.collection.Collection.find
- finalized deprecation of changes from versions <= 1.4
- take any non-
dict
as an"_id"
query for~pymongo.collection.Collection.find_one
or~pymongo.collection.Collection.remove
- added ability to pass a
dict
for fields argument to~pymongo.collection.Collection.find
(supports"$slice"
and field negation) - simplified code to find master, since paired setups don't always have a remote
- fixed bug in C encoder for certain invalid types (like
~pymongo.collection.Collection
instances). - don't transparently map
"filename"
key toname
attribute for GridFS.
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.
- fixed issue where connection pool was being shared across
~pymongo.connection.Connection
instances. - more improvements to Python code caching in C extension - should improve behavior on mod_wsgi.
- added
~bson.objectid.ObjectId.from_datetime
. - complete rewrite of
gridfs
support. - improvements to the
~pymongo.database.Database.command
API. - fixed
~pymongo.collection.Collection.drop_indexes
behavior on non-existent collections. - disallow empty bulk inserts.
- fixed response handling to ignore unknown response flags in queries.
- handle server versions containing '-pre-'.
- added
~gridfs.grid_file.GridFile._id
property for~gridfs.grid_file.GridFile
instances. - fix for making a
~pymongo.connection.Connection
(with slave_okay set) directly to a slave in a replica pair. - accept kwargs for
~pymongo.collection.Collection.create_index
and~pymongo.collection.Collection.ensure_index
to support all indexing options. - add
pymongo.GEO2D
and support for geo indexing. - improvements to Python code caching in C extension - should improve behavior on mod_wsgi.
- added subtype constants to
~bson.binary
module. - DEPRECATED options argument to
~pymongo.collection.Collection
and~pymongo.database.Database.create_collection
in favor of kwargs. - added
~pymongo.has_c
to check for C extension. - added
~pymongo.connection.Connection.copy_database
. - added
~pymongo.cursor.Cursor.alive
to tell when a cursor might have more data to return (useful for tailable cursors). - added
~bson.timestamp.Timestamp
to better support dealing with internal MongoDB timestamps. - added name argument for
~pymongo.collection.Collection.create_index
and~pymongo.collection.Collection.ensure_index
. - fixed connection pooling w/ fork
~pymongo.connection.Connection.paired
takes all kwargs that are allowed for~pymongo.connection.Connection
.~pymongo.collection.Collection.insert
returns list for bulk inserts of size one.- fixed handling of
datetime.datetime
instances in~bson.json_util
. - added
~pymongo.connection.Connection.from_uri
to support MongoDB connection uri scheme. - fixed chunk number calculation when unaligned in
gridfs
. ~pymongo.database.Database.command
takes a string for simple commands.- added
~pymongo.database.Database.system_js
helper for dealing with server-side JS. - don't wrap queries containing
"$query"
(support manual use of"$min"
, etc.). - added
~gridfs.errors.GridFSError
as base class forgridfs
exceptions.
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:
- move
"_id"
to front only for top-level documents (fixes some corner cases). ~pymongo.collection.Collection.update
and~pymongo.collection.Collection.remove
return the entire response to the lastError command when safe isTrue
.- completed removal of things that were deprecated in version 1.2 or earlier.
- enforce that collection names do not contain the NULL byte.
- fix to allow using UTF-8 collection names with the C extension.
- added
~pymongo.errors.PyMongoError
as base exception class for all~pymongo.errors
. this changes the exception hierarchy somewhat, and is a BREAKING change if you depend on~pymongo.errors.ConnectionFailure
being aIOError
or~bson.errors.InvalidBSON
being aValueError
, for example. - added
~pymongo.errors.DuplicateKeyError
for calls to~pymongo.collection.Collection.insert
or~pymongo.collection.Collection.update
with safe set toTrue
. - removed
~pymongo.thread_util
. - added
~pymongo.database.Database.add_user
and~pymongo.database.Database.remove_user
helpers. - fix for
~pymongo.database.Database.authenticate
when using non-UTF-8 names or passwords. - minor fixes for
~pymongo.master_slave_connection.MasterSlaveConnection
. - clean up all cases where
~pymongo.errors.ConnectionFailure
is raised. - simplification of connection pooling - makes driver ~2x faster for simple benchmarks. see
connection-pooling
for more information. - DEPRECATED pool_size, auto_start_request and timeout parameters to
~pymongo.connection.Connection
. DEPRECATED~pymongo.connection.Connection.start_request
. - use
socket.sendall
. - removed
~bson.son.SON.from_xml
as it was only being used for some internal testing - also eliminates dependency onelementtree
. - implementation of
~pymongo.message.update
in C. - deprecate
~pymongo.database.Database._command
in favor of~pymongo.database.Database.command
. - send all commands without wrapping as
{"query": ...}
. - support string as key argument to
~pymongo.collection.Collection.group
(keyf) and run all groups as commands. - support for equality testing for
~bson.code.Code
instances. - allow the NULL byte in strings and disallow it in key names or regex patterns
- DEPRECATED running
~pymongo.collection.Collection.group
as~pymongo.database.Database.eval
, also changed default for~pymongo.collection.Collection.group
to running as a command - remove
pymongo.cursor.Cursor.__len__
, which was deprecated in 1.1.1 - needed to do this aggressively due to it's presence breaking Django template for loops - DEPRECATED
~pymongo.connection.Connection.host
,~pymongo.connection.Connection.port
,~pymongo.database.Database.connection
,~pymongo.database.Database.name
,~pymongo.collection.Collection.database
,~pymongo.collection.Collection.name
and~pymongo.collection.Collection.full_name
in favor of~pymongo.connection.Connection.host
,~pymongo.connection.Connection.port
,~pymongo.database.Database.connection
,~pymongo.database.Database.name
,~pymongo.collection.Collection.database
,~pymongo.collection.Collection.name
and~pymongo.collection.Collection.full_name
, respectively. The deprecation schedule for this change will probably be faster than usual, as it carries some performance implications. - added
~pymongo.connection.Connection.disconnect
- added
changelog
to docs - added
setup.py doc --test
to run doctests for tutorial, examples - moved most examples to Sphinx docs (and remove from examples/ directory)
- raise
~bson.errors.InvalidId
instead ofTypeError
when passing a 24 character string to~bson.objectid.ObjectId
that contains non-hexadecimal characters - allow
unicode
instances for~bson.objectid.ObjectId
init
- spec parameter for
~pymongo.collection.Collection.remove
is now optional to allow for deleting all documents in a~pymongo.collection.Collection
- always wrap queries with
{query: ...}
even when no special options -get around some issues with queries on fields namedquery
- enforce 4MB document limit on the client side
- added
~pymongo.collection.Collection.map_reduce
helper - seeexample <examples/aggregation>
- added
~pymongo.cursor.Cursor.distinct
method on~pymongo.cursor.Cursor
instances to allow distinct with queries - fix for
~pymongo.cursor.Cursor.__getitem__
after~pymongo.cursor.Cursor.skip
- allow any UTF-8 string in
~bson.BSON
encoder, not just ASCII subset - added
~bson.objectid.ObjectId.generation_time
- removed support for legacy
~bson.objectid.ObjectId
format - pretty sure this was never used, and is just confusing - DEPRECATED
~bson.objectid.ObjectId.url_encode
and~bson.objectid.ObjectId.url_decode
in favor ofstr
and~bson.objectid.ObjectId
, respectively - allow oplog.$main as a valid collection name
- some minor fixes for installation process
- added support for datetime and regex in
~bson.json_util
- improvements to
~pymongo.collection.Collection.insert
speed (using C for insert message creation) - use random number for request_id
- fix some race conditions with
~pymongo.errors.AutoReconnect
- added multi parameter for
~pymongo.collection.Collection.update
- fix unicode regex patterns with C extension
- added
~pymongo.collection.Collection.distinct
- added database support for
~bson.dbref.DBRef
- added
~bson.json_util
with helpers for encoding / decoding special types to JSON - DEPRECATED
pymongo.cursor.Cursor.__len__
in favor of~pymongo.cursor.Cursor.count
with with_limit_and_skip set toTrue
due to performance regression - switch documentation to Sphinx
- added
__hash__
for~bson.dbref.DBRef
and~bson.objectid.ObjectId
- bulk
~pymongo.collection.Collection.insert
works with any iterable - fix
~bson.objectid.ObjectId
generation when usingmultiprocessing
- added
~pymongo.cursor.Cursor.collection
- added network_timeout parameter for
~pymongo.connection.Connection
- DEPRECATED slave_okay parameter for individual queries
- fix for safe mode when multi-threaded
- added safe parameter for
~pymongo.collection.Collection.remove
- added tailable parameter for
~pymongo.collection.Collection.find
- fixes for
~pymongo.master_slave_connection.MasterSlaveConnection
- added finalize parameter for
~pymongo.collection.Collection.group
- improvements to
~pymongo.collection.Collection.insert
speed - improvements to
gridfs
speed - added
~pymongo.cursor.Cursor.__getitem__
and~pymongo.cursor.Cursor.__len__
for~pymongo.cursor.Cursor
instances
- support for encoding/decoding
uuid.UUID
instances - fix for
~pymongo.cursor.Cursor.explain
with limits
- documentation changes only
- various performance improvements
- API CHANGE no longer need to specify direction for
~pymongo.collection.Collection.create_index
and~pymongo.collection.Collection.ensure_index
when indexing a single key - support for encoding
tuple
instances aslist
instances
- fix string representation of
~bson.objectid.ObjectId
instances - added timeout parameter for
~pymongo.collection.Collection.find
- allow scope for reduce function in
~pymongo.collection.Collection.group
- minor bugfixes
~gridfs.grid_file.GridFile.seek
and~gridfs.grid_file.GridFile.tell
for (read mode)~gridfs.grid_file.GridFile
instances
- support for long in
~bson.BSON
- added
~pymongo.collection.Collection.rename
- added snapshot parameter for
~pymongo.collection.Collection.find
- better
~pymongo.master_slave_connection.MasterSlaveConnection
support - API CHANGE
~pymongo.collection.Collection.insert
and~pymongo.collection.Collection.save
both return inserted_id
- DEPRECATED passing an index name to
~pymongo.cursor.Cursor.hint
- improved
~bson.objectid.ObjectId
generation - added
~pymongo.errors.AutoReconnect
exception for when reconnection is possible - make
gridfs
thread-safe - fix for
gridfs
with non~bson.objectid.ObjectId
_id
- don't allow NULL bytes in string encoder
- fixes for Python 2.3
- PEP 8
- updates for
~pymongo.collection.Collection.group
- VS build
- fix for connection pooling under Python 2.5
- better build failure detection
- driver support for selecting fields in sub-documents
- disallow insertion of invalid key names
- added timeout parameter for
~pymongo.connection.Connection
- fix bug with large
~pymongo.cursor.Cursor.limit
- better exception when modules get reloaded out from underneath the C extension
- better exception messages when calling a
~pymongo.collection.Collection
or~pymongo.database.Database
instance
- support subclasses of
dict
in C encoder
- alias
~pymongo.connection.Connection
aspymongo.Connection
- raise an exception rather than silently overflowing in encoder
- added
~pymongo.collection.Collection.ensure_index
- allow sub-collections of $cmd as valid
~pymongo.collection.Collection
names - add version as
pymongo.version
- add
--no_ext
command line option to setup.py
python3 examples/gevent