PYTHON-3930 Add docs page for network compression (#1415)

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`.

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

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 <https://pypi.org/project/python-snappy>`_ available in MongoDB 3.4 and later.
+- :mod:`zlib` available in MongoDB 3.6 and later.
+- `zstandard <https://pypi.org/project/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 <https://dochub.mongodb.org/core/compression-options>`_.

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
 <https://pypi.python.org/pypi/dnspython>`_
 
+.. _optional-deps:
 
-Optional dependencies:
+Optional dependencies
+.....................
 
 GSSAPI authentication requires `pykerberos
 <https://pypi.python.org/pypi/pykerberos>`_ on Unix or `WinKerberos

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