support for python 3.14 compression.zstd instead of zstandard

[trim21]

the python 3.14 has add compression.zstd to stdlib, which can decompress zstd data without need of installing another third party library.

We should consider add zstd support when python 3.14 is used and no zstandard installed

[amasen02]

This is a great proposal for Python 3.14+. Relying on standard library decompression eliminates the need to compile or distribute the zstandard C-extension wheel on platforms where wheels may not be pre-built.

Here is an analysis of how this can be cleanly integrated into httpx's decoder architecture and dependency configuration:

---

1. Decoder Architecture in httpx/_decoders.py

Currently, httpx handles Content-Encoding: zstd via:

try:
    import zstandard
except ImportError:
    zstandard = None  # type: ignore

In Python 3.14, the standard library introduces compression.zstd. To maintain backward compatibility with Python 3.8–3.13 while providing zero-dependency support on 3.14+, httpx can prioritize the third-party zstandard (which often includes highly tuned native bindings) and fall back to the standard library module:

try:
    import zstandard
except ImportError:
    try:
        import compression.zstd as zstandard
    except ImportError:
        zstandard = None  # type: ignore

Handling Decompression Stream APIs

httpx.decoders.ZStandardDecoder consumes bytes incrementally via a streaming decompressor object:

class ZStandardDecoder(ContentDecoder):
    def __init__(self) -> None:
        if zstandard is None:
            raise ImportError(
                "Using 'zstd' Content-Encoding requires either Python 3.14+ (stdlib compression.zstd) "
                "or the 'zstandard' library. Use 'pip install httpx[zstd]'."
            )
        # Adapt to both stdlib and third-party interfaces
        if hasattr(zstandard, "ZstdDecompressor"):
            self.decompressor = zstandard.ZstdDecompressor().decompressobj()
        else:
            self.decompressor = zstandard.decompressobj()

    def decode(self, data: bytes) -> bytes:
        return self.decompressor.decompress(data)

    def flush(self) -> bytes:
        if hasattr(self.decompressor, "flush"):
            return self.decompressor.flush()
        return b""

---

2. Packaging & Extra Dependencies (pyproject.toml)

In pyproject.toml, the optional dependency marker can be scoped so that installations on Python 3.14+ do not strictly require external wheels:

[project.optional-dependencies]
zstd = [
    "zstandard>=0.18.0; python_version < '3.14'",
]

This guarantees:

1. Python 3.8–3.13 environments continue getting the robust third-party zstandard package when requested.
2. Python 3.14+ environments can handle Content-Encoding: zstd out of the box without requiring compiler toolchains or pre-built wheels.
3. Users who explicitly install zstandard on 3.14 can still use it for maximum throughput.

[trim21]

use httpx2