Use backports.zstd on Python 3.13 and earlier (#1146)

Author: Kludex

README.md

@@ -149,7 +149,7 @@ As well as these optional installs:
 * `rich` - Rich terminal support. *(Optional, with `httpx2[cli]`)*
 * `click` - Command line client support. *(Optional, with `httpx2[cli]`)*
 * `brotli` or `brotlicffi` - Decoding for "brotli" compressed responses. *(Optional, with `httpx2[brotli]`)*
-* `zstandard` - Decoding for "zstd" compressed responses on Python 3.13 and below. *(Optional, with `httpx2[zstd]`. On Python 3.14+, `zstd` is supported via the stdlib [`compression.zstd`](https://docs.python.org/3/library/compression.zstd.html) module when it is available; the `httpx2[zstd]` extra installs nothing there, so decoding falls back to `zstandard` only on 3.13 and below.)*
+* `backports.zstd` - Decoding for "zstd" compressed responses on Python 3.13 and below. *(Optional, with `httpx2[zstd]`. On Python 3.14+, `zstd` is supported via the stdlib [`compression.zstd`](https://docs.python.org/3/library/compression.zstd.html) module when it is available, and the `httpx2[zstd]` extra installs nothing.)*
 
 A huge amount of credit is due to `requests` for the API layout that
 much of this work follows, as well as to `urllib3` for plenty of design

docs/index.md

@@ -119,7 +119,7 @@ As well as these optional installs:
 * `rich` - Rich terminal support. *(Optional, with `httpx2[cli]`)*
 * `click` - Command line client support. *(Optional, with `httpx2[cli]`)*
 * `brotli` or `brotlicffi` - Decoding for "brotli" compressed responses. *(Optional, with `httpx2[brotli]`)*
-* `zstandard` - Decoding for "zstd" compressed responses on Python 3.13 and below. *(Optional, with `httpx2[zstd]`. On Python 3.14+, `zstd` is supported via the stdlib [`compression.zstd`][] module when it is available; the `httpx2[zstd]` extra installs nothing there, so decoding falls back to `zstandard` only on 3.13 and below.)*
+* `backports.zstd` - Decoding for "zstd" compressed responses on Python 3.13 and below. *(Optional, with `httpx2[zstd]`. On Python 3.14+, `zstd` is supported via the stdlib [`compression.zstd`][] module when it is available, and the `httpx2[zstd]` extra installs nothing.)*
 
 A huge amount of credit is due to `requests` for the API layout that
 much of this work follows, as well as to `urllib3` for plenty of design

docs/quickstart.md

@@ -102,7 +102,7 @@ Any `gzip` and `deflate` HTTP response encodings will automatically
 be decoded for you. If `brotlipy` is installed, then the `brotli` response
 encoding will be supported. The `zstd` response encoding is supported
 on Python 3.14+ via the stdlib [`compression.zstd`][] module when it is
-available; on Python 3.13 and below it requires the `zstandard` package.
+available; on Python 3.13 and below it requires the `backports.zstd` package.
 
 For example, to create an image from binary data returned by a request, you can use the following code:
 

src/httpx2/httpx2/_decoders.py

@@ -7,7 +7,6 @@
 from __future__ import annotations
 
 import codecs
-import functools
 import io
 import sys
 import typing
@@ -31,30 +30,22 @@
 # Zstandard support is optional on Python <= 3.13.
 # On Python 3.14+, the stdlib includes an optional built-in zstd implementation.
 if typing.TYPE_CHECKING:
-    # We keep checking Python version in the type checker path because try..except doesn't help type checkers.
     if sys.version_info >= (3, 14):
         from compression.zstd import ZstdDecompressor, ZstdError
     else:
-        from zstandard import ZstdDecompressor as _ZstdDecompressor, ZstdError
+        from backports.zstd import ZstdDecompressor, ZstdError
 
-        ZstdDecompressor = functools.partial(_ZstdDecompressor().decompressobj)
-
-    _zstandard_installed: bool = False
+    _zstandard_installed: bool
 else:  # pragma: no cover
-    _zstandard_installed = False
     try:
-        from compression.zstd import ZstdDecompressor, ZstdError
+        if sys.version_info >= (3, 14):
+            from compression.zstd import ZstdDecompressor, ZstdError
+        else:
+            from backports.zstd import ZstdDecompressor, ZstdError
 
         _zstandard_installed = True
-    # Either Python <3.14 or the distro doesn't have `compression.zstd`.
     except ImportError:
-        try:
-            from zstandard import ZstdDecompressor as _ZstdDecompressor, ZstdError
-
-            ZstdDecompressor = functools.partial(_ZstdDecompressor().decompressobj)
-            _zstandard_installed = True
-        except ImportError:
-            pass
+        _zstandard_installed = False
 
 
 class ContentDecoder:
@@ -185,8 +176,7 @@ def flush(self) -> bytes:
 class ZStandardDecoder(ContentDecoder):
     """Handle 'zstd' RFC 8878 decoding.
 
-    If running on Python 3.14+ or a distro that doesn't have the `compression.zstd` stdlib module, requires either:
-    `pip install zstandard` or `pip install httpx2[zstd]`.
+    On Python 3.13 and below, this requires `pip install httpx2[zstd]`.
     """
 
     # inspired by the ZstdDecoder implementation in urllib3

src/httpx2/pyproject.toml

@@ -74,7 +74,7 @@ ws = [
 ]
 # TODO(Marcelo): Remove when Python 3.13 reaches EOL.
 zstd = [
-  "zstandard>=0.18.0; python_version <= '3.13'",
+    "backports.zstd>=1.0.0; python_version <= '3.13'",
 ]
 
 [project.scripts]

tests/httpx2/test_decoders.py

@@ -13,7 +13,7 @@
 if sys.version_info >= (3, 14):  # pragma: no cover
     from compression import zstd
 else:  # pragma: no cover
-    import zstandard as zstd
+    from backports import zstd
 
 
 def test_deflate() -> None: