gh-139707: Add docs for optional modules

Doc/glossary.rst

@@ -1025,6 +1025,13 @@ 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 extension module that is part of the :term:`standard library`, but
+      may be missing in some builds of CPython, usually due to missing
+      third-party libraries.
+      See :ref:`optional-module-requirements` for a list of optional modules
+      and the required libraries.
+
    package
       A Python :term:`module` which can contain submodules or recursively,
       subpackages.  Technically, a package is a Python module with a

Doc/includes/optional-module.rst

@@ -0,0 +1,5 @@
+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`.

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
 ------------------------

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
 ----------

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:
 

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

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`

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

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
 

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

Doc/library/sqlite3.rst

@@ -33,6 +33,8 @@ The :mod:`!sqlite3` module was written by Gerhard Häring.  It provides an SQL i
 compliant with the DB-API 2.0 specification described by :pep:`249`, and
 requires SQLite 3.15.2 or newer.
 
+.. include:: ../includes/optional-module.rst
+
 This document includes four main sections:
 
 * :ref:`sqlite3-tutorial` teaches how to use the :mod:`!sqlite3` module.

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::
 

Doc/library/zlib.rst

@@ -8,9 +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.  zlib 1.2.2.1 is the minium
-supported version.
+allow compression and decompression, using the zlib library.
+
+.. 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;

Doc/using/configure.rst

@@ -4,10 +4,13 @@ Configure Python
 
 .. highlight:: sh
 
+
+.. _build-requirements:
+
 Build Requirements
 ==================
 
-Features and minimum versions required to build CPython:
+To build CPython, you will need:
 
 * A `C11 <https://en.cppreference.com/w/c/11>`_ compiler. `Optional C11
   features
@@ -22,83 +25,135 @@ Features and minimum versions required to build CPython:
 
 * Support for threads.
 
-To build optional modules:
-
-* `libbz2 <https://sourceware.org/bzip2/>`_ for the :mod:`bz2` module.
-
-* `libb2 <https://github.com/BLAKE2/libb2>`_ (:ref:`BLAKE2 <hashlib-blake2>`)
-  for the :mod:`hashlib` module.
-
-* `libffi <https://sourceware.org/libffi/>`_ 3.3.0 is the recommended
-  minimum version for the :mod:`ctypes` module.
-
-* ``liblzma`` for the :mod:`lzma` module.
-
-* `libmpdec <https://www.bytereef.org/mpdecimal/doc/libmpdec/>`_ 2.5.0
-  for the :mod:`decimal` module.
-
-* ``libncurses`` or ``libncursesw`` for the :mod:`curses` module.
-
-* ``libpanel`` or ``libpanelw`` for the :mod:`curses.panel` module.
-
-* `libreadline <https://tiswww.case.edu/php/chet/readline/rltop.html>`_ or
-  `libedit <https://www.thrysoee.dk/editline/>`_
-  for the :mod:`readline` module.
-
-* `libuuid <https://linux.die.net/man/3/libuuid>`_ for the :mod:`uuid` module.
-
-* `OpenSSL <https://www.openssl.org/>`_ 1.1.1 is the minimum version and
-  OpenSSL 3.0.18 is the recommended minimum version for the
-  :mod:`ssl` and :mod:`hashlib` extension modules.
+.. versionchanged:: 3.5
+   On Windows, Visual Studio 2015 or later is now required.
 
-* `SQLite <https://sqlite.org/>`_ 3.15.2 for the :mod:`sqlite3` extension module.
+.. versionchanged:: 3.6
+   Selected C99 features, like ``<stdint.h>`` and ``static inline`` functions,
+   are now required.
 
-* `Tcl/Tk <https://www.tcl-lang.org/>`_ 8.5.12 for the :mod:`tkinter` module.
+.. versionchanged:: 3.7
+   Thread support is now required.
 
-* `zlib <https://www.zlib.net>`_ 1.2.2.1 is the minimum version for the
-  :mod:`zlib` module.
+.. versionchanged:: 3.11
+   C11 compiler, IEEE 754 and NaN support are now required.
+   On Windows, Visual Studio 2017 or later is required.
 
-* `zstd <https://facebook.github.io/zstd/>`_ 1.4.5 is the minimum version for
-  the :mod:`compression.zstd` module.
+See also :pep:`7` "Style Guide for C Code" and :pep:`11` "CPython platform
+support".
 
-For a full list of dependencies required to build all modules and how to install
-them, see the
-`devguide <https://devguide.python.org/getting-started/setup-building/#install-dependencies>`_.
 
-* Autoconf 2.72 and aclocal 1.16.5 are required to regenerate the
-  :file:`configure` script.
+.. _optional-module-requirements:
+
+Requirements for Optional Modules
+---------------------------------
+
+To build :term:`optional modules <optional module>` of the standard library,
+you will need several third-party libraries installed for development
+(for example, header files must be available).
+
+Missing requirements are generally given in ``configure`` output.
+Missing optional modules are listed near the end of ``make`` output,
+sometimes using an internal name such as ``_ctypes`` for the :mod:`ctypes`
+module.
+
+If you distribute a CPython interpreter without optional modules,
+it's best practice to advise users, who generally expect that
+standard library modules are available.
+
+Dependencies to build optional modules are:
+
+.. list-table::
+   :header-rows: 1
+   :align: left
+
+   * - Dependency
+     - Minimum version
+     - Python module
+   * - `libbz2 <https://sourceware.org/bzip2/>`_
+     -
+     - :mod:`bz2`
+   * - `libffi <https://sourceware.org/libffi/>`_
+     - 3.3.0 recommended
+     - :mod:`ctypes`
+   * - `liblzma <https://tukaani.org/xz/>`_
+     -
+     - :mod:`lzma`
+   * - `libmpdec <https://www.bytereef.org/mpdecimal/doc/libmpdec/>`_
+     - 2.5.0
+     - :mod:`decimal` [1]_
+   * - `libreadline <https://tiswww.case.edu/php/chet/readline/rltop.html>`_ or
+       `libedit <https://www.thrysoee.dk/editline/>`_ [2]_
+     -
+     - :mod:`readline`
+   * - `libuuid <https://linux.die.net/man/3/libuuid>`_
+     -
+     - ``_uuid`` [3]_
+   * - `ncurses <https://gnu.org/software/ncurses/ncurses.html>`_ [4]_
+     -
+     - :mod:`curses`
+   * - `OpenSSL <https://openssl-library.org/>`_
+     - | 3.0.18 recommended
+       | (1.1.1 minimum)
+     - :mod:`ssl`, :mod:`hashlib` [5]_
+   * - `SQLite <https://sqlite.org/>`_
+     - 3.15.2
+     - :mod:`sqlite3`
+   * - `Tcl/Tk <https://www.tcl-lang.org/>`_
+     - 8.5.12
+     - :mod:`tkinter`
+   * - `zlib <https://www.zlib.net>`_
+     - 1.2.2.1
+     - :mod:`zlib`, :mod:`gzip`, :mod:`ensurepip`
+   * - `zstd <https://facebook.github.io/zstd/>`_
+     - 1.4.5
+     - :mod:`compression.zstd`
+
+.. [1] If *libmpdec* is not available, CPython will use a bundled copy.
+   This is deprecated; see :option:`--with-system-libmpdec` for details.
+
+   .. when the bundled libmpdec is removed, we should instead note that
+      :mod:`decimal` will fall back to a pure-Python implementation.
+
+.. [2] See :option:`--with-readline` for choosing the backend for the
+   :mod:`readline` module.
+.. [3] The :mod:`uuid` module uses ``_uuid`` to generate "safe" UUIDs.
+   See the module documentation for details.
+.. [4] The :mod:`curses` module requires the ``libncurses`` or ``libncursesw``
+   library.
+   The :mod:`curses.panel` module additionally requires the ``libpanel`` or
+   ``libpanelw`` library.
+.. [5] If OpenSSL is not available, the :mod:`hashlib` module will use
+   bundled implementations of several hash functions.
+   See :option:`--with-builtin-hashlib-hashes` for *forcing* usage of OpenSSL.
+
+.. seealso::
+
+   * The `devguide <https://devguide.python.org/getting-started/setup-building/#install-dependencies>`_
+     includes a full list of dependencies required to build all modules and
+     instructions on how to install them on common platforms.
+   * :option:`--with-system-expat` allows building with an external
+     `libexpat <https://libexpat.github.io/>`_ library.
+   * :ref:`configure-options-for-dependencies`
 
 .. versionchanged:: 3.1
-   Tcl/Tk version 8.3.1 is now required.
+   Tcl/Tk version 8.3.1 is now required for :mod:`tkinter`.
 
 .. versionchanged:: 3.5
-   On Windows, Visual Studio 2015 or later is now required.
-   Tcl/Tk version 8.4 is now required.
-
-.. versionchanged:: 3.6
-   Selected C99 features are now required, like ``<stdint.h>`` and ``static
-   inline`` functions.
+   Tcl/Tk version 8.4 is now required for :mod:`tkinter`.
 
 .. versionchanged:: 3.7
-   Thread support and OpenSSL 1.0.2 are now required.
+   OpenSSL 1.0.2 are now required for :mod:`hashlib`.
 
 .. versionchanged:: 3.10
-   OpenSSL 1.1.1 is now required.
-   Require SQLite 3.7.15.
+   OpenSSL 1.1.1 is now required for :mod:`hashlib`.
+   SQLite 3.7.15 is now required for :mod:`sqlite3`.
 
 .. versionchanged:: 3.11
-   C11 compiler, IEEE 754 and NaN support are now required.
-   On Windows, Visual Studio 2017 or later is required.
-   Tcl/Tk version 8.5.12 is now required for the :mod:`tkinter` module.
+   Tcl/Tk version 8.5.12 is now required for :mod:`tkinter`.
 
 .. versionchanged:: 3.13
-   Autoconf 2.71, aclocal 1.16.5 and SQLite 3.15.2 are now required.
-
-.. versionchanged:: 3.14
-   Autoconf 2.72 is now required.
-
-See also :pep:`7` "Style Guide for C Code" and :pep:`11` "CPython platform
-support".
+   SQLite 3.15.2 is now required for :mod:`sqlite3`.
 
 
 Generated files
@@ -127,8 +182,19 @@ The container is optional, the following command can be run locally::
 
     autoreconf -ivf -Werror
 
-The generated files can change depending on the exact ``autoconf-archive``,
-``aclocal`` and ``pkg-config`` versions.
+The generated files can change depending on the exact versions of the
+tools used.
+The container that CPython uses has
+`Autoconf <https://gnu.org/software/autoconf>`_ 2.72,
+``aclocal`` from `Automake <https://www.gnu.org/software/automake>`_ 1.16.5,
+and `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`_ 1.8.1.
+
+.. versionchanged:: 3.13
+   Autoconf 2.71 and aclocal 1.16.5 and are now used to regenerate
+   :file:`configure`.
+
+.. versionchanged:: 3.14
+   Autoconf 2.72 is now used to regenerate :file:`configure`.
 
 
 .. _configure-options:
@@ -409,6 +475,8 @@ Linker options
    Name for machine-dependent library files.
 
 
+.. _configure-options-for-dependencies:
+
 Options for third-party dependencies
 ------------------------------------
 
@@ -431,12 +499,6 @@ Options for third-party dependencies
 
    C compiler and linker flags for ``gdbm``.
 
-.. option:: LIBB2_CFLAGS
-.. option:: LIBB2_LIBS
-
-   C compiler and linker flags for ``libb2`` (:ref:`BLAKE2 <hashlib-blake2>`),
-   used by :mod:`hashlib` module, overriding ``pkg-config``.
-
 .. option:: LIBEDIT_CFLAGS
 .. option:: LIBEDIT_LIBS