[pull] main from python:main

Doc/c-api/codec.rst

@@ -129,3 +129,13 @@ Registry API for Unicode encoding error handlers
    Replace the unicode encode error with ``\N{...}`` escapes.
 
    .. versionadded:: 3.5
+
+
+Codec utility variables
+-----------------------
+
+.. c:var:: const char *Py_hexdigits
+
+   A string constant containing the lowercase hexadecimal digits: ``"0123456789abcdef"``.
+
+   .. versionadded:: 3.3

Doc/c-api/iterator.rst

@@ -52,6 +52,45 @@ sentinel value is returned.
    *sentinel*, the iteration will be terminated.
 
 
+Range Objects
+^^^^^^^^^^^^^
+
+.. c:var:: PyTypeObject PyRange_Type
+
+   The type object for :class:`range` objects.
+
+
+.. c:function:: int PyRange_Check(PyObject *o)
+
+   Return true if the object *o* is an instance of a :class:`range` object.
+   This function always succeeds.
+
+
+Builtin Iterator Types
+^^^^^^^^^^^^^^^^^^^^^^
+
+These are built-in iteration types that are included in Python's C API, but
+provide no additional functions. They are here for completeness.
+
+
+.. list-table::
+   :widths: auto
+   :header-rows: 1
+
+   * * C type
+     * Python type
+   * * .. c:var:: PyTypeObject PyEnum_Type
+     * :py:class:`enumerate`
+   * * .. c:var:: PyTypeObject PyFilter_Type
+     * :py:class:`filter`
+   * * .. c:var:: PyTypeObject PyMap_Type
+     * :py:class:`map`
+   * * .. c:var:: PyTypeObject PyReversed_Type
+     * :py:class:`reversed`
+   * * .. c:var:: PyTypeObject PyZip_Type
+     * :py:class:`zip`
+
+
 Other Iterator Objects
 ^^^^^^^^^^^^^^^^^^^^^^
 

Doc/c-api/long.rst

@@ -161,6 +161,17 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionadded:: 3.13
 
 
+.. c:macro:: PyLong_FromPid(pid)
+
+   Macro for creating a Python integer from a process identifier.
+
+   This can be defined as an alias to :c:func:`PyLong_FromLong` or
+   :c:func:`PyLong_FromLongLong`, depending on the size of the system's
+   PID type.
+
+   .. versionadded:: 3.2
+
+
 .. c:function:: long PyLong_AsLong(PyObject *obj)
 
    .. index::
@@ -575,6 +586,17 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionadded:: 3.13
 
 
+.. c:macro:: PyLong_AsPid(pid)
+
+   Macro for converting a Python integer into a process identifier.
+
+   This can be defined as an alias to :c:func:`PyLong_AsLong`,
+   :c:func:`PyLong_FromLongLong`, or :c:func:`PyLong_AsInt`, depending on the
+   size of the system's PID type.
+
+   .. versionadded:: 3.2
+
+
 .. c:function:: int PyLong_GetSign(PyObject *obj, int *sign)
 
    Get the sign of the integer object *obj*.

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

Doc/howto/free-threading-extensions.rst

@@ -203,7 +203,7 @@ Memory Allocation APIs
 Python's memory management C API provides functions in three different
 :ref:`allocation domains <allocator-domains>`: "raw", "mem", and "object".
 For thread-safety, the free-threaded build requires that only Python objects
-are allocated using the object domain, and that all Python object are
+are allocated using the object domain, and that all Python objects are
 allocated using that domain.  This differs from the prior Python versions,
 where this was only a best practice and not a hard requirement.
 
@@ -344,12 +344,12 @@ This means you cannot rely on nested critical sections to lock multiple objects
 at once, as the inner critical section may suspend the outer ones. Instead, use
 :c:macro:`Py_BEGIN_CRITICAL_SECTION2` to lock two objects simultaneously.
 
-Note that the locks described above are only :c:type:`!PyMutex` based locks.
+Note that the locks described above are only :c:type:`PyMutex` based locks.
 The critical section implementation does not know about or affect other locking
 mechanisms that might be in use, like POSIX mutexes.  Also note that while
-blocking on any :c:type:`!PyMutex` causes the critical sections to be
+blocking on any :c:type:`PyMutex` causes the critical sections to be
 suspended, only the mutexes that are part of the critical sections are
-released.  If :c:type:`!PyMutex` is used without a critical section, it will
+released.  If :c:type:`PyMutex` is used without a critical section, it will
 not be released and therefore does not get the same deadlock avoidance.
 
 Important Considerations
@@ -397,7 +397,8 @@ The wheels, shared libraries, and binaries are indicated by a ``t`` suffix.
 * `pypa/manylinux <https://github.com/pypa/manylinux>`_ supports the
   free-threaded build, with the ``t`` suffix, such as ``python3.13t``.
 * `pypa/cibuildwheel <https://github.com/pypa/cibuildwheel>`_ supports the
-  free-threaded build if you set
+  free-threaded build on Python 3.13 and 3.14. On Python 3.14, free-threaded
+  wheels will be built by default. On Python 3.13, you will need to set
   `CIBW_ENABLE to cpython-freethreading <https://cibuildwheel.pypa.io/en/stable/options/#enable>`_.
 
 Limited C API and Stable ABI

Doc/howto/free-threading-python.rst

@@ -116,12 +116,14 @@ after the main thread is running.  The following objects are immortalized:
 * :ref:`classes <classes>` (type objects)
 
 Because immortal objects are never deallocated, applications that create many
-objects of these types may see increased memory usage.  This is expected to be
-addressed in the 3.14 release.
+objects of these types may see increased memory usage under Python 3.13.  This
+has been addressed in the 3.14 release, where the aforementioned objects use
+deferred reference counting to avoid reference count contention.
 
 Additionally, numeric and string literals in the code as well as strings
-returned by :func:`sys.intern` are also immortalized.  This behavior is
-expected to remain in the 3.14 free-threaded build.
+returned by :func:`sys.intern` are also immortalized in the 3.13 release.  This
+behavior is part of the 3.14 release as well and it is expected to remain in
+future free-threaded builds.
 
 
 Frame objects
@@ -150,11 +152,12 @@ compared to the default GIL-enabled build.  In 3.13, this overhead is about
 40% on the `pyperformance <https://pyperformance.readthedocs.io/>`_ suite.
 Programs that spend most of their time in C extensions or I/O will see
 less of an impact.  The largest impact is because the specializing adaptive
-interpreter (:pep:`659`) is disabled in the free-threaded build.  We expect
-to re-enable it in a thread-safe way in the 3.14 release.  This overhead is
-expected to be reduced in upcoming Python release.   We are aiming for an
-overhead of 10% or less on the pyperformance suite compared to the default
-GIL-enabled build.
+interpreter (:pep:`659`) is disabled in the free-threaded build.
+
+The specializing adaptive interpreter has been re-enabled in a thread-safe way
+in the 3.14 release.  The performance penalty on single-threaded code in
+free-threaded mode is now roughly 5-10%, depending on the platform and C
+compiler used.
 
 
 Behavioral changes

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

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

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

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

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

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/>`_

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

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

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