Merge branch 'main' into bitfields

.github/CODEOWNERS

@@ -4,6 +4,9 @@
 # It uses the same pattern rule for gitignore file
 # https://git-scm.com/docs/gitignore#_pattern_format
 
+# GitHub
+.github/**                    @ezio-melotti
+
 # asyncio
 **/*asyncio*                  @1st1 @asvetlov @gvanrossum
 

.github/CONTRIBUTING.rst

@@ -38,7 +38,7 @@ also suggestions on how you can most effectively help the project.
 
 Please be aware that our workflow does deviate slightly from the typical GitHub
 project. Details on how to properly submit a pull request are covered in
-`Lifecycle of a Pull Request <https://devguide.python.org/pullrequest/>`_.
+`Lifecycle of a Pull Request <https://devguide.python.org/getting-started/pull-request-lifecycle.html>`_.
 We utilize various bots and status checks to help with this, so do follow the
 comments they leave and their "Details" links, respectively. The key points of
 our workflow that are not covered by a bot or status check are:

.github/workflows/build.yml

@@ -25,6 +25,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
   check_source:
     name: 'Check for source changes'

.github/workflows/build_msi.yml

@@ -18,6 +18,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
   build:
     name: Windows Installer

.github/workflows/doc.yml

@@ -28,6 +28,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
   build_doc:
     name: 'Docs'

.github/workflows/project-updater.yml

@@ -6,6 +6,9 @@ on:
       - opened
       - labeled
 
+permissions:
+  contents: read
+
 jobs:
   add-to-project:
     name: Add issues to projects

.github/workflows/verify-ensurepip-wheels.yml

@@ -16,6 +16,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
   verify:
     runs-on: ubuntu-latest

Doc/c-api/buffer.rst

@@ -99,7 +99,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
       For :term:`contiguous` arrays, the value points to the beginning of
       the memory block.
 
-   .. c:member:: void *obj
+   .. c:member:: PyObject *obj
 
       A new reference to the exporting object. The reference is owned by
       the consumer and automatically decremented and set to ``NULL`` by

Doc/c-api/memoryview.rst

@@ -55,7 +55,7 @@ any other object.
    *mview* **must** be a memoryview instance; this macro doesn't check its type,
    you must do it yourself or you will risk crashes.
 
-.. c:function:: Py_buffer *PyMemoryView_GET_BASE(PyObject *mview)
+.. c:function:: PyObject *PyMemoryView_GET_BASE(PyObject *mview)
 
    Return either a pointer to the exporting object that the memoryview is based
    on or ``NULL`` if the memoryview has been created by one of the functions

Doc/howto/descriptor.rst

@@ -847,7 +847,7 @@ afterwards, :meth:`__set_name__` will need to be called manually.
 ORM example
 -----------
 
-The following code is simplified skeleton showing how data descriptors could
+The following code is a simplified skeleton showing how data descriptors could
 be used to implement an `object relational mapping
 <https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping>`_.
 
@@ -1535,6 +1535,8 @@ by member descriptors:
         def __get__(self, obj, objtype=None):
             'Emulate member_get() in Objects/descrobject.c'
             # Also see PyMember_GetOne() in Python/structmember.c
+            if obj is None:
+                return self
             value = obj._slotvalues[self.offset]
             if value is null:
                 raise AttributeError(self.name)
@@ -1563,13 +1565,13 @@ variables:
     class Type(type):
         'Simulate how the type metaclass adds member objects for slots'
 
-        def __new__(mcls, clsname, bases, mapping):
+        def __new__(mcls, clsname, bases, mapping, **kwargs):
             'Emulate type_new() in Objects/typeobject.c'
             # type_new() calls PyTypeReady() which calls add_methods()
             slot_names = mapping.get('slot_names', [])
             for offset, name in enumerate(slot_names):
                 mapping[name] = Member(name, clsname, offset)
-            return type.__new__(mcls, clsname, bases, mapping)
+            return type.__new__(mcls, clsname, bases, mapping, **kwargs)
 
 The :meth:`object.__new__` method takes care of creating instances that have
 slots instead of an instance dictionary.  Here is a rough simulation in pure
@@ -1580,7 +1582,7 @@ Python:
     class Object:
         'Simulate how object.__new__() allocates memory for __slots__'
 
-        def __new__(cls, *args):
+        def __new__(cls, *args, **kwargs):
             'Emulate object_new() in Objects/typeobject.c'
             inst = super().__new__(cls)
             if hasattr(cls, 'slot_names'):
@@ -1593,7 +1595,7 @@ Python:
             cls = type(self)
             if hasattr(cls, 'slot_names') and name not in cls.slot_names:
                 raise AttributeError(
-                    f'{type(self).__name__!r} object has no attribute {name!r}'
+                    f'{cls.__name__!r} object has no attribute {name!r}'
                 )
             super().__setattr__(name, value)
 
@@ -1602,7 +1604,7 @@ Python:
             cls = type(self)
             if hasattr(cls, 'slot_names') and name not in cls.slot_names:
                 raise AttributeError(
-                    f'{type(self).__name__!r} object has no attribute {name!r}'
+                    f'{cls.__name__!r} object has no attribute {name!r}'
                 )
             super().__delattr__(name)
 

Doc/library/copyreg.rst

@@ -25,20 +25,17 @@ Such constructors may be factory functions or class instances.
    hence not valid as a constructor), raises :exc:`TypeError`.
 
 
-.. function:: pickle(type, function, constructor=None)
+.. function:: pickle(type, function, constructor_ob=None)
 
    Declares that *function* should be used as a "reduction" function for objects
    of type *type*.  *function* should return either a string or a tuple
-   containing two or three elements.
+   containing two or three elements. See the :attr:`~pickle.Pickler.dispatch_table`
+   for more details on the interface of *function*.
 
-   The optional *constructor* parameter, if provided, is a callable object which
-   can be used to reconstruct the object when called with the tuple of arguments
-   returned by *function* at pickling time.  A :exc:`TypeError` is raised if the
-   *constructor* is not callable.
+   The *constructor_ob* parameter is a legacy feature and is now ignored, but if
+   passed it must be a callable.
 
-   See the :mod:`pickle` module for more details on the interface
-   expected of *function* and *constructor*.  Note that the
-   :attr:`~pickle.Pickler.dispatch_table` attribute of a pickler
+   Note that the :attr:`~pickle.Pickler.dispatch_table` attribute of a pickler
    object or subclass of :class:`pickle.Pickler` can also be used for
    declaring reduction functions.
 

Doc/library/http.server.rst

@@ -392,8 +392,8 @@ provides three different variants:
       contents of the file are output. If the file's MIME type starts with
       ``text/`` the file is opened in text mode; otherwise binary mode is used.
 
-      For example usage, see the implementation of the :func:`test` function
-      invocation in the :mod:`http.server` module.
+      For example usage, see the implementation of the ``test`` function
+      in :source:`Lib/http/server.py`.
 
       .. versionchanged:: 3.7
          Support of the ``'If-Modified-Since'`` header.

Doc/library/os.rst

@@ -304,8 +304,8 @@ process and user.
 
 .. function:: getenv(key, default=None)
 
-   Return the value of the environment variable *key* if it exists, or
-   *default* if it doesn't. *key*, *default* and the result are str. Note that
+   Return the value of the environment variable *key* as a string if it exists, or
+   *default* if it doesn't. *key* is a string. Note that
    since :func:`getenv` uses :data:`os.environ`, the mapping of :func:`getenv` is
    similarly also captured on import, and the function may not reflect
    future environment changes.
@@ -319,8 +319,8 @@ process and user.
 
 .. function:: getenvb(key, default=None)
 
-   Return the value of the environment variable *key* if it exists, or
-   *default* if it doesn't. *key*, *default* and the result are bytes. Note that
+   Return the value of the environment variable *key* as bytes if it exists, or
+   *default* if it doesn't. *key* must be bytes. Note that
    since :func:`getenvb` uses :data:`os.environb`, the mapping of :func:`getenvb` is
    similarly also captured on import, and the function may not reflect
    future environment changes.

Doc/library/venv.rst

@@ -85,6 +85,19 @@ Creating virtual environments
    without there needing to be any reference to its virtual environment in
    ``PATH``.
 
+.. warning:: Because scripts installed in environments should not expect the
+   environment to be activated, their shebang lines contain the absolute paths
+   to their environment's interpreters. Because of this, environments are
+   inherently non-portable, in the general case. You should always have a
+   simple means of recreating an environment (for example, if you have a
+   requirements file ``requirements.txt``, you can invoke ``pip install -r
+   requirements.txt`` using the environment's ``pip`` to install all of the
+   packages needed by the environment). If for any reason you need to move the
+   environment to a new location, you should recreate it at the desired
+   location and delete the one at the old location. If you move an environment
+   because you moved a parent directory of it, you should recreate the
+   environment in its new location. Otherwise, software installed into the
+   environment may not work as expected.
 
 .. _venv-api:
 

Doc/library/xml.sax.utils.rst

@@ -25,6 +25,11 @@ or as base classes.
    replaced with its corresponding value.  The characters ``'&'``, ``'<'`` and
    ``'>'`` are always escaped, even if *entities* is provided.
 
+   .. note::
+
+      This function should only be used to escape characters that
+      can't be used directly in XML. Do not use this function as a general
+      string translation function.
 
 .. function:: unescape(data, entities={})
 

Doc/license.rst

@@ -302,7 +302,8 @@ for third-party software incorporated in the Python distribution.
 Mersenne Twister
 ----------------
 
-The :mod:`_random` module includes code based on a download from
+The :mod:`!_random` C extension underlying the :mod:`random` module
+includes code based on a download from
 http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/emt19937ar.html. The following are
 the verbatim comments from the original code::
 
@@ -819,7 +820,8 @@ sources unless the build is configured ``--with-system-expat``::
 libffi
 ------
 
-The :mod:`_ctypes` extension is built using an included copy of the libffi
+The :mod:`!_ctypes` C extension underlying the :mod:`ctypes` module
+is built using an included copy of the libffi
 sources unless the build is configured ``--with-system-libffi``::
 
    Copyright (c) 1996-2008  Red Hat, Inc and others.
@@ -920,7 +922,8 @@ on the cfuhash project::
 libmpdec
 --------
 
-The :mod:`_decimal` module is built using an included copy of the libmpdec
+The :mod:`!_decimal` C extension underlying the :mod:`decimal` module
+is built using an included copy of the libmpdec
 library unless the build is configured ``--with-system-libmpdec``::
 
    Copyright (c) 2008-2020 Stefan Krah. All rights reserved.

Doc/reference/expressions.rst

@@ -1741,6 +1741,12 @@ returns a boolean value regardless of the type of its argument
 (for example, ``not 'foo'`` produces ``False`` rather than ``''``.)
 
 
+.. index::
+   single: := (colon equals)
+   single: assignment expression
+   single: walrus operator
+   single: named expression
+
 Assignment expressions
 ======================
 

Doc/tutorial/introduction.rst

@@ -70,8 +70,8 @@ the ones with a fractional part (e.g. ``5.0``, ``1.6``) have type
 :class:`float`.  We will see more about numeric types later in the tutorial.
 
 Division (``/``) always returns a float.  To do :term:`floor division` and
-get an integer result (discarding any fractional result) you can use the ``//``
-operator; to calculate the remainder you can use ``%``::
+get an integer result you can use the ``//`` operator; to calculate
+the remainder you can use ``%``::
 
    >>> 17 / 3  # classic division returns a float
    5.666666666666667

Doc/whatsnew/3.12.rst

@@ -37,11 +37,11 @@
    * Credit the author of a patch or bugfix.   Just the name is
    sufficient; the e-mail address isn't necessary.
 
-   * It's helpful to add the bug/patch number as a comment:
+   * It's helpful to add the issue number as a comment:
 
    XXX Describe the transmogrify() function added to the socket
    module.
-   (Contributed by P.Y. Developer in :issue:`12345`.)
+   (Contributed by P.Y. Developer in :gh:`12345`.)
 
    This saves the maintainer the effort of going through the VCS log when
    researching a change.
@@ -93,6 +93,13 @@ Other Language Changes
   when parsing source code containing null bytes. (Contributed by Pablo Galindo
   in :gh:`96670`.)
 
+* The Garbage Collector now runs only on the eval breaker mechanism of the
+  Python bytecode evaluation loop instead on object allocations. The GC can
+  also run when :c:func:`PyErr_CheckSignals` is called so C extensions that
+  need to run for a long time without executing any Python code also have a
+  chance to execute the GC periodically. (Contributed by Pablo Galindo in
+  :gh:`97922`.)
+
 New Modules
 ===========
 
@@ -102,6 +109,24 @@ New Modules
 Improved Modules
 ================
 
+asyncio
+-------
+
+* On Linux, :mod:`asyncio` uses :class:`~asyncio.PidfdChildWatcher` by default
+  if :func:`os.pidfd_open` is available and functional instead of
+  :class:`~asyncio.ThreadedChildWatcher`.
+  (Contributed by Kumar Aditya in :gh:`98024`.)
+
+* The child watcher classes :class:`~asyncio.MultiLoopChildWatcher`,
+  :class:`~asyncio.FastChildWatcher` and
+  :class:`~asyncio.SafeChildWatcher` are deprecated and
+  will be removed in Python 3.14. It is recommended to not manually
+  configure a child watcher as the event loop now uses the best available
+  child watcher for each platform (:class:`~asyncio.PidfdChildWatcher`
+  if supported and :class:`~asyncio.ThreadedChildWatcher` otherwise).
+  (Contributed by Kumar Aditya in :gh:`94597`.)
+
+
 pathlib
 -------
 

Include/cpython/code.h

@@ -32,6 +32,13 @@ typedef uint16_t _Py_CODEUNIT;
 #define _Py_SET_OPCODE(word, opcode) \
     do { ((unsigned char *)&(word))[0] = (opcode); } while (0)
 
+typedef struct {
+    PyObject *_co_code;
+    PyObject *_co_varnames;
+    PyObject *_co_cellvars;
+    PyObject *_co_freevars;
+} _PyCoCached;
+
 // To avoid repeating ourselves in deepfreeze.py, all PyCodeObject members are
 // defined in this macro:
 #define _PyCode_DEF(SIZE) {                                                    \
@@ -90,7 +97,7 @@ typedef uint16_t _Py_CODEUNIT;
     PyObject *co_qualname;        /* unicode (qualname, for reference) */      \
     PyObject *co_linetable;       /* bytes object that holds location info */  \
     PyObject *co_weakreflist;     /* to support weakrefs to code objects */    \
-    PyObject *_co_code;           /* cached co_code object/attribute */        \
+    _PyCoCached *_co_cached;      /* cached co_* attributes */                 \
     int _co_firsttraceable;       /* index of first traceable instruction */   \
     char *_co_linearray;          /* array of line offsets */                  \
     /* Scratch space for extra data relating to the code object.               \

Include/internal/pycore_gc.h

@@ -202,6 +202,8 @@ extern void _PyList_ClearFreeList(PyInterpreterState *interp);
 extern void _PyDict_ClearFreeList(PyInterpreterState *interp);
 extern void _PyAsyncGen_ClearFreeLists(PyInterpreterState *interp);
 extern void _PyContext_ClearFreeList(PyInterpreterState *interp);
+extern void _Py_ScheduleGC(PyInterpreterState *interp);
+extern void _Py_RunGC(PyThreadState *tstate);
 
 #ifdef __cplusplus
 }