From 4ebbc3dac79395499782d8ef8454f1e7398d38e4 Mon Sep 17 00:00:00 2001 From: Shane Harvey Date: Tue, 31 Oct 2023 14:27:10 -0700 Subject: [PATCH 1/5] PYTHON-3930 Add docs page for network compression --- doc/changelog.rst | 5 +++-- doc/examples/index.rst | 1 + doc/examples/network_compression.rst | 33 ++++++++++++++++++++++++++++ doc/installation.rst | 7 ++++-- pymongo/mongo_client.py | 1 + 5 files changed, 43 insertions(+), 4 deletions(-) create mode 100644 doc/examples/network_compression.rst 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..e2122448f1 --- /dev/null +++ b/doc/examples/network_compression.rst @@ -0,0 +1,33 @@ + +.. _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') + >>> client.test.test.insert_one({'data': 's'*1*1024*1024}) # Will be compressed with 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,zlib') + >>> client.test.test.insert_one({'data': 's'*1*1024*1024}) # Will be compressed with snappy. + +The ``compressors`` option can also be set via the URI:: + + >>> client = MongoClient('mongodb://example.com/?compressors=zstandard,snappy,zlib') 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 From f350ed8180080e8f2acecb22c47a99a1e3dbd126 Mon Sep 17 00:00:00 2001 From: Shane Harvey Date: Tue, 31 Oct 2023 14:36:13 -0700 Subject: [PATCH 2/5] PYTHON-3930 Simplify examples --- doc/examples/network_compression.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/examples/network_compression.rst b/doc/examples/network_compression.rst index e2122448f1..772ec3328b 100644 --- a/doc/examples/network_compression.rst +++ b/doc/examples/network_compression.rst @@ -20,14 +20,12 @@ Applications can enable wire protocol compression via the ``compressors`` URI an keyword argument to :meth:`~pymongo.mongo_client.MongoClient`. For example:: >>> client = MongoClient(compressors='zlib') - >>> client.test.test.insert_one({'data': 's'*1*1024*1024}) # Will be compressed with 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,zlib') - >>> client.test.test.insert_one({'data': 's'*1*1024*1024}) # Will be compressed with snappy. + >>> client = MongoClient(compressors='snappy,zstandard,zlib') The ``compressors`` option can also be set via the URI:: - >>> client = MongoClient('mongodb://example.com/?compressors=zstandard,snappy,zlib') + >>> client = MongoClient('mongodb://example.com/?compressors=snappy,zstandard,zlib') From 1efbefe399c9ea796ef8bfa206b2645416dfe681 Mon Sep 17 00:00:00 2001 From: Shane Harvey Date: Tue, 31 Oct 2023 16:35:56 -0700 Subject: [PATCH 3/5] PYTHON-3930 Add zlibCompressionLevel --- doc/examples/network_compression.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/examples/network_compression.rst b/doc/examples/network_compression.rst index 772ec3328b..d15b1dc641 100644 --- a/doc/examples/network_compression.rst +++ b/doc/examples/network_compression.rst @@ -29,3 +29,9 @@ list supported by the MongoDB instance to which it is connected. For example:: 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`. From 787c9dea5599a76358c9bcf8f7b80deba144e6ac Mon Sep 17 00:00:00 2001 From: Shane Harvey Date: Wed, 1 Nov 2023 11:25:25 -0700 Subject: [PATCH 4/5] PYTHON-3930 Add link to mongodb docs --- doc/examples/network_compression.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/examples/network_compression.rst b/doc/examples/network_compression.rst index d15b1dc641..c2fe354ad7 100644 --- a/doc/examples/network_compression.rst +++ b/doc/examples/network_compression.rst @@ -35,3 +35,5 @@ Additionally, zlib compression allows specifying a compression level with suppor >>> 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 `_. From 2b576a708dc4807f5c76b848e053d92437f600fe Mon Sep 17 00:00:00 2001 From: Shane Harvey Date: Wed, 1 Nov 2023 11:32:18 -0700 Subject: [PATCH 5/5] PYTHON-3930 Use dochub link --- doc/examples/network_compression.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/examples/network_compression.rst b/doc/examples/network_compression.rst index c2fe354ad7..c270dff4b3 100644 --- a/doc/examples/network_compression.rst +++ b/doc/examples/network_compression.rst @@ -36,4 +36,4 @@ Additionally, zlib compression allows specifying a compression level with suppor The ``zlibCompressionLevel`` is passed as the ``level`` argument to :func:`zlib.compress`. -.. seealso:: The MongoDB documentation on `network compression URI options `_. +.. seealso:: The MongoDB documentation on `network compression URI options `_.