diff --git a/doc/changelog.rst b/doc/changelog.rst index b12382e3a8..38b3049c0e 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -30,6 +30,7 @@ PyMongo 4.6 brings a number of improvements including: "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 :ref:`network-compression-example` documentation page. Changes in Version 4.5 ---------------------- @@ -1278,8 +1279,8 @@ Version 3.7 adds support for MongoDB 4.0. Highlights include: - Support for single replica set multi-document ACID transactions. See :ref:`transactions-ref`. -- Support for wire protocol compression. See the - :meth:`~pymongo.mongo_client.MongoClient` documentation for details. +- Support for wire protocol compression via the new ``compressors`` URI and keyword argument to + :meth:`~pymongo.mongo_client.MongoClient`. See :ref:`network-compression-example` for details. - Support for Python 3.7. - New count methods, :meth:`~pymongo.collection.Collection.count_documents` and :meth:`~pymongo.collection.Collection.estimated_document_count`. diff --git a/doc/examples/index.rst b/doc/examples/index.rst index ee4aa27284..23f7a6f181 100644 --- a/doc/examples/index.rst +++ b/doc/examples/index.rst @@ -28,6 +28,7 @@ MongoDB, you can start it like so: gridfs high_availability mod_wsgi + network_compression server_selection tailable timeouts diff --git a/doc/examples/network_compression.rst b/doc/examples/network_compression.rst new file mode 100644 index 0000000000..c270dff4b3 --- /dev/null +++ b/doc/examples/network_compression.rst @@ -0,0 +1,39 @@ + +.. _network-compression-example: + +Network Compression +=================== + +PyMongo supports network compression where network traffic between the client +and MongoDB server are compressed which reduces the amount of data passed +over the network. By default no compression is used. + +The driver supports the following algorithms: + +- `snappy `_ available in MongoDB 3.4 and later. +- :mod:`zlib` available in MongoDB 3.6 and later. +- `zstandard `_ available in MongoDB 4.2 and later. + +.. note:: snappy and zstandard compression require additional dependencies. See :ref:`optional-deps`. + +Applications can enable wire protocol compression via the ``compressors`` URI and +keyword argument to :meth:`~pymongo.mongo_client.MongoClient`. For example:: + + >>> client = MongoClient(compressors='zlib') + +When multiple compression algorithms are given, the driver selects the first one in the +list supported by the MongoDB instance to which it is connected. For example:: + + >>> client = MongoClient(compressors='snappy,zstandard,zlib') + +The ``compressors`` option can also be set via the URI:: + + >>> client = MongoClient('mongodb://example.com/?compressors=snappy,zstandard,zlib') + +Additionally, zlib compression allows specifying a compression level with supported values from -1 to 9:: + + >>> client = MongoClient(compressors='zlib', zlibCompressionLevel=-1) + +The ``zlibCompressionLevel`` is passed as the ``level`` argument to :func:`zlib.compress`. + +.. seealso:: The MongoDB documentation on `network compression URI options `_. diff --git a/doc/installation.rst b/doc/installation.rst index fc9b6ad3de..edbdc0ac63 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -30,13 +30,16 @@ Dependencies PyMongo supports CPython 3.7+ and PyPy3.7+. -Required dependencies: +Required dependencies +..................... Support for mongodb+srv:// URIs requires `dnspython `_ +.. _optional-deps: -Optional dependencies: +Optional dependencies +..................... GSSAPI authentication requires `pykerberos `_ on Unix or `WinKerberos diff --git a/pymongo/mongo_client.py b/pymongo/mongo_client.py index 422f8924f0..5d3cfcd832 100644 --- a/pymongo/mongo_client.py +++ b/pymongo/mongo_client.py @@ -402,6 +402,7 @@ def __init__( package. By default no compression is used. Compression support must also be enabled on the server. MongoDB 3.6+ supports snappy and zlib compression. MongoDB 4.2+ adds support for zstd. + See :ref:`network-compression-example` for details. - `zlibCompressionLevel`: (int) The zlib compression level to use when zlib is used as the wire protocol compressor. Supported values are -1 through 9. -1 tells the zlib library to use its default