From d89a92d97ec6274add84e49ea467f3dad6084404 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 15 Oct 2025 16:01:08 +0200 Subject: [PATCH 01/17] Use a table for optional module dependencies --- Doc/using/configure.rst | 166 ++++++++++++++++++++++++++-------------- 1 file changed, 109 insertions(+), 57 deletions(-) diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 1f773a3a547c2b..66b04773ea5187 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -7,7 +7,7 @@ Configure Python Build Requirements ================== -Features and minimum versions required to build CPython: +To build CPython, you will need: * A `C11 `_ compiler. `Optional C11 features @@ -22,83 +22,135 @@ Features and minimum versions required to build CPython: * Support for threads. -To build optional modules: +* On non-Windows platforms, Autoconf 2.72 and aclocal 1.16.5 are required to + regenerate the :file:`configure` script. -* `libbz2 `_ for the :mod:`bz2` module. - -* `libb2 `_ (:ref:`BLAKE2 `) - for the :mod:`hashlib` module. - -* `libffi `_ 3.3.0 is the recommended - minimum version for the :mod:`ctypes` module. - -* ``liblzma`` for the :mod:`lzma` module. - -* `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 `_ or - `libedit `_ - for the :mod:`readline` module. +.. versionchanged:: 3.5 + On Windows, Visual Studio 2015 or later is now required. -* `libuuid `_ for the :mod:`uuid` module. +.. versionchanged:: 3.6 + Selected C99 features, like ```` and ``static inline`` functions, + are now required. -* `OpenSSL `_ 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.7 + Thread support is now required. -* `SQLite `_ 3.15.2 for the :mod:`sqlite3` extension module. +.. versionchanged:: 3.11 + C11 compiler, IEEE 754 and NaN support are now required. + On Windows, Visual Studio 2017 or later is required. -* `Tcl/Tk `_ 8.5.12 for the :mod:`tkinter` module. +.. versionchanged:: 3.13 + Autoconf 2.71 and aclocal 1.16.5 and are now required to regenerate + :file:`configure`. -* `zlib `_ 1.2.2.1 is the minimum version for the - :mod:`zlib` module. +.. versionchanged:: 3.14 + Autoconf 2.72 is now required to regenerate :file:`configure`. -* `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 `_. -* Autoconf 2.72 and aclocal 1.16.5 are required to regenerate the - :file:`configure` script. +Requirements for Optional Modules +--------------------------------- + +To build *optional modules* of the standard library, you will need several +third-party libraries, along with development dependencies like header files. +(In common Linux distributions, development dependencies are found in +``-dev`` or ``-devel`` packages.) + +Missing optional modules are listed near the end of ``make`` output. +If you distribute a CPython interpreter without them, 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 `_ + - + - :mod:`bz2` + * - `libb2 `_ + - + - :mod:`hashlib` (:ref:`BLAKE2 `) + * - `libffi `_ + - 3.3.0 recommended + - :mod:`ctypes` + * - `liblzma `_ + - + - :mod:`lzma` + * - `libmpdec `_ [4]_ + - 2.5.0 + - :mod:`decimal` + * - `libreadline `_ or + `libedit `_ [1]_ + - + - :mod:`readline` + * - `libuuid `_ + - + - :mod:`uuid` + * - `ncurses `_ [2]_ + - + - :mod:`curses` + * - `OpenSSL `_ + - | 3.0.18 recommended + | (1.1.1 minimum) + - :mod:`ssl`, :mod:`hashlib` [3]_ + * - `SQLite `_ + - 3.15.2 + - :mod:`sqlite3` + * - `Tcl/Tk `_ + - 8.5.12 + - :mod:`tkinter` + * - `zlib `_ + - 1.2.2.1 + - :mod:`zlib`, :mod:`ensurepip` + * - `zstd `_ + - 1.4.5 + - :mod:`compression.zstd` + +.. [1] See :option:`--with-readline` for choosing the backend for the + :mod:`readline` module. +.. [2] The :mod:`curses` module requires the ``libncurses`` or ``libncursesw`` + library. + The :mod:`curses.panel` module additionally requires the ``libpanel`` or + ``libpanelw`` library. +.. [3] 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. +.. [4] If *libmpdec* is not available, CPython will use a bundled copy. + This is deprecated; see :option:`--with-system-libmpdec` for details. + +.. seealso:: + + * The `devguide `_ + 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 `_ library. .. 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 ```` 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 From 3cff6819c17e92526d04d53bae403ddb805d1fcb Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 15 Oct 2025 16:44:50 +0200 Subject: [PATCH 02/17] Add a little note to "Building Python" --- Doc/using/configure.rst | 5 +++++ Doc/using/unix.rst | 12 +++++++++--- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 66b04773ea5187..a50b71a8112c07 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -4,6 +4,9 @@ Configure Python .. highlight:: sh + +.. _build-requirements: + Build Requirements ================== @@ -50,6 +53,8 @@ See also :pep:`7` "Style Guide for C Code" and :pep:`11` "CPython platform support". +.. _optional-module-requirements: + Requirements for Optional Modules --------------------------------- diff --git a/Doc/using/unix.rst b/Doc/using/unix.rst index 9ec4e3419321a4..9b3faa86e57eec 100644 --- a/Doc/using/unix.rst +++ b/Doc/using/unix.rst @@ -84,11 +84,17 @@ On FreeBSD and OpenBSD Building Python =============== +.. seealso:: + + If you want to contribute to CPython, refer to the + `devguide `_, + which includes build instructions and other tips on setting up environment. + If you want to compile CPython yourself, first thing you should do is get the `source `_. You can download either the -latest release's source or just grab a fresh `clone -`_. (If you want -to contribute patches, you will need a clone.) +latest release's source or grab a fresh `clone +`_. +You will also need to install :ref:`build requirements `. The build process consists of the usual commands:: From f8f2161c45f47e23ff5ba9524df2430466f6c8fd Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 15 Oct 2025 17:27:56 +0200 Subject: [PATCH 03/17] Move requirements for regenerating configure --- Doc/using/configure.rst | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index a50b71a8112c07..63cdb9d412ccaa 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -25,9 +25,6 @@ To build CPython, you will need: * Support for threads. -* On non-Windows platforms, Autoconf 2.72 and aclocal 1.16.5 are required to - regenerate the :file:`configure` script. - .. versionchanged:: 3.5 On Windows, Visual Studio 2015 or later is now required. @@ -42,13 +39,6 @@ To build CPython, you will need: C11 compiler, IEEE 754 and NaN support are now required. On Windows, Visual Studio 2017 or later is required. -.. versionchanged:: 3.13 - Autoconf 2.71 and aclocal 1.16.5 and are now required to regenerate - :file:`configure`. - -.. versionchanged:: 3.14 - Autoconf 2.72 is now required to regenerate :file:`configure`. - See also :pep:`7` "Style Guide for C Code" and :pep:`11` "CPython platform support". @@ -184,8 +174,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 `_ 2.72, +``aclocal`` from `Automake `_ 1.16.5, +and `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: From c8f352150f48fa8739e303d0592161d2b87b07d5 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 15 Oct 2025 17:41:48 +0200 Subject: [PATCH 04/17] Requirements for Optional Modules --- Doc/glossary.rst | 7 ++++++ Doc/using/configure.rst | 47 +++++++++++++++++++++++++---------------- 2 files changed, 36 insertions(+), 18 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index c0ca0be304ebe4..d198989aed6374 100644 --- a/Doc/glossary.rst +++ b/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 diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 63cdb9d412ccaa..984f9509c3809f 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -48,14 +48,18 @@ support". Requirements for Optional Modules --------------------------------- -To build *optional modules* of the standard library, you will need several -third-party libraries, along with development dependencies like header files. -(In common Linux distributions, development dependencies are found in -``-dev`` or ``-devel`` packages.) +To build :term:`optional modules ` of the standard library, +you will need several third-party libraries installed for development +(for example, header files must be available). -Missing optional modules are listed near the end of ``make`` output. -If you distribute a CPython interpreter without them, it's best practice to -advise users, who generally expect that standard library modules are 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: @@ -78,23 +82,23 @@ Dependencies to build optional modules are: * - `liblzma `_ - - :mod:`lzma` - * - `libmpdec `_ [4]_ + * - `libmpdec `_ - 2.5.0 - - :mod:`decimal` + - :mod:`decimal` [1]_ * - `libreadline `_ or - `libedit `_ [1]_ + `libedit `_ [2]_ - - :mod:`readline` * - `libuuid `_ - - :mod:`uuid` - * - `ncurses `_ [2]_ + * - `ncurses `_ [3]_ - - :mod:`curses` * - `OpenSSL `_ - | 3.0.18 recommended | (1.1.1 minimum) - - :mod:`ssl`, :mod:`hashlib` [3]_ + - :mod:`ssl`, :mod:`hashlib` [4]_ * - `SQLite `_ - 3.15.2 - :mod:`sqlite3` @@ -103,22 +107,26 @@ Dependencies to build optional modules are: - :mod:`tkinter` * - `zlib `_ - 1.2.2.1 - - :mod:`zlib`, :mod:`ensurepip` + - :mod:`zlib`, :mod:`gzip`, :mod:`ensurepip` * - `zstd `_ - 1.4.5 - :mod:`compression.zstd` -.. [1] See :option:`--with-readline` for choosing the backend for the +.. [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. -.. [2] The :mod:`curses` module requires the ``libncurses`` or ``libncursesw`` +.. [3] The :mod:`curses` module requires the ``libncurses`` or ``libncursesw`` library. The :mod:`curses.panel` module additionally requires the ``libpanel`` or ``libpanelw`` library. -.. [3] If OpenSSL is not available, the :mod:`hashlib` module will use +.. [4] 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. -.. [4] If *libmpdec* is not available, CPython will use a bundled copy. - This is deprecated; see :option:`--with-system-libmpdec` for details. .. seealso:: @@ -127,6 +135,7 @@ Dependencies to build optional modules are: instructions on how to install them on common platforms. * :option:`--with-system-expat` allows building with an external `libexpat `_ library. + * :ref:`configure-options-for-dependencies` .. versionchanged:: 3.1 Tcl/Tk version 8.3.1 is now required for :mod:`tkinter`. @@ -467,6 +476,8 @@ Linker options Name for machine-dependent library files. +.. _configure-options-for-dependencies: + Options for third-party dependencies ------------------------------------ From b9de7858f5bd6e811a1a6ccae7ce4c10bd19529f Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 15 Oct 2025 18:25:07 +0200 Subject: [PATCH 05/17] Add notes to affected modules --- Doc/includes/optional-module.rst | 5 +++++ Doc/library/bz2.rst | 2 ++ Doc/library/compression.zstd.rst | 2 ++ Doc/library/ctypes.rst | 2 ++ Doc/library/curses.rst | 2 ++ Doc/library/ensurepip.rst | 2 ++ Doc/library/gzip.rst | 2 ++ Doc/library/lzma.rst | 2 ++ Doc/library/readline.rst | 2 ++ Doc/library/sqlite3.rst | 2 ++ Doc/library/ssl.rst | 5 +++-- Doc/library/zlib.rst | 6 +++--- Doc/using/configure.rst | 21 +++++++-------------- 13 files changed, 36 insertions(+), 19 deletions(-) create mode 100644 Doc/includes/optional-module.rst diff --git a/Doc/includes/optional-module.rst b/Doc/includes/optional-module.rst new file mode 100644 index 00000000000000..fac45f288d8762 --- /dev/null +++ b/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`. diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst index ebe2e43febaefa..12650861c0fb5d 100644 --- 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 index a901403621b84f..89b6fe540f5ba7 100644 --- 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 index d8dac24c8ab532..9c0b246c095483 100644 --- 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 index fb84cf32246879..2229bdea357e9f 100644 --- 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 index fa102c4a080103..165b9a9f823154 100644 --- 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 index 4bdcec66088db2..cb36be42a83f12 100644 --- 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/lzma.rst b/Doc/library/lzma.rst index 69f7cb8d48d7ae..8a4f68f3502521 100644 --- 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 index f649fce5efc377..75db832c546b64 100644 --- 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 index 9d56e81dee10d5..f7c8a48e7988ff 100644 --- a/Doc/library/sqlite3.rst +++ b/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. diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index e0d85c852fa655..fa0a5234720422 100644 --- 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/zlib.rst b/Doc/library/zlib.rst index e37be69d6a69f8..3ac2150111812c 100644 --- a/Doc/library/zlib.rst +++ b/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; diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 984f9509c3809f..a70885513d4f04 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -73,9 +73,6 @@ Dependencies to build optional modules are: * - `libbz2 `_ - - :mod:`bz2` - * - `libb2 `_ - - - - :mod:`hashlib` (:ref:`BLAKE2 `) * - `libffi `_ - 3.3.0 recommended - :mod:`ctypes` @@ -91,14 +88,14 @@ Dependencies to build optional modules are: - :mod:`readline` * - `libuuid `_ - - - :mod:`uuid` - * - `ncurses `_ [3]_ + - ``_uuid`` [3]_ + * - `ncurses `_ [4]_ - - :mod:`curses` * - `OpenSSL `_ - | 3.0.18 recommended | (1.1.1 minimum) - - :mod:`ssl`, :mod:`hashlib` [4]_ + - :mod:`ssl`, :mod:`hashlib` [5]_ * - `SQLite `_ - 3.15.2 - :mod:`sqlite3` @@ -120,11 +117,13 @@ Dependencies to build optional modules are: .. [2] See :option:`--with-readline` for choosing the backend for the :mod:`readline` module. -.. [3] The :mod:`curses` module requires the ``libncurses`` or ``libncursesw`` +.. [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. -.. [4] If OpenSSL is not available, the :mod:`hashlib` module will use +.. [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. @@ -500,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 `), - used by :mod:`hashlib` module, overriding ``pkg-config``. - .. option:: LIBEDIT_CFLAGS .. option:: LIBEDIT_LIBS From 9f2c9e560f926d45e216f6dd798131e1cd69403e Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 15 Oct 2025 18:49:30 +0200 Subject: [PATCH 06/17] Fix ReST syntax ... And add Stan as contributor: Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/using/configure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index a70885513d4f04..3cb5e503141ebb 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -117,7 +117,7 @@ Dependencies to build optional modules are: .. [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. +.. [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. From 145f0fc03e2b18f6bbf9e08137bba5e660efd717 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 22 Oct 2025 16:13:17 +0200 Subject: [PATCH 07/17] Apply suggestions from code review Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/glossary.rst | 6 +++--- Doc/using/configure.rst | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index d198989aed6374..7b5b7a12e11c66 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -1026,9 +1026,9 @@ Glossary 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. + 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. See :ref:`optional-module-requirements` for a list of optional modules and the required libraries. diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 3cb5e503141ebb..7e0f6e23394c27 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -45,7 +45,7 @@ support". .. _optional-module-requirements: -Requirements for Optional Modules +Requirements for optional modules --------------------------------- To build :term:`optional modules ` of the standard library, @@ -143,7 +143,7 @@ Dependencies to build optional modules are: Tcl/Tk version 8.4 is now required for :mod:`tkinter`. .. versionchanged:: 3.7 - OpenSSL 1.0.2 are now required for :mod:`hashlib`. + OpenSSL 1.0.2 is now required for :mod:`hashlib`. .. versionchanged:: 3.10 OpenSSL 1.1.1 is now required for :mod:`hashlib`. From cd7b04279e074df277d94e27538321ea04f07d87 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 22 Oct 2025 16:20:58 +0200 Subject: [PATCH 08/17] Adjust for libmpdec change --- Doc/using/configure.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 7e0f6e23394c27..5f51399ded2c89 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -109,12 +109,9 @@ Dependencies to build optional modules are: - 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. - +.. [1] If *libmpdec* is not available, the :mod:`decimal` module will use + a pure-Python implementation. + See :option:`--with-system-libmpdec` for details. .. [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. @@ -964,6 +961,13 @@ Libraries options .. versionchanged:: 3.13 Default to using the installed ``mpdecimal`` library. + .. versionchanged:: 3.15 + + A bundled copy of the library will no longer be selected + implicitly if an installed ``mpdecimal`` library is not found. + In Python 3.15 only, it can still be selected explicitly using + ``--with-system-libmpdec=no`` or ``--without-system-libmpdec``. + .. deprecated-removed:: 3.13 3.16 A copy of the ``mpdecimal`` library sources will no longer be distributed with Python 3.16. From 2f91ce5b6fae183f83b0be5a72a03bc0fa563ee4 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 22 Oct 2025 16:46:09 +0200 Subject: [PATCH 09/17] Add and cross-link notes in optional module docs --- Doc/includes/optional-module.rst | 4 ++++ Doc/library/idle.rst | 3 +++ Doc/library/tarfile.rst | 8 ++++++++ Doc/library/tkinter.rst | 2 ++ Doc/library/turtle.rst | 2 ++ Doc/library/zipfile.rst | 10 ++++++++++ Doc/using/configure.rst | 2 +- 7 files changed, 30 insertions(+), 1 deletion(-) diff --git a/Doc/includes/optional-module.rst b/Doc/includes/optional-module.rst index fac45f288d8762..66d1a20fa8c545 100644 --- a/Doc/includes/optional-module.rst +++ b/Doc/includes/optional-module.rst @@ -3,3 +3,7 @@ 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`. + +.. Notes similar wording appear in these module docs: + - zipfile + - tarfile diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index fabea611e0ebcd..1abfb9462604ef 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -37,6 +37,9 @@ IDLE has the following features: * configuration, browsers, and other dialogs +.. include:: ../includes/optional-module.rst + + Menus ----- diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index c4614bf28a4aea..5ff8502bbe219f 100644 --- 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 ` 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 index f284988daf2d4e..8f29c18d22a649 100644 --- 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 `_ diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index b687231bd489cc..58b99e0d44173a 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -29,6 +29,8 @@ introduced in Logo `_, 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 index f6ec33640b60d2..60af683bb262b0 100644 --- 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 ` +such as :mod:`zlib`, :mod:`bz2`, :mod:`lzma`, :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/using/configure.rst b/Doc/using/configure.rst index 5f51399ded2c89..65d0c4b7519078 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -101,7 +101,7 @@ Dependencies to build optional modules are: - :mod:`sqlite3` * - `Tcl/Tk `_ - 8.5.12 - - :mod:`tkinter` + - :mod:`tkinter`, :ref:`IDLE `, :mod:`turtle` * - `zlib `_ - 1.2.2.1 - :mod:`zlib`, :mod:`gzip`, :mod:`ensurepip` From 644a7d560c37812b173d131aa9be481f1879610f Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 23 Oct 2025 09:03:43 +0200 Subject: [PATCH 10/17] Apply suggestions from code review Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/includes/optional-module.rst | 2 +- Doc/library/idle.rst | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/includes/optional-module.rst b/Doc/includes/optional-module.rst index 66d1a20fa8c545..262e73f2eaa09f 100644 --- a/Doc/includes/optional-module.rst +++ b/Doc/includes/optional-module.rst @@ -4,6 +4,6 @@ look for documentation from your distributor (that is, whoever provided Python to you). If you are the distributor, see :ref:`optional-module-requirements`. -.. Notes similar wording appear in these module docs: +.. Similar notes appear in the docs of the modules: - zipfile - tarfile diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 1abfb9462604ef..9ddb41e92ad1b3 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -39,7 +39,6 @@ IDLE has the following features: .. include:: ../includes/optional-module.rst - Menus ----- From 88dc122e1fb3babca62a69142b103786cc85cb73 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 23 Oct 2025 09:10:09 +0200 Subject: [PATCH 11/17] Apply suggestions from code review Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/sqlite3.rst | 2 +- Doc/library/zipfile.rst | 2 +- Doc/library/zlib.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index f7c8a48e7988ff..3b1a9c2f6eefe9 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -31,7 +31,7 @@ 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 `_ library. .. include:: ../includes/optional-module.rst diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 60af683bb262b0..5a8bbc8c1aedf7 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -27,7 +27,7 @@ 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 ` -such as :mod:`zlib`, :mod:`bz2`, :mod:`lzma`, :mod:`~compression.zstd`. +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). diff --git a/Doc/library/zlib.rst b/Doc/library/zlib.rst index ac2d79feef3222..ce0a22b9456d0b 100644 --- a/Doc/library/zlib.rst +++ b/Doc/library/zlib.rst @@ -8,7 +8,7 @@ -------------- For applications that require data compression, the functions in this module -allow compression and decompression, using the zlib library. +allow compression and decompression, using the `zlib library `_. .. include:: ../includes/optional-module.rst From 7a7050be08e6445f00961004a50915d7787034ed Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 5 Nov 2025 12:36:33 +0100 Subject: [PATCH 12/17] Apply suggestions from code review Co-authored-by: Emma Smith Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/using/configure.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 65d0c4b7519078..e4918d241c59ea 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -52,8 +52,8 @@ To build :term:`optional modules ` 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, +Missing requirements are reported in the ``configure`` output. +Missing optional modules are listed near the end of the ``make`` output, sometimes using an internal name such as ``_ctypes`` for the :mod:`ctypes` module. From d62c851510adfa771f7fbfa9722506faf43218c9 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 5 Nov 2025 12:36:55 +0100 Subject: [PATCH 13/17] Platform availability --- Doc/glossary.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 7b5b7a12e11c66..cbe5a80b3c503e 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -1028,7 +1028,8 @@ Glossary 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. + 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 and the required libraries. From 1146543531e99c6e62d17f4c59397a03fb74f87f Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 5 Nov 2025 12:46:27 +0100 Subject: [PATCH 14/17] Abjust wording to cover platform-specific optional modules --- Doc/glossary.rst | 3 ++- Doc/using/configure.rst | 10 +++++++--- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index cbe5a80b3c503e..a4066d42927f64 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -1030,8 +1030,9 @@ Glossary 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 - and the required libraries. + that require third-party libraries. package A Python :term:`module` which can contain submodules or recursively, diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index e4918d241c59ea..14444f0a24981a 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -48,12 +48,13 @@ support". Requirements for optional modules --------------------------------- -To build :term:`optional modules ` of the standard library, -you will need several third-party libraries installed for development +Some :term:`optional modules ` of the standard library +require third-party libraries installed for development (for example, header files must be available). Missing requirements are reported in the ``configure`` output. -Missing optional modules are listed near the end of the ``make`` output, +Modules that are missing due to missing dependencies are listed near the end +of the ``make`` output, sometimes using an internal name such as ``_ctypes`` for the :mod:`ctypes` module. @@ -124,6 +125,9 @@ Dependencies to build optional modules are: bundled implementations of several hash functions. See :option:`--with-builtin-hashlib-hashes` for *forcing* usage of OpenSSL. +Note that the table does not include all optional modules; in particular, +platform-specific modules like :mod:`winreg` are not listed here. + .. seealso:: * The `devguide `_ From 828c39159ecd2ce34393bc9f5435c0c2a41cf97e Mon Sep 17 00:00:00 2001 From: "Author: Terry Jan Reedy" Date: Wed, 5 Nov 2025 12:47:54 +0100 Subject: [PATCH 15/17] Note idlelib at the start of IDLE docs --- Doc/library/idle.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index b3b1dbcec41010..e4af391060d9ff 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -37,6 +37,8 @@ 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 From 45f4ec3e5bdc340a8a08f456c8d31737bee70fe2 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 5 Nov 2025 15:00:38 +0100 Subject: [PATCH 16/17] Apply suggestions from code review Co-authored-by: Victor Stinner --- Doc/using/configure.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 14444f0a24981a..5e471845586606 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -144,10 +144,10 @@ platform-specific modules like :mod:`winreg` are not listed here. Tcl/Tk version 8.4 is now required for :mod:`tkinter`. .. versionchanged:: 3.7 - OpenSSL 1.0.2 is now required for :mod:`hashlib`. + OpenSSL 1.0.2 is now required for :mod:`hashlib` and :mod:`ssl`. .. versionchanged:: 3.10 - OpenSSL 1.1.1 is now required for :mod:`hashlib`. + OpenSSL 1.1.1 is now required for :mod:`hashlib` and :mod:`ssl`. SQLite 3.7.15 is now required for :mod:`sqlite3`. .. versionchanged:: 3.11 From 66ac795baa7025b36ccf83bd6ea51ecc8201284f Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 6 Nov 2025 11:05:01 +0100 Subject: [PATCH 17/17] Apply suggestions from code review Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/using/configure.rst | 2 +- Doc/using/unix.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 5e471845586606..cdadbe51417499 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -55,7 +55,7 @@ require third-party libraries installed for development Missing requirements are reported in the ``configure`` output. Modules that are missing due to missing dependencies are listed near the end of the ``make`` output, -sometimes using an internal name such as ``_ctypes`` for the :mod:`ctypes` +sometimes using an internal name, for example, ``_ctypes`` for :mod:`ctypes` module. If you distribute a CPython interpreter without optional modules, diff --git a/Doc/using/unix.rst b/Doc/using/unix.rst index 9b3faa86e57eec..a9950ef7525497 100644 --- a/Doc/using/unix.rst +++ b/Doc/using/unix.rst @@ -94,7 +94,7 @@ If you want to compile CPython yourself, first thing you should do is get the `source `_. You can download either the latest release's source or grab a fresh `clone `_. -You will also need to install :ref:`build requirements `. +You will also need to install the :ref:`build requirements `. The build process consists of the usual commands::