Merge branch 'main' into pythongh-105793-is-dir-follow-symlinks

.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/get-changed-files@v2.2.0
       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

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

Doc/data/refcounts.dat

@@ -974,6 +974,9 @@ PyCoro_New:PyFrameObject*:frame:0:
 PyCoro_New:PyObject*:name:0:
 PyCoro_New:PyObject*:qualname:0:
 
+PyImport_AddModuleRef:PyObject*::+1:
+PyImport_AddModuleRef:const char*:name::
+
 PyImport_AddModule:PyObject*::0:reference borrowed from sys.modules
 PyImport_AddModule:const char*:name::
 
@@ -1794,6 +1797,9 @@ PyObject_Size:PyObject*:o:0:
 PyObject_Str:PyObject*::+1:
 PyObject_Str:PyObject*:o:0:
 
+Py_TYPE:PyObject*::0:
+Py_TYPE:PyObject*:ob:0:
+
 PyObject_Type:PyObject*::+1:
 PyObject_Type:PyObject*:o:0:
 
@@ -2807,6 +2813,10 @@ PyWeakref_GET_OBJECT:PyObject*:ref:0:
 PyWeakref_GetObject:PyObject*::0:
 PyWeakref_GetObject:PyObject*:ref:0:
 
+PyWeakref_GetRef:int:::
+PyWeakref_GetRef:PyObject*:ref:0:
+PyWeakref_GetRef:PyObject**:pobj:+1:
+
 PyWeakref_NewProxy:PyObject*::+1:
 PyWeakref_NewProxy:PyObject*:ob:0:
 PyWeakref_NewProxy:PyObject*:callback:0:

Doc/library/exceptions.rst

@@ -912,10 +912,11 @@ their subgroups based on the types of the contained exceptions.
       Returns an exception group that contains only the exceptions from the
       current group that match *condition*, or ``None`` if the result is empty.
 
-      The condition can be either a function that accepts an exception and returns
-      true for those that should be in the subgroup, or it can be an exception type
-      or a tuple of exception types, which is used to check for a match using the
-      same check that is used in an ``except`` clause.
+      The condition can be an exception type or tuple of exception types, in which
+      case each exception is checked for a match using the same check that is used
+      in an ``except`` clause.  The condition can also be a callable (other than
+      a type object) that accepts an exception as its single argument and returns
+      true for the exceptions that should be in the subgroup.
 
       The nesting structure of the current exception is preserved in the result,
       as are the values of its :attr:`message`, :attr:`__traceback__`,
@@ -926,6 +927,9 @@ their subgroups based on the types of the contained exceptions.
       including the top-level and any nested exception groups. If the condition is
       true for such an exception group, it is included in the result in full.
 
+      .. versionadded:: 3.13
+         ``condition`` can be any callable which is not a type object.
+
    .. method:: split(condition)
 
       Like :meth:`subgroup`, but returns the pair ``(match, rest)`` where ``match``