docs should mention that compression.zstd and other modules are optional

[ShaneHarvey]

Documentation

The compression.zstd docs page and 3.14 what's new changelog entry neglect to mention that compression.zstd is an optional build time dependency. The import will fail when cpython is built without libzstd:

    import compression.zstd  # noqa: I900
    ^^^^^^^^^^^^^^^^^^^^^^^
/opt/python/3.14/lib/python3.14/compression/zstd/__init__.py:29: in <module>
    import _zstd
E   ModuleNotFoundError: No module named '_zstd'

https://docs.python.org/3/library/compression.zstd.html#module-compression.zstd

Linked PRs

• gh-139707: Add docs for optional modules #140171
• gh-139707: Better ModuleNotFoundError message for missing stdlib modules #140219
• gh-139707: Add mechanism for distributors to supply error messages for missing stdlib modules #140783
• [3.14] gh-139707: Add docs for optional modules (GH-140171) #141204
• gh-139707: Specify winreg, msvcrt and winsound module availability in docs #140429
• [3.14] gh-139707: Specify winreg, msvcrt and winsound module availability in docs (GH-140429) #141351
• [3.13] gh-139707: Specify winreg, msvcrt and winsound module availability in docs (GH-140429) #141350
• gh-139707: Fix example for configure option #142153
• gh-139707: Copy-strip change to idle.rst into idlelib #143718
• [3.14] gh-139707: Copy-strip change to idle.rst into idlelib (GH-143718) #143744
• [3.13] gh-139707: Copy-strip change to idle.rst into idlelib #143767

[StanFromIreland]

The import will fail when cpython is built without libzstd

Note that this is the same for several other modules when built without their dependency, e.g. zlib and is not done there. This is a more general issue.
This could be a good thing to add to the agenda for today's docs community meeting.

cc @emmatyping

[ShaneHarvey]

Thanks. It would be great if the docs included this info from the PEP:

The libzstd library will become an optional dependency of CPython. If the library is not available, the compression.zstd module will be unavailable. This is handled automatically on Unix platforms as part of the normal build environment detection.

On Windows, libzstd will be added to the source dependencies used to build libraries CPython depends on for Windows.

https://peps.python.org/pep-0784/#libzstd-optional-dependency

[AA-Turner]

I agree with Stan, note that many extension modules are similarly optional, and CPython can be built without them. Worse, some Linux distributions (notably Debian/Ubuntu) intentionally split up 'python' into several OS level packages.

I don't think anything needs to change here, I'd suggest closing.

A

[ShaneHarvey]

Not mentioning that it's optional is intentionally misleading because library developers don't know they need to guard against the import error.

[AA-Turner]

In that vein, you should guard against importing eg threading as OS support might not exist.

We aren't generally in the business of documenting all the ways that different configuration options can change what exists at runtime, given if building Python from source we expect the user to manage their own environment etc, which includes ensuring all the required/desired system libraries are installed.

A

[ShaneHarvey]

I think the difference is that threading is a core component that doesn't really have a fallback option so libraries that depend on it can't do anything if it doesn't exist. Compression however is often an optional feature that can be ignored. aio-libs/aiohttp#11603 is a real example of a bug that likely could have been avoided if the docs were more clear.

That said I understand either outcome here and don't really have anything else to add. Thank you for the consideration.

[StanFromIreland]

Note that this has been discussed at today's docs community meeting.

[emmatyping]

@ShaneHarvey out of curiosity, did you build CPython yourself?