[3.14] pythongh-139707: Add docs for optional modules (pythonGH-140171)

encukou · StanFromIreland · hugovk · StanFromIreland · commit b73cb36b3a03 · 2025-11-07T16:19:55.000Z
(cherry picked from commit d2ce6d7) Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Emma Smith <emma@emmatyping.dev> Co-authored-by: Author: Terry Jan Reedy <tjreedy@udel.edu> Co-authored-by: Victor Stinner <vstinner@python.org>
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
@@ -1025,6 +1025,15 @@ Glossary
       applied to all scopes, only those relying on a known set of local
       and nonlocal variable names are restricted to optimized scopes.
 
+   optional module
+      An :term:`extension module` that is part of the :term:`standard library`,
+      but may be absent in some builds of :term:`CPython`,
+      usually due to missing third-party libraries or because the module
+      is not available for a given platform.
+
+      See :ref:`optional-module-requirements` for a list of optional modules
+      that require third-party libraries.
+
    package
       A Python :term:`module` which can contain submodules or recursively,
       subpackages.  Technically, a package is a Python module with a
diff --git a/Doc/includes/optional-module.rst b/Doc/includes/optional-module.rst
@@ -0,0 +1,9 @@
+This is an :term:`optional module`.
+If it is missing from your copy of CPython,
+look for documentation from your distributor (that is,
+whoever provided Python to you).
+If you are the distributor, see :ref:`optional-module-requirements`.
+
+.. Similar notes appear in the docs of the modules:
+   - zipfile
+   - tarfile
diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
@@ -25,6 +25,8 @@ The :mod:`bz2` module contains:
 * The :func:`compress` and :func:`decompress` functions for one-shot
   (de)compression.
 
+.. include:: ../includes/optional-module.rst
+
 
 (De)compression of files
 ------------------------
diff --git a/Doc/library/compression.zstd.rst b/Doc/library/compression.zstd.rst
@@ -33,6 +33,8 @@ The :mod:`!compression.zstd` module contains:
 * The :class:`CompressionParameter`, :class:`DecompressionParameter`, and
   :class:`Strategy` classes for setting advanced (de)compression parameters.
 
+.. include:: ../includes/optional-module.rst
+
 
 Exceptions
 ----------
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
@@ -14,6 +14,8 @@
 data types, and allows calling functions in DLLs or shared libraries.  It can be
 used to wrap these libraries in pure Python.
 
+.. include:: ../includes/optional-module.rst
+
 
 .. _ctypes-ctypes-tutorial:
 
diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
@@ -23,6 +23,8 @@ Linux and the BSD variants of Unix.
 
 .. include:: ../includes/wasm-mobile-notavail.rst
 
+.. include:: ../includes/optional-module.rst
+
 .. note::
 
    Whenever the documentation mentions a *character* it can be specified
diff --git a/Doc/library/ensurepip.rst b/Doc/library/ensurepip.rst
@@ -30,6 +30,8 @@ when creating a virtual environment) or after explicitly uninstalling
    needed to bootstrap ``pip`` are included as internal parts of the
    package.
 
+.. include:: ../includes/optional-module.rst
+
 .. seealso::
 
    :ref:`installing-index`
diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst
@@ -11,6 +11,8 @@
 This module provides a simple interface to compress and decompress files just
 like the GNU programs :program:`gzip` and :program:`gunzip` would.
 
+.. include:: ../includes/optional-module.rst
+
 The data compression is provided by the :mod:`zlib` module.
 
 The :mod:`gzip` module provides the :class:`GzipFile` class, as well as the
diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst
@@ -37,6 +37,10 @@ IDLE has the following features:
 
 * configuration, browsers, and other dialogs
 
+The IDLE application is implemented in the :mod:`idlelib` package.
+
+.. include:: ../includes/optional-module.rst
+
 Menus
 -----
 
diff --git a/Doc/library/lzma.rst b/Doc/library/lzma.rst
@@ -23,6 +23,8 @@ module. Note that :class:`LZMAFile` and :class:`bz2.BZ2File` are *not*
 thread-safe, so if you need to use a single :class:`LZMAFile` instance
 from multiple threads, it is necessary to protect it with a lock.
 
+.. include:: ../includes/optional-module.rst
+
 
 .. exception:: LZMAError
 
diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst
@@ -26,6 +26,8 @@ Readline library in general.
 
 .. include:: ../includes/wasm-mobile-notavail.rst
 
+.. include:: ../includes/optional-module.rst
+
 .. note::
 
   The underlying Readline library API may be implemented by
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
@@ -31,7 +31,9 @@ PostgreSQL or Oracle.
 
 The :mod:`!sqlite3` module was written by Gerhard Häring.  It provides an SQL interface
 compliant with the DB-API 2.0 specification described by :pep:`249`, and
-requires SQLite 3.15.2 or newer.
+requires the third-party `SQLite <https://sqlite.org/>`_ library.
+
+.. include:: ../includes/optional-module.rst
 
 This document includes four main sections:
 
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
@@ -18,8 +18,9 @@
 This module provides access to Transport Layer Security (often known as "Secure
 Sockets Layer") encryption and peer authentication facilities for network
 sockets, both client-side and server-side.  This module uses the OpenSSL
-library. It is available on all modern Unix systems, Windows, macOS, and
-probably additional platforms, as long as OpenSSL is installed on that platform.
+library.
+
+.. include:: ../includes/optional-module.rst
 
 .. note::
 
diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst
@@ -21,6 +21,14 @@ Some facts and figures:
 * reads and writes :mod:`gzip`, :mod:`bz2`, :mod:`compression.zstd`, and
   :mod:`lzma` compressed archives if the respective modules are available.
 
+  ..
+     The following paragraph should be similar to ../includes/optional-module.rst
+
+  If any of these :term:`optional modules <optional module>` are missing from
+  your copy of CPython, look for documentation from your distributor (that is,
+  whoever provided Python to you).
+  If you are the distributor, see :ref:`optional-module-requirements`.
+
 * read/write support for the POSIX.1-1988 (ustar) format.
 
 * read/write support for the GNU tar format including *longname* and *longlink*
diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst
@@ -36,6 +36,8 @@ details that are unchanged.
    Most documentation you will find online still uses the old API and
    can be woefully outdated.
 
+.. include:: ../includes/optional-module.rst
+
 .. seealso::
 
    * `TkDocs <https://tkdocs.com/>`_
diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst
@@ -29,6 +29,8 @@ introduced in Logo <https://en.wikipedia.org/wiki/Turtle_
 (robot)>`_, developed by Wally Feurzeig, Seymour Papert and Cynthia Solomon
 in 1967.
 
+.. include:: ../includes/optional-module.rst
+
 
 Get started
 ===========
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
@@ -23,6 +23,16 @@ decryption of encrypted files in ZIP archives, but it currently cannot
 create an encrypted file.  Decryption is extremely slow as it is
 implemented in native Python rather than C.
 
+..
+   The following paragraph should be similar to ../includes/optional-module.rst
+
+Handling compressed archives requires :term:`optional modules <optional module>`
+such as :mod:`zlib`, :mod:`bz2`, :mod:`lzma`, and :mod:`compression.zstd`.
+If any of them are missing from your copy of CPython,
+look for documentation from your distributor (that is,
+whoever provided Python to you).
+If you are the distributor, see :ref:`optional-module-requirements`.
+
 The module defines the following items:
 
 .. exception:: BadZipFile
diff --git a/Doc/library/zlib.rst b/Doc/library/zlib.rst
@@ -8,11 +8,9 @@
 --------------
 
 For applications that require data compression, the functions in this module
-allow compression and decompression, using the zlib library. The zlib library
-has its own home page at https://www.zlib.net.   There are known
-incompatibilities between the Python module and versions of the zlib library
-earlier than 1.1.3; 1.1.3 has a `security vulnerability <https://zlib.net/zlib_faq.html#faq33>`_, so we recommend using
-1.1.4 or later.
+allow compression and decompression, using the `zlib library <https://www.zlib.net>`_.
+
+.. include:: ../includes/optional-module.rst
 
 zlib's functions have many options and often need to be used in a particular
 order.  This documentation doesn't attempt to cover all of the permutations;
diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
diff --git a/Doc/using/unix.rst b/Doc/using/unix.rst
