mongo-python-driver Documentation

Technical Documentation: mongodb/mongo-python-driver

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

PyMongo

About

The PyMongo distribution contains tools for interacting with MongoDB
database from Python. The bson package is an implementation of the
BSON format for Python. The pymongo package is
a native Python driver for MongoDB, offering both synchronous and asynchronous APIs. The gridfs package is a
gridfs
implementation on top of pymongo.

PyMongo supports MongoDB 4.4, 5.0, 6.0, 7.0, 8.0, and 9.0. PyMongo follows semantic versioning for its releases.

Documentation

Documentation is available at
mongodb.com.

API documentation and the full changelog for each release is available at readthedocs.io.

Support / Feedback

For issues with, questions about, or feedback for PyMongo, please look
into our support channels. Please
do not email any of the PyMongo developers directly with issues or
questions - you're more likely to get an answer on
StackOverflow
(using a "mongodb" tag).

Bugs / Feature Requests

Think you've found a bug? Want to see a new feature in PyMongo? Please
open a case in our issue management tool, JIRA:

Create an account and login.
Navigate to the PYTHON
project.
Click Create Issue - Please provide as much information as
possible about the issue type and how to reproduce it.

Bug reports in JIRA for all driver projects (i.e. PYTHON, CSHARP, JAVA)
and the Core Server (i.e. SERVER) project are public.

How To Ask For Help

Please include all of the following information when opening an issue:

Detailed steps to reproduce the problem, including full traceback,
if possible.
The exact python version used, with patch level:

bash

python -c "import sys; print(sys.version)"

The exact version of PyMongo used, with patch level:

bash

python -c "import pymongo; print(pymongo.version); print(pymongo.has_c())"

The operating system and version (e.g. Windows 7, OSX 10.8, ...)
Web framework or asynchronous network library used, if any, with
version (e.g. Django 1.7, mod_wsgi 4.3.0, gevent 1.0.1, Tornado
4.0.2, ...)

Security Vulnerabilities

If you've identified a security vulnerability in a driver or any other
MongoDB project, please report it according to the instructions
here.

Installation

PyMongo can be installed with pip:

bash

python -m pip install pymongo

You can also download the project source and do:

bash

pip install .

Do not install the "bson" package from pypi. PyMongo comes with
its own bson package; running "pip install bson" installs a third-party
package that is incompatible with PyMongo.

Dependencies

PyMongo supports CPython 3.11+.

Required dependencies:

Support for mongodb+srv:// URIs requires dnspython

Optional dependencies:

GSSAPI authentication requires
pykerberos on Unix or
WinKerberos on Windows. The
correct dependency can be installed automatically along with PyMongo:

bash

python -m pip install "pymongo[gssapi]"

MONGODB-AWS authentication requires
pymongo-auth-aws:

bash

python -m pip install "pymongo[aws]"

OCSP (Online Certificate Status Protocol) requires
PyOpenSSL,
requests,
service_identity and may
require certifi:

bash

python -m pip install "pymongo[ocsp]"

Wire protocol compression with snappy requires
python-snappy:

bash

python -m pip install "pymongo[snappy]"

Wire protocol compression with zstandard requires
backports.zstd
when used with Python versions before 3.14:

bash

python -m pip install "pymongo[zstd]"

Client-Side Field Level Encryption requires
pymongocrypt and
pymongo-auth-aws:

bash

python -m pip install "pymongo[encryption]"

You can install all dependencies automatically with the following
command:

bash

python -m pip install "pymongo[gssapi,aws,ocsp,snappy,zstd,encryption]"

Examples

Here's a basic example (for more see the examples section of the
docs):

pycon

>>> import pymongo
>>> client = pymongo.MongoClient("localhost", 27017)
>>> db = client.test
>>> db.name
'test'
>>> db.my_collection
Collection(Database(MongoClient('localhost', 27017), 'test'), 'my_collection')
>>> db.my_collection.insert_one({"x": 10}).inserted_id
ObjectId('4aba15ebe23f6b53b0000000')
>>> db.my_collection.insert_one({"x": 8}).inserted_id
ObjectId('4aba160ee23f6b543e000000')
>>> db.my_collection.insert_one({"x": 11}).inserted_id
ObjectId('4aba160ee23f6b543e000002')
>>> db.my_collection.find_one()
{'x': 10, '_id': ObjectId('4aba15ebe23f6b53b0000000')}
>>> for item in db.my_collection.find():
...     print(item["x"])
...
10
8
11
>>> db.my_collection.create_index("x")
'x_1'
>>> for item in db.my_collection.find().sort("x", pymongo.ASCENDING):
...     print(item["x"])
...
8
10
11
>>> [item["x"] for item in db.my_collection.find().limit(2).skip(1)]
[8, 11]

Learning Resources

MongoDB Learn - Python
courses.
Python Articles on Developer
Center.

Testing

The easiest way to run the tests is to run the following from the repository root.

bash

pip install -e ".[test]"
pytest

For more advanced testing scenarios, see the contributing guide.

Overview (`integration_tests/README.md`)

Integration Tests

A set of tests that verify the usage of PyMongo with downstream packages or frameworks.

Each test uses PEP 723 inline metadata and can be run using pipx or uv.

The run.sh convenience script can be used to run all of the files using uv.

Here is an example header for the script with the inline dependencies:

python

# /// script
# dependencies = [
#   "uvloop>=0.18"
# ]
# requires-python = ">=3.10"
# ///

Here is an example of using the test helper function to create a configured client for the test:

python

import asyncio
import sys
from pathlib import Path

# Use pymongo from parent directory.
root = Path(__file__).parent.parent
sys.path.insert(0, str(root))

from test.asynchronous import async_simple_test_client  # noqa: E402


async def main():
    async with async_simple_test_client() as client:
        result = await client.admin.command("ping")
        assert result["ok"]


asyncio.run(main())

Overview (`test/lambda/README.md`)

AWS Lambda Testing

Running locally

Prerequisites:

AWS SAM CLI
Docker daemon running

Usage

Start a local mongodb instance on port 27017
Run build.sh
Run test.sh

Doc Changelog (`doc/changelog.rst`)

Changelog

Changes in Version 4.20.0 (2026/XX/XX)

Bug fixes
.........

Fixed a disagreement between the C extension and pure-Python BSON decoders
for binary elements with UUID subtypes (3 and 4) whose payload is not 16
bytes. Both now decode them to :class:~bson.binary.Binary under the
default UNSPECIFIED UUID representation, and raise
:class:~bson.errors.InvalidBSON when UUID conversion is requested
(PYTHON-6172_).
Fixed a bug where MongoClient(maxPoolSize=0, minPoolSize>0) raised
ValueError, even though maxPoolSize=0 means "no limit". The
minPoolSize <= maxPoolSize validation now treats both 0 and None
as unlimited (PYTHON-6149_).

.. _PYTHON-6172: https://jira.mongodb.org/browse/PYTHON-6172
.. _PYTHON-6149: https://jira.mongodb.org/browse/PYTHON-6149

Changes in Version 4.19.0 (2026/10/14)

PyMongo 4.19 brings a number of changes including:

.. warning:: PyMongo 4.19 drops support for Python 3.9 and 3.10 and removes
PyPy support: Python 3.11+ is now required.

Added support for Python 3.15.
Dropped support for Python 3.9 and 3.10.
Removed support for PyPy.
Removed the deprecated Algorithm.RANGEPREVIEW and
QueryType.RANGEPREVIEW members (PYTHON-6009_).
Added support for running the synchronous and asynchronous clients in
subinterpreters, including inside
concurrent.futures.InterpreterPoolExecutor (Python 3.14+). Only in
subinterpreters, which do not allow daemon threads, the synchronous
client's monitor threads now start as non-daemon threads and are stopped
and joined when the interpreter is torn down. Monitor threads in the main
interpreter remain daemon threads and shutdown behavior is unchanged.
Note that because these threads are non-daemon, a subinterpreter may block
on teardown until any in-flight monitor work completes.
Added support for routing Key Management Service (KMS) requests for
Client-Side Field Level Encryption and Queryable Encryption through an HTTP
proxy, using the new kms_connect_callback option on
:class:~pymongo.encryption_options.AutoEncryptionOpts,
:class:~pymongo.encryption.ClientEncryption, and
:class:~pymongo.asynchronous.encryption.AsyncClientEncryption. The callback
opens the connection and the driver performs the KMS TLS handshake over it, so
verification still targets the KMS host rather than the proxy. For an ordinary
HTTP proxy, pass :class:~pymongo.encryption_options.HTTPProxyKMSConnect or
:class:~pymongo.encryption_options.AsyncHTTPProxyKMSConnect instead of
writing a callback. Both helpers accept custom CONNECT headers, e.g.
Proxy-Authorization for proxies that require authentication.
Added the srv_host_validator keyword argument to
:class:~pymongo.synchronous.mongo_client.MongoClient and
:class:~pymongo.asynchronous.mongo_client.AsyncMongoClient, an alternative to
srvAllowedHostsSuffix for deployments whose acceptable SRV hosts cannot be
expressed as a single suffix. The callback is invoked once per SRV-returned
host and must return a boolean: True to accept the host and False to
reject it. During initial DNS discovery a non-boolean return raises an error;
during SRV polling it is treated as a rejection. It is mutually exclusive with
srvAllowedHostsSuffix and, because it takes a callable, cannot be set in a
connection string. See the
:class:~pymongo.synchronous.mongo_client.MongoClient and
:class:~pymongo.asynchronous.mongo_client.AsyncMongoClient documentation for
security considerations.
srvAllowedHostsSuffix may now be set to a single label reserved for
private or special use, such as localhost, test, or internal.

Bug fixes
.........

Fixed a bug where the synchronous client could permanently deadlock under
gevent when a greenlet was killed while checking a connection back into
the pool (PYTHON-6074_).
MongoClient.append_metadata() and AsyncMongoClient.append_metadata()
now detect duplicates by comparing the whole
:class:~pymongo.driver_info.DriverInfo instead of only its name. The
comparison is exact, so drivers that differ in name case or platform are no
longer treated as duplicates (PYTHON-6040_).
driver.name and driver.version in the handshake metadata are now
|-delimited lists with 1:1 index correspondence, including empty version
entries for the built-in |c and |async name segments
(PYTHON-6040_).
Fixed a bug where truncating the handshake metadata to 512 bytes could leave
driver.name and driver.version with different numbers of |
delimiters (PYTHON-6040_).
:class:~pymongo.driver_info.DriverInfo now raises :class:ValueError when
any field contains the reserved | delimiter (PYTHON-6040_).
Fixed a bug in SRV polling where invalid hosts where topology would not be
updated if one returned host was invalid.
Fixed a bug where the C extension's BSON decoder accepted documents whose
element data overlaps the document terminator instead of raising
InvalidBSON (PYTHON-6111_).
Fixed a bug where the pure-Python decode_all() accepted buffers ending
in a partial document instead of raising InvalidBSON, now matching the
C extension (PYTHON-6163_).

.. _PYTHON-6074: https://jira.mongodb.org/browse/PYTHON-6074
.. _PYTHON-6040: https://jira.mongodb.org/browse/PYTHON-6040
.. _PYTHON-6111: https://jira.mongodb.org/browse/PYTHON-6111
.. _PYTHON-6163: https://jira.mongodb.org/browse/PYTHON-6163
.. _PYTHON-6009: https://jira.mongodb.org/browse/PYTHON-6009

Issues Resolved
...............

See the PyMongo 4.19.0 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.19.0 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=52147

Changes in Version 4.18.2 (2026/09/24)

Version 4.18.2 is a bug fix release.

Hardened the bson buffer size guard against signed integer overflow. (CVE-2026-96749_).
Fixed connection string parsing to percent-decode each host individually. (CVE-2026-96748_).
Client-side field level encryption now rejects a KMS endpoint ending in .sock. (CVE-2026-96747_).

.. _CVE-2026-96749: https://www.cve.org/CVERecord?id=CVE-2026-96749
.. _CVE-2026-96748: https://www.cve.org/CVERecord?id=CVE-2026-96748
.. _CVE-2026-96747: https://www.cve.org/CVERecord?id=CVE-2026-96747

Issues Resolved
...............

See the PyMongo 4.18.2 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.18.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=52896

Changes in Version 4.18.1 (2026/09/10)

Version 4.18.1 is a bug fix release.

Use an exact match for the file ID in GridFS delete methods
(CVE-2026-88029_).

.. _CVE-2026-88029: https://www.cve.org/CVERecord?id=CVE-2026-88029

Changes in Version 4.18.0 (2026/09/03)

PyMongo 4.18 brings a number of changes including:

Added srvAllowedHostsSuffix as a URI option and keyword argument to
:class:~pymongo.synchronous.mongo_client.MongoClient and
:class:~pymongo.asynchronous.mongo_client.AsyncMongoClient. When connecting
via mongodb+srv://, this option overrides the default requirement that
SRV-returned hosts share the same parent domain as the seed hostname,
allowing hosts under a different domain suffix to be accepted. The suffix must
not be a public suffix (per the Public Suffix List <https://publicsuffix.org/list/>_). See the
:class:~pymongo.synchronous.mongo_client.MongoClient and
:class:~pymongo.asynchronous.mongo_client.AsyncMongoClient documentation for
security considerations.
Dropped support for MongoDB 4.2.
Added support for MongoDB 9.0.
PyPy support is deprecated and will be removed in a future release.
Improved TLS connection performance by reusing TLS sessions across connections
to the same server, avoiding a full handshake on each new connection.
Session resumption is supported on all Python versions for synchronous clients
and on Python 3.11+ for async clients.
Improved performance for MongoDB 9.0's Intelligent Workload Management (IWM) by only retrying overload errors when doing so is expected to not worsen server conditions.
Added support for exhaust cursors (:attr:~pymongo.cursor.CursorType.EXHAUST)
against mongos 7.1+. An older mongos still raises
:class:~pymongo.errors.InvalidOperation, now on the first iteration of the
cursor rather than from
:meth:~pymongo.synchronous.collection.Collection.find, since the requirement
is checked against the connection in use. Separately, async cursors combining
limit with :attr:~pymongo.cursor.CursorType.EXHAUST now raise at find
rather than on first iteration, matching the synchronous API.
Redacted potentially sensitive authentication mechanism properties, including
AWS session tokens, from the representations of
:class:~pymongo.synchronous.mongo_client.MongoClient and
:class:~pymongo.asynchronous.mongo_client.AsyncMongoClient.
Command monitoring events and command log messages for a single logical
operation now share one stable operation_id across all of its retry
attempts, so consumers can correlate a retried operation's events. As a
result, operation_id is no longer equal to the per-attempt request_id
for these operations.
Added validation of OP_COMPRESSED decompressed message size against
max_message_size to prevent memory exhaustion from maliciously crafted
compressed server responses.
Improved the performance and memory usage of decoding large documents to
:class:~bson.raw_bson.RawBSONDocument. Documents and subdocuments that are 4KB or greater
and decoded from an immutable buffer are now exposed as read-only :class:memoryview
slices instead of :class:bytes copies. Documents decoded from mutable buffers such as a
:class:bytearray are always :class:bytes copies.
:func:bson.get_data_and_view now returns a view of a private :class:bytes copy
for buffer-protocol inputs other than :class:bytes or :class:bytearray.
Improved the performance of lazily decoding a
:class:~bson.raw_bson.RawBSONDocument when the C extension is available.
Fixed a potential out-of-bounds read in the C extension when decoding an
array of BSON documents. An embedded document whose declared length exceeds
the bytes remaining in the array now raises
:class:~bson.errors.InvalidBSON instead of reading past the end of the
buffer.
Fixed :func:bson.json_util.loads to reject $timestamp values containing
fields other than t and i.
Fixed a bug on Windows, and on macOS when using PyOpenSSL, where
SSL_CERT_FILE/SSL_CERT_DIR were merged with, rather than replacing,
the OS/certifi certificate store.
Added general availability support for Queryable Encryption prefix, suffix,
and substring queries against MongoDB 9.0+. These queries require
libmongocrypt 1.20.0 or later:
- Added :attr:~pymongo.encryption.Algorithm.STRING and
  :class:~pymongo.encryption_options.StringOpts, replacing
  Algorithm.TEXTPREVIEW and TextOpts, which are now deprecated.
- Added :attr:~pymongo.encryption.QueryType.PREFIX,
  :attr:~pymongo.encryption.QueryType.SUFFIX, and
  :attr:~pymongo.encryption.QueryType.SUBSTRING. The corresponding
  PREFIXPREVIEW, SUFFIXPREVIEW, and SUBSTRINGPREVIEW query types
  remain for experimental use with MongoDB versions before 9.0.
- Added the string_opts parameter to
  :meth:~pymongo.encryption.ClientEncryption.encrypt and
  :meth:~pymongo.asynchronous.encryption.AsyncClientEncryption.encrypt,
  deprecating text_opts. pymongocrypt added text_opts in 1.16 and
  renamed it to string_opts in 1.19, and accepts only one of the two
  names per release, so passing text_opts with pymongocrypt 1.19 or
  later, string_opts with pymongocrypt 1.16 through 1.18, or both names
  at once, raises :exc:~pymongo.errors.ConfigurationError.
Aggregation helpers now raise :exc:~pymongo.errors.ConfigurationError when
passed an aggregate or pipeline keyword argument. Previously these
keys silently replaced the target namespace and pipeline of the generated
aggregate command. This affects
:meth:~pymongo.asynchronous.collection.AsyncCollection.aggregate and
:meth:~pymongo.synchronous.collection.Collection.aggregate,
:meth:~pymongo.asynchronous.collection.AsyncCollection.aggregate_raw_batches
and :meth:~pymongo.synchronous.collection.Collection.aggregate_raw_batches,
:meth:~pymongo.asynchronous.database.AsyncDatabase.aggregate and
:meth:~pymongo.synchronous.database.Database.aggregate, and
:meth:~pymongo.asynchronous.collection.AsyncCollection.list_search_indexes
and :meth:~pymongo.synchronous.collection.Collection.list_search_indexes.

Changes in Version 4.17.0 (2026/04/20)

PyMongo 4.17 brings a number of changes including:

has_key, iterkeys and itervalues in :class:bson.son.SON have
been deprecated and will be removed in PyMongo 5.0. These methods were
deprecated in favor of the standard dictionary containment operator in
and the keys() and values() methods, respectively.
Added the :meth:~pymongo.asynchronous.client_session.AsyncClientSession.bind and :meth:~pymongo.client_session.ClientSession.bind methods
that allow users to bind a session to all database operations within the scope of a context manager instead of having to explicitly pass the session to each individual operation.
See the Transactions docs <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/transactions/#methods>_ for examples and more information.
Added support for MongoDB's Intelligent Workload Management <https://www.mongodb.com/docs/atlas/intelligent-workload-management/>_ (IWM) and ingress connection rate limiting features in MongoDB server version 9.0.
The driver will gracefully handle write-blocking scenarios and optimizes connection establishment during high-load conditions to maintain application availability.

Changes in Version 4.16.0 (2026/01/07)

PyMongo 4.16 brings a number of changes including:

Removed invalid documents from :class:bson.errors.InvalidDocument error messages as
doing so may leak sensitive user data.
Instead, invalid documents are stored in :attr:bson.errors.InvalidDocument.document.
PyMongo now requires dnspython>=2.6.1, since dnspython 1.0 is no longer maintained.
The minimum version is 2.6.1 to account for CVE-2023-29483 <https://www.cve.org/CVERecord?id=CVE-2023-29483>_.
Removed support for Eventlet.
Eventlet is actively being sunset by its maintainers and has compatibility issues with PyMongo's dnspython dependency.
Use Zstandard support from the standard library for Python 3.14+, and use backports.zstd for older versions.
Fixed return type annotation for find_one_and_* methods on :class:~pymongo.asynchronous.collection.AsyncCollection
and :class:~pymongo.synchronous.collection.Collection to include None.
Added support for NumPy 1D-arrays in :class:bson.binary.BinaryVector.
Prevented :class:~pymongo.encryption.ClientEncryption from loading the crypt
shared library to fix "MongoCryptError: An existing crypt_shared library is
loaded by the application" unless the linked library search path is set.

Changes in Version 4.15.5 (2025/12/02)

Version 4.15.5 is a bug fix release.

Fixed a bug that could cause AutoReconnect("connection pool paused") errors when cursors fetched more documents from the database after SDAM heartbeat failures.

Changes in Version 4.15.4 (2025/10/21)

Version 4.15.4 is a bug fix release.

Relaxed the callback type of :meth:~pymongo.asynchronous.client_session.AsyncClientSession.with_transaction to allow the broader Awaitable type rather than only Coroutine objects.
Added the missing Python 3.14 trove classifier to the package metadata.

Issues Resolved
...............

See the PyMongo 4.15.4 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.15.4 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=47237

Changes in Version 4.15.3 (2025/10/07)

Version 4.15.3 is a bug fix release.

Fixed a memory leak when raising :class:bson.errors.InvalidDocument with C extensions.
Fixed the return type of the :meth:~pymongo.asynchronous.collection.AsyncCollection.distinct,
:meth:~pymongo.synchronous.collection.Collection.distinct, :meth:pymongo.asynchronous.cursor.AsyncCursor.distinct,
and :meth:pymongo.asynchronous.cursor.AsyncCursor.distinct methods.

Issues Resolved
...............

See the PyMongo 4.15.3 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.15.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=47293

Changes in Version 4.15.2 (2025/10/01)

Version 4.15.2 is a bug fix release.

Add wheels for Python 3.14 and 3.14t that were missing from 4.15.0 release. Drop the 3.13t wheel.

Issues Resolved
...............

See the PyMongo 4.15.2 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.15.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=47186

Changes in Version 4.15.1 (2025/09/16)

Version 4.15.1 is a bug fix release.

Fixed a bug in :meth:~pymongo.synchronous.encryption.ClientEncryption.encrypt
and :meth:~pymongo.asynchronous.encryption.AsyncClientEncryption.encrypt
that would cause a TypeError when using pymongocrypt<1.16 by passing
an unsupported type_opts parameter even if Queryable Encryption text
queries beta was not used.
Fixed a bug in AsyncMongoClient that caused a ServerSelectionTimeoutError
when used with uvicorn, FastAPI, or uvloop.

Issues Resolved
...............

See the PyMongo 4.15.1 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.15.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=46486

Changes in Version 4.15.0 (2025/09/10)

PyMongo 4.15 brings a number of changes including:

Added :class:~pymongo.encryption_options.TextOpts,
:attr:~pymongo.encryption.Algorithm.TEXTPREVIEW,
:attr:~pymongo.encryption.QueryType.PREFIXPREVIEW,
:attr:~pymongo.encryption.QueryType.SUFFIXPREVIEW,
:attr:~pymongo.encryption.QueryType.SUBSTRINGPREVIEW,
as part of the experimental Queryable Encryption text queries beta.
pymongocrypt>=1.16 is required for text query support.
Added :class:bson.decimal128.DecimalEncoder and
:class:bson.decimal128.DecimalDecoder
to support encoding and decoding of BSON Decimal128 values to
decimal.Decimal values using the TypeRegistry API.
Added support for Windows arm64 wheels.

Changes in Version 4.14.1 (2025/08/19)

Version 4.14.1 is a bug fix release.

Fixed a bug in MongoClient.append_metadata() and
AsyncMongoClient.append_metadata()
that allowed duplicate DriverInfo.name to be appended to the metadata.

Issues Resolved
...............

See the PyMongo 4.14.1 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.14.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=45256

Changes in Version 4.14.0 (2025/08/06)

.. warning:: PyMongo 4.14 drops support for MongoDB 4.0. PyMongo now supports
MongoDB 4.2+.

PyMongo 4.14 brings a number of changes including:

Dropped support for MongoDB 4.0.
Added preliminary support for Python 3.14 and 3.14 with free-threading. We do
not yet support the following with Python 3.14:
- Subinterpreters (concurrent.interpreters)
- Free-threading with Encryption
- mod_wsgi
Removed experimental support for free-threading support in Python 3.13.
Added :attr:bson.codec_options.TypeRegistry.codecs and
:attr:bson.codec_options.TypeRegistry.fallback_encoder properties
to allow users to directly access the type codecs and fallback encoder for a
given :class:bson.codec_options.TypeRegistry.
Added
:meth:pymongo.asynchronous.mongo_client.AsyncMongoClient.append_metadata and
:meth:pymongo.mongo_client.MongoClient.append_metadata to allow instantiated
MongoClients to send client metadata on-demand
Improved performance of selecting a server with the Primary selector.
Introduces a minor breaking change. When encoding
:class:bson.binary.BinaryVector, a ValueError will be raised if the
'padding' metadata field is < 0 or > 7, or non-zero for any type other than
PACKED_BIT.
Changed :meth:~pymongo.uri_parser.parse_uri's options return value to be
type dict instead of _CaseInsensitiveDictionary.

Issues Resolved
...............

See the PyMongo 4.14 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.14 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=43041

Changes in Version 4.13.2 (2025/06/17)

Version 4.13.2 is a bug fix release.

Fixed a bug where AsyncMongoClient would block the event loop while creating new connections,
potentially significantly increasing latency for ongoing operations.

Issues Resolved
...............

See the PyMongo 4.13.2 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.13.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=43937

Changes in Version 4.13.1 (2025/06/10)

Version 4.13.1 is a bug fix release.

Fixed a bug that could raise ServerSelectionTimeoutError when using timeouts with AsyncMongoClient.
Fixed a bug that could raise NetworkTimeout errors on Windows.

Issues Resolved
...............

See the PyMongo 4.13.1 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.13.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=43924

Changes in Version 4.13.0 (2025/05/14)

PyMongo 4.13 brings a number of changes including:

The asynchronous API is now stable and no longer in beta.
See the :mod:pymongo.asynchronous docs
or the migration guide <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/reference/migration/>_ for more information.
Fixed a bug where :class:pymongo.write_concern.WriteConcern repr was not eval-able
when using w="majority".
When padding is set, ignored bits in a BSON BinaryVector of PACKED_BIT dtype should be set to zero.
When encoding, this is enforced and is a breaking change.
It is not yet enforced when decoding, so reading from the database will not fail, however a warning will be triggered.
From PyMongo 5.0, this rule will be enforced for both encoding and decoding.

Issues Resolved
...............

See the PyMongo 4.13 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.13 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=42509

Changes in Version 4.12.1 (2025/04/29)

Version 4.12.1 is a bug fix release.

Fixed a bug that could raise UnboundLocalError when creating asynchronous connections over SSL.
Fixed a bug causing SRV hostname validation to fail when resolver and resolved hostnames are identical with three domain levels.
Fixed a bug that caused direct use of pymongo.uri_parser to raise an AttributeError.
Fixed a bug where clients created with connect=False and a "mongodb+srv://" connection string
could cause public pymongo.MongoClient and pymongo.AsyncMongoClient attributes (topology_description,
nodes, address, primary, secondaries, arbiters) to incorrectly return a Database, leading to type
errors such as: "NotImplementedError: Database objects do not implement truth value testing or bool()".
Removed Eventlet testing against Python versions newer than 3.9 since
Eventlet is actively being sunset by its maintainers and has compatibility issues with PyMongo's dnspython dependency.
Fixed a bug where MongoDB cluster topology changes could cause asynchronous operations to take much longer to complete
due to holding the Topology lock while closing stale connections.
Fixed a bug that would cause AsyncMongoClient to attempt to use PyOpenSSL when available, resulting in errors such as
"pymongo.errors.ServerSelectionTimeoutError: 'SSLContext' object has no attribute 'wrap_bio'".

Issues Resolved
...............

See the PyMongo 4.12.1 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.12.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=43094

Changes in Version 4.12.0 (2025/04/08)

.. warning:: Driver support for MongoDB 4.0 reached end of life in April 2025.
PyMongo 4.12 will be the last release to support MongoDB 4.0.

PyMongo 4.12 brings a number of changes including:

Support for configuring DEK cache lifetime via the key_expiration_ms argument to
:class:~pymongo.encryption_options.AutoEncryptionOpts.
Support for $lookup in CSFLE and QE supported on MongoDB 8.1+.
pymongocrypt>=1.13 is now required for In-Use Encryption <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/in-use-encryption/#in-use-encryption>_ support.
Added :meth:gridfs.asynchronous.grid_file.AsyncGridFSBucket.rename_by_name and :meth:gridfs.grid_file.GridFSBucket.rename_by_name
for more performant renaming of a file with multiple revisions.
Added :meth:gridfs.asynchronous.grid_file.AsyncGridFSBucket.delete_by_name and :meth:gridfs.grid_file.GridFSBucket.delete_by_name
for more performant deletion of a file with multiple revisions.
AsyncMongoClient no longer performs DNS resolution for "mongodb+srv://" connection strings on creation.
To avoid blocking the asyncio loop, the resolution is now deferred until the client is first connected.
Added index hinting support to the
:meth:~pymongo.asynchronous.collection.AsyncCollection.distinct and
:meth:~pymongo.collection.Collection.distinct commands.
Deprecated the hedge parameter for
:class:~pymongo.read_preferences.PrimaryPreferred,
:class:~pymongo.read_preferences.Secondary,
:class:~pymongo.read_preferences.SecondaryPreferred,
:class:~pymongo.read_preferences.Nearest. Support for hedge will be removed in PyMongo 5.0.
Removed PyOpenSSL support from the asynchronous API due to limitations of the CPython asyncio.Protocol SSL implementation.
Allow valid SRV hostnames with less than 3 parts.

Issues Resolved
...............

See the PyMongo 4.12 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.12 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=41916

Changes in Version 4.11.2 (2025/03/05)

Version 4.11.2 is a bug fix release.

Fixed a bug where :meth:~pymongo.database.Database.command would fail when attempting to run the bulkWrite command.

Issues Resolved
...............

See the PyMongo 4.11.2 release notes in JIRA_ for the list of resolved issues in this release.

.. _PyMongo 4.11.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=42506

Changes in Version 4.11.1 (2025/02/10)

Fixed support for prebuilt ppc64le and s390x wheels.

Changes in Version 4.11.0 (2025/01/28)

.. warning:: PyMongo 4.11 drops support for Python 3.8 and PyPy 3.9: Python 3.9+ or PyPy 3.10+ is now required.
.. warning:: PyMongo 4.11 drops support for MongoDB 3.6. PyMongo now supports MongoDB 4.0+.
Driver support for MongoDB 3.6 reached end of life in April 2024.
.. warning:: Driver support for MongoDB 4.0 reaches end of life in April 2025.
A future minor release of PyMongo will raise the minimum supported MongoDB Server version from 4.0 to 4.2.
This is in accordance with MongoDB Software Lifecycle Schedules.
Support for MongoDB Server 4.0 will be dropped in a future release!
.. warning:: This version does not include wheels for ppc64le or s390x architectures, see PYTHON-5058_ for more information.

PyMongo 4.11 brings a number of changes including:

Dropped support for Python 3.8 and PyPy 3.9.
Dropped support for MongoDB 3.6.
Dropped support for the MONGODB-CR authenticate mechanism, which is no longer supported by MongoDB 4.0+.
pymongocrypt>=1.12 is now required for In-Use Encryption <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/in-use-encryption/#in-use-encryption>_ support.
Added support for free-threaded Python with the GIL disabled. For more information see:
Free-threaded CPython <https://docs.python.org/3.13/whatsnew/3.13.html#whatsnew313-free-threaded-cpython>.
We do not yet support free-threaded Python on Windows (PYTHON-5027) or with In-Use Encryption (PYTHON-5024_).
:attr:~pymongo.asynchronous.mongo_client.AsyncMongoClient.address and
:attr:~pymongo.mongo_client.MongoClient.address now correctly block when called on unconnected clients
until either connection succeeds or a server selection timeout error is raised.
Added :func:repr support to :class:pymongo.operations.IndexModel.
Added :func:repr support to :class:pymongo.operations.SearchIndexModel.
Added sort parameter to
:meth:~pymongo.collection.Collection.update_one, :meth:~pymongo.collection.Collection.replace_one,
:class:~pymongo.operations.UpdateOne, and
:class:~pymongo.operations.UpdateMany,
:meth:~pymongo.mongo_client.MongoClient.bulk_write and
:meth:~pymongo.asynchronous.mongo_client.AsyncMongoClient.bulk_write now throw an error
when ordered=True or verboseResults=True are used with unacknowledged writes.
These are unavoidable breaking changes.
Fixed a bug in :const:bson.json_util.dumps where a :class:bson.datetime_ms.DatetimeMS would
be incorrectly encoded as '{"$date": "X"}' instead of '{"$date": X}' when using the
legacy MongoDB Extended JSON datetime representation.
Fixed a bug where :const:bson.json_util.loads would raise an IndexError when parsing an invalid
"$date" instead of a ValueError.

Issues Resolved
...............

See the PyMongo 4.11 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.11 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=40784
.. _PYTHON-5027: https://jira.mongodb.org/browse/PYTHON-5027
.. _PYTHON-5024: https://jira.mongodb.org/browse/PYTHON-5024
.. _PYTHON-5058: https://jira.mongodb.org/browse/PYTHON-5058

Changes in Version 4.10.1 (2024/10/01)

Version 4.10.1 is a bug fix release.

Fixed a bug where :meth:~pymongo.results.UpdateResult.did_upsert would raise a TypeError.
Fixed Binary BSON subtype (9) support on big-endian operating systems (such as zSeries).

Issues Resolved
...............

See the PyMongo 4.10.1 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.10.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=40788

Changes in Version 4.10.0 (2024/09/30)

Added provisional (BETA) support for a new Binary BSON subtype (9) used for efficient storage and retrieval of vectors:
densely packed arrays of numbers, all of the same type.
This includes new methods :meth:~bson.binary.Binary.from_vector and :meth:~bson.binary.Binary.as_vector.
Added C extension use to client metadata, for example: {"driver": {"name": "PyMongo|c", "version": "4.10.0"}, ...}
Fixed a bug where :class:~pymongo.asynchronous.mongo_client.AsyncMongoClient could deadlock.
Fixed a bug where PyMongo could fail to import on Windows if asyncio is misconfigured.

Issues Resolved
...............

See the PyMongo 4.10 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.10 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=40553

Changes in Version 4.9.2 (2024/10/02)

Fixed a bug where :class:~pymongo.asynchronous.mongo_client.AsyncMongoClient could deadlock.
Fixed a bug where PyMongo could fail to import on Windows if asyncio is misconfigured.
Fixed a bug where :meth:~pymongo.results.UpdateResult.did_upsert would raise a TypeError.

Issues Resolved
...............

See the PyMongo 4.9.2 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.9.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=40732

Changes in Version 4.9.1 (2024/09/18)

Add missing documentation about the fact the async API is in beta state.

Issues Resolved
...............

See the PyMongo 4.9.1 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.9.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=40720

Changes in Version 4.9 (2024/09/18)

.. warning:: Driver support for MongoDB 3.6 reached end of life in April 2024.
PyMongo 4.9 will be the last release to support MongoDB 3.6.

.. warning:: PyMongo 4.9 refactors a large portion of internal APIs to support the new asynchronous API beta.
As a result, versions of Motor older than 3.6 are not compatible with PyMongo 4.9.
Existing users of these versions must either upgrade to Motor 3.6 and PyMongo 4.9,
or cap their PyMongo version to < 4.9.
Any applications that use private APIs may also break as a result of these internal changes.

PyMongo 4.9 brings a number of improvements including:

Added support for MongoDB 8.0.
Added support for Python 3.13.
A new beta asynchronous API with full asyncio support.
This new asynchronous API is a work-in-progress that may change during the beta period before the full release.
Added support for In-Use Encryption range queries with MongoDB 8.0.
Added :attr:~pymongo.encryption.Algorithm.RANGE.
sparsity and trim_factor are now optional in :class:~pymongo.encryption_options.RangeOpts.
Added support for the "delegated" option for the KMIP master_key in
:meth:~pymongo.encryption.ClientEncryption.create_data_key.
pymongocrypt>=1.10 is now required for In-Use Encryption <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/in-use-encryption/#in-use-encryption>_ support.
Added :meth:~pymongo.cursor.Cursor.to_list to :class:~pymongo.cursor.Cursor,
:class:~pymongo.command_cursor.CommandCursor,
:class:~pymongo.asynchronous.cursor.AsyncCursor,
and :class:~pymongo.asynchronous.command_cursor.AsyncCommandCursor
as an asynchronous-friendly alternative to list(cursor).
Added :meth:~pymongo.mongo_client.MongoClient.bulk_write to :class:~pymongo.mongo_client.MongoClient
and :class:~pymongo.asynchronous.mongo_client.AsyncMongoClient,
enabling users to perform insert, update, and delete operations
against mixed namespaces in a minimized number of round trips.
Please see Client Bulk Write <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/bulk-write/#client-bulk-write-example>_ for more information.
Added support for the namespace parameter to the
:class:~pymongo.operations.InsertOne,
:class:~pymongo.operations.ReplaceOne,
:class:~pymongo.operations.UpdateOne,
:class:~pymongo.operations.UpdateMany,
:class:~pymongo.operations.DeleteOne, and
:class:~pymongo.operations.DeleteMany operations, so
they can be used in the new :meth:~pymongo.mongo_client.MongoClient.bulk_write.
Added :func:repr support to :class:bson.tz_util.FixedOffset.
Fixed a bug where PyMongo would raise InvalidBSON: unhashable type: 'tzfile'
when using :attr:~bson.codec_options.DatetimeConversion.DATETIME_CLAMP or
:attr:~bson.codec_options.DatetimeConversion.DATETIME_AUTO with a timezone from dateutil.
Fixed a bug where PyMongo would raise InvalidBSON: date value out of range
when using :attr:~bson.codec_options.DatetimeConversion.DATETIME_CLAMP or
:attr:~bson.codec_options.DatetimeConversion.DATETIME_AUTO with a non-UTC timezone.
Added a warning to unclosed MongoClient instances
telling users to explicitly close clients when finished with them to avoid leaking resources.
For example:

.. code-block::

sys:1: ResourceWarning: Unclosed MongoClient opened at:
File "/Users//my_file.py", line 8, in ``
client = MongoClient()

Call MongoClient.close() to safely shut down your client and free up resources.
The default value for connect in MongoClient is changed to False when running on
unction-as-a-service (FaaS) like AWS Lambda, Google Cloud Functions, and Microsoft Azure Functions.
On some FaaS systems, there is a fork() operation at function
startup. By delaying the connection to the first operation, we avoid a deadlock. See
multiple forks <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/mongoclient/#multiple-forks>_ for more information.

Issues Resolved
...............

See the PyMongo 4.9 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.9 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=39940

Changes in Version 4.8.0 (2024/06/26)

.. warning:: PyMongo 4.8 drops support for Python 3.7 and PyPy 3.8: Python 3.8+ or PyPy 3.9+ is now required.

PyMongo 4.8 brings a number of improvements including:

The handshake metadata for "os.name" on Windows has been simplified to "Windows" to improve import time.
The repr of bson.binary.Binary is now redacted when the subtype is SENSITIVE_SUBTYPE(8).
Secure Software Development Life Cycle automation for release process.
GitHub Releases now include a Software Bill of Materials, and signature
files corresponding to the distribution files released on PyPI.
Fixed a bug in change streams where both startAtOperationTime and resumeToken
could be added to a retry attempt, which caused the retry to fail.
Fallback to stdlib ssl module when pyopenssl import fails with AttributeError.
Improved performance of MongoClient operations, especially when many operations are being run concurrently.

Unavoidable breaking changes
............................

Since we are now using hatch as our build backend, we no longer have a usable setup.py file
and require installation using pip. Attempts to invoke the setup.py file will raise an exception.
Additionally, pip >= 21.3 is now required for editable installs.
We no longer support the srv extra, since dnspython is included as a dependency in PyMongo 4.7+.
Instead of pip install pymongo[srv], use pip install pymongo.
We no longer support the tls extra, which was only valid for Python 2.
Instead of pip install pymongo[tls], use pip install pymongo.

Issues Resolved
...............

See the PyMongo 4.8 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.8 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=37057

Changes in Version 4.7.3 (2024/06/04)

Version 4.7.3 has further fixes for lazily loading modules.

Use deferred imports instead of importlib lazy module loading.
Improve import time on Windows.
Reduce verbosity of "Waiting for suitable server to become available" log message from info to debug.

Issues Resolved
...............

See the PyMongo 4.7.3 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.7.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=39865

Changes in Version 4.7.2 (2024/05/07)

Version 4.7.2 fixes a bug introduced in 4.7.0:

Fixed a bug where PyMongo could not be used with the Nuitka compiler.

Issues Resolved
...............

See the PyMongo 4.7.2 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.7.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=39710

Changes in Version 4.7.1 (2024/04/30)

Version 4.7.1 fixes a bug introduced in 4.7.0:

Fixed a bug where PyMongo would cause an AttributeError if dns.resolver was imported and referenced
after PyMongo was imported.
Clarified the behavior of the TOKEN_RESOURCE auth mechanism property for MONGODB-OIDC.

Issues Resolved
...............

See the PyMongo 4.7.1 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.7.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=39680

Changes in Version 4.7.0 (2024/04/24)

PyMongo 4.7 brings a number of improvements including:

Added support for MONGODB-OIDC authentication. The MONGODB-OIDC mechanism authenticates
using an OpenID Connect (OIDC) access token.
The driver supports OIDC for workload identity, defined as an identity you assign to a software workload
(such as an application, service, script, or container) to authenticate and access other services and resources.
Please see Authentication <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/authentication/#authentication-mechanisms>_ for more information.
Added support for Python's native logging library <https://docs.python.org/3/howto/logging.html>,
enabling developers to customize the verbosity of log messages for their applications.
Please see Logging <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/monitoring-and-logging/logging/#logging> for more information.
Significantly improved the performance of encoding BSON documents to JSON.
Added support for named KMS providers for client side field level encryption.
Previously supported KMS providers were only: aws, azure, gcp, kmip, and local.
The KMS provider is now expanded to support name suffixes (e.g. local:myname).
Named KMS providers enables more than one of each KMS provider type to be configured.
See the docstring for :class:~pymongo.encryption_options.AutoEncryptionOpts.
Note that named KMS providers requires pymongocrypt >=1.9 and libmongocrypt >=1.9.
Added the :class:pymongo.hello.Hello.connection_id,
:attr:pymongo.monitoring.CommandStartedEvent.server_connection_id,
:attr:pymongo.monitoring.CommandSucceededEvent.server_connection_id, and
:attr:pymongo.monitoring.CommandFailedEvent.server_connection_id properties.
Fixed a bug where inflating a :class:~bson.raw_bson.RawBSONDocument containing a :class:~bson.code.Code would cause an error.
:meth:~pymongo.encryption.ClientEncryption.encrypt and
:meth:~pymongo.encryption.ClientEncryption.encrypt_expression now allow key_id
to be passed in as a :class:uuid.UUID.
Fixed a bug where :class:~bson.int64.Int64 instances could not always be encoded by orjson_. The following now
works::

import orjson
from bson import json_util
orjson.dumps({'a': Int64(1)}, default=json_util.default, option=orjson.OPT_PASSTHROUGH_SUBCLASS)

.. _orjson: https://github.com/ijl/orjson

Fixed a bug appearing in Python 3.12 where "RuntimeError: can't create new thread at interpreter shutdown"
could be written to stderr when a MongoClient's thread starts as the python interpreter is shutting down.
Added a warning when connecting to DocumentDB and CosmosDB clusters.
For more information regarding feature compatibility and support please visit
mongodb.com/supportability/documentdb <https://mongodb.com/supportability/documentdb>_ and
mongodb.com/supportability/cosmosdb <https://mongodb.com/supportability/cosmosdb>_.
Added the :attr:pymongo.monitoring.ConnectionCheckedOutEvent.duration,
:attr:pymongo.monitoring.ConnectionCheckOutFailedEvent.duration, and
:attr:pymongo.monitoring.ConnectionReadyEvent.duration properties.
Added the type and kwargs arguments to :class:~pymongo.operations.SearchIndexModel to enable
creating vector search indexes in MongoDB Atlas.
Fixed a bug where read_concern and write_concern were improperly added to
:meth:~pymongo.collection.Collection.list_search_indexes queries.
Deprecated :attr:pymongo.write_concern.WriteConcern.wtimeout and :attr:pymongo.mongo_client.MongoClient.wTimeoutMS.
Use :meth:~pymongo.timeout instead.

.. warning:: PyMongo depends on dnspython, which released version 2.6.1 with a fix for
CVE-2023-29483 <https://www.cve.org/CVERecord?id=CVE-2023-29483>_. We do not explicitly require
that version, but we strongly recommend that you install at least that version in your environment.

Unavoidable breaking changes
............................

Replaced usage of :class:bson.son.SON on all internal classes and commands to dict,
:attr:options.pool_options.metadata is now of type dict as opposed to :class:bson.son.SON.
Here's some examples of how this changes expected output as well as how to convert from :class:dict to :class:bson.son.SON::

Before

from pymongo import MongoClient
client = MongoClient()
client.options.pool_options.metadata
SON([('driver', SON([('name', 'PyMongo'), ('version', '4.7.0.dev0')])), ('os', SON([('type', 'Darwin'), ('name', 'Darwin'), ('architecture', 'arm64'), ('version', '14.3')])), ('platform', 'CPython 3.11.6.final.0')])

After

client.options.pool_options.metadata
{'driver': {'name': 'PyMongo', 'version': '4.7.0.dev0'}, 'os': {'type': 'Darwin', 'name': 'Darwin', 'architecture': 'arm64', 'version': '14.3'}, 'platform': 'CPython 3.11.6.final.0'}

To convert from dict to SON

This will only convert the first layer of the dictionary

data_as_dict = client.options.pool_options.metadata
SON(data_as_dict)
SON([('driver', {'name': 'PyMongo', 'version': '4.7.0.dev0'}), ('os', {'type': 'Darwin', 'name': 'Darwin', 'architecture': 'arm64', 'version': '14.3'}), ('platform', 'CPython 3.11.6.final.0')])

To convert from dict to SON on a nested dictionary

def dict_to_SON(data_as_dict: dict[Any, Any]):
... data_as_SON = SON()
... for key, value in data_as_dict.items():
... data_as_SON[key] = dict_to_SON(value) if isinstance(value, dict) else value
... return data_as_SON

dict_to_SON(data_as_dict)
SON([('driver', SON([('name', 'PyMongo'), ('version', '4.7.0.dev0')])), ('os', SON([('type', 'Darwin'), ('name', 'Darwin'), ('architecture', 'arm64'), ('version', '14.3')])), ('platform', 'CPython 3.11.6.final.0')])
PyMongo now uses lazy imports <https://docs.python.org/3/library/importlib.html#implementing-lazy-imports>_ for external dependencies.
If you are relying on any kind of monkey-patching of the standard library, you may need to explicitly import those external libraries in addition
to pymongo before applying the patch. Note that we test with gevent and eventlet patching, and those continue to work.
The "aws" extra now requires minimum version of 1.1.0 for pymongo_auth_aws.

Changes in Version 4.6.3 (2024/03/27)

PyMongo 4.6.3 fixes the following bug:

Fixed a potential memory access violation when decoding invalid bson.

Issues Resolved
...............

See the PyMongo 4.6.3 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.6.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=38360

Changes in Version 4.6.2 (2024/02/21)

PyMongo 4.6.2 fixes the following bug:

Fixed a bug appearing in Python 3.12 where "RuntimeError: can't create new thread at interpreter shutdown"
could be written to stderr when a MongoClient's thread starts as the python interpreter is shutting down.

Issues Resolved
...............

See the PyMongo 4.6.2 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.6.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=37906

Changes in Version 4.6.1 (2023/11/29)

PyMongo 4.6.1 fixes the following bug:

Ensure retryable read OperationFailure errors re-raise exception when 0 or NoneType error code is provided.

Issues Resolved
...............

See the PyMongo 4.6.1 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.6.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=37138

Changes in Version 4.6.0 (2023/11/01)

PyMongo 4.6 brings a number of improvements including:

Added the serverMonitoringMode URI and keyword argument to :class:~pymongo.mongo_client.MongoClient.
Improved client performance and reduced connection requirements in Function-as-a-service (FaaS)
environments like AWS Lambda, Google Cloud Functions, and Microsoft Azure Functions.
Added the :attr:pymongo.monitoring.CommandSucceededEvent.database_name property.
Added the :attr:pymongo.monitoring.CommandFailedEvent.database_name property.
Allow passing a dict to sort/create_index/hint.
Added :func:repr support to the write result classes:
:class:~pymongo.results.BulkWriteResult,
:class:~pymongo.results.DeleteResult,
:class:~pymongo.results.InsertManyResult,
:class:~pymongo.results.InsertOneResult,
:class:~pymongo.results.UpdateResult, and
:class:~pymongo.encryption.RewrapManyDataKeyResult. For example:

client.t.t.insert_one({})
InsertOneResult(ObjectId('65319acdd55bb3a27ab5502b'), acknowledged=True)
client.t.t.insert_many([{} for _ in range(3)])
InsertManyResult([ObjectId('6532f85e826f2b6125d6ce39'), ObjectId('6532f85e826f2b6125d6ce3a'), ObjectId('6532f85e826f2b6125d6ce3b')], acknowledged=True)
:meth:~pymongo.uri_parser.parse_uri now considers the delimiting slash (/)
between hosts and connection options optional. For example,
"mongodb://example.com?tls=true" is now a valid URI.
Fixed a bug where PyMongo would incorrectly promote all cursors to exhaust cursors
when connected to load balanced MongoDB clusters or Serverless clusters.
Added the network compression <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-options/network-compression/#compress-network-traffic>_ documentation page.
Added more timeout information to network errors.

Issues Resolved
...............

See the PyMongo 4.6 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.6 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=36542

Changes in Version 4.5.0 (2023/08/22)

PyMongo 4.5 brings a number of improvements including:

Added new helper methods for Atlas Search Index (requires MongoDB Server 7.0+):
:meth:~pymongo.collection.Collection.list_search_indexes,
:meth:~pymongo.collection.Collection.create_search_index,
:meth:~pymongo.collection.Collection.create_search_indexes,
:meth:~pymongo.collection.Collection.drop_search_index,
:meth:~pymongo.collection.Collection.update_search_index
Added :meth:~pymongo.database.Database.cursor_command
and :meth:~pymongo.command_cursor.CommandCursor.try_next to support
executing an arbitrary command that returns a cursor.
cryptography 2.5 or later is now required for OCSP <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls/#ocsp>_ support.
Improved bson encoding and decoding performance by up to 134%(PYTHON-3729, PYTHON-3797, PYTHON-3816, PYTHON-3817, PYTHON-3820, PYTHON-3824, and PYTHON-3846_).

.. warning:: PyMongo no longer supports PyPy3 versions older than 3.8. Users
must upgrade to PyPy3.8+.

Issues Resolved
...............

See the PyMongo 4.5 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.5 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=35492

.. _PYTHON-3729: https://jira.mongodb.org/browse/PYTHON-3729
.. _PYTHON-3797: https://jira.mongodb.org/browse/PYTHON-3797
.. _PYTHON-3816: https://jira.mongodb.org/browse/PYTHON-3816
.. _PYTHON-3817: https://jira.mongodb.org/browse/PYTHON-3817
.. _PYTHON-3820: https://jira.mongodb.org/browse/PYTHON-3820
.. _PYTHON-3824: https://jira.mongodb.org/browse/PYTHON-3824
.. _PYTHON-3846: https://jira.mongodb.org/browse/PYTHON-3846

Changes in Version 4.4.1 (2023/07/13)

Version 4.4.1 fixes the following bugs:

Fixed a bug where pymongo would raise a ConfigurationError: Invalid SRV host
error when connecting to a "mongodb+srv://" URI that included capital letters
in the SRV hosts returned from DNS. (PYTHON-3800_).
Fixed a minor reference counting bug in the C extension (PYTHON-3798_).

Issues Resolved
...............

See the PyMongo 4.4.1 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PYTHON-3798: https://jira.mongodb.org/browse/PYTHON-3798
.. _PYTHON-3800: https://jira.mongodb.org/browse/PYTHON-3800
.. _PyMongo 4.4.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=36329

Changes in Version 4.4.0 (2023/06/21)

PyMongo 4.4 brings a number of improvements including:

Added support for MongoDB 7.0.
Added support for Python 3.11.
Added support for passing a list containing (key, direction) pairs
or keys to :meth:~pymongo.collection.Collection.create_index.
Improved bson encoding performance (PYTHON-3717_ and PYTHON-3718_).
Improved support for Pyright to improve typing support for IDEs like Visual Studio Code
or Visual Studio.
Improved support for type-checking with MyPy "strict" mode (--strict).
Added :meth:~pymongo.encryption.ClientEncryption.create_encrypted_collection,
:class:~pymongo.errors.EncryptedCollectionError,
:meth:~pymongo.encryption.ClientEncryption.encrypt_expression,
:class:~pymongo.encryption_options.RangeOpts,
and :attr:~pymongo.encryption.Algorithm.RANGEPREVIEW as part of the experimental
Queryable Encryption beta.
pymongocrypt 1.6.0 or later is now required for In-Use Encryption <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/in-use-encryption/#in-use-encryption>_ support. MongoDB
Server 7.0 introduced a backwards breaking change to the QE protocol. Users taking
advantage of the Queryable Encryption beta must now upgrade to MongoDB 7.0+ and
PyMongo 4.4+.
Previously, PyMongo's docs recommended using :meth:datetime.datetime.utcnow and
:meth:datetime.datetime.utcfromtimestamp. utcnow and utcfromtimestamp are deprecated
in Python 3.12, for reasons explained in this Github issue_. Instead, users should
use :meth:datetime.datetime.now(tz=timezone.utc) and
:meth:datetime.datetime.fromtimestamp(tz=timezone.utc) instead.

.. _in this Github issue: https://github.com/python/cpython/issues/103857

Issues Resolved
...............

See the PyMongo 4.4 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.4 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=34354

.. _PYTHON-3717: https://jira.mongodb.org/browse/PYTHON-3717
.. _PYTHON-3718: https://jira.mongodb.org/browse/PYTHON-3718

Changes in Version 4.3.3 (2022/11/17)

Version 4.3.3 documents support for the following:

CSFLE on-demand credentials <https://www.mongodb.com/docs/v7.0/core/csfle/tutorials/aws/aws-automatic/?interface=driver&language=python#use-automatic-client-side-field-level-encryption-with-aws>_ for cloud KMS providers.
Authentication support for EKS Clusters <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/authentication/aws-iam/#assumerolewithwebidentity>_.
Added the timeout <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-options/csot/#limit-server-execution-time>_ example page to improve the documentation
for :func:pymongo.timeout.

Bug Fixes
.........

Fixed a performance regression in :meth:~gridfs.GridFSBucket.download_to_stream
and :meth:~gridfs.GridFSBucket.download_to_stream_by_name by reading in chunks
instead of line by line (PYTHON-3502_).
Improved performance of :meth:gridfs.grid_file.GridOut.read and
:meth:gridfs.grid_file.GridOut.readline (PYTHON-3508_).

Issues Resolved
...............

See the PyMongo 4.3.3 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PYTHON-3502: https://jira.mongodb.org/browse/PYTHON-3502
.. _PYTHON-3508: https://jira.mongodb.org/browse/PYTHON-3508
.. _PyMongo 4.3.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=34709

Changes in Version 4.3.2 (2022/10/18)

Note: We withheld uploading tags 4.3.0 and 4.3.1 to PyPI due to a
version handling error and a necessary documentation update.

dnspython <https://pypi.python.org/pypi/dnspython>_ is now a required
dependency. This change makes PyMongo easier to install for use with "mongodb+srv://"
connection strings and MongoDB Atlas <https://www.mongodb.com/cloud>_.

PyMongo 4.3 brings a number of improvements including:

Added support for decoding BSON datetimes outside of the range supported
by Python's :class:~datetime.datetime builtin. See
handling out of range datetimes <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/dates-and-times/#handling-out-of-range-datetimes>_ for examples, as well as
:class:bson.datetime_ms.DatetimeMS,
:class:bson.codec_options.DatetimeConversion, and
:class:bson.codec_options.CodecOptions's datetime_conversion
parameter for more details (PYTHON-1824_).
PyMongo now resets its locks and other shared state in the child process
after a :py:func:os.fork to reduce the frequency of deadlocks. Note that
deadlocks are still possible because libraries that PyMongo depends like
OpenSSL cannot be made fork() safe in multithreaded applications.
(PYTHON-2484). For more info see multiple forks <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/mongoclient/#multiple-forks>.
When used with MongoDB 6.0+, :class:~pymongo.change_stream.ChangeStream s
now allow for new types of events (such as DDL and C2C replication events)
to be recorded with the new parameter show_expanded_events
that can be passed to methods such as :meth:~pymongo.collection.Collection.watch.
PyMongo now internally caches AWS credentials that it fetches from AWS
endpoints, to avoid rate limitations. The cache is cleared when the
credentials expire or an error is encountered.
When using the MONGODB-AWS authentication mechanism with the
aws extra, the behavior of credential fetching has changed with
pymongo_auth_aws>=1.1.0. Please see Authentication <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/authentication/#authentication-mechanisms>_ for
more information.

Bug fixes
.........

Fixed a bug where :class:~pymongo.change_stream.ChangeStream
would allow an app to retry calling next() or try_next() even
after non-resumable errors (PYTHON-3389_).
Fixed a bug where the client could be unable to discover the new primary
after a simultaneous replica set election and reconfig (PYTHON-2970_).

Issues Resolved
...............

See the PyMongo 4.3 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PYTHON-1824: https://jira.mongodb.org/browse/PYTHON-1824
.. _PYTHON-2484: https://jira.mongodb.org/browse/PYTHON-2484
.. _PYTHON-2970: https://jira.mongodb.org/browse/PYTHON-2970
.. _PYTHON-3389: https://jira.mongodb.org/browse/PYTHON-3389
.. _PyMongo 4.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=33425

Changes in Version 4.2.0 (2022/07/20)

.. warning:: PyMongo 4.2 drops support for Python 3.6: Python 3.7+ is now required.

PyMongo 4.2 brings a number of improvements including:

Support for MongoDB 6.0.
Support for the Queryable Encryption beta with MongoDB 6.0. Note that backwards-breaking
changes may be made before the final release. See automatic queryable client-side encryption <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/in-use-encryption/#queryable-encryption>_ for example usage.
Provisional (beta) support for :func:pymongo.timeout to apply a single timeout
to an entire block of pymongo operations. See timeout <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-options/csot/#limit-server-execution-time>_ for examples.
Added the timeoutMS URI and keyword argument to :class:~pymongo.mongo_client.MongoClient.
Added the :attr:pymongo.errors.PyMongoError.timeout property which is True when
the error was caused by a timeout.
Added the check_exists argument to :meth:~pymongo.database.Database.create_collection
that when True (the default) runs an additional listCollections command to verify that the
collection does not exist already.
Added the following key management APIs to :class:~pymongo.encryption.ClientEncryption:
- :meth:~pymongo.encryption.ClientEncryption.get_key
- :meth:~pymongo.encryption.ClientEncryption.get_keys
- :meth:~pymongo.encryption.ClientEncryption.delete_key
- :meth:~pymongo.encryption.ClientEncryption.add_key_alt_name
- :meth:~pymongo.encryption.ClientEncryption.get_key_by_alt_name
- :meth:~pymongo.encryption.ClientEncryption.remove_key_alt_name
- :meth:~pymongo.encryption.ClientEncryption.rewrap_many_data_key
- :class:~pymongo.encryption.RewrapManyDataKeyResult
Support for the crypt_shared library to replace mongocryptd using the new
crypt_shared_lib_path and crypt_shared_lib_required arguments to
:class:~pymongo.encryption_options.AutoEncryptionOpts.

Bug fixes
.........

Fixed a bug where :meth:~pymongo.collection.Collection.estimated_document_count
would fail with a "CommandNotSupportedOnView" error on views (PYTHON-2885_).
Fixed a bug where invalid UTF-8 strings could be passed as patterns for :class:~bson.regex.Regex
objects. :func:bson.encode now correctly raises :class:bson.errors.InvalidStringData (PYTHON-3048_).
Fixed a bug that caused AutoReconnect("connection pool paused") errors in the child
process after fork (PYTHON-3257_).
Fixed a bug where :meth:~pymongo.collection.Collection.count_documents and
:meth:~pymongo.collection.Collection.distinct would fail in a transaction with
directConnection=True (PYTHON-3333_).
GridFS no longer uploads an incomplete files collection document after encountering an
error in the middle of an upload fork. This results in fewer
:class:~gridfs.errors.CorruptGridFile errors (PYTHON-1552_).
Renamed PyMongo's internal C extension methods to avoid crashing due to name conflicts
with mpi4py and other shared libraries (PYTHON-2110_).
Fixed tight CPU loop for network I/O when using PyOpenSSL (PYTHON-3187_).

Unavoidable breaking changes
............................

pymongocrypt 1.3.0 or later is now required for client side field level
encryption support.
:meth:~pymongo.collection.Collection.estimated_document_count now always uses
the count_ command. Due to an oversight in versions 5.0.0-5.0.8 of MongoDB,
the count command was not included in V1 of the Stable API <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-options/stable-api/#stable-api>.
Users of the Stable API with estimated_document_count are recommended to upgrade
their server version to 5.0.9+ or set :attr:pymongo.server_api.ServerApi.strict
to False to avoid encountering errors (PYTHON-3167).
Removed generic typing from :class:~pymongo.client_session.ClientSession to improve
support for Pyright (PYTHON-3283_).
Added __all__ to the bson, pymongo, and gridfs packages. This could be a breaking
change for apps that relied on from bson import * to import APIs not present in
__all__ (PYTHON-3311_).

.. _count: https://mongodb.com/docs/manual/reference/command/count/

Issues Resolved
...............

See the PyMongo 4.2 release notes in JIRA_ for the list of resolved issues
in this release.

Changes in Version 4.1.1 (2022/04/13)

Version 4.1.1 fixes a number of bugs:

Fixed a memory leak bug when calling :func:~bson.decode_all without a
codec_options argument (PYTHON-3222_).
Fixed a bug where :func:~bson.decode_all did not accept codec_options
as a keyword argument (PYTHON-3222_).
Fixed an oversight where type markers (py.typed files) were not included
in our release distributions (PYTHON-3214_).
Fixed a bug where pymongo would raise a "NameError: name sys is not defined"
exception when attempting to parse a "mongodb+srv://" URI when the dnspython
dependency was not installed (PYTHON-3198_).

Issues Resolved
...............

See the PyMongo 4.1.1 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PYTHON-3198: https://jira.mongodb.org/browse/PYTHON-3198
.. _PYTHON-3214: https://jira.mongodb.org/browse/PYTHON-3214
.. _PYTHON-3222: https://jira.mongodb.org/browse/PYTHON-3222
.. _PyMongo 4.1.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=33290

Changes in Version 4.1 (2021/12/07)

.. warning:: PyMongo 4.1 drops support for Python 3.6.0 and 3.6.1, Python 3.6.2+ is now required.

PyMongo 4.1 brings a number of improvements including:

Type Hinting support (formerly provided by pymongo-stubs). See Type Hints <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/run-command/#type-hints> for more information.
Added support for the comment parameter to all helpers. For example see
:meth:~pymongo.collection.Collection.insert_one.
Added support for the let parameter to
:meth:~pymongo.collection.Collection.update_one,
:meth:~pymongo.collection.Collection.update_many,
:meth:~pymongo.collection.Collection.delete_one,
:meth:~pymongo.collection.Collection.delete_many,
:meth:~pymongo.collection.Collection.replace_one,
:meth:~pymongo.collection.Collection.aggregate,
:meth:~pymongo.collection.Collection.find_one_and_delete,
:meth:~pymongo.collection.Collection.find_one_and_replace,
:meth:~pymongo.collection.Collection.find_one_and_update,
:meth:~pymongo.collection.Collection.find,
:meth:~pymongo.collection.Collection.find_one,
and :meth:~pymongo.collection.Collection.bulk_write.
let is a map of parameter names and values.
Parameters can then be accessed as variables in an aggregate expression
context.
:meth:~pymongo.collection.Collection.aggregate now supports
$merge and $out executing on secondaries on MongoDB >=5.0.
aggregate() now always obeys the collection's :attr:read_preference on
MongoDB >= 5.0.
:meth:gridfs.grid_file.GridOut.seek now returns the new position in the file, to
conform to the behavior of :meth:io.IOBase.seek.
Improved reuse of implicit sessions (PYTHON-2956_).

Bug fixes
.........

Fixed bug that would cause SDAM heartbeat timeouts and connection churn on
AWS Lambda and other FaaS environments (PYTHON-3186_).
Fixed bug where :class:~pymongo.mongo_client.MongoClient,
:class:~pymongo.database.Database, and :class:~pymongo.collection.Collection
mistakenly implemented :class:typing.Iterable (PYTHON-3084_).

Issues Resolved
...............

See the PyMongo 4.1 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=30619
.. _PYTHON-2956: https://jira.mongodb.org/browse/PYTHON-2956
.. _PYTHON-3084: https://jira.mongodb.org/browse/PYTHON-3084
.. _PYTHON-3186: https://jira.mongodb.org/browse/PYTHON-3186
.. _pymongo-stubs: https://github.com/mongodb-labs/pymongo-stubs

Changes in Version 4.0.2 (2022/03/03)

No changes

Changes in Version 4.0.1 (2021/12/07)

No changes

Changes in Version 4.0 (2021/11/29)

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

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

.. warning:: PyMongo 4.0 changes the default value of the directConnection URI option and
keyword argument to :class:~pymongo.mongo_client.MongoClient
to False instead of None, allowing for the automatic
discovery of replica sets. This means that if you
want a direct connection to a single server you must pass
directConnection=True as a URI option or keyword argument.
For more details, see the relevant section of the PyMongo 4.x migration
guide: :ref:pymongo4-migration-direct-connection.

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

Breaking Changes in 4.0
.......................

Removed support for Python 2.7, 3.4, and 3.5. Python 3.6.2+ is now required.
The default uuid_representation for :class:~bson.codec_options.CodecOptions,
:class:~bson.json_util.JSONOptions, and
:class:~pymongo.mongo_client.MongoClient has been changed from
:data:bson.binary.UuidRepresentation.PYTHON_LEGACY to
:data:bson.binary.UuidRepresentation.UNSPECIFIED. Attempting to encode a
:class:uuid.UUID instance to BSON or JSON now produces an error by default.
See UUID representations <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid/#universally-unique-ids--uuids->_ for details.
Removed the waitQueueMultiple keyword argument to
:class:~pymongo.mongo_client.MongoClient and removed
:exc:pymongo.errors.ExceededMaxWaiters.
Removed the socketKeepAlive keyword argument to
:class:~pymongo.mongo_client.MongoClient.
Removed :meth:pymongo.mongo_client.MongoClient.fsync,
:meth:pymongo.mongo_client.MongoClient.unlock, and
:attr:pymongo.mongo_client.MongoClient.is_locked.
Removed :meth:pymongo.mongo_client.MongoClient.database_names.
Removed :attr:pymongo.mongo_client.MongoClient.max_bson_size.
Removed :attr:pymongo.mongo_client.MongoClient.max_message_size.
Removed :attr:pymongo.mongo_client.MongoClient.max_write_batch_size.
Removed :attr:pymongo.mongo_client.MongoClient.event_listeners.
Removed :attr:pymongo.mongo_client.MongoClient.max_pool_size.
Removed :attr:pymongo.mongo_client.MongoClient.max_idle_time_ms.
Removed :attr:pymongo.mongo_client.MongoClient.local_threshold_ms.
Removed :attr:pymongo.mongo_client.MongoClient.server_selection_timeout.
Removed :attr:pymongo.mongo_client.MongoClient.retry_writes.
Removed :attr:pymongo.mongo_client.MongoClient.retry_reads.
Removed :meth:pymongo.database.Database.eval,
:data:pymongo.database.Database.system_js and
:class:pymongo.database.SystemJS.
Removed :meth:pymongo.database.Database.collection_names.
Removed :meth:pymongo.database.Database.current_op.
Removed :meth:pymongo.database.Database.authenticate and
:meth:pymongo.database.Database.logout.
Removed :meth:pymongo.database.Database.error,
:meth:pymongo.database.Database.last_status,
:meth:pymongo.database.Database.previous_error,
:meth:pymongo.database.Database.reset_error_history.
Removed :meth:pymongo.database.Database.add_user and
:meth:pymongo.database.Database.remove_user.
Removed support for database profiler helpers
:meth:~pymongo.database.Database.profiling_level,
:meth:~pymongo.database.Database.set_profiling_level,
and :meth:~pymongo.database.Database.profiling_info. Instead, users
should run the profile command_ with the
:meth:~pymongo.database.Database.command helper directly.
Removed :attr:pymongo.OFF, :attr:pymongo.SLOW_ONLY, and
:attr:pymongo.ALL.
Removed :meth:pymongo.collection.Collection.parallel_scan.
Removed :meth:pymongo.collection.Collection.ensure_index.
Removed :meth:pymongo.collection.Collection.reindex.
Removed :meth:pymongo.collection.Collection.save.
Removed :meth:pymongo.collection.Collection.insert.
Removed :meth:pymongo.collection.Collection.update.
Removed :meth:pymongo.collection.Collection.remove.
Removed :meth:pymongo.collection.Collection.find_and_modify.
Removed :meth:pymongo.collection.Collection.count.
Removed :meth:pymongo.collection.Collection.initialize_ordered_bulk_op,
:meth:pymongo.collection.Collection.initialize_unordered_bulk_op, and
:class:pymongo.bulk.BulkOperationBuilder. Use
:meth:pymongo.collection.Collection.bulk_write instead.
Removed :meth:pymongo.collection.Collection.group.
Removed :meth:pymongo.collection.Collection.map_reduce and
:meth:pymongo.collection.Collection.inline_map_reduce.
Removed the useCursor option for
:meth:~pymongo.collection.Collection.aggregate.
Removed :meth:pymongo.mongo_client.MongoClient.close_cursor. Use
:meth:pymongo.cursor.Cursor.close instead.
Removed :meth:pymongo.mongo_client.MongoClient.kill_cursors.
Removed :class:pymongo.cursor_manager.CursorManager and
:mod:pymongo.cursor_manager.
Removed :meth:pymongo.mongo_client.MongoClient.set_cursor_manager.
Removed :meth:pymongo.cursor.Cursor.count.
Removed :mod:pymongo.thread_util.
Removed :class:~pymongo.mongo_replica_set_client.MongoReplicaSetClient.
Removed :class:~pymongo.ismaster.IsMaster.
Use :class:~pymongo.hello.Hello instead.
Removed :mod:pymongo.son_manipulator,
:class:pymongo.son_manipulator.SONManipulator,
:class:pymongo.son_manipulator.ObjectIdInjector,
:class:pymongo.son_manipulator.ObjectIdShuffler,
:class:pymongo.son_manipulator.AutoReference,
:class:pymongo.son_manipulator.NamespaceInjector,
:meth:pymongo.database.Database.add_son_manipulator,
:attr:pymongo.database.Database.outgoing_copying_manipulators,
:attr:pymongo.database.Database.outgoing_manipulators,
:attr:pymongo.database.Database.incoming_copying_manipulators, and
:attr:pymongo.database.Database.incoming_manipulators.
Removed the manipulate and modifiers parameters from
:meth:~pymongo.collection.Collection.find,
:meth:~pymongo.collection.Collection.find_one,
:meth:~pymongo.collection.Collection.find_raw_batches, and
:meth:~pymongo.cursor.Cursor.
Removed :meth:pymongo.message.delete, :meth:pymongo.message.get_more,
:meth:pymongo.message.insert, :meth:pymongo.message.kill_cursors,
:meth:pymongo.message.query, and :meth:pymongo.message.update.
Removed :exc:pymongo.errors.NotMasterError.
Use :exc:pymongo.errors.NotPrimaryError instead.
Removed :exc:pymongo.errors.CertificateError.
Removed :attr:pymongo.GEOHAYSTACK.
Removed :class:bson.binary.UUIDLegacy.
Removed :const:bson.json_util.STRICT_JSON_OPTIONS. Use
:const:~bson.json_util.RELAXED_JSON_OPTIONS or
:const:~bson.json_util.CANONICAL_JSON_OPTIONS instead.
Changed the default JSON encoding representation from legacy to relaxed.
The json_mode parameter for :const:bson.json_util.dumps now defaults to
:const:~bson.json_util.RELAXED_JSON_OPTIONS.
Changed the BSON and JSON decoding behavior of :class:~bson.dbref.DBRef
to match the behavior outlined in the DBRef specification_ version 1.0.
Specifically, PyMongo now only decodes a subdocument into a
:class:~bson.dbref.DBRef if and only if, it contains both $ref and
$id fields and the $ref, $id, and $db fields are of the
correct type. Otherwise the document is returned as normal. Previously, any
subdocument containing a $ref field would be decoded as a
:class:~bson.dbref.DBRef.
The "tls" install extra is no longer necessary or supported and will be
ignored by pip.
The tz_aware argument to :class:~bson.json_util.JSONOptions
now defaults to False instead of True. :meth:bson.json_util.loads now
decodes datetime as naive by default. See :ref:tz_aware_default_change for more info.
directConnection URI option and keyword argument to :class:~pymongo.mongo_client.MongoClient
defaults to False instead of None, allowing for the automatic
discovery of replica sets. This means that if you
want a direct connection to a single server you must pass
directConnection=True as a URI option or keyword argument.
The hint option is now required when using min or max queries
with :meth:~pymongo.collection.Collection.find.
name is now a required argument for the :class:pymongo.driver_info.DriverInfo class.
When providing a "mongodb+srv://" URI to
:class:~pymongo.mongo_client.MongoClient constructor you can now use the
srvServiceName URI option to specify your own SRV service name.
:meth:~bson.son.SON.items now returns a dict_items object rather
than a list.
Removed :meth:bson.son.SON.iteritems.
:class:~pymongo.collection.Collection and :class:~pymongo.database.Database
now raises an error upon evaluating as a Boolean, please use the
syntax if collection is not None: or if database is not None: as
opposed to
the previous syntax which was simply if collection: or if database:.
You must now explicitly compare with None.
:class:~pymongo.mongo_client.MongoClient cannot execute any operations
after being closed. The previous behavior would simply reconnect. However,
now you must create a new instance.
Classes :class:~bson.int64.Int64, :class:~bson.min_key.MinKey,
:class:~bson.max_key.MaxKey, :class:~bson.timestamp.Timestamp,
:class:~bson.regex.Regex, and :class:~bson.dbref.DBRef all implement
__slots__ now. This means that their attributes are fixed, and new
attributes cannot be added to them at runtime.
Empty projections (eg {} or []) for
:meth:~pymongo.collection.Collection.find, and
:meth:~pymongo.collection.Collection.find_one
are passed to the server as-is rather than the previous behavior which
substituted in a projection of {"_id": 1}. This means that an empty
projection will now return the entire document, not just the "_id" field.
:class:~pymongo.mongo_client.MongoClient now raises a
:exc:~pymongo.errors.ConfigurationError when more than one URI is passed
into the hosts argument.
:class:~pymongo.mongo_client.MongoClient`` now raises an :exc:~pymongo.errors.InvalidURI` exception
when it encounters unescaped percent signs in username and password when
parsing MongoDB URIs.
Comparing two :class:~pymongo.mongo_client.MongoClient instances now
uses a set of immutable properties rather than
:attr:~pymongo.mongo_client.MongoClient.address which can change.
Removed the disable_md5 parameter for :class:~gridfs.GridFSBucket and
:class:~gridfs.GridFS. See :ref:removed-gridfs-checksum for details.
pymongocrypt 1.2.0 or later is now required for client side field level
encryption support.

Notable improvements
....................

Enhanced connection pooling to create connections more efficiently and
avoid connection storms.
Added the maxConnecting URI and
:class:~pymongo.mongo_client.MongoClient keyword argument.
:class:~pymongo.mongo_client.MongoClient now accepts a URI and keyword
argument srvMaxHosts that limits the number of mongos-like hosts a client
will connect to. More specifically, when a mongodb+srv:// connection string
resolves to more than srvMaxHosts number of hosts, the client will randomly
choose a srvMaxHosts sized subset of hosts.
Added :attr:pymongo.mongo_client.MongoClient.options for read-only access
to a client's configuration options.
Support for the "kmip" KMS provider for client side field level encryption.
See the docstring for :class:~pymongo.encryption_options.AutoEncryptionOpts
and :mod:~pymongo.encryption.

Issues Resolved
...............

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

.. _PyMongo 4.0 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=18463
.. _DBRef specification: https://github.com/mongodb/specifications/blob/master/source/dbref/dbref.md

Changes in Version 3.13.0 (2022/11/01)

Version 3.13 provides an upgrade path to PyMongo 4.x. Most of the API changes
from PyMongo 4.0 have been backported in a backward compatible way, allowing
applications to be written against PyMongo >= 3.13, rather then PyMongo 3.x or
PyMongo 4.x. See the PyMongo 4 Migration Guide_ for detailed examples.

Notable improvements
....................

Added :attr:pymongo.mongo_client.MongoClient.options for read-only access
to a client's configuration options.

Issues Resolved
...............

PyMongo 3.13 drops support for Python 3.4.

Bug fixes
.........

Fixed a memory leak bug when calling :func:~bson.decode_all without a
codec_options argument (PYTHON-3222_).
Fixed a bug where :func:~bson.decode_all did not accept codec_options
as a keyword argument (PYTHON-3222_).

Deprecations
............

Deprecated :meth:~pymongo.collection.Collection.map_reduce and
:meth:~pymongo.collection.Collection.inline_map_reduce.
Use :meth:~pymongo.collection.Collection.aggregate instead.
Deprecated :attr:pymongo.mongo_client.MongoClient.event_listeners.
Use :attr:~pymongo.mongo_client.options.event_listeners instead.
Deprecated :attr:pymongo.mongo_client.MongoClient.max_pool_size.
Use :attr:~pymongo.mongo_client.options.pool_options.max_pool_size instead.
Deprecated :attr:pymongo.mongo_client.MongoClient.max_idle_time_ms.
Use :attr:~pymongo.mongo_client.options.pool_options.max_idle_time_seconds instead.
Deprecated :attr:pymongo.mongo_client.MongoClient.local_threshold_ms.
Use :attr:~pymongo.mongo_client.options.local_threshold_ms instead.
Deprecated :attr:pymongo.mongo_client.MongoClient.server_selection_timeout.
Use :attr:~pymongo.mongo_client.options.server_selection_timeout instead.
Deprecated :attr:pymongo.mongo_client.MongoClient.retry_writes.
Use :attr:~pymongo.mongo_client.options.retry_writes instead.
Deprecated :attr:pymongo.mongo_client.MongoClient.retry_reads.
Use :attr:~pymongo.mongo_client.options.retry_reads instead.
Deprecated :attr:pymongo.mongo_client.MongoClient.max_bson_size,
:attr:pymongo.mongo_client.MongoClient.max_message_size, and
:attr:pymongo.mongo_client.MongoClient.max_write_batch_size. These helpers
were incorrect when in loadBalanced=true mode and ambiguous in clusters
with mixed versions. Use the hello command_ to get the authoritative
value from the remote server instead. Code like this::

max_bson_size = client.max_bson_size
max_message_size = client.max_message_size
max_write_batch_size = client.max_write_batch_size

can be changed to this::

text

doc = client.admin.command('hello')
max_bson_size = doc['maxBsonObjectSize']
max_message_size = doc['maxMessageSizeBytes']
max_write_batch_size = doc['maxWriteBatchSize']

.. _hello command: https://docs.mongodb.com/manual/reference/command/hello/

See the PyMongo 3.13.0 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PyMongo 4 Migration Guide: https://pymongo.readthedocs.io/en/stable/migrate-to-pymongo4.html
.. _PYTHON-3222: https://jira.mongodb.org/browse/PYTHON-3222
.. _PyMongo 3.13.0 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=31570

Changes in Version 3.12.3 (2021/12/07)

Issues Resolved
...............

Version 3.12.3 fixes a bug that prevented :meth:bson.json_util.loads from
decoding a document with a non-string "$regex" field (PYTHON-3028_).

See the PyMongo 3.12.3 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PYTHON-3028: https://jira.mongodb.org/browse/PYTHON-3028
.. _PyMongo 3.12.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=32505

Changes in Version 3.12.2 (2021/11/29)

Issues Resolved
...............

Version 3.12.2 fixes a number of bugs:

Fixed a bug that prevented PyMongo from retrying bulk writes
after a writeConcernError on MongoDB 4.4+ (PYTHON-2984_).
Fixed a bug that could cause the driver to hang during automatic
client side field level encryption (PYTHON-3017_).

See the PyMongo 3.12.2 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PYTHON-2984: https://jira.mongodb.org/browse/PYTHON-2984
.. _PYTHON-3017: https://jira.mongodb.org/browse/PYTHON-3017
.. _PyMongo 3.12.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=32310

Changes in Version 3.12.1 (2021/10/19)

Issues Resolved
...............

Version 3.12.1 fixes a number of bugs:

Fixed a bug that caused a multi-document transaction to fail when the first
operation was large bulk write (>48MB) that required splitting a batched
write command (PYTHON-2915_).
Fixed a bug that caused the tlsDisableOCSPEndpointCheck URI option to
be applied incorrectly (PYTHON-2866_).

See the PyMongo 3.12.1 release notes in JIRA_ for the list of resolved issues
in this release.

.. _PYTHON-2915: https://jira.mongodb.org/browse/PYTHON-2915
.. _PYTHON-2866: https://jira.mongodb.org/browse/PYTHON-2866
.. _PyMongo 3.12.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=31527

Changes in Version 3.12.0 (2021/07/13)

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

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

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

Notable improvements
....................

Added support for MongoDB 5.0.
Support for MongoDB Stable API, see :class:~pymongo.server_api.ServerApi.
Support for snapshot reads on secondaries (see snapshot reads <https://www.mongodb.com/docs/manual/reference/read-concern-snapshot/#read-concern--snapshot->_).
Support for Azure and GCP KMS providers for client side field level
encryption. See the docstring for :class:~pymongo.mongo_client.MongoClient,
:class:~pymongo.encryption_options.AutoEncryptionOpts,
and :mod:~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 and
expireAfterSeconds arguments to
:meth:~pymongo.database.Database.create_collection.
Added :attr:pymongo.mongo_client.MongoClient.topology_description.
Added hash support to :class:~pymongo.mongo_client.MongoClient,
:class:~pymongo.database.Database and
:class:~pymongo.collection.Collection (PYTHON-2466_).
Improved the error message returned by
:meth:~pymongo.collection.Collection.insert_many when supplied with an
argument of incorrect type (PYTHON-1690_).
Added session and read concern support to
:meth:~pymongo.collection.Collection.find_raw_batches
and :meth:~pymongo.collection.Collection.aggregate_raw_batches.

Bug fixes
.........

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

Deprecations
............

Deprecated support for Python 2.7, 3.4 and 3.5.
Deprecated support for database profiler helpers
:meth:~pymongo.database.Database.profiling_level,
:meth:~pymongo.database.Database.set_profiling_level,
and :meth:~pymongo.database.Database.profiling_info. Instead, users
should run the profile command_ with the
:meth:~pymongo.database.Database.command helper directly.
Deprecated :exc:~pymongo.errors.NotMasterError. Users should
use :exc:~pymongo.errors.NotPrimaryError instead.
Deprecated :class:~pymongo.ismaster.IsMaster and :mod:~pymongo.ismaster
which will be removed in PyMongo 4.0 and are replaced by
:class:~pymongo.hello.Hello and :mod:~pymongo.hello which provide the
same API.
Deprecated the :mod:pymongo.messeage module.
Deprecated the ssl_keyfile and ssl_certfile URI options in favor
of tlsCertificateKeyFile (see TLS <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls/#configure-transport-layer-security--tls->_).

.. _PYTHON-2466: https://jira.mongodb.org/browse/PYTHON-2466
.. _PYTHON-1690: https://jira.mongodb.org/browse/PYTHON-1690
.. _PYTHON-2472: https://jira.mongodb.org/browse/PYTHON-2472
.. _profile command: https://mongodb.com/docs/manual/reference/command/profile/

Issues Resolved
...............

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

.. _PyMongo 3.12.0 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=29594

Changes in Version 3.11.3 (2021/02/02)

Issues Resolved
...............

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

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

.. _PYTHON-2452: https://jira.mongodb.org/browse/PYTHON-2452
.. _PyMongo 3.11.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=30355

Changes in Version 3.11.2 (2020/12/02)

Issues Resolved
...............

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
:exc:~pymongo.errors.BulkWriteError (PYTHON-2438_).
Fixed a bug that made it impossible to use
:meth:bson.codec_options.CodecOptions.with_options and
:meth:~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
of :meth:collections.namedtuple._asdict (PYTHON-2440_).
Fixed a bug that resulted in a :exc:TypeError exception when a PyOpenSSL
socket was configured with a timeout of None (PYTHON-2443_).

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

.. _PYTHON-2433: https://jira.mongodb.org/browse/PYTHON-2433
.. _PYTHON-2438: https://jira.mongodb.org/browse/PYTHON-2438
.. _PYTHON-2440: https://jira.mongodb.org/browse/PYTHON-2440
.. _PYTHON-2443: https://jira.mongodb.org/browse/PYTHON-2443
.. _PyMongo 3.11.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=30315

Changes in Version 3.11.1 (2020/11/17)

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
:class:~pymongo.mongo_client.MongoClient,
:class:~pymongo.encryption_options.AutoEncryptionOpts,
and :mod:~pymongo.encryption. Note: Backwards-breaking changes may be
made before the final release.
Fixed a bug where the :class:bson.json_util.JSONOptions API did not match
the :class:bson.codec_options.CodecOptions API due to the absence of
a :meth:bson.json_util.JSONOptions.with_options method. This method has now
been added.
Fixed a bug which made it impossible to serialize
:class:~pymongo.errors.BulkWriteError instances using :mod:pickle.
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 :mod:bson module when using a
:class:~bson.codec_options.TypeRegistry.

Issues Resolved
...............

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

.. _PyMongo 3.11.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=29997

Changes in Version 3.11.0 (2020/07/30)

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

Support for OCSP <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls/#ocsp>_ (Online Certificate Status Protocol).
Support for PyOpenSSL <https://pypi.org/project/pyOpenSSL/>_ as an
alternative TLS implementation. PyOpenSSL is required for OCSP <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls/#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 <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/authentication/aws-iam/#aws-identity-and-access-management>_ authentication mechanism.
Support for the directConnection URI option and kwarg to
:class:~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
:meth:~pymongo.database.Database.create_collection on MongoDB 4.4+.
Added index hinting support to the
:meth:~pymongo.collection.Collection.replace_one,
:meth:~pymongo.collection.Collection.update_one,
:meth:~pymongo.collection.Collection.update_many,
:meth:~pymongo.collection.Collection.find_one_and_replace,
:meth:~pymongo.collection.Collection.find_one_and_update,
:meth:~pymongo.collection.Collection.delete_one,
:meth:~pymongo.collection.Collection.delete_many, and
:meth:~pymongo.collection.Collection.find_one_and_delete commands.
Added index hinting support to the
:class:~pymongo.operations.ReplaceOne,
:class:~pymongo.operations.UpdateOne,
:class:~pymongo.operations.UpdateMany,
:class:~pymongo.operations.DeleteOne, and
:class:~pymongo.operations.DeleteMany bulk operations.
Added support for :data:bson.binary.UuidRepresentation.UNSPECIFIED and
MongoClient(uuidRepresentation='unspecified') which will become the
default UUID representation starting in PyMongo 4.0. See
UUID representations <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid/#universally-unique-ids--uuids->_ for details.
New methods :meth:bson.binary.Binary.from_uuid and
:meth:bson.binary.Binary.as_uuid.
Added the background parameter to
:meth:pymongo.database.Database.validate_collection. For a description
of this parameter see the MongoDB documentation for the validate command_.
Added the allow_disk_use parameters to
:meth:pymongo.collection.Collection.find.
Added the hedge parameter to
:class:~pymongo.read_preferences.PrimaryPreferred,
:class:~pymongo.read_preferences.Secondary,
:class:~pymongo.read_preferences.SecondaryPreferred,
:class:~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 to
:meth:pymongo.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 :meth:pymongo.collection.Collection.reindex. Use
:meth:~pymongo.database.Database.command to run the reIndex command
instead.
Deprecated :meth:pymongo.mongo_client.MongoClient.fsync. Use
:meth:~pymongo.database.Database.command to run the fsync command
instead.
Deprecated :meth:pymongo.mongo_client.MongoClient.unlock. Use
:meth:~pymongo.database.Database.command to run the fsyncUnlock command
instead. See the documentation for more information.
Deprecated :attr:pymongo.mongo_client.MongoClient.is_locked. Use
:meth:~pymongo.database.Database.command to run the currentOp command
instead. See the documentation for more information.
Deprecated :class:bson.binary.UUIDLegacy. Use
:meth:bson.binary.Binary.from_uuid instead.

Unavoidable breaking changes:

:class:~gridfs.GridFSBucket and :class:~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

.. _validate command: https://mongodb.com/docs/manual/reference/command/validate/

Issues Resolved
...............

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

.. _PyMongo 3.11.0 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=24799

Changes in Version 3.10.1 (2020/01/07)

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 :meth:pymongo.mongo_client.MongoClient.close.
Avoid creating new connections during
:meth:pymongo.mongo_client.MongoClient.close.

Issues Resolved
...............

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

.. _PyMongo 3.10.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=25039

Changes in Version 3.10.0 (2019/12/10)

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
Client-Side Field Level Encryption <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/in-use-encryption/#client-side-field-level-encryption>_ for examples.
Support for Python 3.8.
Added :attr:pymongo.client_session.ClientSession.in_transaction.
Do not hold the Topology lock while creating connections in a MongoClient's
background thread. This change fixes a bug where application operations would
block while the background thread ensures that all server pools have
minPoolSize connections.
Fix a UnicodeDecodeError bug when coercing a PyMongoError with a non-ascii
error message to unicode on Python 2.
Fix an edge case bug where PyMongo could exceed the server's
maxMessageSizeBytes when generating a compressed bulk write command.

Issues Resolved
...............

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

.. _PyMongo 3.10 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=23944

Changes in Version 3.9.0 (2019/08/13)

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 <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/transactions/#transactions>_.
New method :meth: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
:class:~pymongo.mongo_client.MongoClient,
:class:~pymongo.encryption_options.AutoEncryptionOpts,
and :mod:~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
:meth:~pymongo.client_session.ClientSession.start_transaction.
Implement the URI options specification_ in the
:meth:~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 older ssl option has been retained
  as an alias to the new tls option.
- wTimeout has been deprecated in favor of wTimeoutMS.
- wTimeoutMS now overrides wTimeout if the user provides both.
- j has been deprecated in favor of journal.
- journal now overrides j if the user provides both.
- ssl_cert_reqs has been deprecated in favor of tlsAllowInvalidCertificates.
  Instead of ssl.CERT_NONE, ssl.CERT_OPTIONAL and ssl.CERT_REQUIRED, the
  new option expects a boolean value - True is equivalent to ssl.CERT_NONE,
  while False is equivalent to ssl.CERT_REQUIRED.
- ssl_match_hostname has been deprecated in favor of tlsAllowInvalidHostnames.
- ssl_ca_certs has been deprecated in favor of tlsCAFile.
- ssl_certfile has been deprecated in favor of tlsCertificateKeyFile.
- ssl_pem_passphrase has been deprecated in favor of tlsCertificateKeyFilePassword.
- 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 retryWrites URI option now defaults to True. Supported write
operations that fail with a retryable error will automatically be retried one
time, with at-most-once semantics.
Support for retryable reads and the retryReads URI option which is
enabled by default. See the :class:~pymongo.mongo_client.MongoClient
documentation for details. Now that supported operations are retried
automatically and transparently, users should consider adjusting any custom
retry logic to prevent an application from inadvertently retrying for too
long.
Support zstandard for wire protocol compression.
Support for periodically polling DNS SRV records to update the mongos proxy
list without having to change client configuration.
New method :meth:pymongo.database.Database.aggregate to support running
database level aggregations.
Support for publishing Connection Monitoring and Pooling events via the new
:class:~pymongo.monitoring.ConnectionPoolListener class. See
:mod:~pymongo.monitoring for an example.
:meth:pymongo.collection.Collection.aggregate and
:meth:pymongo.database.Database.aggregate now support the $merge pipeline
stage and use read preference
:attr:~pymongo.read_preferences.ReadPreference.PRIMARY if the $out or
$merge pipeline stages are used.
Support for specifying a pipeline or document in
:meth:~pymongo.collection.Collection.update_one,
:meth:~pymongo.collection.Collection.update_many,
:meth:~pymongo.collection.Collection.find_one_and_update,
:meth:~pymongo.operations.UpdateOne, and
:meth:~pymongo.operations.UpdateMany.
New BSON utility functions :func:~bson.encode and :func:~bson.decode
:class:~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
:attr:~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 :class:~pymongo.mongo_client.MongoClient constructor's keyword argument
(e.g. MongoClient("mongodb://my.mongodb.cluster/db", retryWrites=False))
to avoid running into :class:~pymongo.errors.OperationFailure exceptions
during write operations. The MMAPv1 storage engine is deprecated and does
not support retryable writes which are now turned on by default.
In order to ensure that the connectTimeoutMS URI option is honored when
connecting to clusters with a mongodb+srv:// connection string, the
minimum required version of the optional dnspython dependency has been
bumped to 1.16.0. This is a breaking change for applications that use
PyMongo's SRV support with a version of dnspython older than 1.16.0.

.. _URI options specification: https://github.com/mongodb/specifications/blob/master/source/uri-options/uri-options.md

Issues Resolved
...............

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

.. _PyMongo 3.9 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=21787

Changes in Version 3.8.0 (2019/04/22)

.. 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 <https://wiki.centos.org/AdditionalResources/Repositories/SCL>_

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

:class:~bson.objectid.ObjectId now implements the ObjectID specification version 0.2 <https://github.com/mongodb/specifications/blob/master/source/bson-objectid/objectid.md>_.
For better performance and to better follow the GridFS spec,
:class:~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 :meth:~pymongo.collection.Collection.find_one.
:meth: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.
:meth:~pymongo.database.Database.current_op now always uses the
Database's :attr:~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 :meth:~pymongo.mongo_client.MongoClient.get_default_database
and added the default parameter.
TLS Renegotiation is now disabled when possible.
Custom types can now be directly encoded to, and decoded from MongoDB using
the :class:~bson.codec_options.TypeCodec and
:class:~bson.codec_options.TypeRegistry APIs. For more information, see
Custom Types <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/custom-types/type-codecs/#encode-data-with-type-codecs>_.
Attempting a multi-document transaction on a sharded cluster now raises a
:exc:~pymongo.errors.ConfigurationError.
:meth:pymongo.cursor.Cursor.distinct and
:meth:pymongo.cursor.Cursor.count now send the Cursor's
:meth:~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
:meth:~pymongo.database.Database.list_collection_names.
Changes can now be requested from a ChangeStream cursor without blocking
indefinitely using the new
:meth:pymongo.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 :meth:~pymongo.cursor.Cursor.min
and/or :meth:~pymongo.cursor.Cursor.max but do not also set a
:meth:~pymongo.cursor.Cursor.hint of which index to use. The find command
is expected to require a :meth:~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.
:class:~bson.raw_bson.RawBSONDocument now validates that the bson_bytes
passed in represent a single bson document. Earlier versions would mistakenly
accept multiple bson documents.
Iterating over a :class:~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 Customize Server Selection <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-options/server-selection/#customize-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.

Issues Resolved
...............

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

.. _PyMongo 3.8 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=19904

Changes in Version 3.7.2 (2018/10/10)

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 :meth:pymongo.collection.Collection.ensure_index
to only cache a single index per database.
Updated the documentation examples to use
:meth:pymongo.collection.Collection.count_documents instead of
:meth:pymongo.collection.Collection.count and
:meth:pymongo.cursor.Cursor.count.

Issues Resolved
...............

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

.. _PyMongo 3.7.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=21519

Changes in Version 3.7.1 (2018/07/16)

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

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

Issues Resolved
...............

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

.. _PyMongo 3.7.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=21096

Changes in Version 3.7.0 (2018/06/26)

Version 3.7 adds support for MongoDB 4.0. Highlights include:

Support for single replica set multi-document ACID transactions.
See transactions <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/transactions/#transactions>_.
Support for wire protocol compression via the new compressors URI and keyword argument to
:meth:~pymongo.mongo_client.MongoClient. See network compression <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-options/network-compression/#compress-network-traffic>_ for details.
Support for Python 3.7.
New count methods, :meth:~pymongo.collection.Collection.count_documents
and :meth:~pymongo.collection.Collection.estimated_document_count.
:meth:~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 deprecated
:meth:pymongo.collection.Collection.count and
:meth:pymongo.cursor.Cursor.count methods.
Support for watching changes on all collections in a database using the
new :meth:pymongo.database.Database.watch method.
Support for watching changes on all collections in all databases using the
new :meth: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 the watch() 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 <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/authentication/scram/#scram>_
  authentication mechanism. The GSSAPI <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/authentication/kerberos/#kerberos--gssapi->,
  PLAIN <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/authentication/ldap/#overview>, and MONGODB-X509 <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/authentication/x509/#x.509>_
  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 :class:~gridfs.GridFS and :class:~gridfs.GridFSBucket.
- :class:~bson.objectid.ObjectId machine bytes are now hashed using
  FNV-1a <https://en.wikipedia.org/wiki/Fowler-Noll-Vo_hash_function>_
  instead of MD5.
The :meth:~pymongo.database.Database.list_collection_names and
:meth:~pymongo.database.Database.collection_names methods use
the nameOnly option when supported by MongoDB.
The :meth:pymongo.collection.Collection.watch method now returns an
instance of the :class:~pymongo.change_stream.CollectionChangeStream
class which is a subclass of :class:~pymongo.change_stream.ChangeStream.
SCRAM client and server keys are cached for improved performance, following
RFC 5802 <https://tools.ietf.org/html/rfc5802>_.
If not specified, the authSource for the PLAIN <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/authentication/ldap/#overview>_
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:
:meth:~pymongo.collection.Collection.insert_one,
:meth:~pymongo.collection.Collection.replace_one,
:meth:~pymongo.collection.Collection.update_one,
:meth:~pymongo.collection.Collection.update_many.

Deprecations:

Deprecated :meth:pymongo.collection.Collection.count and
:meth:pymongo.cursor.Cursor.count. These two methods use the count
command and may or may not be accurate <https://mongodb.com/docs/manual/reference/command/count/#behavior>_,
depending on the options used and connected MongoDB topology. Use
:meth:~pymongo.collection.Collection.count_documents instead.
Deprecated the snapshot option of :meth:~pymongo.collection.Collection.find
and :meth:~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 :meth:~pymongo.collection.Collection.find
and :meth:~pymongo.collection.Collection.find_one. The option was
deprecated in MongoDB 4.0. Use maxTimeMS instead.
Deprecated :meth:~pymongo.mongo_client.MongoClient.close_cursor. Use
:meth:~pymongo.cursor.Cursor.close instead.
Deprecated :meth:~pymongo.mongo_client.MongoClient.database_names. Use
:meth:~pymongo.mongo_client.MongoClient.list_database_names instead.
Deprecated :meth:~pymongo.database.Database.collection_names. Use
:meth:~pymongo.database.Database.list_collection_names instead.
Deprecated :meth:~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
:class:~pymongo.errors.NotMasterError instead of
:class:~pymongo.errors.OperationFailure.
:meth:~pymongo.collection.Collection.parallel_scan no longer uses an
implicit session. Explicit sessions are still supported.
Unacknowledged writes (w=0) with an explicit session parameter now
raise a client side error. Since PyMongo does not wait for a response for an
unacknowledged write, two unacknowledged writes run serially by the client
may be executed simultaneously on the server. However, the server requires a
single session must not be used simultaneously by more than one operation.
Therefore explicit sessions cannot support unacknowledged writes.
Unacknowledged writes without a session parameter are still supported.

Issues Resolved
...............

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

.. _PyMongo 3.7 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=19287

Changes in Version 3.6.1 (2018/03/01)

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 after
maxIdleTimeMS milliseconds.
:attr:pymongo.mongo_client.MongoClient.max_idle_time_ms now returns
milliseconds instead of seconds.
Properly import and use the
monotonic <https://pypi.python.org/pypi/monotonic>_
library for monotonic time when it is installed.
:meth:~pymongo.collection.Collection.aggregate now ignores the
batchSize argument when running a pipeline with a $out stage.
Always send handshake metadata for new connections.

Issues Resolved
...............

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

.. _PyMongo 3.6.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=19438

Changes in Version 3.6.0 (2017/08/23)

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

Highlights include:

Support for change streams. See the
:meth:~pymongo.collection.Collection.watch method for details.
Support for array_filters in
:meth:~pymongo.collection.Collection.update_one,
:meth:~pymongo.collection.Collection.update_many,
:meth:~pymongo.collection.Collection.find_one_and_update,
:meth:~pymongo.operations.UpdateOne, and
:meth:~pymongo.operations.UpdateMany.
New Session API, see :meth:~pymongo.mongo_client.MongoClient.start_session.
New methods :meth:~pymongo.collection.Collection.find_raw_batches and
:meth:~pymongo.collection.Collection.aggregate_raw_batches for use with
external libraries that can parse raw batches of BSON data.
New methods :meth:~pymongo.mongo_client.MongoClient.list_databases and
:meth:~pymongo.mongo_client.MongoClient.list_database_names.
New methods :meth:~pymongo.database.Database.list_collections and
:meth:~pymongo.database.Database.list_collection_names.
Support for mongodb+srv:// URIs. See
:class:~pymongo.mongo_client.MongoClient for details.
Index management helpers
(:meth:~pymongo.collection.Collection.create_index,
:meth:~pymongo.collection.Collection.create_indexes,
:meth:~pymongo.collection.Collection.drop_index,
:meth:~pymongo.collection.Collection.drop_indexes,
:meth:~pymongo.collection.Collection.reindex) now support maxTimeMS.
Support for retryable writes and the retryWrites URI option. See
:class:~pymongo.mongo_client.MongoClient for details.

Deprecations:

The useCursor option for :meth:~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 :meth:~pymongo.database.Database.add_user and
:meth:~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
:meth:~pymongo.database.Database.authenticate and
:meth:~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 :class:~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 :data:bson.binary.JAVA_LEGACY or
:data:bson.binary.CSHARP_LEGACY to decode BSON binary subtype 4. Other
UUID representations, :data:bson.binary.PYTHON_LEGACY (the default) and
:data:bson.binary.STANDARD, and the decoding of BSON binary subtype 3
are unchanged.

Issues Resolved
...............

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

.. _PyMongo 3.6 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=18043

Changes in Version 3.5.1 (2017/08/23)

Version 3.5.1 fixes bugs reported since the release of 3.5.0:

Work around socket.getsockopt issue with NetBSD.
:meth: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.

Issues Resolved
...............

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

.. _PyMongo 3.5.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=18721

Changes in Version 3.5.0 (2017/08/08)

Version 3.5 implements a number of improvements and bug fixes:

Highlights include:

Username and password can be passed to
:class:~pymongo.mongo_client.MongoClient as keyword arguments. Before, the
only way to pass them was in the URI.
Increased the performance of using :class:~bson.raw_bson.RawBSONDocument.
Increased the performance of
:meth:~pymongo.mongo_client.MongoClient.database_names by using the
nameOnly option for listDatabases when available.
Increased the performance of
:meth:~pymongo.collection.Collection.bulk_write by reducing the memory
overhead of :class:~pymongo.operations.InsertOne,
:class:~pymongo.operations.DeleteOne, and
:class:~pymongo.operations.DeleteMany.
Added the collation option to :class:~pymongo.operations.DeleteOne,
:class:~pymongo.operations.DeleteMany,
:class:~pymongo.operations.ReplaceOne,
:class:~pymongo.operations.UpdateOne, and
:class:~pymongo.operations.UpdateMany.
Implemented the MongoDB Extended JSON <https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md>_
specification.
:class:~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:

:meth:~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 :meth:~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 :meth:~pymongo.collection.Collection.aggregate
with the $group pipeline stage instead.
Deprecated :meth:~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
:class:~pymongo.mongo_client.MongoClient.
Deprecated :meth:~pymongo.database.Database.eval. The eval command
was deprecated in MongoDB 3.0 and will be removed in a future server version.
Deprecated :class:~pymongo.database.SystemJS.
Deprecated :meth:~pymongo.mongo_client.MongoClient.get_default_database.
Applications should use
:meth:~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? <https://mongodb.com/docs/manual/faq/diagnostics/#does-tcp-keepalive-time-affect-mongodb-deployments->_
Deprecated :meth:~pymongo.collection.Collection.initialize_ordered_bulk_op,
:meth:~pymongo.collection.Collection.initialize_unordered_bulk_op, and
:class:~pymongo.bulk.BulkOperationBuilder. Use
:meth:~pymongo.collection.Collection.bulk_write instead.
Deprecated :const:~bson.json_util.STRICT_JSON_OPTIONS. Use
:const:~bson.json_util.RELAXED_JSON_OPTIONS or
:const:~bson.json_util.CANONICAL_JSON_OPTIONS instead.
If a custom :class:~bson.codec_options.CodecOptions is passed to
:class:RawBSONDocument, its ``document_class``` must be
:class:RawBSONDocument.
:meth:~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
:class:~pymongo.command_cursor.CommandCursor to make the behavior
consistent across all MongoDB versions.
In Python 3, :meth:~bson.json_util.loads now automatically decodes JSON
$binary with a subtype of 0 into :class:bytes instead of
:class:~bson.binary.Binary.
:meth:~bson.json_util.loads now raises TypeError or ValueError
when parsing JSON type wrappers with values of the wrong type or any
extra keys.
:meth:pymongo.cursor.Cursor.close and
:meth:pymongo.mongo_client.MongoClient.close
now kill cursors synchronously instead of deferring to a background thread.
:meth:~pymongo.uri_parser.parse_uri now returns the original value
of the readPreference MongoDB URI option instead of the validated read
preference mode.

Issues Resolved
...............

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

.. _PyMongo 3.5 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=17590

Changes in Version 3.4.0 (2016/11/29)

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 Collation <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/configure/#collation>_.
- Support for the new :class:~bson.decimal128.Decimal128 BSON type.
- A new maxStalenessSeconds read preference option.
- A username is no longer required for the MONGODB-X509 authentication
  mechanism when connected to MongoDB >= 3.4.
- :meth:~pymongo.collection.Collection.parallel_scan supports maxTimeMS.
- :attr:~pymongo.write_concern.WriteConcern is automatically
  applied by all helpers for commands that write to the database when
  connected to MongoDB 3.4+. This change affects the following helpers:
  - :meth:~pymongo.mongo_client.MongoClient.drop_database
  - :meth:~pymongo.database.Database.create_collection
  - :meth:~pymongo.database.Database.drop_collection
  - :meth:~pymongo.collection.Collection.aggregate (when using $out)
  - :meth:~pymongo.collection.Collection.create_indexes
  - :meth:~pymongo.collection.Collection.create_index
  - :meth:~pymongo.collection.Collection.drop_indexes
  - :meth:~pymongo.collection.Collection.drop_indexes
  - :meth:~pymongo.collection.Collection.drop_index
  - :meth:~pymongo.collection.Collection.map_reduce (when output is not
    "inline")
  - :meth:~pymongo.collection.Collection.reindex
  - :meth:~pymongo.collection.Collection.rename
Improved support for logging server discovery and monitoring events. See
:mod:~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
:class:~bson.json_util.JSONOptions.
Allow :class:~bson.code.Code objects to have a scope of None,
signifying no scope. Also allow encoding Code objects with an empty scope
(i.e. {}).

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

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

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.

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

Issues Resolved
...............

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

.. _PyMongo 3.4 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=16594

Changes in Version 3.3.1 (2016/10/27)

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

Issues Resolved
...............

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

.. _PyMongo 3.3.1 release notes in Jira: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=17636

Changes in Version 3.3.0 (2016/07/12)

Version 3.3 adds the following major new features:

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

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

Issues Resolved
...............

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

.. _PyMongo 3.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=16005

Changes in Version 3.2.2 (2016/03/15)

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

Issues Resolved
...............

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

.. _PyMongo 3.2.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=16538

Changes in Version 3.2.1 (2016/02/02)

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

Issues Resolved
...............

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

.. _PyMongo 3.2.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=16312

Changes in Version 3.2 (2015/12/07)

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

Highlights include:

Full support for MongoDB 3.2 including:
- Support for :class:~pymongo.read_concern.ReadConcern
- :class:~pymongo.write_concern.WriteConcern is now applied to
  :meth:~pymongo.collection.Collection.find_one_and_replace,
  :meth:~pymongo.collection.Collection.find_one_and_update, and
  :meth:~pymongo.collection.Collection.find_one_and_delete.
- Support for the new bypassDocumentValidation option in write
  helpers.
Support for reading and writing raw BSON with
:class:~bson.raw_bson.RawBSONDocument

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

Issues Resolved
...............

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

.. _PyMongo 3.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=15612

Changes in Version 3.1.1 (2015/11/17)

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

Issues Resolved
...............

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

.. _PyMongo 3.1.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=16211

Changes in Version 3.1 (2015/11/02)

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 :mod:~pymongo.monitoring for details.
Configurable error handling for :exc:UnicodeDecodeError. See the
unicode_decode_error_handler option of
:class:~bson.codec_options.CodecOptions.
Optional automatic timezone conversion when decoding BSON datetime. See the
tzinfo option of :class:~bson.codec_options.CodecOptions.
An implementation of :class:~gridfs.GridFSBucket from the new GridFS spec.
Compliance with the new Connection String spec.
Reduced idle CPU usage in Python 2.

Changes in internal classes
...........................

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

Issues Resolved
...............

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

.. _PyMongo 3.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=14796

Changes in Version 3.0.3 (2015/06/30)

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

Issues Resolved
...............

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

.. _PyMongo 3.0.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=15528

Changes in Version 3.0.2 (2015/05/12)

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

Issues Resolved
...............

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

.. _PyMongo 3.0.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=15430

Changes in Version 3.0.1 (2015/04/21)

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

Issues Resolved
...............

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

.. _PyMongo 3.0.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=15322

Changes in Version 3.0 (2015/04/07)

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

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

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

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

SONManipulator changes
......................

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

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

SSL/TLS changes
...............

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

Gevent Support
..............

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

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

For more information,
see Gevent <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/#gevent>_.

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

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

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

The :class:~pymongo.mongo_client.MongoClient constructor no
longer blocks while connecting to the server or servers, and it no
longer raises :class:~pymongo.errors.ConnectionFailure if they
are unavailable, nor :class:~pymongo.errors.ConfigurationError
if the user's credentials are wrong. Instead, the constructor
returns immediately and launches the connection process on
background threads. The connect option is added to control whether
these threads are started immediately, or when the client is first used.

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

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

text

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 load balancing <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-targets/#replica-sets>_ 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 <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/configure/#read-and-write-settings>_ of
PRIMARY.

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

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

The copy_database method is removed, see Copy and Clone Databases <https://www.mongodb.com/docs/database-tools/mongodump/mongodump-examples/#copy-and-clone-databases>_ for alternatives.

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

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

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

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

The following read-only attributes have been added:

:attr:~pymongo.mongo_client.MongoClient.codec_options

The following attributes are now read-only:

:attr:~pymongo.mongo_client.MongoClient.read_preference
:attr:~pymongo.mongo_client.MongoClient.write_concern

The following attributes have been removed:

:attr:~pymongo.mongo_client.MongoClient.document_class
(use :attr:~pymongo.mongo_client.MongoClient.codec_options instead)
:attr:~pymongo.mongo_client.MongoClient.host
(use :attr:~pymongo.mongo_client.MongoClient.address instead)
:attr:~pymongo.mongo_client.MongoClient.min_wire_version
:attr:~pymongo.mongo_client.MongoClient.max_wire_version
:attr:~pymongo.mongo_client.MongoClient.port
(use :attr:~pymongo.mongo_client.MongoClient.address instead)
:attr:~pymongo.mongo_client.MongoClient.safe
(use :attr:~pymongo.mongo_client.MongoClient.write_concern instead)
:attr:~pymongo.mongo_client.MongoClient.slave_okay
(use :attr:~pymongo.mongo_client.MongoClient.read_preference instead)
:attr:~pymongo.mongo_client.MongoClient.tag_sets
(use :attr:~pymongo.mongo_client.MongoClient.read_preference instead)
:attr:~pymongo.mongo_client.MongoClient.tz_aware
(use :attr:~pymongo.mongo_client.MongoClient.codec_options instead)

The following attributes have been renamed:

:attr:~pymongo.mongo_client.MongoClient.secondary_acceptable_latency_ms is
now :attr:~pymongo.mongo_client.MongoClient.local_threshold_ms and is now
read-only.

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

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

Cursor management changes
.........................

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

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

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

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

The following read-only attributes have been added:

:attr:~pymongo.database.Database.codec_options

The following attributes are now read-only:

:attr:~pymongo.database.Database.read_preference
:attr:~pymongo.database.Database.write_concern

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

The following attributes have been removed:

:attr:~pymongo.database.Database.safe
:attr:~pymongo.database.Database.secondary_acceptable_latency_ms
:attr:~pymongo.database.Database.slave_okay
:attr:~pymongo.database.Database.tag_sets

The following methods have been added:

:meth:~pymongo.database.Database.get_collection

The following methods have been changed:

:meth:~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
:class:~bson.codec_options.CodecOptions as codec_options and an instance
of a read preference class from :mod:~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 :class:~bson.regex.Regex.

The following methods have been deprecated:

:meth:~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
:class:~pymongo.write_concern.WriteConcern with
:meth:~pymongo.mongo_client.MongoClient.get_database instead.

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

The following read-only attributes have been added:

:attr:~pymongo.collection.Collection.codec_options

The following attributes are now read-only:

:attr:~pymongo.collection.Collection.read_preference
:attr:~pymongo.collection.Collection.write_concern

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

The following attributes have been removed:

:attr:~pymongo.collection.Collection.safe
:attr:~pymongo.collection.Collection.secondary_acceptable_latency_ms
:attr:~pymongo.collection.Collection.slave_okay
:attr:~pymongo.collection.Collection.tag_sets

The following methods have been added:

:meth:~pymongo.collection.Collection.bulk_write
:meth:~pymongo.collection.Collection.insert_one
:meth:~pymongo.collection.Collection.insert_many
:meth:~pymongo.collection.Collection.update_one
:meth:~pymongo.collection.Collection.update_many
:meth:~pymongo.collection.Collection.replace_one
:meth:~pymongo.collection.Collection.delete_one
:meth:~pymongo.collection.Collection.delete_many
:meth:~pymongo.collection.Collection.find_one_and_delete
:meth:~pymongo.collection.Collection.find_one_and_replace
:meth:~pymongo.collection.Collection.find_one_and_update
:meth:~pymongo.collection.Collection.with_options
:meth:~pymongo.collection.Collection.create_indexes
:meth:~pymongo.collection.Collection.list_indexes

The following methods have changed:

:meth:~pymongo.collection.Collection.aggregate now always returns an
instance of :class:~pymongo.command_cursor.CommandCursor. See the
documentation for all options.
:meth:~pymongo.collection.Collection.count now optionally takes a filter
argument, as well as other options supported by the count command.
:meth:~pymongo.collection.Collection.distinct now optionally takes a filter
argument.
:meth:~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:

:meth:~pymongo.collection.Collection.save
:meth:~pymongo.collection.Collection.insert
:meth:~pymongo.collection.Collection.update
:meth:~pymongo.collection.Collection.remove
:meth:~pymongo.collection.Collection.find_and_modify
:meth:~pymongo.collection.Collection.ensure_index

The following methods have been removed:

Changes to :meth:~pymongo.collection.Collection.find and :meth:~pymongo.collection.Collection.find_one

text

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

Issues resolved
...............

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

Changes in Version 1.10.1 (2011/04/07)
--------------------------------------

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 :class:`~pymongo.errors.AutoReconnect`
  :class:`~pymongo.master_slave_connection.MasterSlaveConnection` will now
  retry the query on each slave until it is successful or all slaves have
  raised :class:`~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
  :class:`~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.

Issues resolved
...............

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

Changes in Version 1.10 (2011/03/30)
------------------------------------

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 :meth:`~pymongo.collection.Collection.find_and_modify`.
- added :meth:`~pymongo.collection.Collection.inline_map_reduce`.
- changed :meth:`~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. :meth:`~pymongo.collection.Collection.map_reduce` now
   requires the ``out`` parameter.

Issues resolved
...............

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

Changes in Version 1.9 (2010/09/28)
-----------------------------------

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

  - :mod:`pymongo.bson` -> :mod:`bson`
  - :mod:`pymongo._cbson` -> :mod:`bson._cbson` and
    :mod:`pymongo._cmessage`
  - :mod:`pymongo.binary` -> :mod:`bson.binary`
  - :mod:`pymongo.code` -> :mod:`bson.code`
  - :mod:`pymongo.dbref` -> :mod:`bson.dbref`
  - :mod:`pymongo.json_util` -> :mod:`bson.json_util`
  - :mod:`pymongo.max_key` -> :mod:`bson.max_key`
  - :mod:`pymongo.min_key` -> :mod:`bson.min_key`
  - :mod:`pymongo.objectid` -> :mod:`bson.objectid`
  - :mod:`pymongo.son` -> :mod:`bson.son`
  - :mod:`pymongo.timestamp` -> :mod:`bson.timestamp`
  - :mod:`pymongo.tz_util` -> :mod:`bson.tz_util`

In addition, the following exception classes have been renamed:

  - :class:`pymongo.errors.InvalidBSON` ->
    :class:`bson.errors.InvalidBSON`
  - :class:`pymongo.errors.InvalidStringData` ->
    :class:`bson.errors.InvalidStringData`
  - :class:`pymongo.errors.InvalidDocument` ->
    :class:`bson.errors.InvalidDocument`
  - :class:`pymongo.errors.InvalidId` ->
    :class:`bson.errors.InvalidId`

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

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

.. warning::

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

- the C extension now shares buffer.c/h with the Ruby driver
- :mod:`bson` no longer raises :class:`~pymongo.errors.InvalidName`,
  all occurrences have been replaced with
  :class:`~bson.errors.InvalidDocument`.
- renamed :meth:`bson._to_dicts` to :meth:`~bson.decode_all`.
- renamed :meth:`~bson.BSON.from_dict` to :meth:`~bson.BSON.encode`
  and :meth:`~bson.BSON.to_dict` to :meth:`~bson.BSON.decode`.
- added :meth:`~pymongo.cursor.Cursor.batch_size`.
- allow updating (some) file metadata after a
  :class:`~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 :class:`unicode` to GridFS if an :attr:`encoding`
  attribute has been specified for the file.
- added :meth:`gridfs.GridFS.get_version`.
- scope variables for :class:`~bson.code.Code` can now be specified as
  keyword arguments.
- added :meth:`~gridfs.grid_file.GridOut.readline` to
  :class:`~gridfs.grid_file.GridOut`.
- make a best effort to transparently auto-reconnect if a
  :class:`~pymongo.connection.Connection` has been idle for a while.
- added :meth:`~pymongo.database.SystemJS.list` to
  :class:`~pymongo.database.SystemJS`.
- added ``file_document`` argument to :meth:`~gridfs.grid_file.GridOut`
  to allow initializing from an existing file document.
- raise :class:`~pymongo.errors.TimeoutError` even if the
  ``getLastError`` command was run manually and not through "safe"
  mode.
- added :class:`uuid` support to :mod:`~bson.json_util`.

Changes in Version 1.8.1 (2010/08/13)
-------------------------------------

- fixed a typo in the C extension that could cause safe-mode
  operations to report a failure (:class:`SystemError`) even when none
  occurred.
- added a :meth:`__ne__` implementation to any class where we define
  :meth:`__eq__`.

Changes in Version 1.8 (2010/08/05)
-----------------------------------

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
  :class:`~bson.dbref.DBRef`.
- added support for ``w``, ``wtimeout``, and ``fsync`` (and any other
  options for ``getLastError``) to "safe mode" operations.
- added :attr:`~pymongo.connection.Connection.nodes` property.
- added a maximum pool size of 10 sockets.
- added support for replica sets.
- DEPRECATED :meth:`~pymongo.connection.Connection.from_uri` and
  :meth:`~pymongo.connection.Connection.paired`, both are supplanted
  by extended functionality in :meth:`~pymongo.connection.Connection`.
- added tz aware support for datetimes in
  :class:`~bson.objectid.ObjectId`,
  :class:`~bson.timestamp.Timestamp` and :mod:`~bson.json_util`
  methods.
- added :meth:`~pymongo.collection.Collection.drop` helper.
- reuse the socket used for finding the master when a
  :class:`~pymongo.connection.Connection` is first created.
- added support for :class:`~bson.min_key.MinKey`,
  :class:`~bson.max_key.MaxKey` and
  :class:`~bson.timestamp.Timestamp` to :mod:`~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
  :meth:`~pymongo.connection.Connection` to ``True``.
- added ``network_timeout`` option for individual calls to
  :meth:`~pymongo.collection.Collection.find` and
  :meth:`~pymongo.collection.Collection.find_one`.
- added :meth:`~gridfs.GridFS.exists` to check if a file exists in
  GridFS.
- added support for additional keys in :class:`~bson.dbref.DBRef`
  instances.
- added :attr:`~pymongo.errors.OperationFailure.code` attribute to
  :class:`~pymongo.errors.OperationFailure` exceptions.
- fixed serialization of int and float subclasses in the C extension.

Changes in Version 1.7 (2010/06/17)
-----------------------------------

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
<https://dirolf.com/2010/06/17/pymongo-1.7-released.html>`_.

- no longer attempt to build the C extension on big-endian systems.
- added :class:`~bson.min_key.MinKey` and
  :class:`~bson.max_key.MaxKey`.
- use unsigned for :class:`~bson.timestamp.Timestamp` in BSON
  encoder/decoder.
- support ``True`` as ``"ok"`` in command responses, in addition to
  ``1.0`` - necessary for server versions **>= 1.5.X**
- BREAKING change to
  :meth:`~pymongo.collection.Collection.index_information` to add
  support for querying unique status and other index information.
- added :attr:`~pymongo.connection.Connection.document_class`, to
  specify class for returned documents.
- added ``as_class`` argument for
  :meth:`~pymongo.collection.Collection.find`, and in the BSON decoder.
- added support for creating :class:`~bson.timestamp.Timestamp`
  instances using a :class:`~datetime.datetime`.
- allow ``dropTarget`` argument for
  :class:`~pymongo.collection.Collection.rename`.
- handle aware :class:`~datetime.datetime` instances, by converting to
  UTC.
- added support for :class:`~pymongo.cursor.Cursor.max_scan`.
- raise :class:`~gridfs.errors.FileExists` exception when creating a
  duplicate GridFS file.
- use `y2038 <https://github.com/evalEmpire/y2038/>`_ for time handling in
  the C extension - eliminates 2038 problems when extension is
  installed.
- added ``sort`` parameter to
  :meth:`~pymongo.collection.Collection.find`
- finalized deprecation of changes from versions **<= 1.4**
- take any non-:class:`dict` as an ``"_id"`` query for
  :meth:`~pymongo.collection.Collection.find_one` or
  :meth:`~pymongo.collection.Collection.remove`
- added ability to pass a :class:`dict` for ``fields`` argument to
  :meth:`~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
  :class:`~pymongo.collection.Collection` instances).
- don't transparently map ``"filename"`` key to :attr:`name` attribute
  for GridFS.

Changes in Version 1.6 (2010/04/14)
-----------------------------------

The biggest change in version 1.6 is a complete re-implementation of
:mod:`gridfs` with a lot of improvements over the old
implementation. There are many details and examples of using the new
API in `this blog post
<https://dirolf.com/2010/03/29/new-gridfs-implementation-for-pymongo.html>`_. 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
  :class:`~pymongo.connection.Connection` instances.
- more improvements to Python code caching in C extension - should
  improve behavior on mod_wsgi.
- added :meth:`~bson.objectid.ObjectId.from_datetime`.
- complete rewrite of :mod:`gridfs` support.
- improvements to the :meth:`~pymongo.database.Database.command` API.
- fixed :meth:`~pymongo.collection.Collection.drop_indexes` behavior
  on non-existent collections.
- disallow empty bulk inserts.

Changes in Version 1.5.2 (2010/03/31)
-------------------------------------
- fixed response handling to ignore unknown response flags in queries.
- handle server versions containing '-pre-'.

Changes in Version 1.5.1 (2010/03/17)
-------------------------------------
- added :data:`~gridfs.grid_file.GridFile._id` property for
  :class:`~gridfs.grid_file.GridFile` instances.
- fix for making a :class:`~pymongo.connection.Connection` (with
  ``slave_okay`` set) directly to a slave in a replica pair.
- accept kwargs for
  :meth:`~pymongo.collection.Collection.create_index` and
  :meth:`~pymongo.collection.Collection.ensure_index` to support all
  indexing options.
- add :data:`pymongo.GEO2D` and support for geo indexing.
- improvements to Python code caching in C extension - should improve
  behavior on mod_wsgi.

Changes in Version 1.5 (2010/03/10)
-----------------------------------
- added subtype constants to :mod:`~bson.binary` module.
- DEPRECATED ``options`` argument to
  :meth:`~pymongo.collection.Collection` and
  :meth:`~pymongo.database.Database.create_collection` in favor of
  kwargs.
- added :meth:`~pymongo.has_c` to check for C extension.
- added :meth:`~pymongo.connection.Connection.copy_database`.
- added :data:`~pymongo.cursor.Cursor.alive` to tell when a cursor
  might have more data to return (useful for tailable cursors).
- added :class:`~bson.timestamp.Timestamp` to better support
  dealing with internal MongoDB timestamps.
- added ``name`` argument for
  :meth:`~pymongo.collection.Collection.create_index` and
  :meth:`~pymongo.collection.Collection.ensure_index`.
- fixed connection pooling w/ fork
- :meth:`~pymongo.connection.Connection.paired` takes all kwargs that
  are allowed for :meth:`~pymongo.connection.Connection`.
- :meth:`~pymongo.collection.Collection.insert` returns list for bulk
  inserts of size one.
- fixed handling of :class:`datetime.datetime` instances in
  :mod:`~bson.json_util`.
- added :meth:`~pymongo.connection.Connection.from_uri` to support
  MongoDB connection uri scheme.
- fixed chunk number calculation when unaligned in :mod:`gridfs`.
- :meth:`~pymongo.database.Database.command` takes a string for simple
  commands.
- added :data:`~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 :class:`~gridfs.errors.GridFSError` as base class for
  :mod:`gridfs` exceptions.

Changes in Version 1.4 (2010/01/17)
-----------------------------------

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).
- :meth:`~pymongo.collection.Collection.update` and
  :meth:`~pymongo.collection.Collection.remove` return the entire
  response to the *lastError* command when safe is ``True``.
- 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 :class:`~pymongo.errors.PyMongoError` as base exception class
  for all :mod:`~pymongo.errors`. this changes the exception hierarchy
  somewhat, and is a BREAKING change if you depend on
  :class:`~pymongo.errors.ConnectionFailure` being a :class:`IOError`
  or :class:`~bson.errors.InvalidBSON` being a :class:`ValueError`,
  for example.
- added :class:`~pymongo.errors.DuplicateKeyError` for calls to
  :meth:`~pymongo.collection.Collection.insert` or
  :meth:`~pymongo.collection.Collection.update` with ``safe`` set to
  ``True``.
- removed :mod:`~pymongo.thread_util`.
- added :meth:`~pymongo.database.Database.add_user` and
  :meth:`~pymongo.database.Database.remove_user` helpers.
- fix for :meth:`~pymongo.database.Database.authenticate` when using
  non-UTF-8 names or passwords.
- minor fixes for
  :class:`~pymongo.master_slave_connection.MasterSlaveConnection`.
- clean up all cases where :class:`~pymongo.errors.ConnectionFailure`
  is raised.
- simplification of connection pooling - makes driver ~2x faster for
  simple benchmarks. see `connection pooling <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-options/connection-pools/#connection-pools>`_ for more information.
- DEPRECATED ``pool_size``, ``auto_start_request`` and ``timeout``
  parameters to :class:`~pymongo.connection.Connection`. DEPRECATED
  :meth:`~pymongo.connection.Connection.start_request`.
- use :meth:`socket.sendall`.
- removed :meth:`~bson.son.SON.from_xml` as it was only being used
  for some internal testing - also eliminates dependency on
  :mod:`elementtree`.
- implementation of :meth:`~pymongo.message.update` in C.
- deprecate :meth:`~pymongo.database.Database._command` in favor of
  :meth:`~pymongo.database.Database.command`.
- send all commands without wrapping as ``{"query": ...}``.
- support string as ``key`` argument to
  :meth:`~pymongo.collection.Collection.group` (keyf) and run all
  groups as commands.
- support for equality testing for :class:`~bson.code.Code`
  instances.
- allow the NULL byte in strings and disallow it in key names or regex
  patterns

Changes in Version 1.3 (2009/12/16)
-----------------------------------
- DEPRECATED running :meth:`~pymongo.collection.Collection.group` as
  :meth:`~pymongo.database.Database.eval`, also changed default for
  :meth:`~pymongo.collection.Collection.group` to running as a command
- remove :meth:`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 :meth:`~pymongo.connection.Connection.host`,
  :meth:`~pymongo.connection.Connection.port`,
  :meth:`~pymongo.database.Database.connection`,
  :meth:`~pymongo.database.Database.name`,
  :meth:`~pymongo.collection.Collection.database`,
  :meth:`~pymongo.collection.Collection.name` and
  :meth:`~pymongo.collection.Collection.full_name` in favor of
  :attr:`~pymongo.connection.Connection.host`,
  :attr:`~pymongo.connection.Connection.port`,
  :attr:`~pymongo.database.Database.connection`,
  :attr:`~pymongo.database.Database.name`,
  :attr:`~pymongo.collection.Collection.database`,
  :attr:`~pymongo.collection.Collection.name` and
  :attr:`~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 :meth:`~pymongo.connection.Connection.disconnect`

Changes in Version 1.2.1 (2009/12/10)
-------------------------------------
- added :doc:`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 :class:`~bson.errors.InvalidId` instead of
  :class:`TypeError` when passing a 24 character string to
  :class:`~bson.objectid.ObjectId` that contains non-hexadecimal
  characters
- allow :class:`unicode` instances for :class:`~bson.objectid.ObjectId` init

Changes in Version 1.2 (2009/12/09)
-----------------------------------
- ``spec`` parameter for :meth:`~pymongo.collection.Collection.remove` is
  now optional to allow for deleting all documents in a
  :class:`~pymongo.collection.Collection`
- always wrap queries with ``{query: ...}`` even when no special options -
  get around some issues with queries on fields named ``query``
- enforce 4MB document limit on the client side
- added :meth:`~pymongo.collection.Collection.map_reduce` helper - see
  `Aggregation <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/aggregation/#transform-your-data-with-aggregation>`_
- added :meth:`~pymongo.cursor.Cursor.distinct` method on
  :class:`~pymongo.cursor.Cursor` instances to allow distinct with
  queries
- fix for :meth:`~pymongo.cursor.Cursor.__getitem__` after
  :meth:`~pymongo.cursor.Cursor.skip`
- allow any UTF-8 string in :class:`~bson.BSON` encoder, not
  just ASCII subset
- added :attr:`~bson.objectid.ObjectId.generation_time`
- removed support for legacy :class:`~bson.objectid.ObjectId`
  format - pretty sure this was never used, and is just confusing
- DEPRECATED :meth:`~bson.objectid.ObjectId.url_encode` and
  :meth:`~bson.objectid.ObjectId.url_decode` in favor of :meth:`str`
  and :meth:`~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 :mod:`~bson.json_util`

Changes in Version 1.1.2 (2009/11/23)
-------------------------------------
- improvements to :meth:`~pymongo.collection.Collection.insert` speed
  (using C for insert message creation)
- use random number for request_id
- fix some race conditions with :class:`~pymongo.errors.AutoReconnect`

Changes in Version 1.1.1 (2009/11/14)
-------------------------------------
- added ``multi`` parameter for
  :meth:`~pymongo.collection.Collection.update`
- fix unicode regex patterns with C extension
- added :meth:`~pymongo.collection.Collection.distinct`
- added ``database`` support for :class:`~bson.dbref.DBRef`
- added :mod:`~bson.json_util` with helpers for encoding / decoding
  special types to JSON
- DEPRECATED :meth:`pymongo.cursor.Cursor.__len__` in favor of
  :meth:`~pymongo.cursor.Cursor.count` with ``with_limit_and_skip`` set
  to ``True`` due to performance regression
- switch documentation to Sphinx

Changes in Version 1.1 (2009/10/21)
-----------------------------------
- added :meth:`__hash__` for :class:`~bson.dbref.DBRef` and
  :class:`~bson.objectid.ObjectId`
- bulk :meth:`~pymongo.collection.Collection.insert` works with any
  iterable
- fix :class:`~bson.objectid.ObjectId` generation when using
  :mod:`multiprocessing`
- added :attr:`~pymongo.cursor.Cursor.collection`
- added ``network_timeout`` parameter for
  :meth:`~pymongo.connection.Connection`
- DEPRECATED ``slave_okay`` parameter for individual queries
- fix for ``safe`` mode when multi-threaded
- added ``safe`` parameter for :meth:`~pymongo.collection.Collection.remove`
- added ``tailable`` parameter for :meth:`~pymongo.collection.Collection.find`

Changes in Version 1.0 (2009/09/30)
-----------------------------------
- fixes for
  :class:`~pymongo.master_slave_connection.MasterSlaveConnection`
- added ``finalize`` parameter for :meth:`~pymongo.collection.Collection.group`
- improvements to :meth:`~pymongo.collection.Collection.insert` speed
- improvements to :mod:`gridfs` speed
- added :meth:`~pymongo.cursor.Cursor.__getitem__` and
  :meth:`~pymongo.cursor.Cursor.__len__` for
  :class:`~pymongo.cursor.Cursor` instances

Changes in Version 0.16 (2009/09/16)
------------------------------------
- support for encoding/decoding :class:`uuid.UUID` instances
- fix for :meth:`~pymongo.cursor.Cursor.explain` with limits

Changes in Version 0.15.2 (2009/09/09)
--------------------------------------
- documentation changes only

Changes in Version 0.15.1 (2009/09/02)
--------------------------------------
- various performance improvements
- API CHANGE no longer need to specify direction for
  :meth:`~pymongo.collection.Collection.create_index` and
  :meth:`~pymongo.collection.Collection.ensure_index` when indexing a
  single key
- support for encoding :class:`tuple` instances as :class:`list`
  instances

Changes in Version 0.15 (2009/08/26)
------------------------------------
- fix string representation of :class:`~bson.objectid.ObjectId`
  instances
- added ``timeout`` parameter for
  :meth:`~pymongo.collection.Collection.find`
- allow scope for ``reduce`` function in
  :meth:`~pymongo.collection.Collection.group`

Changes in Version 0.14.2 (2009/08/24)
--------------------------------------
- minor bugfixes

Changes in Version 0.14.1 (2009/08/21)
--------------------------------------
- :meth:`~gridfs.grid_file.GridFile.seek` and
  :meth:`~gridfs.grid_file.GridFile.tell` for (read mode)
  :class:`~gridfs.grid_file.GridFile` instances

Changes in Version 0.14 (2009/08/19)
------------------------------------
- support for long in :class:`~bson.BSON`
- added :meth:`~pymongo.collection.Collection.rename`
- added ``snapshot`` parameter for
  :meth:`~pymongo.collection.Collection.find`

Changes in Version 0.13 (2009/07/29)
------------------------------------
- better
  :class:`~pymongo.master_slave_connection.MasterSlaveConnection`
  support
- API CHANGE :meth:`~pymongo.collection.Collection.insert` and
  :meth:`~pymongo.collection.Collection.save` both return inserted
  ``_id``
- DEPRECATED passing an index name to
  :meth:`~pymongo.cursor.Cursor.hint`

Changes in Version 0.12 (2009/07/08)
------------------------------------
- improved :class:`~bson.objectid.ObjectId` generation
- added :class:`~pymongo.errors.AutoReconnect` exception for when
  reconnection is possible
- make :mod:`gridfs` thread-safe
- fix for :mod:`gridfs` with non :class:`~bson.objectid.ObjectId` ``_id``

Changes in Version 0.11.3 (2009/06/18)
--------------------------------------
- don't allow NULL bytes in string encoder
- fixes for Python 2.3

Changes in Version 0.11.2 (2009/06/08)
--------------------------------------
- PEP 8
- updates for :meth:`~pymongo.collection.Collection.group`
- VS build

Changes in Version 0.11.1 (2009/06/04)
--------------------------------------
- fix for connection pooling under Python 2.5

Changes in Version 0.11 (2009/06/03)
------------------------------------
- better build failure detection
- driver support for selecting fields in sub-documents
- disallow insertion of invalid key names
- added ``timeout`` parameter for :meth:`~pymongo.connection.Connection`

Changes in Version 0.10.3 (2009/05/27)
--------------------------------------
- fix bug with large :meth:`~pymongo.cursor.Cursor.limit`
- better exception when modules get reloaded out from underneath the C
  extension
- better exception messages when calling a
  :class:`~pymongo.collection.Collection` or
  :class:`~pymongo.database.Database` instance

Changes in Version 0.10.2 (2009/05/22)
--------------------------------------
- support subclasses of :class:`dict` in C encoder

Changes in Version 0.10.1 (2009/05/18)
--------------------------------------
- alias :class:`~pymongo.connection.Connection` as
  :attr:`pymongo.Connection`
- raise an exception rather than silently overflowing in encoder

Changes in Version 0.10 (2009/05/14)
------------------------------------
- added :meth:`~pymongo.collection.Collection.ensure_index`

Changes in Version 0.9.7 (2009/05/13)
-------------------------------------
- allow sub-collections of *$cmd* as valid
  :class:`~pymongo.collection.Collection` names
- add version as :attr:`pymongo.version`
- add ``--no_ext`` command line option to *setup.py*

---

### Doc Contributors (`doc/contributors.rst`)

Contributors
============
The following is a list of people who have contributed to
**PyMongo**. If you belong here and are missing please let us know
(or send a pull request after adding yourself to the list):

- Mike Dirolf (mdirolf)
- Jeff Jenkins (jeffjenkins)
- Jim Jones
- Eliot Horowitz (erh)
- Michael Stephens (mikejs)
- Joakim Sernbrant (serbaut)
- Alexander Artemenko (svetlyak40wt)
- Mathias Stearn (RedBeard0531)
- Fajran Iman Rusadi (fajran)
- Brad Clements (bkc)
- Andrey Fedorov (andreyf)
- Joshua Roesslein (joshthecoder)
- Gregg Lind (gregglind)
- Michael Schurter (schmichael)
- Daniel Lundin
- Michael Richardson (mtrichardson)
- Dan McKinley (mcfunley)
- David Wolever (wolever)
- Carlos Valiente (carletes)
- Jehiah Czebotar (jehiah)
- Drew Perttula (drewp)
- Carl Baatz (c-w-b)
- Johan Bergstrom (jbergstroem)
- Jonas Haag (jonashaag)
- Kristina Chodorow (kchodorow)
- Andrew Sibley (sibsibsib)
- Flavio Percoco Premoli (FlaPer87)
- Ken Kurzweil (kurzweil)
- Christian Wyglendowski (dowski)
- James Murty (jmurty)
- Brendan W. McAdams (bwmcadams)
- Bernie Hackett (behackett)
- Reed O'Brien (reedobrien)
- Francisco Souza (fsouza)
- Alexey I. Froloff (raorn)
- Steve Lacy (slacy)
- Richard Shea (shearic)
- Vladimir Sidorenko (gearheart)
- Aaron Westendorf (awestendorf)
- Dan Crosta (dcrosta)
- Ryan Smith-Roberts (rmsr)
- David Pisoni (gefilte)
- Abhay Vardhan (abhayv)
- Alexey Borzenkov (snaury)
- Kostya Rybnikov (k-bx)
- A Jesse Jiryu Davis (ajdavis)
- Samuel Clay (samuelclay)
- Ross Lawley (rozza)
- Wouter Bolsterlee (wbolster)
- Alex Grönholm (agronholm)
- Christoph Simon (kalanzun)
- Chris Tompkinson (tompko)
- Mike O'Brien (mpobrien)
- T Dampier (dampier)
- Michael Henson (hensom)
- Craig Hobbs (craigahobbs)
- Emily Stolfo (estolfo)
- Sam Helman (shelman)
- Justin Patrin (reversefold)
- Xiuming Chen (cxmcc)
- Tyler Jones (thomascirca)
- Amalia Hawkins (hawka)
- Yuchen Ying (yegle)
- Kyle Erf (3rf)
- Luke Lovett (lovett89)
- Jaroslav Semančík (girogiro)
- Don Mitchell (dmitchell)
- Ximing (armnotstrong)
- Can Zhang (cannium)
- Sergey Azovskov (last-g)
- Heewa Barfchin (heewa)
- Anna Herlihy (aherlihy)
- Len Buckens (buckensl)
- ultrabug
- Shane Harvey (ShaneHarvey)
- Cao Siyang (caosiyang)
- Zhecong Kwok (gzcf)
- TaoBeier(tao12345666333)
- Jagrut Trivedi(Jagrut)
- Shrey Batra(shreybatra)
- Felipe Rodrigues(fbidu)
- Terence Honles (terencehonles)
- Paul Fisher (thetorpedodog)
- Julius Park (juliusgeo)
- Khanh Nguyen (KN99HN)
- Henri Froese (henrifroese)
- Ishmum Jawad Khan (ishmum123)
- Arie Bovenberg (ariebovenberg)
- Ben Warner (bcwarner)
- Jean-Christophe Fillion-Robin (jcfr)
- Sean Cheah (thalassemia)
- Dainis Gorbunovs (DainisGorbunovs)
- Iris Ho (sleepyStick)
- Stephan Hof (stephan-hof)
- Casey Clements (caseyclements)
- Ivan Lukyanchikov (ilukyanchikov)
- Terry Patterson
- Romain Morotti
- Navjot Singh (navjots18)
- Jib Adegunloye (Jibola)
- Jeffrey A. Clark (aclark4life)
- Steven Silvester (blink1073)
- Noah Stapp (NoahStapp)
- Cal Jacobson (cj81499)
- Sophia Yang (sophiayangDB)
- Madan Kumar (winklemad)
- Junyao Dong (carsontung666)

---

### Doc Index (`doc/index.rst`)

PyMongo |release| Documentation
===============================

.. note:: The PyMongo documentation has been migrated to the
   `MongoDB Documentation site <https://www.mongodb.com/docs/languages/python/pymongo-driver/current>`_.
   This site contains only the detailed changelog and API docs, while the
   rest of the documentation appears on the MongoDB Documentation site.

Overview
--------
**PyMongo** is a Python distribution containing tools for working with
`MongoDB <https://www.mongodb.org>`_, and is the recommended way to
work with MongoDB from Python.

:doc:`api/index`
  The complete API documentation, organized by module.

:doc:`changelog`
  A full list of changes to PyMongo.


Getting Help
------------
If you're having trouble or have questions about PyMongo, ask your question on
one of the platforms listed on `Technical Support <https://www.mongodb.com/docs/manual/support/>`_.
You may also want to consider a
`commercial support subscription <https://support.mongodb.com/welcome>`_.
Once you get an answer, it'd be great if you could work it back into this
documentation and contribute!

Issues
------
All issues should be reported (and can be tracked / voted for /
commented on) at the main `MongoDB JIRA bug tracker
<https://jira.mongodb.org/browse/PYTHON>`_, in the "Python Driver"
project.

Feature Requests / Feedback
---------------------------
Use our `feedback engine <https://feedback.mongodb.com/?category=7548141816650747033>`_
to send us feature requests and general feedback about PyMongo.

Contributing
------------
**PyMongo** has a large :doc:`community <contributors>` and
contributions are always encouraged. Contributions can be as simple as
minor tweaks to this documentation. To contribute, fork the project on
`GitHub <https://github.com/mongodb/mongo-python-driver/>`_ and send a
pull request.

About This Documentation
------------------------
This documentation is generated using the `Sphinx
<https://www.sphinx-doc.org/en/master/>`_ documentation generator. The source files
for the documentation are located in the *doc/* directory of the
**PyMongo** distribution. See the PyMongo `contributing guide <https://github.com/mongodb/mongo-python-driver/blob/main/CONTRIBUTING.md>`_
for instructions on building the docs from source.

Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. toctree::
   :hidden:

   api/index
   changelog
   contributors

---

### Doc Migrate To Pymongo4 (`doc/migrate-to-pymongo4.rst`)

:orphan:

.. _pymongo4-migration-guide:

PyMongo 4 Migration Guide
=========================

.. testsetup::

  from pymongo import MongoClient, ReadPreference

  client = MongoClient()
  database = client.my_database
  collection = database.my_collection

PyMongo 4.0 brings a number of improvements as well as some backward breaking
changes. This guide provides a roadmap for migrating an existing application
from PyMongo 3.x to 4.x or writing libraries that will work with both
PyMongo 3.x and 4.x.

PyMongo 3
---------

The first step in any successful migration involves upgrading to, or
requiring, at least that latest version of PyMongo 3.x. If your project has a
requirements.txt file, add the line "pymongo >= 3.12, < 4.0" until you have
completely migrated to PyMongo 4. Most of the key new methods and options from
PyMongo 4.0 are backported in PyMongo 3.12 making migration much easier.

.. note:: Users of PyMongo 2.X who wish to upgrade to 4.x must first upgrade
   to PyMongo 3.x by following the `PyMongo 3 Migration Guide
   <https://pymongo.readthedocs.io/en/3.12.1/migrate-to-pymongo3.html>`_.

Python 3.6+
-----------

PyMongo 4.0 drops support for Python 2.7, 3.4, and 3.5. Users who wish to
upgrade to 4.x must first upgrade to Python 3.6.2+. Users upgrading from
Python 2 should consult `Python 3 <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/reference/upgrade/#upgrade-pymongo-versions>`_.

Enable Deprecation Warnings
---------------------------

:exc:`DeprecationWarning` is raised by most methods removed in PyMongo 4.0.
Make sure you enable runtime warnings to see where deprecated functions and
methods are being used in your application::

  python -Wd <your application>

Warnings can also be changed to errors::

  python -Wd -Werror <your application>

.. note:: Not all deprecated features raise :exc:`DeprecationWarning` when
  used. See `Removed features with no migration path`_.

MongoReplicaSetClient
---------------------

Removed :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient`.
Since PyMongo 3.0, ``MongoReplicaSetClient`` has been identical to
:class:`pymongo.mongo_client.MongoClient`. Applications can simply replace
``MongoReplicaSetClient`` with :class:`pymongo.mongo_client.MongoClient` and
get the same behavior.

MongoClient
-----------

.. _pymongo4-migration-direct-connection:

``directConnection`` defaults to False
......................................

``directConnection`` URI option and keyword argument to :class:`~pymongo
.mongo_client.MongoClient` defaults to ``False`` instead of ``None``,
allowing for the automatic discovery of replica sets. This means that if you
want a direct connection to a single server you must pass
``directConnection=True`` as a URI option or keyword argument.

If you see any :exc:`~pymongo.errors.ServerSelectionTimeoutError`'s after upgrading from PyMongo 3 to 4.x, you likely
need to add ``directConnection=True`` when creating the client.
Here are some example errors:

.. code-block::

        pymongo.errors.ServerSelectionTimeoutError: mongo_node2: [Errno 8] nodename nor servname
        provided, or not known,mongo_node1:27017

.. code-block::

        ServerSelectionTimeoutError: No servers match selector "Primary()", Timeout: 30s,
        Topology Description: ...


Additionally, the "isWritablePrimary" attribute of a hello command sent back by the server will
always be True if ``directConnection=False``::

   >>> client.admin.command('hello')['isWritablePrimary']
   True


The waitQueueMultiple parameter is removed
..........................................

Removed the ``waitQueueMultiple`` keyword argument to
:class:`~pymongo.mongo_client.MongoClient` and removed
:exc:`pymongo.errors.ExceededMaxWaiters`. Instead of using
``waitQueueMultiple`` to bound queuing, limit the size of the thread
pool in your application.

The socketKeepAlive parameter is removed
..........................................

Removed the ``socketKeepAlive`` keyword argument to
:class:`~pymongo.mongo_client.MongoClient`. PyMongo now always enables TCP
keepalive. For more information see the `documentation <https://mongodb.com/docs/manual/faq/diagnostics/#does-tcp-keepalive-time-affect-mongodb-deployments->`_.

Renamed URI options
...................

Several deprecated URI options have been renamed to the standardized
option names defined in the
`URI options specification <https://github.com/mongodb/specifications/blob/master/source/uri-options/uri-options.md>`_.
The old option names and their renamed equivalents are summarized in the table
below. Some renamed options have different semantics from the option being
replaced as noted in the 'Migration Notes' column.

+--------------------+-------------------------------+--------------------------------------------------------+
| Old URI Option     | Renamed URI Option            | Migration Notes                                        |
+====================+===============================+========================================================+
| ssl_pem_passphrase | tlsCertificateKeyFilePassword | -                                                      |
+--------------------+-------------------------------+--------------------------------------------------------+
| ssl_ca_certs       | tlsCAFile                     | -                                                      |
+--------------------+-------------------------------+--------------------------------------------------------+
| ssl_crlfile        | tlsCRLFile                    | -                                                      |
+--------------------+-------------------------------+--------------------------------------------------------+
| ssl_match_hostname | tlsAllowInvalidHostnames      | ``ssl_match_hostname=True`` is equivalent to           |
|                    |                               | ``tlsAllowInvalidHostnames=False`` and vice-versa.     |
+--------------------+-------------------------------+--------------------------------------------------------+
| ssl_cert_reqs      | tlsAllowInvalidCertificates   | Instead of ``ssl.CERT_NONE``, ``ssl.CERT_OPTIONAL``    |
|                    |                               | and ``ssl.CERT_REQUIRED``, the new option expects      |
|                    |                               | a boolean value - ``True`` is equivalent to            |
|                    |                               | ``ssl.CERT_NONE``, while ``False`` is equivalent to    |
|                    |                               | ``ssl.CERT_REQUIRED``.                                 |
+--------------------+-------------------------------+--------------------------------------------------------+
| ssl_certfile       | tlsCertificateKeyFile         | Instead of using ``ssl_certfile`` and ``ssl_keyfile``  |
|                    |                               | to specify the certificate and private key files       |
+--------------------+                               | respectively,  use ``tlsCertificateKeyFile`` to pass   |
| ssl_keyfile        |                               | a single file containing both the client certificate   |
|                    |                               | and the private key.                                   |
+--------------------+-------------------------------+--------------------------------------------------------+
| j                  | journal                       | -                                                      |
+--------------------+-------------------------------+--------------------------------------------------------+
| wtimeout           | wTimeoutMS                    | -                                                      |
+--------------------+-------------------------------+--------------------------------------------------------+

MongoClient.fsync is removed
............................

Removed :meth:`pymongo.mongo_client.MongoClient.fsync`. Run the
`fsync command`_ directly with :meth:`~pymongo.database.Database.command`
instead. For example::

    client.admin.command('fsync', lock=True)

.. _fsync command: https://mongodb.com/docs/manual/reference/command/fsync/

MongoClient.unlock is removed
.............................

Removed :meth:`pymongo.mongo_client.MongoClient.unlock`. Run the
`fsyncUnlock command`_ directly with
:meth:`~pymongo.database.Database.command` instead. For example::

     client.admin.command('fsyncUnlock')

.. _fsyncUnlock command: https://mongodb.com/docs/manual/reference/command/fsyncUnlock/

MongoClient.is_locked is removed
................................

Removed :attr:`pymongo.mongo_client.MongoClient.is_locked`. Run the
`currentOp command`_ directly with
:meth:`~pymongo.database.Database.command` instead. For example::

    is_locked = client.admin.command('currentOp').get('fsyncLock')

.. _currentOp command: https://mongodb.com/docs/manual/reference/command/currentOp/

MongoClient.database_names is removed
.....................................

Removed :meth:`pymongo.mongo_client.MongoClient.database_names`. Use
:meth:`~pymongo.mongo_client.MongoClient.list_database_names` instead. Code like
this::

    names = client.database_names()

can be changed to this::

    names = client.list_database_names()

MongoClient.max_bson_size/max_message_size/max_write_batch_size are removed
...........................................................................

Removed :attr:`pymongo.mongo_client.MongoClient.max_bson_size`,
:attr:`pymongo.mongo_client.MongoClient.max_message_size`, and
:attr:`pymongo.mongo_client.MongoClient.max_write_batch_size`. These helpers
were incorrect when in ``loadBalanced=true mode`` and ambiguous in clusters
with mixed versions. Use the `hello command`_ to get the authoritative
value from the remote server instead. Code like this::

    max_bson_size = client.max_bson_size
    max_message_size = client.max_message_size
    max_write_batch_size = client.max_write_batch_size

can be changed to this::

    doc = client.admin.command('hello')
    max_bson_size = doc['maxBsonObjectSize']
    max_message_size = doc['maxMessageSizeBytes']
    max_write_batch_size = doc['maxWriteBatchSize']

.. _hello command: https://mongodb.com/docs/manual/reference/command/hello/

MongoClient.event_listeners and other configuration option helpers are removed
..............................................................................

The following client configuration option helpers are removed:
- :attr:`pymongo.mongo_client.MongoClient.event_listeners`.
- :attr:`pymongo.mongo_client.MongoClient.max_pool_size`.
- :attr:`pymongo.mongo_client.MongoClient.max_idle_time_ms`.
- :attr:`pymongo.mongo_client.MongoClient.local_threshold_ms`.
- :attr:`pymongo.mongo_client.MongoClient.server_selection_timeout`.
- :attr:`pymongo.mongo_client.MongoClient.retry_writes`.
- :attr:`pymongo.mongo_client.MongoClient.retry_reads`.

These helpers have been replaced by
:attr:`pymongo.mongo_client.MongoClient.options`. Code like this::

    client.event_listeners
    client.local_threshold_ms
    client.server_selection_timeout
    client.max_pool_size
    client.min_pool_size
    client.max_idle_time_ms

can be changed to this::

    client.options.event_listeners
    client.options.local_threshold_ms
    client.options.server_selection_timeout
    client.options.pool_options.max_pool_size
    client.options.pool_options.min_pool_size
    client.options.pool_options.max_idle_time_seconds

.. _tz_aware_default_change:

``tz_aware`` defaults to ``False``
..................................

The ``tz_aware`` argument to :class:`~bson.json_util.JSONOptions`
now defaults to ``False`` instead of ``True``. :meth:`bson.json_util.loads`
now decodes datetime as naive by default::

    >>> from bson import json_util
    >>> s = '{"dt": {"$date": "2022-05-09T17:54:00Z"}}'
    >>> json_util.loads(s)
    {'dt': datetime.datetime(2022, 5, 9, 17, 54)}

To retain the PyMongo 3 behavior set ``tz_aware=True``, for example::

    >>> from bson import json_util
    >>> opts = json_util.JSONOptions(tz_aware=True)
    >>> s = '{"dt": {"$date": "2022-05-09T17:54:00Z"}}'
    >>> json_util.loads(s, json_options=opts)
    {'dt': datetime.datetime(2022, 5, 9, 17, 54, tzinfo=)}

This change was made to match the default behavior of
:class:`~bson.codec_options.CodecOptions` and :class:`bson.decode`.

MongoClient cannot execute operations after ``close()``
.......................................................

:class:`~pymongo.mongo_client.MongoClient` cannot execute any operations
after being closed. The previous behavior would simply reconnect. However,
now you must create a new instance.

MongoClient raises exception when given more than one URI
.........................................................

:class:`~pymongo.mongo_client.MongoClient` now raises a :exc:`~pymongo.errors.ConfigurationError`
when more than one URI is passed into the ``hosts`` argument.

MongoClient raises exception when given unescaped percent sign in login info
............................................................................

:class:`~pymongo.mongo_client.MongoClient` now raises an
:exc:`~pymongo.errors.InvalidURI` exception
when it encounters unescaped percent signs in username and password.

Database
--------

Database.authenticate and Database.logout are removed
.....................................................

Removed :meth:`pymongo.database.Database.authenticate` and
:meth:`pymongo.database.Database.logout`. Authenticating multiple users
on the same client conflicts with support for logical sessions in MongoDB 3.6+.
To authenticate as multiple users, create multiple instances of
:class:`~pymongo.mongo_client.MongoClient`. Code like this::

    client = MongoClient()
    client.admin.authenticate('user1', 'pass1')
    client.admin.authenticate('user2', 'pass2')

can be changed to this::

    client1 = MongoClient(username='user1', password='pass1')
    client2 = MongoClient(username='user2', password='pass2')

Alternatively, create a single user that contains all the authentication privileges
required by your application.

Database.collection_names is removed
....................................

Removed :meth:`pymongo.database.Database.collection_names`. Use
:meth:`~pymongo.database.Database.list_collection_names` instead. Code like
this::

    names = client.db.collection_names()
    non_system_names = client.db.collection_names(include_system_collections=False)

can be changed to this::

    names = client.db.list_collection_names()
    non_system_names = client.db.list_collection_names(filter={"name": {"$regex": "^(?!system\\.)"}})

Database.current_op is removed
..............................

Removed :meth:`pymongo.database.Database.current_op`. Use
:meth:`~pymongo.database.Database.aggregate` instead with the
`$currentOp aggregation pipeline stage`_. Code like
this::

    ops = client.admin.current_op()['inprog']

can be changed to this::

    ops = list(client.admin.aggregate([{'$currentOp': {}}]))

.. _$currentOp aggregation pipeline stage: https://mongodb.com/docs/manual/reference/operator/aggregation/currentOp/

Database.add_user is removed
............................

Removed :meth:`pymongo.database.Database.add_user`  which was deprecated in
PyMongo 3.6. Use the `createUser command`_ or `updateUser command`_ instead.
To create a user::

  db.command("createUser", "admin", pwd="password", roles=["dbAdmin"])

To create a read-only user::

  db.command("createUser", "user", pwd="password", roles=["read"])

To change a password::

  db.command("updateUser", "user", pwd="newpassword")

Or change roles::

  db.command("updateUser", "user", roles=["readWrite"])

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

Database.remove_user is removed
...............................

Removed :meth:`pymongo.database.Database.remove_user` which was deprecated in
PyMongo 3.6. Use the `dropUser command`_ instead::

  db.command("dropUser", "user")

.. _dropUser command: https://mongodb.com/docs/manual/reference/command/createUser/

Database.profiling_level is removed
...................................

Removed :meth:`pymongo.database.Database.profiling_level` which was deprecated in
PyMongo 3.12. Use the `profile command`_ instead. Code like this::

  level = db.profiling_level()

Can be changed to this::

  profile = db.command('profile', -1)
  level = profile['was']

.. _profile command: https://mongodb.com/docs/manual/reference/command/profile/

Database.set_profiling_level is removed
.......................................

Removed :meth:`pymongo.database.Database.set_profiling_level` which was deprecated in
PyMongo 3.12. Use the `profile command`_ instead. Code like this::

  db.set_profiling_level(pymongo.ALL, filter={'op': 'query'})

Can be changed to this::

  res = db.command('profile', 2, filter={'op': 'query'})

Database.profiling_info is removed
..................................

Removed :meth:`pymongo.database.Database.profiling_info` which was deprecated in
PyMongo 3.12. Query the `'system.profile' collection`_ instead. Code like this::

  profiling_info = db.profiling_info()

Can be changed to this::

  profiling_info = list(db['system.profile'].find())

.. _'system.profile' collection: https://mongodb.com/docs/manual/reference/database-profiler/

Database.__bool__ raises NotImplementedError
............................................
:class:`~pymongo.database.Database` now raises an error upon evaluating as a
Boolean. Code like this::

  if database:

Can be changed to this::

  if database is not None:

You must now explicitly compare with None.

Collection
----------

The useCursor option for Collection.aggregate is removed
........................................................

Removed the ``useCursor`` option for
:meth:`~pymongo.collection.Collection.aggregate` which was deprecated in
PyMongo 3.6. The option was only necessary when upgrading from MongoDB 2.4
to MongoDB 2.6.

Collection.insert is removed
............................

Removed :meth:`pymongo.collection.Collection.insert`. Use
:meth:`~pymongo.collection.Collection.insert_one` or
:meth:`~pymongo.collection.Collection.insert_many` instead.

Code like this::

  collection.insert({'doc': 1})
  collection.insert([{'doc': 2}, {'doc': 3}])

Can be changed to this::

  collection.insert_one({'my': 'document'})
  collection.insert_many([{'doc': 2}, {'doc': 3}])

Collection.save is removed
..........................

Removed :meth:`pymongo.collection.Collection.save`. Applications will
get better performance using :meth:`~pymongo.collection.Collection.insert_one`
to insert a new document and :meth:`~pymongo.collection.Collection.update_one`
to update an existing document. Code like this::

  doc = collection.find_one({"_id": "some id"})
  doc["some field"] = <some value>
  db.collection.save(doc)

Can be changed to this::

  result = collection.update_one({"_id": "some id"}, {"$set": {"some field": <some value>}})

If performance is not a concern and refactoring is untenable, ``save`` can be
implemented like so::

  def save(doc):
      if '_id' in doc:
          collection.replace_one({'_id': doc['_id']}, doc, upsert=True)
          return doc['_id']
      else:
          res = collection.insert_one(doc)
          return res.inserted_id

Collection.update is removed
............................

Removed :meth:`pymongo.collection.Collection.update`. Use
:meth:`~pymongo.collection.Collection.update_one`
to update a single document or
:meth:`~pymongo.collection.Collection.update_many` to update multiple
documents. Code like this::

  collection.update({}, {'$set': {'a': 1}})
  collection.update({}, {'$set': {'b': 1}}, multi=True)

Can be changed to this::

  collection.update_one({}, {'$set': {'a': 1}})
  collection.update_many({}, {'$set': {'b': 1}})

Collection.remove is removed
............................

Removed :meth:`pymongo.collection.Collection.remove`. Use
:meth:`~pymongo.collection.Collection.delete_one`
to delete a single document or
:meth:`~pymongo.collection.Collection.delete_many` to delete multiple
documents. Code like this::

  collection.remove({'a': 1}, multi=False)
  collection.remove({'b': 1})

Can be changed to this::

  collection.delete_one({'a': 1})
  collection.delete_many({'b': 1})

Collection.find_and_modify is removed
.....................................

Removed :meth:`pymongo.collection.Collection.find_and_modify`. Use
:meth:`~pymongo.collection.Collection.find_one_and_update`,
:meth:`~pymongo.collection.Collection.find_one_and_replace`, or
:meth:`~pymongo.collection.Collection.find_one_and_delete` instead.
Code like this::

  updated_doc = collection.find_and_modify({'a': 1}, {'$set': {'b': 1}})
  replaced_doc = collection.find_and_modify({'b': 1}, {'c': 1})
  deleted_doc = collection.find_and_modify({'c': 1}, remove=True)

Can be changed to this::

  updated_doc = collection.find_one_and_update({'a': 1}, {'$set': {'b': 1}})
  replaced_doc = collection.find_one_and_replace({'b': 1}, {'c': 1})
  deleted_doc = collection.find_one_and_delete({'c': 1})

Collection.count and Cursor.count is removed
............................................

Removed :meth:`pymongo.collection.Collection.count` and
:meth:`pymongo.cursor.Cursor.count`. Use
:meth:`~pymongo.collection.Collection.count_documents` or
:meth:`~pymongo.collection.Collection.estimated_document_count` instead.
Code like this::

  ntotal = collection.count({})
  nmatched = collection.count({'price': {'$gte': 10}})
  # Or via the Cursor.count api:
  ntotal = collection.find({}).count()
  nmatched = collection.find({'price': {'$gte': 10}}).count()

Can be changed to this::

  ntotal = collection.estimated_document_count()
  nmatched = collection.count_documents({'price': {'$gte': 10}})

.. note:: When migrating from :meth:`count` to :meth:`count_documents`
   the following query operators must be replaced:

   +-------------+--------------------------------------------------------------+
   | Operator    | Replacement                                                  |
   +=============+==============================================================+
   | $where      | `$expr`_                                                     |
   +-------------+--------------------------------------------------------------+
   | $near       | `$geoWithin`_ with `$center`_; i.e.                          |
   |             | ``{'$geoWithin': {'$center': [[<x>,<y>], <radius>]}}``       |
   +-------------+--------------------------------------------------------------+
   | $nearSphere | `$geoWithin`_ with `$centerSphere`_; i.e.                    |
   |             | ``{'$geoWithin': {'$centerSphere': [[<x>,<y>], <radius>]}}`` |
   +-------------+--------------------------------------------------------------+

.. _$expr: https://mongodb.com/docs/manual/reference/operator/query/expr/
.. _$geoWithin: https://mongodb.com/docs/manual/reference/operator/query/geoWithin/
.. _$center: https://mongodb.com/docs/manual/reference/operator/query/center/
.. _$centerSphere: https://mongodb.com/docs/manual/reference/operator/query/centerSphere/

Collection.initialize_ordered_bulk_op and initialize_unordered_bulk_op is removed
.................................................................................

Removed :meth:`pymongo.collection.Collection.initialize_ordered_bulk_op`
and :class:`pymongo.bulk.BulkOperationBuilder`. Use
:meth:`pymongo.collection.Collection.bulk_write` instead. Code like this::

  batch = coll.initialize_ordered_bulk_op()
  batch.insert({'a': 1})
  batch.find({'a': 1}).update_one({'$set': {'b': 1}})
  batch.find({'a': 2}).upsert().replace_one({'b': 2})
  batch.find({'a': 3}).remove()
  result = batch.execute()

Can be changed to this::

  coll.bulk_write([
      InsertOne({'a': 1}),
      UpdateOne({'a': 1}, {'$set': {'b': 1}}),
      ReplaceOne({'a': 2}, {'b': 2}, upsert=True),
      DeleteOne({'a': 3}),
  ])

Collection.initialize_unordered_bulk_op is removed
..................................................

Removed :meth:`pymongo.collection.Collection.initialize_unordered_bulk_op`.
Use :meth:`pymongo.collection.Collection.bulk_write` instead. Code like this::

  batch = coll.initialize_unordered_bulk_op()
  batch.insert({'a': 1})
  batch.find({'a': 1}).update_one({'$set': {'b': 1}})
  batch.find({'a': 2}).upsert().replace_one({'b': 2})
  batch.find({'a': 3}).remove()
  result = batch.execute()

Can be changed to this::

  coll.bulk_write([
      InsertOne({'a': 1}),
      UpdateOne({'a': 1}, {'$set': {'b': 1}}),
      ReplaceOne({'a': 2}, {'b': 2}, upsert=True),
      DeleteOne({'a': 3}),
  ], ordered=False)

Collection.group is removed
...........................

Removed :meth:`pymongo.collection.Collection.group`. This method was
deprecated in PyMongo 3.5. MongoDB 4.2 removed the group command.
Use :meth:`~pymongo.collection.Collection.aggregate` with the ``$group`` stage
instead.

Collection.map_reduce and Collection.inline_map_reduce are removed
..................................................................

Removed :meth:`pymongo.collection.Collection.map_reduce` and
:meth:`pymongo.collection.Collection.inline_map_reduce`.
Migrate to :meth:`~pymongo.collection.Collection.aggregate` or run the
`mapReduce command`_ directly with :meth:`~pymongo.database.Database.command`
instead. For more guidance on this migration see:

- https://mongodb.com/docs/manual/reference/map-reduce-to-aggregation-pipeline/
- https://mongodb.com/docs/manual/reference/aggregation-commands-comparison/

.. _mapReduce command: https://mongodb.com/docs/manual/reference/command/mapReduce/

Collection.ensure_index is removed
..................................

Removed :meth:`pymongo.collection.Collection.ensure_index`. Use
:meth:`~pymongo.collection.Collection.create_index` or
:meth:`~pymongo.collection.Collection.create_indexes` instead. Note that
``ensure_index`` maintained an in memory cache of recently created indexes
whereas the newer methods do not. Applications should avoid frequent calls
to :meth:`~pymongo.collection.Collection.create_index` or
:meth:`~pymongo.collection.Collection.create_indexes`. Code like this::

  def persist(self, document):
      collection.ensure_index('a', unique=True)
      collection.insert_one(document)

Can be changed to this::

  def persist(self, document):
      if not self.created_index:
          collection.create_index('a', unique=True)
          self.created_index = True
      collection.insert_one(document)

Collection.reindex is removed
.............................

Removed :meth:`pymongo.collection.Collection.reindex`. Run the
`reIndex command`_ directly instead. Code like this::

  >>> result = database.my_collection.reindex()

can be changed to this::

  >>> result = database.command('reIndex', 'my_collection')

.. _reIndex command: https://mongodb.com/docs/manual/reference/command/reIndex/

The modifiers parameter is removed
..................................

Removed the ``modifiers`` parameter from
:meth:`~pymongo.collection.Collection.find`,
:meth:`~pymongo.collection.Collection.find_one`,
:meth:`~pymongo.collection.Collection.find_raw_batches`, and
:meth:`~pymongo.cursor.Cursor`. Pass the options directly to the method
instead. Code like this::

  cursor = coll.find({}, modifiers={
      "$comment": "comment",
      "$hint": {"_id": 1},
      "$min": {"_id": 0},
      "$max": {"_id": 6},
      "$maxTimeMS": 6000,
      "$returnKey": False,
      "$showDiskLoc": False,
  })

can be changed to this::

  cursor = coll.find(
      {},
      comment="comment",
      hint={"_id": 1},
      min={"_id": 0},
      max={"_id": 6},
      max_time_ms=6000,
      return_key=False,
      show_record_id=False,
  )

The hint parameter is required with min/max
...........................................

The ``hint`` option is now required when using ``min`` or ``max`` queries
with :meth:`~pymongo.collection.Collection.find` to ensure the query utilizes
the correct index. For example, code like this::

  cursor = coll.find({}, min={'x', min_value})

can be changed to this::

  cursor = coll.find({}, min={'x', min_value}, hint=[('x', ASCENDING)])

Collection.__bool__ raises NotImplementedError
..............................................
:class:`~pymongo.collection.Collection` now raises an error upon evaluating
as a Boolean. Code like this::

  if collection:

Can be changed to this::

  if collection is not None:

You must now explicitly compare with None.

Collection.find returns entire document with empty projection
.............................................................
Empty projections (eg {} or []) for
:meth:`~pymongo.collection.Collection.find`, and
:meth:`~pymongo.collection.Collection.find_one`
are passed to the server as-is rather than the previous behavior which
substituted in a projection of ``{"_id": 1}``. This means that an empty
projection will now return the entire document, not just the ``"_id"`` field.
To ensure that behavior remains consistent, code like this::

  coll.find({}, projection={})

Can be changed to this::

  coll.find({}, projection={"_id":1})

SONManipulator is removed
-------------------------

Removed :mod:`pymongo.son_manipulator`,
:class:`pymongo.son_manipulator.SONManipulator`,
:class:`pymongo.son_manipulator.ObjectIdInjector`,
:class:`pymongo.son_manipulator.ObjectIdShuffler`,
:class:`pymongo.son_manipulator.AutoReference`,
:class:`pymongo.son_manipulator.NamespaceInjector`,
:meth:`pymongo.database.Database.add_son_manipulator`,
:attr:`pymongo.database.Database.outgoing_copying_manipulators`,
:attr:`pymongo.database.Database.outgoing_manipulators`,
:attr:`pymongo.database.Database.incoming_copying_manipulators`, and
:attr:`pymongo.database.Database.incoming_manipulators`.

Removed the ``manipulate`` parameter from
:meth:`~pymongo.collection.Collection.find`,
:meth:`~pymongo.collection.Collection.find_one`, and
:meth:`~pymongo.cursor.Cursor`.

The :class:`pymongo.son_manipulator.SONManipulator` API has limitations as a
technique for transforming your data and was deprecated in PyMongo 3.0.
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.

Alternatively, if your application uses the ``SONManipulator`` API to convert
custom types to BSON, the :class:`~bson.codec_options.TypeCodec` and
:class:`~bson.codec_options.TypeRegistry` APIs may be a suitable alternative.
For more information, see `Custom Types <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/custom-types/type-codecs/#encode-data-with-type-codecs>`_.

``SON().items()`` now returns ``dict_items`` object.
----------------------------------------------------
:meth:`~bson.son.SON.items` now returns a ``dict_items`` object rather than
a list.

``SON().iteritems()`` removed.
------------------------------
``SON.iteritems()`` now removed. Code that looks like this::

    for k, v in son.iteritems():

Can now be replaced by code that looks like::

    for k, v in son.items():

IsMaster is removed
-------------------

Removed :class:`pymongo.ismaster.IsMaster`.
Use :class:`pymongo.hello.Hello` instead.

NotMasterError is removed
-------------------------

Removed :exc:`~pymongo.errors.NotMasterError`.
Use :exc:`~pymongo.errors.NotPrimaryError` instead.

CertificateError is removed
---------------------------

Removed :exc:`~pymongo.errors.CertificateError`. Since PyMongo 3.0 this error
is handled internally and is never raised to the application.

pymongo.GEOHAYSTACK is removed
------------------------------

Removed :attr:`pymongo.GEOHAYSTACK`. Replace with "geoHaystack" or create a
2d index and use $geoNear or $geoWithin instead.

UUIDLegacy is removed
---------------------

Removed :class:`bson.binary.UUIDLegacy`. Use
:meth:`bson.binary.Binary.from_uuid` instead.  Code like this::

  uu = uuid.uuid4()
  uuid_legacy = UUIDLegacy(uu)

can be changed to this::

  uu = uuid.uuid4()
  uuid_legacy = Binary.from_uuid(uu, PYTHON_LEGACY)

Default JSONMode changed from LEGACY to RELAXED
-----------------------------------------------

Changed the default JSON encoding representation from legacy to relaxed.
The json_mode parameter for :const:`bson.json_util.dumps` now defaults to
:const:`~bson.json_util.RELAXED_JSON_OPTIONS`.

GridFS changes
--------------

.. _removed-gridfs-checksum:

disable_md5 parameter is removed
................................

Removed the ``disable_md5`` option for :class:`~gridfs.GridFSBucket` and
:class:`~gridfs.GridFS`. GridFS no longer generates checksums.
Applications that desire a file digest should implement it outside GridFS
and store it with other file metadata. For example::

  import hashlib
  my_db = MongoClient().test
  fs = GridFSBucket(my_db)
  with fs.open_upload_stream("test_file") as grid_in:
      file_data = b'...'
      sha356 = hashlib.sha256(file_data).hexdigest()
      grid_in.write(file_data)
      grid_in.sha356 = sha356  # Set the custom 'sha356' field

Note that for large files, the checksum may need to be computed in chunks
to avoid the excessive memory needed to load the entire file at once.

Removed features with no migration path
---------------------------------------

cursor_manager support is removed
.................................

Removed :class:`pymongo.cursor_manager.CursorManager`,
:mod:`pymongo.cursor_manager`, and
:meth:`pymongo.mongo_client.MongoClient.set_cursor_manager`.

MongoClient.close_cursor is removed
...................................

Removed :meth:`pymongo.mongo_client.MongoClient.close_cursor` and
:meth:`pymongo.mongo_client.MongoClient.kill_cursors`. Instead, close cursors
with :meth:`pymongo.cursor.Cursor.close` or
:meth:`pymongo.command_cursor.CommandCursor.close`.

.. _killCursors command: https://mongodb.com/docs/manual/reference/command/killCursors/

Database.eval, Database.system_js, and SystemJS are removed
...........................................................

Removed :meth:`~pymongo.database.Database.eval`,
:data:`~pymongo.database.Database.system_js` and
:class:`~pymongo.database.SystemJS`. The eval command was deprecated in
MongoDB 3.0 and removed in MongoDB 4.2. There is no replacement for eval with
MongoDB 4.2+.

However, on MongoDB <= 4.0, code like this::

  >>> result = database.eval('function (x) {return x;}', 3)

can be changed to this::

  >>> from bson.code import Code
  >>> result = database.command('eval', Code('function (x) {return x;}'), args=[3]).get('retval')

Database.error, Database.last_status, Database.previous_error, and Database.reset_error_history are removed
...........................................................................................................

Removed :meth:`pymongo.database.Database.error`,
:meth:`pymongo.database.Database.last_status`,
:meth:`pymongo.database.Database.previous_error`, and
:meth:`pymongo.database.Database.reset_error_history`.
These methods are obsolete: all MongoDB write operations use an acknowledged
write concern and report their errors by default. These methods were
deprecated in PyMongo 2.8.

Collection.parallel_scan is removed
...................................

Removed :meth:`~pymongo.collection.Collection.parallel_scan`. MongoDB 4.2
removed the parallelCollectionScan command.  There is no replacement.

pymongo.message helpers are removed
...................................

Removed :meth:`pymongo.message.delete`, :meth:`pymongo.message.get_more`,
:meth:`pymongo.message.insert`, :meth:`pymongo.message.kill_cursors`,
:meth:`pymongo.message.query`, and :meth:`pymongo.message.update`.


Name is a required argument for pymongo.driver_info.DriverInfo
..............................................................

``name`` is now a required argument for the :class:`pymongo.driver_info.DriverInfo` class.

DBRef BSON/JSON decoding behavior
.................................

Changed the BSON and JSON decoding behavior of :class:`~bson.dbref.DBRef`
to match the behavior outlined in the `DBRef specification`_ version 1.0.
Specifically, PyMongo now only decodes a subdocument into a
:class:`~bson.dbref.DBRef` if and only if, it contains both ``$ref`` and
``$id`` fields and the ``$ref``, ``$id``, and ``$db`` fields are of the
correct type. Otherwise the document is returned as normal. Previously, any
subdocument containing a ``$ref`` field would be decoded as a
:class:`~bson.dbref.DBRef`.

.. _DBRef specification: https://github.com/mongodb/specifications/blob/master/source/dbref/dbref.md

Encoding a UUID raises an error by default
..........................................

The default ``uuid_representation`` for :class:`~bson.codec_options.CodecOptions`,
:class:`~bson.json_util.JSONOptions`, and
:class:`~pymongo.mongo_client.MongoClient` has been changed from
:data:`bson.binary.UuidRepresentation.PYTHON_LEGACY` to
:data:`bson.binary.UuidRepresentation.UNSPECIFIED`. Attempting to encode a
:class:`uuid.UUID` instance to BSON or JSON now produces an error by default.
If you were using UUIDs previously, you will need to set your ``uuid_representation`` to
:data:`bson.binary.UuidRepresentation.PYTHON_LEGACY` to avoid data corruption. If you do not have UUIDs,
then you should set :data:`bson.binary.UuidRepresentation.STANDARD`. If you do not explicitly set a value,
you will receive an error like this when attempting to encode a :class:`uuid.UUID`::

    ValueError: cannot encode native uuid.UUID with UuidRepresentation.UNSPECIFIED. UUIDs can be manually converted...

See `Handling UUIDs <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid/#universally-unique-ids--uuids->`_ for details.

Additional BSON classes implement ``__slots__``
...............................................

:class:`~bson.int64.Int64`, :class:`~bson.min_key.MinKey`,
:class:`~bson.max_key.MaxKey`, :class:`~bson.timestamp.Timestamp`,
:class:`~bson.regex.Regex`, and :class:`~bson.dbref.DBRef` now implement
``__slots__`` to reduce memory usage. This means that their attributes are fixed, and new
attributes cannot be added to the object at runtime.

---

### Doc Api Index (`doc/api/index.rst`)

API Documentation
=================

The PyMongo distribution contains three top-level packages for
interacting with MongoDB. :mod:`bson` is an implementation of the
`BSON format <https://bsonspec.org>`_, :mod:`pymongo` is a
full-featured driver for MongoDB, and :mod:`gridfs` is a set of tools
for working with the `GridFS
<https://github.com/mongodb/specifications/blob/master/source/gridfs/gridfs-spec.md/>`_ storage
specification.

.. toctree::
   :maxdepth: 2

   bson/index
   pymongo/index
   gridfs/index

---

### Doc Api Bson Binary (`doc/api/bson/binary.rst`)

:mod:`binary` -- Tools for representing binary data to be stored in MongoDB
===========================================================================

.. automodule:: bson.binary
   :synopsis: Tools for representing binary data to be stored in MongoDB

   .. autodata:: BINARY_SUBTYPE
   .. autodata:: FUNCTION_SUBTYPE
   .. autodata:: OLD_BINARY_SUBTYPE
   .. autodata:: OLD_UUID_SUBTYPE
   .. autodata:: UUID_SUBTYPE
   .. autodata:: STANDARD
   .. autodata:: PYTHON_LEGACY
   .. autodata:: JAVA_LEGACY
   .. autodata:: CSHARP_LEGACY
   .. autodata:: MD5_SUBTYPE
   .. autodata:: COLUMN_SUBTYPE
   .. autodata:: SENSITIVE_SUBTYPE
   .. autodata:: VECTOR_SUBTYPE
   .. autodata:: USER_DEFINED_SUBTYPE

   .. autoclass:: UuidRepresentation
      :members:

   .. autoclass:: BinaryVectorDtype
      :members:
      :show-inheritance:

   .. autoclass:: BinaryVector
      :members:


   .. autoclass:: Binary(data, subtype=BINARY_SUBTYPE)
      :members:
      :show-inheritance:

---

### Doc Api Bson Code (`doc/api/bson/code.rst`)

:mod:`code` -- Tools for representing JavaScript code
=====================================================

.. automodule:: bson.code
   :synopsis: Tools for representing JavaScript code

   .. autoclass:: Code(code, scope=None, **kwargs)
      :members:
      :show-inheritance:

---

### Doc Api Bson Codec Options (`doc/api/bson/codec_options.rst`)

:mod:`codec_options` -- Tools for specifying BSON codec options
===============================================================

.. automodule:: bson.codec_options
   :synopsis: Tools for specifying BSON codec options.
   :members:

---

### Doc Api Bson Datetime Ms (`doc/api/bson/datetime_ms.rst`)

:mod:`datetime_ms` -- Support for BSON UTC Datetime
===================================================

.. automodule:: bson.datetime_ms
   :synopsis: Support for BSON UTC datetimes.
   :members:

---

### Doc Api Bson Dbref (`doc/api/bson/dbref.rst`)

:mod:`dbref` -- Tools for manipulating DBRefs (references to documents stored in MongoDB)
=========================================================================================

.. automodule:: bson.dbref
   :synopsis: Tools for manipulating DBRefs (references to documents stored in MongoDB)
   :members:

---

### Doc Api Bson Decimal128 (`doc/api/bson/decimal128.rst`)

:mod:`decimal128` -- Support for BSON Decimal128
================================================
.. automodule:: bson.decimal128
   :members:

---

### Doc Api Bson Errors (`doc/api/bson/errors.rst`)

:mod:`errors` -- Exceptions raised by the :mod:`bson` package
=============================================================

.. automodule:: bson.errors
   :synopsis: Exceptions raised by the bson package
   :members:

---

### Doc Api Bson Index (`doc/api/bson/index.rst`)

:mod:`bson` -- BSON (Binary JSON) Encoding and Decoding
=======================================================

.. automodule:: bson
   :synopsis: BSON (Binary JSON) Encoding and Decoding
   :members: BSON, decode, decode_all, decode_file_iter, decode_iter, encode, gen_list_name, has_c, is_valid

Sub-modules:

.. toctree::
   :maxdepth: 2

   binary
   code
   codec_options
   datetime_ms
   dbref
   decimal128
   errors
   int64
   json_util
   max_key
   min_key
   objectid
   raw_bson
   regex
   son
   timestamp
   tz_util

---

### Doc Api Bson Int64 (`doc/api/bson/int64.rst`)

:mod:`int64` -- Tools for representing BSON int64
=================================================
.. versionadded:: 3.0

.. automodule:: bson.int64
   :synopsis: Tools for representing BSON int64
   :members:

---

### Doc Api Bson Json Util (`doc/api/bson/json_util.rst`)

:mod:`json_util` -- Tools for using Python's :mod:`json` module with BSON documents
===================================================================================
.. automodule:: bson.json_util
   :synopsis: Tools for using Python's json module with BSON documents
   :members:
   :undoc-members:
   :member-order: bysource

---

### Doc Api Bson Max Key (`doc/api/bson/max_key.rst`)

:mod:`max_key` -- Representation for the MongoDB internal MaxKey type
=====================================================================
.. automodule:: bson.max_key
   :synopsis: Representation for the MongoDB internal MaxKey type
   :members:

---

### Doc Api Bson Min Key (`doc/api/bson/min_key.rst`)

:mod:`min_key` -- Representation for the MongoDB internal MinKey type
=====================================================================
.. automodule:: bson.min_key
   :synopsis: Representation for the MongoDB internal MinKey type
   :members:

---

### Doc Api Bson Objectid (`doc/api/bson/objectid.rst`)

:mod:`objectid` -- Tools for working with MongoDB ObjectIds
===========================================================

.. automodule:: bson.objectid
   :synopsis: Tools for working with MongoDB ObjectIds

   .. autoclass:: bson.objectid.ObjectId(oid=None)
      :members:

      .. describe:: str(o)

         Get a hex encoded version of :class:`ObjectId` `o`.

         The following property always holds:

         .. testsetup::

           from bson.objectid import ObjectId

         .. doctest::

           >>> o = ObjectId()
           >>> o == ObjectId(str(o))
           True

         This representation is useful for urls or other places where
         ``o.binary`` is inappropriate.

---

### Doc Api Bson Raw Bson (`doc/api/bson/raw_bson.rst`)

:mod:`raw_bson` -- Tools for representing raw BSON documents.
=============================================================
.. automodule:: bson.raw_bson
   :synopsis: Tools for representing raw BSON documents.
   :members:

---

### Doc Api Bson Regex (`doc/api/bson/regex.rst`)

:mod:`regex` -- Tools for representing MongoDB regular expressions
==================================================================
.. versionadded:: 2.7

.. automodule:: bson.regex
   :synopsis: Tools for representing MongoDB regular expressions
   :members:

---

### Doc Api Bson Son (`doc/api/bson/son.rst`)

:mod:`son` -- Tools for working with SON, an ordered mapping
============================================================

.. automodule:: bson.son
   :synopsis: Tools for working with SON, an ordered mapping
   :members:

---

### Doc Api Bson Timestamp (`doc/api/bson/timestamp.rst`)

:mod:`timestamp` -- Tools for representing MongoDB internal Timestamps
======================================================================
.. automodule:: bson.timestamp
   :synopsis: Tools for representing MongoDB internal Timestamps
   :members:

---

### Doc Api Bson Tz Util (`doc/api/bson/tz_util.rst`)

:mod:`tz_util` -- Utilities for dealing with timezones in Python
================================================================

.. automodule:: bson.tz_util
   :synopsis: Utilities for dealing with timezones in Python
   :members:

---

### Doc Api Gridfs Errors (`doc/api/gridfs/errors.rst`)

:mod:`errors` -- Exceptions raised by the :mod:`gridfs` package
=================================================================

.. automodule:: gridfs.errors
   :synopsis: Exceptions raised by the gridfs package
   :members:

---

### Doc Api Gridfs Grid File (`doc/api/gridfs/grid_file.rst`)

:mod:`grid_file` -- Tools for representing files stored in GridFS
=================================================================

.. automodule:: gridfs.grid_file
   :synopsis: Tools for representing files stored in GridFS

   .. autoclass:: GridIn
      :members:

      .. autoattribute:: _id

   .. autoclass:: GridOut
      :members:

      .. autoattribute:: _id
      .. automethod:: __iter__

   .. autoclass:: GridOutCursor
      :members:

---

### Doc Api Gridfs Index (`doc/api/gridfs/index.rst`)

:mod:`gridfs` -- Tools for working with GridFS
==============================================

.. automodule:: gridfs
   :synopsis: Tools for working with GridFS
   :members: GridFS, GridFSBucket

Sub-modules:

.. toctree::
   :maxdepth: 3

   asynchronous/index
   errors
   grid_file

---

### Doc Api Pymongo Auth Oidc (`doc/api/pymongo/auth_oidc.rst`)

:mod:`auth_oidc` -- MONGODB-OIDC Authentication
===========================================================================

.. automodule:: pymongo.auth_oidc
   :members:

---

### Doc Api Pymongo Change Stream (`doc/api/pymongo/change_stream.rst`)

:mod:`change_stream` -- Watch changes on a collection, database, or cluster
===========================================================================

.. automodule:: pymongo.change_stream
   :members:
   :inherited-members:

---

### Doc Api Pymongo Client Options (`doc/api/pymongo/client_options.rst`)

:mod:`client_options` -- Read only configuration options for a MongoClient.
===========================================================================

.. automodule:: pymongo.client_options

   .. autoclass:: pymongo.client_options.ClientOptions()
      :members:

---

### Doc Api Pymongo Client Session (`doc/api/pymongo/client_session.rst`)

:mod:`client_session` -- Logical sessions for sequential operations
===================================================================

.. automodule:: pymongo.client_session
   :members:
   :inherited-members:

---

### Doc Api Pymongo Collation (`doc/api/pymongo/collation.rst`)

:mod:`collation` -- Tools for working with collations.
======================================================

.. automodule:: pymongo.collation
   :synopsis: Tools for working with collations.

   .. autoclass:: pymongo.collation.Collation
   .. autoclass:: pymongo.collation.CollationStrength
      :members:
      :member-order: bysource
   .. autoclass:: pymongo.collation.CollationAlternate
      :members:
      :member-order: bysource
   .. autoclass:: pymongo.collation.CollationCaseFirst
      :members:
      :member-order: bysource
   .. autoclass:: pymongo.collation.CollationMaxVariable
      :members:
      :member-order: bysource

---

### Doc Api Pymongo Collection (`doc/api/pymongo/collection.rst`)

:mod:`collection` -- Collection level operations
================================================

.. automodule:: pymongo.collection
   :synopsis: Collection level operations

   .. autodata:: pymongo.ASCENDING
   .. autodata:: pymongo.DESCENDING
   .. autodata:: pymongo.GEO2D
   .. autodata:: pymongo.GEOSPHERE
   .. autodata:: pymongo.HASHED
   .. autodata:: pymongo.TEXT

   .. autoclass:: pymongo.collection.ReturnDocument

      .. autoattribute:: BEFORE
         :annotation:
      .. autoattribute:: AFTER
         :annotation:

   .. autoclass:: pymongo.collection.Collection(database, name, create=False, **kwargs)

      .. describe:: c[name] || c.name

         Get the `name` sub-collection of :class:`Collection` `c`.

         Raises :class:`~pymongo.errors.InvalidName` if an invalid
         collection name is used.

      .. autoattribute:: full_name
      .. autoattribute:: name
      .. autoattribute:: database
      .. autoattribute:: codec_options
      .. autoattribute:: read_preference
      .. autoattribute:: write_concern
      .. autoattribute:: read_concern
      .. automethod:: with_options
      .. automethod:: bulk_write
      .. automethod:: insert_one
      .. automethod:: insert_many
      .. automethod:: replace_one
      .. automethod:: update_one
      .. automethod:: update_many
      .. automethod:: delete_one
      .. automethod:: delete_many
      .. automethod:: aggregate
      .. automethod:: aggregate_raw_batches
      .. automethod:: watch
      .. automethod:: find(filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, batch_size=0, collation=None, hint=None, max_scan=None, max_time_ms=None, max=None, min=None, return_key=False, show_record_id=False, snapshot=False, comment=None, session=None, allow_disk_use=None)
      .. automethod:: find_raw_batches(filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, batch_size=0, collation=None, hint=None, max_scan=None, max_time_ms=None, max=None, min=None, return_key=False, show_record_id=False, snapshot=False, comment=None, session=None, allow_disk_use=None)
      .. automethod:: find_one(filter=None, *args, **kwargs)
      .. automethod:: find_one_and_delete
      .. automethod:: find_one_and_replace(filter, replacement, projection=None, sort=None, return_document=ReturnDocument.BEFORE, hint=None, session=None, **kwargs)
      .. automethod:: find_one_and_update(filter, update, projection=None, sort=None, return_document=ReturnDocument.BEFORE, array_filters=None, hint=None, session=None, **kwargs)
      .. automethod:: count_documents
      .. automethod:: estimated_document_count
      .. automethod:: distinct
      .. automethod:: create_index
      .. automethod:: create_indexes
      .. automethod:: drop_index
      .. automethod:: drop_indexes
      .. automethod:: list_indexes
      .. automethod:: index_information
      .. automethod:: create_search_index
      .. automethod:: create_search_indexes
      .. automethod:: drop_search_index
      .. automethod:: list_search_indexes
      .. automethod:: update_search_index
      .. automethod:: drop
      .. automethod:: rename
      .. automethod:: options
      .. automethod:: __getitem__
      .. automethod:: __getattr__

---

### Doc Api Pymongo Command Cursor (`doc/api/pymongo/command_cursor.rst`)

:mod:`command_cursor` -- Tools for iterating over MongoDB command results
=========================================================================

.. automodule:: pymongo.command_cursor
   :synopsis: Tools for iterating over MongoDB command results
   :members:
   :inherited-members:

---

### Doc Api Pymongo Cursor (`doc/api/pymongo/cursor.rst`)

:mod:`cursor` -- Tools for iterating over MongoDB query results
===============================================================

.. automodule:: pymongo.cursor
   :synopsis: Tools for iterating over MongoDB query results

   .. autoclass:: pymongo.cursor.CursorType

      .. autoattribute:: NON_TAILABLE
         :annotation:
      .. autoattribute:: TAILABLE
         :annotation:
      .. autoattribute:: TAILABLE_AWAIT
         :annotation:
      .. autoattribute:: EXHAUST
         :annotation:

   .. autoclass:: pymongo.cursor.Cursor(collection, filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, batch_size=0, collation=None, hint=None, max_scan=None, max_time_ms=None, max=None, min=None, return_key=False, show_record_id=False, snapshot=False, comment=None, session=None, allow_disk_use=None)
      :members:
      :inherited-members:

      .. describe:: c[index]

         See :meth:`__getitem__` and read the warning.

      .. automethod:: __getitem__

   .. autoclass:: pymongo.cursor.RawBatchCursor(collection, filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, batch_size=0, collation=None, hint=None, max_scan=None, max_time_ms=None, max=None, min=None, return_key=False, show_record_id=False, snapshot=False, comment=None, allow_disk_use=None)

---

### Doc Api Pymongo Database (`doc/api/pymongo/database.rst`)

:mod:`database` -- Database level operations
============================================

.. automodule:: pymongo.database
   :synopsis: Database level operations

   .. autodata:: pymongo.auth.MECHANISMS

   .. autoclass:: pymongo.database.Database
      :members:

      .. describe:: db[collection_name] || db.collection_name

         Get the `collection_name` :class:`~pymongo.collection.Collection` of
         :class:`Database` `db`.

         Raises :class:`~pymongo.errors.InvalidName` if an invalid collection
         name is used.

         .. note::  Use dictionary style access if `collection_name` is an
            attribute of the :class:`Database` class eg: db[`collection_name`].

      .. automethod:: __getitem__
      .. automethod:: __getattr__
      .. autoattribute:: codec_options
      .. autoattribute:: read_preference
      .. autoattribute:: write_concern
      .. autoattribute:: read_concern

---

### Doc Api Pymongo Driver Info (`doc/api/pymongo/driver_info.rst`)

:mod:`driver_info`
==================

.. automodule:: pymongo.driver_info

   .. autoclass:: pymongo.driver_info.DriverInfo(name=None, version=None, platform=None)

---

### Doc Api Pymongo Encryption (`doc/api/pymongo/encryption.rst`)

:mod:`encryption` -- Client-Side Field Level Encryption
=======================================================

.. automodule:: pymongo.encryption
   :members:

---

### Doc Api Pymongo Encryption Options (`doc/api/pymongo/encryption_options.rst`)

:mod:`encryption_options` -- Automatic Client-Side Field Level Encryption
=========================================================================

.. automodule:: pymongo.encryption_options
   :synopsis: Support for automatic client-side field level encryption
   :members:

---

### Doc Api Pymongo Errors (`doc/api/pymongo/errors.rst`)

:mod:`errors` -- Exceptions raised by the :mod:`pymongo` package
================================================================

.. automodule:: pymongo.errors
   :synopsis: Exceptions raised by the pymongo package
   :members:

---

### Doc Api Pymongo Event Loggers (`doc/api/pymongo/event_loggers.rst`)

:mod:`event_loggers` -- Example loggers
===========================================


.. automodule:: pymongo.event_loggers
   :synopsis: A collection of simple listeners for monitoring driver events.
   :members:

---

### Doc Api Pymongo Index (`doc/api/pymongo/index.rst`)

:mod:`pymongo` -- Python driver for MongoDB
===========================================

.. automodule:: pymongo
   :synopsis: Python driver for MongoDB

   .. autodata:: version
   .. data:: MongoClient

      Alias for :class:`pymongo.mongo_client.MongoClient`.

   .. data:: AsyncMongoClient

      Alias for :class:`pymongo.asynchronous.mongo_client.AsyncMongoClient`.

   .. data:: ReadPreference

      Alias for :class:`pymongo.read_preferences.ReadPreference`.

   .. autofunction:: has_c
   .. data:: MIN_SUPPORTED_WIRE_VERSION

      The minimum wire protocol version PyMongo supports.

   .. data:: MAX_SUPPORTED_WIRE_VERSION

      The maximum wire protocol version PyMongo supports.

   .. autofunction:: timeout

Sub-modules:

.. toctree::
   :maxdepth: 3

   asynchronous/index
   auth_oidc
   change_stream
   client_options
   client_session
   collation
   collection
   command_cursor
   cursor
   database
   driver_info
   encryption
   encryption_options
   errors
   mongo_client
   monitoring
   operations
   pool
   read_concern
   read_preferences
   results
   server_api
   server_description
   topology_description
   uri_parser
   write_concern
   event_loggers

---

### Doc Api Pymongo Mongo Client (`doc/api/pymongo/mongo_client.rst`)

:mod:`mongo_client` -- Tools for connecting to MongoDB
======================================================

.. automodule:: pymongo.mongo_client
   :synopsis: Tools for connecting to MongoDB

   .. autoclass:: pymongo.mongo_client.MongoClient(host='localhost', port=27017, document_class=dict, tz_aware=False, connect=True, **kwargs)

      .. automethod:: close

      .. describe:: c[db_name] || c.db_name

         Get the `db_name` :class:`~pymongo.database.Database` on :class:`MongoClient` `c`.

         Raises :class:`~pymongo.errors.InvalidName` if an invalid database name is used.

      .. autoattribute:: topology_description
      .. autoattribute:: address
      .. autoattribute:: primary
      .. autoattribute:: secondaries
      .. autoattribute:: arbiters
      .. autoattribute:: is_primary
      .. autoattribute:: is_mongos
      .. autoattribute:: nodes
      .. autoattribute:: codec_options
      .. autoattribute:: read_preference
      .. autoattribute:: write_concern
      .. autoattribute:: read_concern
      .. autoattribute:: options
      .. automethod:: start_session
      .. automethod:: list_databases
      .. automethod:: list_database_names
      .. automethod:: drop_database
      .. automethod:: get_default_database
      .. automethod:: get_database
      .. automethod:: server_info
      .. automethod:: watch
      .. automethod:: bulk_write
      .. automethod:: __getitem__
      .. automethod:: __getattr__

---

### Doc Api Pymongo Monitoring (`doc/api/pymongo/monitoring.rst`)

:mod:`monitoring` -- Tools for monitoring driver events.
========================================================

.. automodule:: pymongo.monitoring
   :synopsis: Tools for monitoring driver events.

   .. autofunction:: register(listener)
   .. autoclass:: CommandListener
      :members:
      :inherited-members:
   .. autoclass:: ServerListener
      :members:
      :inherited-members:
   .. autoclass:: ServerHeartbeatListener
      :members:
      :inherited-members:
   .. autoclass:: TopologyListener
      :members:
      :inherited-members:
   .. autoclass:: ConnectionPoolListener
      :members:
      :inherited-members:

   .. autoclass:: CommandStartedEvent
      :members:
      :inherited-members:
   .. autoclass:: CommandSucceededEvent
      :members:
      :inherited-members:
   .. autoclass:: CommandFailedEvent
      :members:
      :inherited-members:
   .. autoclass:: ServerDescriptionChangedEvent
      :members:
      :inherited-members:
   .. autoclass:: ServerOpeningEvent
      :members:
      :inherited-members:
   .. autoclass:: ServerClosedEvent
      :members:
      :inherited-members:
   .. autoclass:: TopologyDescriptionChangedEvent
      :members:
      :inherited-members:
   .. autoclass:: TopologyOpenedEvent
      :members:
      :inherited-members:
   .. autoclass:: TopologyClosedEvent
      :members:
      :inherited-members:
   .. autoclass:: ServerHeartbeatStartedEvent
      :members:
      :inherited-members:
   .. autoclass:: ServerHeartbeatSucceededEvent
      :members:
      :inherited-members:
   .. autoclass:: ServerHeartbeatFailedEvent
      :members:
      :inherited-members:

   .. autoclass:: PoolCreatedEvent
      :members:
      :inherited-members:
   .. autoclass:: PoolClearedEvent
      :members:
      :inherited-members:
   .. autoclass:: PoolClosedEvent
      :members:
      :inherited-members:

   .. autoclass:: ConnectionCreatedEvent
      :members:
      :inherited-members:
   .. autoclass:: ConnectionReadyEvent
      :members:
      :inherited-members:

   .. autoclass:: ConnectionClosedReason
      :members:

   .. autoclass:: ConnectionClosedEvent
      :members:
      :inherited-members:
   .. autoclass:: ConnectionCheckOutStartedEvent
      :members:
      :inherited-members:

   .. autoclass:: ConnectionCheckOutFailedReason
      :members:

   .. autoclass:: ConnectionCheckOutFailedEvent
      :members:
      :inherited-members:
   .. autoclass:: ConnectionCheckedOutEvent
      :members:
      :inherited-members:
   .. autoclass:: ConnectionCheckedInEvent
      :members:
      :inherited-members:

---

### Doc Api Pymongo Operations (`doc/api/pymongo/operations.rst`)

:mod:`operations` -- Operation class definitions
================================================

.. automodule:: pymongo.operations
   :synopsis: Operation class definitions
   :members:

---

### Doc Api Pymongo Pool (`doc/api/pymongo/pool.rst`)

:mod:`pool` -- Pool module for use with a MongoDB client.
==============================================================

.. automodule:: pymongo.pool

   .. autoclass:: pymongo.pool.PoolOptions()
      :members:

---

### Doc Api Pymongo Read Concern (`doc/api/pymongo/read_concern.rst`)

:mod:`read_concern` -- Tools for working with read concern.
===========================================================

.. automodule:: pymongo.read_concern
   :synopsis: Tools for working with read concern.
   :members:
   :inherited-members:

---

### Doc Api Pymongo Read Preferences (`doc/api/pymongo/read_preferences.rst`)

:mod:`read_preferences` -- Utilities for choosing which member of a replica set to read from.
=============================================================================================

.. automodule:: pymongo.read_preferences
   :synopsis: Utilities for choosing which member of a replica set to read from.

   .. autoclass:: pymongo.read_preferences.Primary

      .. max_staleness, min_wire_version, mongos_mode, and tag_sets don't
         make sense for Primary.

      .. autoattribute:: document
      .. autoattribute:: mode
      .. autoattribute:: name

   .. autoclass:: pymongo.read_preferences.PrimaryPreferred
      :inherited-members:
   .. autoclass:: pymongo.read_preferences.Secondary
      :inherited-members:
   .. autoclass:: pymongo.read_preferences.SecondaryPreferred
      :inherited-members:
   .. autoclass:: pymongo.read_preferences.Nearest
      :inherited-members:

   .. autoclass:: ReadPreference

      .. autoattribute:: PRIMARY
      .. autoattribute:: PRIMARY_PREFERRED
      .. autoattribute:: SECONDARY
      .. autoattribute:: SECONDARY_PREFERRED
      .. autoattribute:: NEAREST

---

### Doc Api Pymongo Results (`doc/api/pymongo/results.rst`)

:mod:`results` -- Result class definitions
==========================================

.. automodule:: pymongo.results
   :synopsis: Result class definitions
   :members:
   :inherited-members:

---

### Doc Api Pymongo Server Api (`doc/api/pymongo/server_api.rst`)

:mod:`server_api` -- Support for MongoDB Stable API
======================================================

.. automodule:: pymongo.server_api
   :synopsis: Support for MongoDB Stable API

   .. autoclass:: pymongo.server_api.ServerApi
      :members:

   .. autoclass:: pymongo.server_api.ServerApiVersion
      :members:

---

### Doc Api Pymongo Server Description (`doc/api/pymongo/server_description.rst`)

:orphan:

:mod:`server_description` -- An object representation of a server the driver is connected to.
=============================================================================================

.. automodule:: pymongo.server_description

   .. autoclass:: pymongo.server_description.ServerDescription()
      :members:

---

### Doc Api Pymongo Topology Description (`doc/api/pymongo/topology_description.rst`)

:orphan:

:mod:`topology_description` -- An object representation of a deployment of MongoDB servers.
===========================================================================================

.. automodule:: pymongo.topology_description

   .. autoclass:: pymongo.topology_description.TopologyDescription()
      :members:

---

### Doc Api Pymongo Uri Parser (`doc/api/pymongo/uri_parser.rst`)

:mod:`uri_parser` -- Tools to parse and validate a MongoDB URI
==============================================================

.. automodule:: pymongo.uri_parser
   :synopsis: Tools to parse and validate a MongoDB URI.
   :members:

---

### Doc Api Pymongo Write Concern (`doc/api/pymongo/write_concern.rst`)

:mod:`write_concern` -- Tools for specifying write concern
==========================================================

.. automodule:: pymongo.write_concern
   :synopsis: Tools for specifying write concern.
   :members:

---

### Doc Api Gridfs Asynchronous Grid File (`doc/api/gridfs/asynchronous/grid_file.rst`)

:mod:`grid_file` -- Async tools for representing files stored in GridFS
=======================================================================

.. automodule:: gridfs.asynchronous.grid_file
   :synopsis: Async tools for representing files stored in GridFS

   .. autoclass:: AsyncGridIn
      :members:

      .. autoattribute:: _id

   .. autoclass:: AsyncGridOut
      :members:

      .. autoattribute:: _id
      .. automethod:: __aiter__

   .. autoclass:: AsyncGridOutCursor
      :members:

---

### Doc Api Gridfs Asynchronous Index (`doc/api/gridfs/asynchronous/index.rst`)

:mod:`gridfs async` -- Async tools for working with GridFS
==========================================================


.. automodule:: gridfs.asynchronous
   :synopsis: Async tools for working with GridFS
   :members: AsyncGridFS, AsyncGridFSBucket

Sub-modules:

.. toctree::
   :maxdepth: 2

   grid_file

---

### Doc Api Pymongo Asynchronous Change Stream (`doc/api/pymongo/asynchronous/change_stream.rst`)

:mod:`change_stream` -- Watch changes on a collection, database, or cluster
===========================================================================


.. automodule:: pymongo.asynchronous.change_stream
   :members:
   :inherited-members:

---

### Doc Api Pymongo Asynchronous Client Session (`doc/api/pymongo/asynchronous/client_session.rst`)

:mod:`client_session` -- Logical sessions for sequential operations
===================================================================


.. automodule:: pymongo.asynchronous.client_session
   :members:
   :inherited-members:

---

### Doc Api Pymongo Asynchronous Collection (`doc/api/pymongo/asynchronous/collection.rst`)

:mod:`collection` -- Collection level operations
================================================


.. automodule:: pymongo.asynchronous.collection
   :synopsis: Collection level operations

   .. autoclass:: pymongo.asynchronous.collection.ReturnDocument

   .. autoclass:: pymongo.asynchronous.collection.AsyncCollection(database, name, create=False, **kwargs)

      .. describe:: c[name] || c.name

         Get the `name` sub-collection of :class:`AsyncCollection` `c`.

         Raises :class:`~pymongo.asynchronous.errors.InvalidName` if an invalid
         collection name is used.

      .. autoattribute:: full_name
      .. autoattribute:: name
      .. autoattribute:: database
      .. autoattribute:: codec_options
      .. autoattribute:: read_preference
      .. autoattribute:: write_concern
      .. autoattribute:: read_concern
      .. automethod:: with_options
      .. automethod:: bulk_write
      .. automethod:: insert_one
      .. automethod:: insert_many
      .. automethod:: replace_one
      .. automethod:: update_one
      .. automethod:: update_many
      .. automethod:: delete_one
      .. automethod:: delete_many
      .. automethod:: aggregate
      .. automethod:: aggregate_raw_batches
      .. automethod:: watch
      .. automethod:: find(filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, batch_size=0, collation=None, hint=None, max_scan=None, max_time_ms=None, max=None, min=None, return_key=False, show_record_id=False, snapshot=False, comment=None, session=None, allow_disk_use=None)
      .. automethod:: find_raw_batches(filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, batch_size=0, collation=None, hint=None, max_scan=None, max_time_ms=None, max=None, min=None, return_key=False, show_record_id=False, snapshot=False, comment=None, session=None, allow_disk_use=None)
      .. automethod:: find_one(filter=None, *args, **kwargs)
      .. automethod:: find_one_and_delete
      .. automethod:: find_one_and_replace(filter, replacement, projection=None, sort=None, return_document=ReturnDocument.BEFORE, hint=None, session=None, **kwargs)
      .. automethod:: find_one_and_update(filter, update, projection=None, sort=None, return_document=ReturnDocument.BEFORE, array_filters=None, hint=None, session=None, **kwargs)
      .. automethod:: count_documents
      .. automethod:: estimated_document_count
      .. automethod:: distinct
      .. automethod:: create_index
      .. automethod:: create_indexes
      .. automethod:: drop_index
      .. automethod:: drop_indexes
      .. automethod:: list_indexes
      .. automethod:: index_information
      .. automethod:: create_search_index
      .. automethod:: create_search_indexes
      .. automethod:: drop_search_index
      .. automethod:: list_search_indexes
      .. automethod:: update_search_index
      .. automethod:: drop
      .. automethod:: rename
      .. automethod:: options
      .. automethod:: __getitem__
      .. automethod:: __getattr__

---

### Doc Api Pymongo Asynchronous Command Cursor (`doc/api/pymongo/asynchronous/command_cursor.rst`)

:mod:`command_cursor` -- Tools for iterating over MongoDB command results
=========================================================================


.. automodule:: pymongo.asynchronous.command_cursor
   :synopsis: Tools for iterating over MongoDB command results
   :members:
   :inherited-members:

---

### Doc Api Pymongo Asynchronous Cursor (`doc/api/pymongo/asynchronous/cursor.rst`)

:mod:`cursor` -- Tools for iterating over MongoDB query results
===============================================================


.. automodule:: pymongo.asynchronous.cursor
   :synopsis: Tools for iterating over MongoDB query results

   .. autoclass:: pymongo.asynchronous.cursor.AsyncCursor(collection, filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, batch_size=0, collation=None, hint=None, max_scan=None, max_time_ms=None, max=None, min=None, return_key=False, show_record_id=False, snapshot=False, comment=None, session=None, allow_disk_use=None)
      :members:
      :inherited-members:


      .. describe:: c[index]

         See :meth:`__getitem__` and read the warning.

      .. automethod:: __getitem__

   .. autoclass:: pymongo.asynchronous.cursor.AsyncRawBatchCursor(collection, filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, batch_size=0, collation=None, hint=None, max_scan=None, max_time_ms=None, max=None, min=None, return_key=False, show_record_id=False, snapshot=False, comment=None, allow_disk_use=None)

---

### Doc Api Pymongo Asynchronous Database (`doc/api/pymongo/asynchronous/database.rst`)

:mod:`database` -- Database level operations
============================================


.. automodule:: pymongo.asynchronous.database
   :synopsis: Database level operations

   .. autoclass:: pymongo.asynchronous.database.AsyncDatabase
      :members:

      .. describe:: db[collection_name] || db.collection_name

         Get the `collection_name` :class:`~pymongo.asynchronous.collection.AsyncCollection` of
         :class:`AsyncDatabase` `db`.

         Raises :class:`~pymongo.errors.InvalidName` if an invalid collection
         name is used.

         .. note::  Use dictionary style access if `collection_name` is an
            attribute of the :class:`AsyncDatabase` class eg: db[`collection_name`].

      .. automethod:: __getitem__
      .. automethod:: __getattr__
      .. autoattribute:: codec_options
      .. autoattribute:: read_preference
      .. autoattribute:: write_concern
      .. autoattribute:: read_concern

---

### Doc Api Pymongo Asynchronous Index (`doc/api/pymongo/asynchronous/index.rst`)

:mod:`pymongo async` -- Async Python driver for MongoDB
=======================================================


.. automodule:: pymongo.asynchronous
   :synopsis: Asynchronous Python driver for MongoDB

   .. data:: AsyncMongoClient

      Alias for :class:`pymongo.asynchronous.mongo_client.MongoClient`.

Sub-modules:

.. toctree::
   :maxdepth: 2

   change_stream
   client_session
   collection
   command_cursor
   cursor
   database
   mongo_client

---

### Doc Api Pymongo Asynchronous Mongo Client (`doc/api/pymongo/asynchronous/mongo_client.rst`)

:mod:`mongo_client` -- Tools for connecting to MongoDB
======================================================


.. automodule:: pymongo.asynchronous.mongo_client
   :synopsis: Tools for connecting to MongoDB

   .. autoclass:: pymongo.asynchronous.mongo_client.AsyncMongoClient(host='localhost', port=27017, document_class=dict, tz_aware=False, connect=True, **kwargs)

      .. automethod:: close

      .. describe:: c[db_name] || c.db_name

         Get the `db_name` :class:`~pymongo.asynchronous.database.AsyncDatabase` on :class:`AsyncMongoClient` `c`.

         Raises :class:`~pymongo.errors.InvalidName` if an invalid database name is used.

      .. autoattribute:: topology_description
      .. autoattribute:: address
      .. autoattribute:: primary
      .. autoattribute:: secondaries
      .. autoattribute:: arbiters
      .. autoattribute:: is_primary
      .. autoattribute:: is_mongos
      .. autoattribute:: nodes
      .. autoattribute:: codec_options
      .. autoattribute:: read_preference
      .. autoattribute:: write_concern
      .. autoattribute:: read_concern
      .. autoattribute:: options
      .. automethod:: start_session
      .. automethod:: list_databases
      .. automethod:: list_database_names
      .. automethod:: drop_database
      .. automethod:: get_default_database
      .. automethod:: get_database
      .. automethod:: server_info
      .. automethod:: watch
      .. automethod:: bulk_write
      .. automethod:: __getitem__
      .. automethod:: __getattr__

---

--- METRICS ---
- Files Extracted: 66
- Estimated Token Budget: ~69969 tokens
- Canonical Reference: https://codewiki.google/github.com/mongodb/mongo-python-driver

Technical Documentation: mongodb/mongo-python-driver

Overview (`README.md`) Copy Section

PyMongo

About Copy Chapter

Documentation Copy Chapter

Support / Feedback Copy Chapter

Bugs / Feature Requests Copy Chapter

How To Ask For Help Copy Section

Security Vulnerabilities Copy Section

Installation Copy Chapter

Dependencies Copy Chapter

Examples Copy Chapter

Learning Resources Copy Chapter

Testing Copy Chapter

Overview (`integration_tests/README.md`) Copy Section

Integration Tests

Overview (`test/lambda/README.md`) Copy Section

AWS Lambda Testing Copy Chapter

Running locally

Usage

Doc Changelog (`doc/changelog.rst`) Copy Section

Changelog

Changes in Version 4.20.0 (2026/XX/XX) Copy Chapter

Changes in Version 4.19.0 (2026/10/14) Copy Chapter

Changes in Version 4.18.2 (2026/09/24) Copy Chapter

Changes in Version 4.18.1 (2026/09/10) Copy Chapter

Changes in Version 4.18.0 (2026/09/03) Copy Chapter

Changes in Version 4.17.0 (2026/04/20) Copy Chapter

Changes in Version 4.16.0 (2026/01/07) Copy Chapter

Changes in Version 4.15.5 (2025/12/02) Copy Chapter

Changes in Version 4.15.4 (2025/10/21) Copy Chapter

Changes in Version 4.15.3 (2025/10/07) Copy Chapter

Changes in Version 4.15.2 (2025/10/01) Copy Chapter

Changes in Version 4.15.1 (2025/09/16) Copy Chapter

Changes in Version 4.15.0 (2025/09/10) Copy Chapter

Changes in Version 4.14.1 (2025/08/19) Copy Chapter

Changes in Version 4.14.0 (2025/08/06) Copy Chapter

Changes in Version 4.13.2 (2025/06/17) Copy Chapter

Changes in Version 4.13.1 (2025/06/10) Copy Chapter

Changes in Version 4.13.0 (2025/05/14) Copy Chapter

Changes in Version 4.12.1 (2025/04/29) Copy Chapter

Changes in Version 4.12.0 (2025/04/08) Copy Chapter

Changes in Version 4.11.2 (2025/03/05) Copy Chapter

Changes in Version 4.11.1 (2025/02/10) Copy Chapter

Changes in Version 4.11.0 (2025/01/28) Copy Chapter

Changes in Version 4.10.1 (2024/10/01) Copy Chapter

Changes in Version 4.10.0 (2024/09/30) Copy Chapter

Changes in Version 4.9.2 (2024/10/02) Copy Chapter

Changes in Version 4.9.1 (2024/09/18) Copy Chapter

Changes in Version 4.9 (2024/09/18) Copy Chapter

Changes in Version 4.8.0 (2024/06/26) Copy Chapter

Changes in Version 4.7.3 (2024/06/04) Copy Chapter

Changes in Version 4.7.2 (2024/05/07) Copy Chapter

Changes in Version 4.7.1 (2024/04/30) Copy Chapter

Changes in Version 4.7.0 (2024/04/24) Copy Chapter

Before

After

To convert from dict to SON

This will only convert the first layer of the dictionary

To convert from dict to SON on a nested dictionary

Changes in Version 4.6.3 (2024/03/27) Copy Chapter

Changes in Version 4.6.2 (2024/02/21) Copy Chapter

Changes in Version 4.6.1 (2023/11/29) Copy Chapter

Changes in Version 4.6.0 (2023/11/01) Copy Chapter

Changes in Version 4.5.0 (2023/08/22) Copy Chapter

Changes in Version 4.4.1 (2023/07/13) Copy Chapter

Changes in Version 4.4.0 (2023/06/21) Copy Chapter

Changes in Version 4.3.3 (2022/11/17) Copy Chapter

Changes in Version 4.3.2 (2022/10/18) Copy Chapter

Changes in Version 4.2.0 (2022/07/20) Copy Chapter

Changes in Version 4.1.1 (2022/04/13) Copy Chapter

Changes in Version 4.1 (2021/12/07) Copy Chapter

Changes in Version 4.0.2 (2022/03/03) Copy Chapter

Changes in Version 4.0.1 (2021/12/07) Copy Chapter

Changes in Version 4.0 (2021/11/29) Copy Chapter

Changes in Version 3.13.0 (2022/11/01) Copy Chapter

Changes in Version 3.12.3 (2021/12/07) Copy Chapter

Changes in Version 3.12.2 (2021/11/29) Copy Chapter

Changes in Version 3.12.1 (2021/10/19) Copy Chapter

Changes in Version 3.12.0 (2021/07/13) Copy Chapter

Overview (`README.md`)

About

Documentation

Support / Feedback

Bugs / Feature Requests

How To Ask For Help

Security Vulnerabilities

Installation

Dependencies

Examples

Learning Resources

Testing

Overview (`integration_tests/README.md`)

Overview (`test/lambda/README.md`)

AWS Lambda Testing

Doc Changelog (`doc/changelog.rst`)

Changes in Version 4.20.0 (2026/XX/XX)

Changes in Version 4.19.0 (2026/10/14)

Changes in Version 4.18.2 (2026/09/24)

Changes in Version 4.18.1 (2026/09/10)

Changes in Version 4.18.0 (2026/09/03)

Changes in Version 4.17.0 (2026/04/20)

Changes in Version 4.16.0 (2026/01/07)

Changes in Version 4.15.5 (2025/12/02)

Changes in Version 4.15.4 (2025/10/21)

Changes in Version 4.15.3 (2025/10/07)

Changes in Version 4.15.2 (2025/10/01)

Changes in Version 4.15.1 (2025/09/16)

Changes in Version 4.15.0 (2025/09/10)

Changes in Version 4.14.1 (2025/08/19)

Changes in Version 4.14.0 (2025/08/06)

Changes in Version 4.13.2 (2025/06/17)

Changes in Version 4.13.1 (2025/06/10)

Changes in Version 4.13.0 (2025/05/14)

Changes in Version 4.12.1 (2025/04/29)

Changes in Version 4.12.0 (2025/04/08)

Changes in Version 4.11.2 (2025/03/05)

Changes in Version 4.11.1 (2025/02/10)

Changes in Version 4.11.0 (2025/01/28)

Changes in Version 4.10.1 (2024/10/01)

Changes in Version 4.10.0 (2024/09/30)

Changes in Version 4.9.2 (2024/10/02)

Changes in Version 4.9.1 (2024/09/18)

Changes in Version 4.9 (2024/09/18)

Changes in Version 4.8.0 (2024/06/26)

Changes in Version 4.7.3 (2024/06/04)

Changes in Version 4.7.2 (2024/05/07)

Changes in Version 4.7.1 (2024/04/30)

Changes in Version 4.7.0 (2024/04/24)

Changes in Version 4.6.3 (2024/03/27)

Changes in Version 4.6.2 (2024/02/21)

Changes in Version 4.6.1 (2023/11/29)

Changes in Version 4.6.0 (2023/11/01)

Changes in Version 4.5.0 (2023/08/22)

Changes in Version 4.4.1 (2023/07/13)

Changes in Version 4.4.0 (2023/06/21)

Changes in Version 4.3.3 (2022/11/17)

Changes in Version 4.3.2 (2022/10/18)

Changes in Version 4.2.0 (2022/07/20)

Changes in Version 4.1.1 (2022/04/13)

Changes in Version 4.1 (2021/12/07)

Changes in Version 4.0.2 (2022/03/03)

Changes in Version 4.0.1 (2021/12/07)

Changes in Version 4.0 (2021/11/29)

Changes in Version 3.13.0 (2022/11/01)

Changes in Version 3.12.3 (2021/12/07)

Changes in Version 3.12.2 (2021/11/29)

Changes in Version 3.12.1 (2021/10/19)

Changes in Version 3.12.0 (2021/07/13)

Changes in Version 3.11.3 (2021/02/02)

Changes in Version 3.11.2 (2020/12/02)

Changes in Version 3.11.1 (2020/11/17)

Changes in Version 3.11.0 (2020/07/30)

Changes in Version 3.10.1 (2020/01/07)

Changes in Version 3.10.0 (2019/12/10)

Changes in Version 3.9.0 (2019/08/13)

Changes in Version 3.8.0 (2019/04/22)

Changes in Version 3.7.2 (2018/10/10)

Changes in Version 3.7.1 (2018/07/16)

Changes in Version 3.7.0 (2018/06/26)