GeezerVison is showing github.com — docs should mention that compression.zstd and other modules are optional · Issue #139707 · python/cpython
docs should mention that compression.zstd and other modules are optional #139707DescriptionDocumentation
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
Reacted by Jacob Henner, Johannes (Joey) Nicholas and Oleg Korsak ActivityStanFromIreland commented on Oct 7, 2025
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 commented on Oct 7, 2025 ContributorAuthor More actions 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 commented on Oct 7, 2025 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 commented on Oct 7, 2025 ContributorAuthor More actions Not mentioning that it's optional is intentionally misleading because library developers don't know they need to guard against the import error. Reacted by Jan Dolecek, Peter Schneider and dolfies AA-Turner commented on Oct 7, 2025 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 commented on Oct 7, 2025 ContributorAuthor More actions 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 commented on Oct 7, 2025 Note that this has been discussed at today's docs community meeting. emmatyping commented on Oct 8, 2025 @ShaneHarvey out of curiosity, did you build CPython yourself? GalaxySnail commented on Oct 8, 2025
In that vein, you should guard against importing eg threading as OS support might not exist.
According to the documentation and PEP 11, threading is no longer optional as of python 3.7. emmatyping commented on Oct 8, 2025 Another example is that the ecosystem depends on the zlib module to install wheel packages and many other uses, but even that is optional and may be missing in some environments.
Pretty much no code that I know of guards against zlib missing but it is optional.
I will also mention that you could always build zstandard yourself and pass the right configure arguments to build with zstandard support (c.f.
|
LIBZSTD_CFLAGS=${LIBZSTD_CFLAGS-""} |
). Specifically LIBZSTD_CFLAGS and LIBZSTD_LIBS. Reacted by Gregory P. Smith terryjreedy commented on Jan 12, 2026 When I reviewed the first PR (#140171), I forgot to mention that changes to idle.rst and hence idle.html need to be copied in idlelib. The command to do so is in the commit message of my new PR, which fixes this oversight. (Stan and I are working to add an auto reminder.) This PR will be auto backported to 3.14 but not 3.13, even though relevant, as the include file did not get backported to 3.13.
I may manually backport the net text addition to 3.13. The diff includes a separate change that I believe is entirely due to a Sphinx change. I expect it would appear in a 3.13 PR. EDIT: I did the backport, which had the extraneous html change before editing.
I checked that the addition looks fine in the IDLE doc display for both main and 3.13.
MetadataMetadataStatusShow more project fields
DevelopmentNo branches or pull requestsIssue actions
|