Merge branch 'main' into isolate-decimal-part1

.gitattributes

@@ -86,6 +86,7 @@ Parser/token.c                                      generated
 Programs/test_frozenmain.h                          generated
 Python/Python-ast.c                                 generated
 Python/generated_cases.c.h                          generated
+Python/executor_cases.c.h                           generated
 Python/opcode_targets.h                             generated
 Python/stdlib_module_names.h                        generated
 Tools/peg_generator/pegen/grammar_parser.py         generated

.github/workflows/build.yml

@@ -87,21 +87,9 @@ jobs:
         with:
           filter: |
             Doc/**
-            # Temporarily skip paths with spaces
-            # (i.e. "C API", "Core and Builtins")
-            # to avoid "Error: One of your files includes a space".
-            # Pending https://github.com/python/core-workflow/issues/186
-            # Misc/**
-            Misc/NEWS.d/next/Build/**
-            Misc/NEWS.d/next/Documentation/**
-            Misc/NEWS.d/next/IDLE/**
-            Misc/NEWS.d/next/Library/**
-            Misc/NEWS.d/next/Security/**
-            Misc/NEWS.d/next/Tests/**
-            Misc/NEWS.d/next/Tools-Demos/**
-            Misc/NEWS.d/next/Windows/**
-            Misc/NEWS.d/next/macOS/**
+            Misc/**
             .github/workflows/reusable-docs.yml
+          format: csv  # works for paths with spaces
       - name: Check for docs changes
         if: >-
           github.event_name == 'pull_request'

.github/workflows/reusable-docs.yml

@@ -38,12 +38,14 @@ jobs:
       uses: Ana06/[email protected]
       with:
         filter: "Doc/**"
+        format: csv  # works for paths with spaces
     - name: 'Build changed files in nit-picky mode'
       if: github.event_name == 'pull_request'
       continue-on-error: true
       run: |
+        set -Eeuo pipefail
         # Mark files the pull request modified
-        touch ${{ steps.changed_files.outputs.added_modified }}
+        python Doc/tools/touch-clean-files.py --clean '${{ steps.changed_files.outputs.added_modified }}'
         # Build docs with the '-n' (nit-picky) option; convert warnings to annotations
         make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n --keep-going" html 2>&1 |
             python Doc/tools/warnings-to-gh-actions.py

.pre-commit-config.yaml

@@ -3,6 +3,9 @@ repos:
     rev: v4.4.0
     hooks:
       - id: check-yaml
+      - id: end-of-file-fixer
+        types: [python]
+        exclude: Lib/test/coding20731.py
       - id: trailing-whitespace
         types_or: [c, python, rst]
 

Doc/c-api/bool.rst

@@ -6,7 +6,7 @@ Boolean Objects
 ---------------
 
 Booleans in Python are implemented as a subclass of integers.  There are only
-two booleans, :const:`Py_False` and :const:`Py_True`.  As such, the normal
+two booleans, :c:data:`Py_False` and :c:data:`Py_True`.  As such, the normal
 creation and deletion functions don't apply to booleans.  The following macros
 are available, however.
 
@@ -19,29 +19,32 @@ are available, however.
 
 .. c:var:: PyObject* Py_False
 
-   The Python ``False`` object.  This object has no methods.  It needs to be
-   treated just like any other object with respect to reference counts.
+   The Python ``False`` object.  This object has no methods and is
+   `immortal <https://peps.python.org/pep-0683/>`_.
+
+.. versionchanged:: 3.12
+   :c:data:`Py_False` is immortal.
 
 
 .. c:var:: PyObject* Py_True
 
-   The Python ``True`` object.  This object has no methods.  It needs to be treated
-   just like any other object with respect to reference counts.
+   The Python ``True`` object.  This object has no methods and is
+   `immortal <https://peps.python.org/pep-0683/>`_.
+
+.. versionchanged:: 3.12
+   :c:data:`Py_True` is immortal.
 
 
 .. c:macro:: Py_RETURN_FALSE
 
-   Return :const:`Py_False` from a function, properly incrementing its reference
-   count.
+   Return :c:data:`Py_False` from a function.
 
 
 .. c:macro:: Py_RETURN_TRUE
 
-   Return :const:`Py_True` from a function, properly incrementing its reference
-   count.
+   Return :c:data:`Py_True` from a function.
 
 
 .. c:function:: PyObject* PyBool_FromLong(long v)
 
-   Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
-   truth value of *v*.
+   Return :c:data:`Py_True` or :c:data:`Py_False`, depending on the truth value of *v*.

Doc/c-api/dict.rst

@@ -98,9 +98,11 @@ Dictionary Objects
    Return the object from dictionary *p* which has a key *key*.  Return ``NULL``
    if the key *key* is not present, but *without* setting an exception.
 
-   Note that exceptions which occur while calling :meth:`__hash__` and
-   :meth:`__eq__` methods will get suppressed.
-   To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
+   .. note::
+
+      Exceptions that occur while this calls :meth:`~object.__hash__` and
+      :meth:`~object.__eq__` methods are silently ignored.
+      Prefer the :c:func:`PyDict_GetItemWithError` function instead.
 
    .. versionchanged:: 3.10
       Calling this API without :term:`GIL` held had been allowed for historical
@@ -120,10 +122,13 @@ Dictionary Objects
    This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
    :c:expr:`const char*`, rather than a :c:expr:`PyObject*`.
 
-   Note that exceptions which occur while calling :meth:`__hash__` and
-   :meth:`__eq__` methods and creating a temporary string object
-   will get suppressed.
-   To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
+   .. note::
+
+      Exceptions that occur while this calls :meth:`~object.__hash__` and
+      :meth:`~object.__eq__` methods or while creating the temporary :class:`str`
+      object are silently ignored.
+      Prefer using the :c:func:`PyDict_GetItemWithError` function with your own
+      :c:func:`PyUnicode_FromString` *key* instead.
 
 
 .. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)

Doc/c-api/import.rst

@@ -98,27 +98,40 @@ Importing Modules
    an exception set on failure (the module still exists in this case).
 
 
-.. c:function:: PyObject* PyImport_AddModuleObject(PyObject *name)
+.. c:function:: PyObject* PyImport_AddModuleRef(const char *name)
+
+   Return the module object corresponding to a module name.
+
+   The *name* argument may be of the form ``package.module``. First check the
+   modules dictionary if there's one there, and if not, create a new one and
+   insert it in the modules dictionary.
+
+   Return a :term:`strong reference` to the module on success. Return ``NULL``
+   with an exception set on failure.
 
-   Return the module object corresponding to a module name.  The *name* argument
-   may be of the form ``package.module``. First check the modules dictionary if
-   there's one there, and if not, create a new one and insert it in the modules
-   dictionary. Return ``NULL`` with an exception set on failure.
+   The module name *name* is decoded from UTF-8.
 
-   .. note::
+   This function does not load or import the module; if the module wasn't
+   already loaded, you will get an empty module object. Use
+   :c:func:`PyImport_ImportModule` or one of its variants to import a module.
+   Package structures implied by a dotted name for *name* are not created if
+   not already present.
+
+   .. versionadded:: 3.13
+
+
+.. c:function:: PyObject* PyImport_AddModuleObject(PyObject *name)
 
-      This function does not load or import the module; if the module wasn't already
-      loaded, you will get an empty module object. Use :c:func:`PyImport_ImportModule`
-      or one of its variants to import a module.  Package structures implied by a
-      dotted name for *name* are not created if not already present.
+   Similar to :c:func:`PyImport_AddModuleRef`, but return a :term:`borrowed
+   reference` and *name* is a Python :class:`str` object.
 
    .. versionadded:: 3.3
 
 
 .. c:function:: PyObject* PyImport_AddModule(const char *name)
 
-   Similar to :c:func:`PyImport_AddModuleObject`, but the name is a UTF-8
-   encoded string instead of a Unicode object.
+   Similar to :c:func:`PyImport_AddModuleRef`, but return a :term:`borrowed
+   reference`.
 
 
 .. c:function:: PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co)

Doc/c-api/list.rst

@@ -86,6 +86,10 @@ List Objects
    Macro form of :c:func:`PyList_SetItem` without error checking. This is
    normally only used to fill in new lists where there is no previous content.
 
+   Bounds checking is performed as an assertion if Python is built in
+   :ref:`debug mode <debug-build>` or :option:`with assertions
+   <--with-assertions>`.
+
    .. note::
 
       This macro "steals" a reference to *item*, and, unlike

Doc/c-api/none.rst

@@ -15,12 +15,12 @@ same reason.
 
 .. c:var:: PyObject* Py_None
 
-   The Python ``None`` object, denoting lack of value.  This object has no methods.
-   It needs to be treated just like any other object with respect to reference
-   counts.
+   The Python ``None`` object, denoting lack of value.  This object has no methods
+   and is `immortal <https://peps.python.org/pep-0683/>`_.
 
+.. versionchanged:: 3.12
+   :c:data:`Py_None` is immortal.
 
 .. c:macro:: Py_RETURN_NONE
 
-   Properly handle returning :c:data:`Py_None` from within a C function (that is,
-   increment the reference count of ``None`` and return it.)
+   Return :c:data:`Py_None` from a function.

Doc/c-api/object.rst

@@ -33,9 +33,11 @@ Object Protocol
    is equivalent to the Python expression ``hasattr(o, attr_name)``.  This function
    always succeeds.
 
-   Note that exceptions which occur while calling :meth:`__getattr__` and
-   :meth:`__getattribute__` methods will get suppressed.
-   To get error reporting use :c:func:`PyObject_GetAttr()` instead.
+   .. note::
+
+      Exceptions that occur when this calls :meth:`~object.__getattr__` and
+      :meth:`~object.__getattribute__` methods are silently ignored.
+      For proper error handling, use :c:func:`PyObject_GetAttr` instead.
 
 
 .. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
@@ -44,10 +46,12 @@ Object Protocol
    is equivalent to the Python expression ``hasattr(o, attr_name)``.  This function
    always succeeds.
 
-   Note that exceptions which occur while calling :meth:`__getattr__` and
-   :meth:`__getattribute__` methods and creating a temporary string object
-   will get suppressed.
-   To get error reporting use :c:func:`PyObject_GetAttrString()` instead.
+   .. note::
+
+      Exceptions that occur when this calls :meth:`~object.__getattr__` and
+      :meth:`~object.__getattribute__` methods or while creating the temporary :class:`str`
+      object are silently ignored.
+      For proper error handling, use :c:func:`PyObject_GetAttrString` instead.
 
 
 .. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)

Doc/c-api/slice.rst

@@ -118,6 +118,9 @@ Ellipsis Object
 
 .. c:var:: PyObject *Py_Ellipsis
 
-   The Python ``Ellipsis`` object.  This object has no methods.  It needs to be
-   treated just like any other object with respect to reference counts.  Like
-   :c:data:`Py_None` it is a singleton object.
+   The Python ``Ellipsis`` object.  This object has no methods.  Like
+   :c:data:`Py_None`, it is an `immortal <https://peps.python.org/pep-0683/>`_.
+   singleton object.
+
+   .. versionchanged:: 3.12
+      :c:data:`Py_Ellipsis` is immortal.

Doc/c-api/tuple.rst

@@ -89,6 +89,9 @@ Tuple Objects
    Like :c:func:`PyTuple_SetItem`, but does no error checking, and should *only* be
    used to fill in brand new tuples.
 
+   Bounds checking is performed as an assertion if Python is built in
+   :ref:`debug mode <debug-build>` or :option:`with assertions <--with-assertions>`.
+
    .. note::
 
       This function "steals" a reference to *o*, and, unlike
@@ -194,12 +197,17 @@ type.
 .. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
 
    Return the object at position *pos* in the struct sequence pointed to by *p*.
-   No bounds checking is performed.
+
+   Bounds checking is performed as an assertion if Python is built in
+   :ref:`debug mode <debug-build>` or :option:`with assertions <--with-assertions>`.
 
 
 .. c:function:: PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)
 
-   Macro equivalent of :c:func:`PyStructSequence_GetItem`.
+   Alias to :c:func:`PyStructSequence_GetItem`.
+
+   .. versionchanged:: 3.13
+      Now implemented as an alias to :c:func:`PyStructSequence_GetItem`.
 
 
 .. c:function:: void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
@@ -208,16 +216,17 @@ type.
    :c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand new
    instances.
 
+   Bounds checking is performed as an assertion if Python is built in
+   :ref:`debug mode <debug-build>` or :option:`with assertions <--with-assertions>`.
+
    .. note::
 
       This function "steals" a reference to *o*.
 
 
 .. c:function:: void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)
 
-   Similar to :c:func:`PyStructSequence_SetItem`, but implemented as a static
-   inlined function.
+   Alias to :c:func:`PyStructSequence_SetItem`.
 
-   .. note::
-
-      This function "steals" a reference to *o*.
+   .. versionchanged:: 3.13
+      Now implemented as an alias to :c:func:`PyStructSequence_SetItem`.

Doc/c-api/weakref.rst

@@ -11,20 +11,20 @@ simple reference object, and the second acts as a proxy for the original object
 as much as it can.
 
 
-.. c:function:: int PyWeakref_Check(ob)
+.. c:function:: int PyWeakref_Check(PyObject *ob)
 
-   Return true if *ob* is either a reference or proxy object.  This function
+   Return non-zero if *ob* is either a reference or proxy object.  This function
    always succeeds.
 
 
-.. c:function:: int PyWeakref_CheckRef(ob)
+.. c:function:: int PyWeakref_CheckRef(PyObject *ob)
 
-   Return true if *ob* is a reference object.  This function always succeeds.
+   Return non-zero if *ob* is a reference object.  This function always succeeds.
 
 
-.. c:function:: int PyWeakref_CheckProxy(ob)
+.. c:function:: int PyWeakref_CheckProxy(PyObject *ob)
 
-   Return true if *ob* is a proxy object.  This function always succeeds.
+   Return non-zero if *ob* is a proxy object.  This function always succeeds.
 
 
 .. c:function:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)
@@ -51,10 +51,21 @@ as much as it can.
    ``None``, or ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`.
 
 
+.. c:function:: int PyWeakref_GetRef(PyObject *ref, PyObject **pobj)
+
+   Get a :term:`strong reference` to the referenced object from a weak
+   reference, *ref*, into *\*pobj*.
+   Return 0 on success. Raise an exception and return -1 on error.
+
+   If the referent is no longer live, set *\*pobj* to ``NULL`` and return 0.
+
+   .. versionadded:: 3.13
+
+
 .. c:function:: PyObject* PyWeakref_GetObject(PyObject *ref)
 
-   Return the referenced object from a weak reference, *ref*.  If the referent is
-   no longer live, returns :const:`Py_None`.
+   Return a :term:`borrowed reference` to the referenced object from a weak
+   reference, *ref*.  If the referent is no longer live, returns ``Py_None``.
 
    .. note::
 
@@ -63,11 +74,17 @@ as much as it can.
       except when it cannot be destroyed before the last usage of the borrowed
       reference.
 
+   .. deprecated-removed:: 3.13 3.15
+      Use :c:func:`PyWeakref_GetRef` instead.
+
 
 .. c:function:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)
 
    Similar to :c:func:`PyWeakref_GetObject`, but does no error checking.
 
+   .. deprecated-removed:: 3.13 3.15
+      Use :c:func:`PyWeakref_GetRef` instead.
+
 
 .. c:function:: void PyObject_ClearWeakRefs(PyObject *object)