Merge branch 'main' into doc_math_monosummary

.github/workflows/build.yml

@@ -40,6 +40,50 @@ jobs:
     if: fromJSON(needs.check_source.outputs.run-docs)
     uses: ./.github/workflows/reusable-docs.yml
 
+  check_autoconf_regen:
+    name: 'Check if Autoconf files are up to date'
+    # Don't use ubuntu-latest but a specific version to make the job
+    # reproducible: to get the same tools versions (autoconf, aclocal, ...)
+    runs-on: ubuntu-24.04
+    container:
+      image: ghcr.io/python/autoconf:2024.10.11.11293396815
+    timeout-minutes: 60
+    needs: check_source
+    if: needs.check_source.outputs.run_tests == 'true'
+    steps:
+      - name: Install Git
+        run: |
+          apt install git -yq
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - name: Runner image version
+        run: echo "IMAGE_VERSION=${ImageVersion}" >> $GITHUB_ENV
+      - name: Check Autoconf and aclocal versions
+        run: |
+          grep "Generated by GNU Autoconf 2.71" configure
+          grep "aclocal 1.16.5" aclocal.m4
+          grep -q "runstatedir" configure
+          grep -q "PKG_PROG_PKG_CONFIG" aclocal.m4
+      - name: Regenerate autoconf files
+        # Same command used by Tools/build/regen-configure.sh ($AUTORECONF)
+        run: autoreconf -ivf -Werror
+      - name: Check for changes
+        run: |
+          git add -u
+          changes=$(git status --porcelain)
+          # Check for changes in regenerated files
+          if test -n "$changes"; then
+            echo "Generated files not up to date."
+            echo "Perhaps you forgot to run make regen-all or build.bat --regen. ;)"
+            echo "configure files must be regenerated with a specific version of autoconf."
+            echo "$changes"
+            echo ""
+            git diff --staged || true
+            exit 1
+          fi
+
   check_generated_files:
     name: 'Check if generated files are up to date'
     # Don't use ubuntu-latest but a specific version to make the job
@@ -69,19 +113,10 @@ jobs:
         uses: hendrikmuhs/ccache-action@v1.2
         with:
           save: false
-      - name: Check Autoconf and aclocal versions
-        run: |
-          grep "Generated by GNU Autoconf 2.71" configure
-          grep "aclocal 1.16.5" aclocal.m4
-          grep -q "runstatedir" configure
-          grep -q "PKG_PROG_PKG_CONFIG" aclocal.m4
       - name: Configure CPython
         run: |
           # Build Python with the libpython dynamic library
           ./configure --config-cache --with-pydebug --enable-shared
-      - name: Regenerate autoconf files
-        # Same command used by Tools/build/regen-configure.sh ($AUTORECONF)
-        run: autoreconf -ivf -Werror
       - name: Build CPython
         run: |
           make -j4 regen-all
@@ -501,6 +536,7 @@ jobs:
     needs:
     - check_source  # Transitive dependency, needed to access `run_tests` value
     - check-docs
+    - check_autoconf_regen
     - check_generated_files
     - build_macos
     - build_ubuntu
@@ -536,6 +572,7 @@ jobs:
           ${{
             needs.check_source.outputs.run_tests != 'true'
             && '
+            check_autoconf_regen,
             check_generated_files,
             build_macos,
             build_ubuntu,

.github/workflows/posix-deps-apt.sh

@@ -1,11 +1,9 @@
 #!/bin/sh
 apt-get update
 
-# autoconf-archive is needed by autoreconf (check_generated_files job)
 apt-get -yq install \
     build-essential \
     pkg-config \
-    autoconf-archive \
     ccache \
     gdb \
     lcov \

.github/workflows/reusable-docs.yml

@@ -84,7 +84,7 @@ jobs:
     - name: 'Set up Python'
       uses: actions/setup-python@v5
       with:
-        python-version: '3.12'  # known to work with Sphinx 6.2.1
+        python-version: '3.13'  # known to work with Sphinx 7.2.6
         cache: 'pip'
         cache-dependency-path: 'Doc/requirements-oldest-sphinx.txt'
     - name: 'Install build dependencies'

Doc/c-api/init.rst

@@ -625,7 +625,7 @@ Process-wide parameters
    returned string points into static storage; the caller should not modify its
    value.  This corresponds to the :makevar:`prefix` variable in the top-level
    :file:`Makefile` and the :option:`--prefix` argument to the :program:`configure`
-   script at build time.  The value is available to Python code as ``sys.prefix``.
+   script at build time.  The value is available to Python code as ``sys.base_prefix``.
    It is only useful on Unix.  See also the next function.
 
    This function should not be called before :c:func:`Py_Initialize`, otherwise
@@ -635,7 +635,8 @@ Process-wide parameters
       It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
 
    .. deprecated-removed:: 3.13 3.15
-      Get :data:`sys.prefix` instead.
+      Get :data:`sys.base_prefix` instead, or :data:`sys.prefix` if
+      :ref:`virtual environments <venv-def>` need to be handled.
 
 
 .. c:function:: wchar_t* Py_GetExecPrefix()
@@ -648,7 +649,8 @@ Process-wide parameters
    should not modify its value.  This corresponds to the :makevar:`exec_prefix`
    variable in the top-level :file:`Makefile` and the ``--exec-prefix``
    argument to the :program:`configure` script at build  time.  The value is
-   available to Python code as ``sys.exec_prefix``.  It is only useful on Unix.
+   available to Python code as ``sys.base_exec_prefix``.  It is only useful on
+   Unix.
 
    Background: The exec-prefix differs from the prefix when platform dependent
    files (such as executables and shared libraries) are installed in a different
@@ -679,7 +681,8 @@ Process-wide parameters
       It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
 
    .. deprecated-removed:: 3.13 3.15
-      Get :data:`sys.exec_prefix` instead.
+      Get :data:`sys.base_exec_prefix` instead, or :data:`sys.exec_prefix` if
+      :ref:`virtual environments <venv-def>` need to be handled.
 
 
 .. c:function:: wchar_t* Py_GetProgramFullPath()
@@ -2418,7 +2421,7 @@ Example usage::
 
 In the above example, :c:macro:`Py_SETREF` calls :c:macro:`Py_DECREF`, which
 can call arbitrary code through an object's deallocation function.  The critical
-section API avoids potentital deadlocks due to reentrancy and lock ordering
+section API avoids potential deadlocks due to reentrancy and lock ordering
 by allowing the runtime to temporarily suspend the critical section if the
 code triggered by the finalizer blocks and calls :c:func:`PyEval_SaveThread`.
 

Doc/c-api/long.rst

@@ -511,7 +511,7 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
       free(bignum);
 
    *flags* is either ``-1`` (``Py_ASNATIVEBYTES_DEFAULTS``) to select defaults
-   that behave most like a C cast, or a combintation of the other flags in
+   that behave most like a C cast, or a combination of the other flags in
    the table below.
    Note that ``-1`` cannot be combined with other flags.
 

Doc/c-api/monitoring.rst

@@ -147,7 +147,7 @@ would typically correspond to a python function.
 
    The ``version`` argument is a pointer to a value which should be allocated
    by the user together with ``state_array`` and initialized to 0,
-   and then set only by :c:func:`!PyMonitoring_EnterScope` itelf. It allows this
+   and then set only by :c:func:`!PyMonitoring_EnterScope` itself. It allows this
    function to determine whether event states have changed since the previous call,
    and to return quickly if they have not.
 

Doc/c-api/typeobj.rst

@@ -682,6 +682,19 @@ and :c:data:`PyType_Type` effectively act as defaults.)
          Py_DECREF(tp);
      }
 
+   .. warning::
+
+      In a garbage collected Python, :c:member:`!tp_dealloc` may be called from
+      any Python thread, not just the thread which created the object (if the
+      object becomes part of a refcount cycle, that cycle might be collected by
+      a garbage collection on any thread).  This is not a problem for Python
+      API calls, since the thread on which :c:member:`!tp_dealloc` is called
+      will own the Global Interpreter Lock (GIL).  However, if the object being
+      destroyed in turn destroys objects from some other C or C++ library, care
+      should be taken to ensure that destroying those objects on the thread
+      which called :c:member:`!tp_dealloc` will not violate any assumptions of
+      the library.
+
 
    **Inheritance:**
 
@@ -2109,17 +2122,6 @@ and :c:data:`PyType_Type` effectively act as defaults.)
           PyErr_Restore(error_type, error_value, error_traceback);
       }
 
-   Also, note that, in a garbage collected Python,
-   :c:member:`~PyTypeObject.tp_dealloc` may be called from
-   any Python thread, not just the thread which created the object (if the object
-   becomes part of a refcount cycle, that cycle might be collected by a garbage
-   collection on any thread).  This is not a problem for Python API calls, since
-   the thread on which tp_dealloc is called will own the Global Interpreter Lock
-   (GIL). However, if the object being destroyed in turn destroys objects from some
-   other C or C++ library, care should be taken to ensure that destroying those
-   objects on the thread which called tp_dealloc will not violate any assumptions
-   of the library.
-
    **Inheritance:**
 
    This field is inherited by subtypes.

Doc/conf.py

@@ -90,11 +90,12 @@
 highlight_language = 'python3'
 
 # Minimum version of sphinx required
-needs_sphinx = '6.2.1'
+needs_sphinx = '7.2.6'
 
 # Create table of contents entries for domain objects (e.g. functions, classes,
 # attributes, etc.). Default is True.
-toc_object_entries = False
+toc_object_entries = True
+toc_object_entries_show_parents = 'hide'
 
 # Ignore any .rst files in the includes/ directory;
 # they're embedded in pages but not rendered individually.

Doc/deprecations/c-api-pending-removal-in-3.15.rst

@@ -13,11 +13,11 @@ Pending removal in Python 3.15
   * :c:func:`PySys_ResetWarnOptions`:
     Clear :data:`sys.warnoptions` and :data:`!warnings.filters` instead.
   * :c:func:`Py_GetExecPrefix`:
-    Get :data:`sys.exec_prefix` instead.
+    Get :data:`sys.base_exec_prefix` and :data:`sys.exec_prefix` instead.
   * :c:func:`Py_GetPath`:
     Get :data:`sys.path` instead.
   * :c:func:`Py_GetPrefix`:
-    Get :data:`sys.prefix` instead.
+    Get :data:`sys.base_prefix` and :data:`sys.prefix` instead.
   * :c:func:`Py_GetProgramFullPath`:
     Get :data:`sys.executable` instead.
   * :c:func:`Py_GetProgramName`:

Doc/deprecations/pending-removal-in-future.rst

@@ -4,16 +4,6 @@ Pending removal in future versions
 The following APIs will be removed in the future,
 although there is currently no date scheduled for their removal.
 
-* :mod:`argparse`:
-
-  * Nesting argument groups and nesting mutually exclusive
-    groups are deprecated.
-  * Passing the undocumented keyword argument *prefix_chars* to
-    :meth:`~argparse.ArgumentParser.add_argument_group` is now
-    deprecated.
-
-* :mod:`array`'s ``'u'`` format code (:gh:`57281`)
-
 * :mod:`builtins`:
 
   * ``bool(NotImplemented)``.
@@ -43,6 +33,17 @@ although there is currently no date scheduled for their removal.
     as a single positional argument.
     (Contributed by Serhiy Storchaka in :gh:`109218`.)
 
+* :mod:`argparse`:
+
+  * Nesting argument groups and nesting mutually exclusive
+    groups are deprecated.
+  * Passing the undocumented keyword argument *prefix_chars* to
+    :meth:`~argparse.ArgumentParser.add_argument_group` is now
+    deprecated.
+  * The :class:`argparse.FileType` type converter is deprecated.
+
+* :mod:`array`'s ``'u'`` format code (:gh:`57281`)
+
 * :mod:`calendar`: ``calendar.January`` and ``calendar.February`` constants are
   deprecated and replaced by :data:`calendar.JANUARY` and
   :data:`calendar.FEBRUARY`.

Doc/library/argparse.rst

@@ -865,16 +865,14 @@ See also :ref:`specifying-ambiguous-arguments`. The supported values are:
   output files::
 
      >>> parser = argparse.ArgumentParser()
-     >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
-     ...                     default=sys.stdin)
-     >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
-     ...                     default=sys.stdout)
+     >>> parser.add_argument('infile', nargs='?')
+     >>> parser.add_argument('outfile', nargs='?')
      >>> parser.parse_args(['input.txt', 'output.txt'])
-     Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
-               outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
+     Namespace(infile='input.txt', outfile='output.txt')
+     >>> parser.parse_args(['input.txt'])
+     Namespace(infile='input.txt', outfile=None)
      >>> parser.parse_args([])
-     Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
-               outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)
+     Namespace(infile=None, outfile=None)
 
 .. index:: single: * (asterisk); in argparse module
 
@@ -1033,7 +1031,6 @@ Common built-in types and functions can be used as type converters:
    parser.add_argument('distance', type=float)
    parser.add_argument('street', type=ascii)
    parser.add_argument('code_point', type=ord)
-   parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
    parser.add_argument('datapath', type=pathlib.Path)
 
 User defined functions can be used as well:
@@ -1827,9 +1824,19 @@ FileType objects
       >>> parser.parse_args(['-'])
       Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)
 
+   .. note::
+
+      If one argument uses *FileType* and then a subsequent argument fails,
+      an error is reported but the file is not automatically closed.
+      This can also clobber the output files.
+      In this case, it would be better to wait until after the parser has
+      run and then use the :keyword:`with`-statement to manage the files.
+
    .. versionchanged:: 3.4
       Added the *encodings* and *errors* parameters.
 
+   .. deprecated:: 3.14
+
 
 Argument groups
 ^^^^^^^^^^^^^^^

Doc/library/builtins.rst

@@ -7,10 +7,7 @@
 --------------
 
 This module provides direct access to all 'built-in' identifiers of Python; for
-example, ``builtins.open`` is the full name for the built-in function
-:func:`open`.  See :ref:`built-in-funcs` and :ref:`built-in-consts` for
-documentation.
-
+example, ``builtins.open`` is the full name for the built-in function :func:`open`.
 
 This module is not normally accessed explicitly by most applications, but can be
 useful in modules that provide objects with the same name as a built-in value,
@@ -40,3 +37,10 @@ available as part of their globals.  The value of ``__builtins__`` is normally
 either this module or the value of this module's :attr:`~object.__dict__` attribute.
 Since this is an implementation detail, it may not be used by alternate
 implementations of Python.
+
+.. seealso::
+
+   * :ref:`built-in-consts`
+   * :ref:`bltin-exceptions`
+   * :ref:`built-in-funcs`
+   * :ref:`bltin-types`

Doc/library/concurrent.futures.rst

@@ -208,7 +208,7 @@ ThreadPoolExecutor Example
            'http://www.cnn.com/',
            'http://europe.wsj.com/',
            'http://www.bbc.co.uk/',
-           'http://nonexistant-subdomain.python.org/']
+           'http://nonexistent-subdomain.python.org/']
 
    # Retrieve a single page and report the URL and contents
    def load_url(url, timeout):

Doc/library/functions.rst

@@ -2032,6 +2032,10 @@ are always available.  They are listed here in alphabetical order.
    :func:`super`, see `guide to using super()
    <https://rhettinger.wordpress.com/2011/05/26/super-considered-super/>`_.
 
+   .. versionchanged:: 3.14
+     :class:`super` objects are now :mod:`pickleable <pickle>` and
+      :mod:`copyable <copy>`.
+
 
 .. _func-tuple:
 .. class:: tuple()

Doc/library/importlib.metadata.rst

@@ -559,7 +559,7 @@ path.
 
 ``DatabaseDistribution``, then, would look something like::
 
-    class DatabaseDistribution(importlib.metadata.Distributon):
+    class DatabaseDistribution(importlib.metadata.Distribution):
         def __init__(self, record):
             self.record = record
 

Doc/library/locale.rst

@@ -158,8 +158,7 @@ The :mod:`locale` module defines the following exception and functions:
 
 .. function:: nl_langinfo(option)
 
-   Return some locale-specific information as a string (or a tuple for
-   ``ALT_DIGITS``).  This function is not
+   Return some locale-specific information as a string.  This function is not
    available on all systems, and the set of possible options might also vary
    across platforms.  The possible argument values are numbers, for which
    symbolic constants are available in the locale module.
@@ -312,7 +311,9 @@ The :mod:`locale` module defines the following exception and functions:
 
    .. data:: ALT_DIGITS
 
-      Get a tuple of up to 100 strings used to represent the values 0 to 99.
+      Get a string consisting of up to 100 semicolon-separated symbols used
+      to represent the values 0 to 99 in a locale-specific way.
+      In most locales this is an empty string.
 
    The function temporarily sets the ``LC_CTYPE`` locale to the locale
    of the category that determines the requested value (``LC_TIME``,