PYTHON-5522: Support std lib zstandard in 3.14 (#2592)

Author: Rogdham

.evergreen/generated_configs/variants.yml

@@ -133,6 +133,15 @@ buildvariants:
       - rhel87-small
     expansions:
       COMPRESSOR: zstd
+  - name: compression-zstd-ubuntu-22
+    tasks:
+      - name: .test-standard !.server-4.2 !.server-4.4 !.server-5.0 .python-3.14
+      - name: .test-standard !.server-4.2 !.server-4.4 !.server-5.0 .python-3.14t
+    display_name: Compression zstd Ubuntu-22
+    run_on:
+      - ubuntu2204-small
+    expansions:
+      COMPRESSOR: ztsd
 
   # Coverage report tests
   - name: coverage-report

.evergreen/scripts/generate_config.py

@@ -194,6 +194,22 @@ def create_compression_variants():
                 expansions=expansions,
             )
         )
+    # Add explicit tests with compression.zstd support on linux.
+    host = HOSTS["ubuntu22"]
+    expansions = dict(COMPRESSOR="ztsd")
+    tasks = [
+        ".test-standard !.server-4.2 !.server-4.4 !.server-5.0 .python-3.14",
+        ".test-standard !.server-4.2 !.server-4.4 !.server-5.0 .python-3.14t",
+    ]
+    display_name = get_variant_name(f"Compression {compressor}", host)
+    variants.append(
+        create_variant(
+            tasks,
+            display_name,
+            host=host,
+            expansions=expansions,
+        )
+    )
     return variants
 
 

README.md

@@ -139,7 +139,8 @@ python -m pip install "pymongo[snappy]"
 ```
 
 Wire protocol compression with zstandard requires
-[zstandard](https://pypi.org/project/zstandard):
+[backports.zstd](https://pypi.org/project/backports.zstd)
+when used with Python versions before 3.14:
 
 ```bash
 python -m pip install "pymongo[zstd]"

doc/changelog.rst

@@ -16,6 +16,7 @@ PyMongo 4.16 brings a number of changes including:
   Python 3.10+.  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.
 
 Changes in Version 4.15.4 (2025/10/21)
 --------------------------------------

pymongo/asynchronous/mongo_client.py

@@ -422,8 +422,8 @@ def __init__(
             with the server. Currently supported options are "snappy", "zlib"
             and "zstd". Support for snappy requires the
             `python-snappy <https://pypi.org/project/python-snappy/>`_ package.
-            zlib support requires the Python standard library zlib module. zstd
-            requires the `zstandard <https://pypi.org/project/zstandard/>`_
+            zlib support requires the Python standard library zlib module. For
+            Python before 3.14 zstd requires the `backports.zstd <https://pypi.org/project/backports.zstd/>`_
             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.

pymongo/compression_support.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 from __future__ import annotations
 
+import sys
 import warnings
 from typing import Any, Iterable, Optional, Union
 
@@ -44,7 +45,10 @@ def _have_zlib() -> bool:
 
 def _have_zstd() -> bool:
     try:
-        import zstandard  # noqa: F401
+        if sys.version_info >= (3, 14):
+            from compression import zstd
+        else:
+            from backports import zstd  # noqa: F401
 
         return True
     except ImportError:
@@ -79,11 +83,18 @@ def validate_compressors(dummy: Any, value: Union[str, Iterable[str]]) -> list[s
             )
         elif compressor == "zstd" and not _have_zstd():
             compressors.remove(compressor)
-            warnings.warn(
-                "Wire protocol compression with zstandard is not available. "
-                "You must install the zstandard module for zstandard support.",
-                stacklevel=2,
-            )
+            if sys.version_info >= (3, 14):
+                warnings.warn(
+                    "Wire protocol compression with zstandard is not available. "
+                    "The compression.zstd module is not available.",
+                    stacklevel=2,
+                )
+            else:
+                warnings.warn(
+                    "Wire protocol compression with zstandard is not available. "
+                    "You must install the backports.zstd module for zstandard support.",
+                    stacklevel=2,
+                )
     return compressors
 
 
@@ -144,12 +155,12 @@ class ZstdContext:
 
     @staticmethod
     def compress(data: bytes) -> bytes:
-        # ZstdCompressor is not thread safe.
-        # TODO: Use a pool?
-
-        import zstandard
+        if sys.version_info >= (3, 14):
+            from compression import zstd
+        else:
+            from backports import zstd
 
-        return zstandard.ZstdCompressor().compress(data)
+        return zstd.compress(data)
 
 
 def decompress(data: bytes | memoryview, compressor_id: int) -> bytes:
@@ -166,10 +177,11 @@ def decompress(data: bytes | memoryview, compressor_id: int) -> bytes:
 
         return zlib.decompress(data)
     elif compressor_id == ZstdContext.compressor_id:
-        # ZstdDecompressor is not thread safe.
-        # TODO: Use a pool?
-        import zstandard
+        if sys.version_info >= (3, 14):
+            from compression import zstd
+        else:
+            from backports import zstd
 
-        return zstandard.ZstdDecompressor().decompress(data)
+        return zstd.decompress(data)
     else:
         raise ValueError("Unknown compressorId %d" % (compressor_id,))

pymongo/synchronous/mongo_client.py

@@ -422,8 +422,8 @@ def __init__(
             with the server. Currently supported options are "snappy", "zlib"
             and "zstd". Support for snappy requires the
             `python-snappy <https://pypi.org/project/python-snappy/>`_ package.
-            zlib support requires the Python standard library zlib module. zstd
-            requires the `zstandard <https://pypi.org/project/zstandard/>`_
+            zlib support requires the Python standard library zlib module. For
+            Python before 3.14 zstd requires the `backports.zstd <https://pypi.org/project/backports.zstd/>`_
             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.

requirements/zstd.txt

@@ -1 +1 @@
-zstandard
+backports.zstd>=1.0.0;python_version<'3.14'