Merge branch 'main' into pythongh-113225-walk-bottom-up

.github/workflows/build.yml

@@ -142,6 +142,8 @@ jobs:
         run: echo "PATH=/usr/lib/ccache:$PATH" >> $GITHUB_ENV
       - name: Configure ccache action
         uses: hendrikmuhs/[email protected]
+        with:
+          save: false
       - name: Check Autoconf and aclocal versions
         run: |
           grep "Generated by GNU Autoconf 2.71" configure
@@ -284,6 +286,8 @@ jobs:
         echo "PATH=/usr/lib/ccache:$PATH" >> $GITHUB_ENV
     - name: Configure ccache action
       uses: hendrikmuhs/[email protected]
+      with:
+        save: false
     - name: Configure CPython
       run: ./configure --config-cache --with-pydebug --with-openssl=$OPENSSL_DIR
     - name: Build CPython
@@ -327,6 +331,8 @@ jobs:
         echo "PATH=/usr/lib/ccache:$PATH" >> $GITHUB_ENV
     - name: Configure ccache action
       uses: hendrikmuhs/[email protected]
+      with:
+        save: false
     - name: Setup directory envs for out-of-tree builds
       run: |
         echo "CPYTHON_RO_SRCDIR=$(realpath -m ${GITHUB_WORKSPACE}/../cpython-ro-srcdir)" >> $GITHUB_ENV
@@ -446,6 +452,9 @@ jobs:
         echo "PATH=/usr/lib/ccache:$PATH" >> $GITHUB_ENV
     - name: Configure ccache action
       uses: hendrikmuhs/[email protected]
+      with:
+        save: ${{ github.event_name == 'push' }}
+        max-size: "200M"
     - name: Configure CPython
       run: ./configure --config-cache --with-address-sanitizer --without-pymalloc
     - name: Build CPython

.github/workflows/build_msi.yml

@@ -32,6 +32,8 @@ jobs:
     strategy:
       matrix:
         type: [x86, x64, arm64]
+    env:
+      IncludeFreethreaded: true
     steps:
     - uses: actions/checkout@v4
     - name: Build CPython installer

.github/workflows/reusable-ubuntu.yml

@@ -41,6 +41,9 @@ jobs:
         echo "PATH=/usr/lib/ccache:$PATH" >> $GITHUB_ENV
     - name: Configure ccache action
       uses: hendrikmuhs/[email protected]
+      with:
+        save: ${{ github.event_name == 'push' }}
+        max-size: "200M"
     - name: Setup directory envs for out-of-tree builds
       run: |
         echo "CPYTHON_RO_SRCDIR=$(realpath -m ${GITHUB_WORKSPACE}/../cpython-ro-srcdir)" >> $GITHUB_ENV

.github/workflows/reusable-windows.yml

@@ -20,7 +20,7 @@ jobs:
     - name: Display build info
       run: .\python.bat -m test.pythoninfo
     - name: Tests
-      run: .\PCbuild\rt.bat -p Win32 -d -q --fast-ci
+      run: .\PCbuild\rt.bat -p Win32 -d -q --fast-ci ${{ inputs.free-threading && '--disable-gil' || '' }}
 
   build_win_amd64:
     name: 'build and test (x64)'
@@ -37,7 +37,7 @@ jobs:
     - name: Display build info
       run: .\python.bat -m test.pythoninfo
     - name: Tests
-      run: .\PCbuild\rt.bat -p x64 -d -q --fast-ci
+      run: .\PCbuild\rt.bat -p x64 -d -q --fast-ci ${{ inputs.free-threading && '--disable-gil' || '' }}
 
   build_win_arm64:
     name: 'build (arm64)'

.pre-commit-config.yaml

@@ -28,7 +28,7 @@ repos:
     hooks:
       - id: sphinx-lint
         args: [--enable=default-role]
-        files: ^Doc/|^Misc/NEWS.d/next/
+        files: ^Doc/|^Misc/NEWS.d/
 
   - repo: meta
     hooks:

Doc/c-api/complex.rst

@@ -117,11 +117,29 @@ Complex Numbers as Python Objects
 
    Return the real part of *op* as a C :c:expr:`double`.
 
+   If *op* is not a Python complex number object but has a
+   :meth:`~object.__complex__` method, this method will first be called to
+   convert *op* to a Python complex number object.  If :meth:`!__complex__` is
+   not defined then it falls back to call :c:func:`PyFloat_AsDouble` and
+   returns its result.  Upon failure, this method returns ``-1.0``, so one
+   should call :c:func:`PyErr_Occurred` to check for errors.
+
+   .. versionchanged:: 3.13
+      Use :meth:`~object.__complex__` if available.
 
 .. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
 
    Return the imaginary part of *op* as a C :c:expr:`double`.
 
+   If *op* is not a Python complex number object but has a
+   :meth:`~object.__complex__` method, this method will first be called to
+   convert *op* to a Python complex number object.  If :meth:`!__complex__` is
+   not defined then it falls back to call :c:func:`PyFloat_AsDouble` and
+   returns ``0.0`` on success.  Upon failure, this method returns ``-1.0``, so
+   one should call :c:func:`PyErr_Occurred` to check for errors.
+
+   .. versionchanged:: 3.13
+      Use :meth:`~object.__complex__` if available.
 
 .. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
 

Doc/c-api/object.rst

@@ -47,9 +47,8 @@ Object Protocol
 
 .. c:function:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
 
-   Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.  This
-   is equivalent to the Python expression ``hasattr(o, attr_name)``.  This function
-   always succeeds.
+   Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.
+   This function always succeeds.
 
    .. note::
 

Doc/c-api/stable.rst

@@ -16,7 +16,7 @@ CPython's Application Binary Interface (ABI) is forward- and
 backwards-compatible across a minor release (if these are compiled the same
 way; see :ref:`stable-abi-platform` below).
 So, code compiled for Python 3.10.0 will work on 3.10.8 and vice versa,
-but will need to be compiled separately for 3.9.x and 3.10.x.
+but will need to be compiled separately for 3.9.x and 3.11.x.
 
 There are two tiers of C API with different stability expectations:
 

Doc/c-api/structures.rst

@@ -399,6 +399,40 @@ definition with the same method name.
    slot.  This is helpful because calls to PyCFunctions are optimized more
    than wrapper object calls.
 
+.. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)
+
+   Turn *ml* into a Python :term:`callable` object.
+   The caller must ensure that *ml* outlives the :term:`callable`.
+   Typically, *ml* is defined as a static variable.
+
+   The *self* parameter will be passed as the *self* argument
+   to the C function in ``ml->ml_meth`` when invoked.
+   *self* can be ``NULL``.
+
+   The :term:`callable` object's ``__module__`` attribute
+   can be set from the given *module* argument.
+   *module* should be a Python string,
+   which will be used as name of the module the function is defined in.
+   If unavailable, it can be set to :const:`None` or ``NULL``.
+
+   .. seealso:: :attr:`function.__module__`
+
+   The *cls* parameter will be passed as the *defining_class*
+   argument to the C function.
+   Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``.
+
+   .. versionadded:: 3.9
+
+
+.. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module)
+
+   Equivalent to ``PyCMethod_New(ml, self, module, NULL)``.
+
+
+.. c:function:: PyObject * PyCFunction_New(PyMethodDef *ml, PyObject *self)
+
+   Equivalent to ``PyCMethod_New(ml, self, NULL, NULL)``.
+
 
 Accessing attributes of extension types
 ---------------------------------------

Doc/conf.py

@@ -74,6 +74,10 @@
 # Minimum version of sphinx required
 needs_sphinx = '4.2'
 
+# Create table of contents entries for domain objects (e.g. functions, classes,
+# attributes, etc.). Default is True.
+toc_object_entries = False
+
 # Ignore any .rst files in the includes/ directory;
 # they're embedded in pages but not rendered individually.
 # Ignore any .rst files in the venv/ directory.

Doc/copyright.rst

@@ -4,7 +4,7 @@ Copyright
 
 Python and this documentation is:
 
-Copyright © 2001-2023 Python Software Foundation. All rights reserved.
+Copyright © 2001-2024 Python Software Foundation. All rights reserved.
 
 Copyright © 2000 BeOpen.com. All rights reserved.
 

Doc/data/refcounts.dat

@@ -402,6 +402,21 @@ PyContextVar_Reset:int:::
 PyContextVar_Reset:PyObject*:var:0:
 PyContextVar_Reset:PyObject*:token:-1:
 
+PyCFunction_New:PyObject*::+1:
+PyCFunction_New:PyMethodDef*:ml::
+PyCFunction_New:PyObject*:self:+1:
+
+PyCFunction_NewEx:PyObject*::+1:
+PyCFunction_NewEx:PyMethodDef*:ml::
+PyCFunction_NewEx:PyObject*:self:+1:
+PyCFunction_NewEx:PyObject*:module:+1:
+
+PyCMethod_New:PyObject*::+1:
+PyCMethod_New:PyMethodDef*:ml::
+PyCMethod_New:PyObject*:self:+1:
+PyCMethod_New:PyObject*:module:+1:
+PyCMethod_New:PyObject*:cls:+1:
+
 PyDate_Check:int:::
 PyDate_Check:PyObject*:ob:0:
 

Doc/faq/design.rst

@@ -451,7 +451,7 @@ on the key and a per-process seed; for example, ``'Python'`` could hash to
 to ``1142331976``.  The hash code is then used to calculate a location in an
 internal array where the value will be stored.  Assuming that you're storing
 keys that all have different hash values, this means that dictionaries take
-constant time -- O(1), in Big-O notation -- to retrieve a key.
+constant time -- *O*\ (1), in Big-O notation -- to retrieve a key.
 
 
 Why must dictionary keys be immutable?

Doc/glossary.rst

@@ -742,7 +742,7 @@ Glossary
    list
       A built-in Python :term:`sequence`.  Despite its name it is more akin
       to an array in other languages than to a linked list since access to
-      elements is O(1).
+      elements is *O*\ (1).
 
    list comprehension
       A compact way to process all or part of the elements in a sequence and

Doc/howto/descriptor.rst

@@ -1250,7 +1250,7 @@ instance::
     <function D.f at 0x00C45070>
 
     >>> d.f.__self__
-    <__main__.D object at 0x1012e1f98>
+    <__main__.D object at 0x00B18C90>
 
 If you have ever wondered where *self* comes from in regular methods or where
 *cls* comes from in class methods, this is it!

Doc/howto/urllib2.rst

@@ -392,16 +392,16 @@ info and geturl
 ===============
 
 The response returned by urlopen (or the :exc:`~urllib.error.HTTPError` instance) has two
-useful methods :meth:`info` and :meth:`geturl` and is defined in the module
-:mod:`urllib.response`..
+useful methods :meth:`!info` and :meth:`!geturl` and is defined in the module
+:mod:`urllib.response`.
 
-**geturl** - this returns the real URL of the page fetched. This is useful
-because ``urlopen`` (or the opener object used) may have followed a
-redirect. The URL of the page fetched may not be the same as the URL requested.
+* **geturl** - this returns the real URL of the page fetched. This is useful
+  because ``urlopen`` (or the opener object used) may have followed a
+  redirect. The URL of the page fetched may not be the same as the URL requested.
 
-**info** - this returns a dictionary-like object that describes the page
-fetched, particularly the headers sent by the server. It is currently an
-:class:`http.client.HTTPMessage` instance.
+* **info** - this returns a dictionary-like object that describes the page
+  fetched, particularly the headers sent by the server. It is currently an
+  :class:`http.client.HTTPMessage` instance.
 
 Typical headers include 'Content-length', 'Content-type', and so on. See the
 `Quick Reference to HTTP Headers <https://jkorpela.fi/http.html>`_
@@ -507,7 +507,7 @@ than the URL you pass to .add_password() will also match. ::
 
     In the above example we only supplied our ``HTTPBasicAuthHandler`` to
     ``build_opener``. By default openers have the handlers for normal situations
-    -- ``ProxyHandler`` (if a proxy setting such as an :envvar:`http_proxy`
+    -- ``ProxyHandler`` (if a proxy setting such as an :envvar:`!http_proxy`
     environment variable is set), ``UnknownHandler``, ``HTTPHandler``,
     ``HTTPDefaultErrorHandler``, ``HTTPRedirectHandler``, ``FTPHandler``,
     ``FileHandler``, ``DataHandler``, ``HTTPErrorProcessor``.

Doc/library/asyncio-policy.rst

@@ -237,7 +237,7 @@ implementation used by the asyncio event loop:
 
    It works reliably even when the asyncio event loop is run in a non-main OS thread.
 
-   There is no noticeable overhead when handling a big number of children (*O(1)* each
+   There is no noticeable overhead when handling a big number of children (*O*\ (1) each
    time a child terminates), but starting a thread per process requires extra memory.
 
    This watcher is used by default.
@@ -257,7 +257,7 @@ implementation used by the asyncio event loop:
    watcher is installed.
 
    The solution is safe but it has a significant overhead when
-   handling a big number of processes (*O(n)* each time a
+   handling a big number of processes (*O*\ (*n*) each time a
    :py:data:`SIGCHLD` is received).
 
    .. versionadded:: 3.8
@@ -273,7 +273,7 @@ implementation used by the asyncio event loop:
    The watcher avoids disrupting other code spawning processes
    by polling every process explicitly on a :py:data:`SIGCHLD` signal.
 
-   This solution is as safe as :class:`MultiLoopChildWatcher` and has the same *O(N)*
+   This solution is as safe as :class:`MultiLoopChildWatcher` and has the same *O*\ (*n*)
    complexity but requires a running event loop in the main thread to work.
 
    .. deprecated:: 3.12
@@ -285,7 +285,7 @@ implementation used by the asyncio event loop:
    processes and waiting for their termination.
 
    There is no noticeable overhead when handling a big number of
-   children (*O(1)* each time a child terminates).
+   children (*O*\ (1) each time a child terminates).
 
    This solution requires a running event loop in the main thread to work, as
    :class:`SafeChildWatcher`.

Doc/library/bisect.rst

@@ -79,7 +79,7 @@ The following functions are provided:
    To support inserting records in a table, the *key* function (if any) is
    applied to *x* for the search step but not for the insertion step.
 
-   Keep in mind that the ``O(log n)`` search is dominated by the slow O(n)
+   Keep in mind that the *O*\ (log *n*) search is dominated by the slow *O*\ (*n*)
    insertion step.
 
    .. versionchanged:: 3.10
@@ -99,7 +99,7 @@ The following functions are provided:
    To support inserting records in a table, the *key* function (if any) is
    applied to *x* for the search step but not for the insertion step.
 
-   Keep in mind that the ``O(log n)`` search is dominated by the slow O(n)
+   Keep in mind that the *O*\ (log *n*) search is dominated by the slow *O*\ (*n*)
    insertion step.
 
    .. versionchanged:: 3.10
@@ -115,7 +115,7 @@ thoughts in mind:
 * Bisection is effective for searching ranges of values.
   For locating specific values, dictionaries are more performant.
 
-* The *insort()* functions are ``O(n)`` because the logarithmic search step
+* The *insort()* functions are *O*\ (*n*) because the logarithmic search step
   is dominated by the linear time insertion step.
 
 * The search functions are stateless and discard key function results after

Doc/library/collections.rst

@@ -458,10 +458,10 @@ or subtracting from an empty counter.
     Deques are a generalization of stacks and queues (the name is pronounced "deck"
     and is short for "double-ended queue").  Deques support thread-safe, memory
     efficient appends and pops from either side of the deque with approximately the
-    same O(1) performance in either direction.
+    same *O*\ (1) performance in either direction.
 
     Though :class:`list` objects support similar operations, they are optimized for
-    fast fixed-length operations and incur O(n) memory movement costs for
+    fast fixed-length operations and incur *O*\ (*n*) memory movement costs for
     ``pop(0)`` and ``insert(0, v)`` operations which change both the size and
     position of the underlying data representation.
 
@@ -585,7 +585,7 @@ or subtracting from an empty counter.
 In addition to the above, deques support iteration, pickling, ``len(d)``,
 ``reversed(d)``, ``copy.copy(d)``, ``copy.deepcopy(d)``, membership testing with
 the :keyword:`in` operator, and subscript references such as ``d[0]`` to access
-the first element.  Indexed access is O(1) at both ends but slows to O(n) in
+the first element.  Indexed access is *O*\ (1) at both ends but slows to *O*\ (*n*) in
 the middle.  For fast random access, use lists instead.
 
 Starting in version 3.5, deques support ``__add__()``, ``__mul__()``,