Catch up with main

Author: brandtbucher

.github/CODEOWNERS

@@ -135,7 +135,7 @@ Lib/ast.py                    @isidentical
 
 **/*idlelib*                  @terryjreedy
 
-**/*typing*                   @gvanrossum @Fidget-Spinner @JelleZijlstra
+**/*typing*                   @gvanrossum @Fidget-Spinner @JelleZijlstra @AlexWaygood
 
 **/*asyncore                  @giampaolo
 **/*asynchat                  @giampaolo

.github/CONTRIBUTING.rst

@@ -4,21 +4,9 @@ Contributing to Python
 Build Status
 ------------
 
-- main
+- `Buildbot status overview <https://buildbot.python.org/all/#/release_status>`_
 
-  + `Stable buildbots <https://buildbot.python.org/3.x.stable/>`_
-
-- 3.9
-
-  + `Stable buildbots <https://buildbot.python.org/3.9.stable/>`_
-
-- 3.8
-
-  + `Stable buildbots <https://buildbot.python.org/3.8.stable/>`_
-
-- 3.7
-
-  + `Stable buildbots <https://buildbot.python.org/3.7.stable/>`_
+- `GitHub Actions status <https://github.com/python/cpython/actions/workflows/build.yml>`_
 
 
 Thank You

.github/SECURITY.md

@@ -4,7 +4,7 @@
 
 The Python team applies security fixes according to the table
 in [the devguide](
-https://devguide.python.org/#status-of-python-branches
+https://devguide.python.org/versions/#supported-versions
 ).
 
 ## Reporting a Vulnerability

.github/workflows/build.yml

@@ -41,7 +41,7 @@ jobs:
         id: check
         run: |
           if [ -z "$GITHUB_BASE_REF" ]; then
-            echo '::set-output name=run_tests::true'
+            echo "run_tests=true" >> $GITHUB_OUTPUT
           else
             git fetch origin $GITHUB_BASE_REF --depth=1
             # git diff "origin/$GITHUB_BASE_REF..." (3 dots) may be more
@@ -57,7 +57,7 @@ jobs:
             # into the PR branch anyway.
             #
             # https://github.com/python/core-workflow/issues/373
-            git diff --name-only origin/$GITHUB_BASE_REF.. | grep -qvE '(\.rst$|^Doc|^Misc)' && echo '::set-output name=run_tests::true' || true
+            git diff --name-only origin/$GITHUB_BASE_REF.. | grep -qvE '(\.rst$|^Doc|^Misc)' && echo "run_tests=true" >> $GITHUB_OUTPUT || true
           fi
 
   check_generated_files:

Doc/c-api/init.rst

@@ -1933,7 +1933,7 @@ is not possible due to its implementation being opaque at build time.
 
    .. note::
       A freed key becomes a dangling pointer. You should reset the key to
-      `NULL`.
+      ``NULL``.
 
 
 Methods

Doc/c-api/init_config.rst

@@ -1571,8 +1571,6 @@ Private provisional API:
 
 * :c:member:`PyConfig._init_main`: if set to ``0``,
   :c:func:`Py_InitializeFromConfig` stops at the "Core" initialization phase.
-* :c:member:`PyConfig._isolated_interpreter`: if non-zero,
-  disallow threads, subprocesses and fork.
 
 .. c:function:: PyStatus _Py_InitializeMain(void)
 

Doc/c-api/structures.rst

@@ -387,27 +387,27 @@ Accessing attributes of extension types
    Structure which describes an attribute of a type which corresponds to a C
    struct member.  Its fields are:
 
-   +------------------+---------------+-------------------------------+
-   | Field            | C Type        | Meaning                       |
-   +==================+===============+===============================+
-   | :attr:`name`     | const char \* | name of the member            |
-   +------------------+---------------+-------------------------------+
-   | :attr:`!type`    | int           | the type of the member in the |
-   |                  |               | C struct                      |
-   +------------------+---------------+-------------------------------+
-   | :attr:`offset`   | Py_ssize_t    | the offset in bytes that the  |
-   |                  |               | member is located on the      |
-   |                  |               | type's object struct          |
-   +------------------+---------------+-------------------------------+
-   | :attr:`flags`    | int           | flag bits indicating if the   |
-   |                  |               | field should be read-only or  |
-   |                  |               | writable                      |
-   +------------------+---------------+-------------------------------+
-   | :attr:`doc`      | const char \* | points to the contents of the |
-   |                  |               | docstring                     |
-   +------------------+---------------+-------------------------------+
+   .. c:member:: const char* PyMemberDef.name
+
+         Name of the member
+
+   .. c:member:: int PyMemberDef.type
+
+      The type of the member in the C struct.
+
+   .. c:member:: Py_ssize_t PyMemberDef.offset
+
+      The offset in bytes that the member is located on the type’s object struct.
+
+   .. c:member:: int PyMemberDef.flags
+
+      Flag bits indicating if the field should be read-only or writable.
+
+   .. c:member:: const char* PyMemberDef.doc
+
+      Points to the contents of the docstring.
 
-   :attr:`!type` can be one of many ``T_`` macros corresponding to various C
+   :c:member:`PyMemberDef.type` can be one of many ``T_`` macros corresponding to various C
    types.  When the member is accessed in Python, it will be converted to the
    equivalent Python type.
 
@@ -441,7 +441,7 @@ Accessing attributes of extension types
    handles use of the :keyword:`del` statement on that attribute more correctly
    than :c:macro:`T_OBJECT`.
 
-   :attr:`flags` can be ``0`` for write and read access or :c:macro:`READONLY` for
+   :c:member:`PyMemberDef.flags` can be ``0`` for write and read access or :c:macro:`READONLY` for
    read-only access.  Using :c:macro:`T_STRING` for :attr:`type` implies
    :c:macro:`READONLY`.  :c:macro:`T_STRING` data is interpreted as UTF-8.
    Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`

Doc/c-api/tuple.rst

@@ -69,7 +69,7 @@ Tuple Objects
 
    Return the slice of the tuple pointed to by *p* between *low* and *high*,
    or ``NULL`` on failure.  This is the equivalent of the Python expression
-   ``p[low:high]``.  Indexing from the end of the list is not supported.
+   ``p[low:high]``.  Indexing from the end of the tuple is not supported.
 
 
 .. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

Doc/c-api/type.rst

@@ -57,6 +57,55 @@ Type Objects
    modification of the attributes or base classes of the type.
 
 
+.. c:function:: int PyType_AddWatcher(PyType_WatchCallback callback)
+
+   Register *callback* as a type watcher. Return a non-negative integer ID
+   which must be passed to future calls to :c:func:`PyType_Watch`. In case of
+   error (e.g. no more watcher IDs available), return ``-1`` and set an
+   exception.
+
+   .. versionadded:: 3.12
+
+
+.. c:function:: int PyType_ClearWatcher(int watcher_id)
+
+   Clear watcher identified by *watcher_id* (previously returned from
+   :c:func:`PyType_AddWatcher`). Return ``0`` on success, ``-1`` on error (e.g.
+   if *watcher_id* was never registered.)
+
+   An extension should never call ``PyType_ClearWatcher`` with a *watcher_id*
+   that was not returned to it by a previous call to
+   :c:func:`PyType_AddWatcher`.
+
+   .. versionadded:: 3.12
+
+
+.. c:function:: int PyType_Watch(int watcher_id, PyObject *type)
+
+   Mark *type* as watched. The callback granted *watcher_id* by
+   :c:func:`PyType_AddWatcher` will be called whenever
+   :c:func:`PyType_Modified` reports a change to *type*. (The callback may be
+   called only once for a series of consecutive modifications to *type*, if
+   :c:func:`PyType_Lookup` is not called on *type* between the modifications;
+   this is an implementation detail and subject to change.)
+
+   An extension should never call ``PyType_Watch`` with a *watcher_id* that was
+   not returned to it by a previous call to :c:func:`PyType_AddWatcher`.
+
+   .. versionadded:: 3.12
+
+
+.. c:type:: int (*PyType_WatchCallback)(PyObject *type)
+
+   Type of a type-watcher callback function.
+
+   The callback must not modify *type* or cause :c:func:`PyType_Modified` to be
+   called on *type* or any type in its MRO; violating this rule could cause
+   infinite recursion.
+
+   .. versionadded:: 3.12
+
+
 .. c:function:: int PyType_HasFeature(PyTypeObject *o, int feature)
 
    Return non-zero if the type object *o* sets the feature *feature*.

Doc/data/stable_abi.dat

@@ -298,16 +298,16 @@ be directly useful to you:
 
   .. code-block:: shell-session
 
-     $ /opt/bin/python3.4-config --cflags
-     -I/opt/include/python3.4m -I/opt/include/python3.4m -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes
+     $ /opt/bin/python3.11-config --cflags
+     -I/opt/include/python3.11 -I/opt/include/python3.11 -Wsign-compare  -DNDEBUG -g -fwrapv -O3 -Wall
 
-* ``pythonX.Y-config --ldflags`` will give you the recommended flags when
-  linking:
+* ``pythonX.Y-config --ldflags --embed`` will give you the recommended flags
+  when linking:
 
   .. code-block:: shell-session
 
-     $ /opt/bin/python3.4-config --ldflags
-     -L/opt/lib/python3.4/config-3.4m -lpthread -ldl -lutil -lm -lpython3.4m -Xlinker -export-dynamic
+     $ /opt/bin/python3.11-config --ldflags --embed
+     -L/opt/lib/python3.11/config-3.11-x86_64-linux-gnu -L/opt/lib -lpython3.11 -lpthread -ldl  -lutil -lm
 
 .. note::
    To avoid confusion between several Python installations (and especially

Doc/extending/embedding.rst

@@ -882,7 +882,7 @@ Glossary
 
    package
       A Python :term:`module` which can contain submodules or recursively,
-      subpackages.  Technically, a package is a Python module with an
+      subpackages.  Technically, a package is a Python module with a
       ``__path__`` attribute.
 
       See also :term:`regular package` and :term:`namespace package`.

Doc/glossary.rst

@@ -1,5 +1,7 @@
 .. highlight:: c
 
+.. _howto-clinic:
+
 **********************
 Argument Clinic How-To
 **********************

Doc/howto/clinic.rst

@@ -994,7 +994,7 @@ requesting iterator-2 and its corresponding key.
 The functools module
 ====================
 
-The :mod:`functools` module in Python 2.5 contains some higher-order functions.
+The :mod:`functools` module contains some higher-order functions.
 A **higher-order function** takes one or more functions as input and returns a
 new function.  The most useful tool in this module is the
 :func:`functools.partial` function.

Doc/howto/functional.rst

@@ -461,7 +461,7 @@ Module State Access from Slot Methods, Getters and Setters
 
    .. After adding to limited API:
 
-      If you use the `limited API <https://docs.python.org/3/c-api/stable.html>__,
+      If you use the :ref:`limited API <stable>,
       you must update ``Py_LIMITED_API`` to ``0x030b0000``, losing ABI
       compatibility with earlier versions.
 

Doc/howto/isolating-extensions.rst

@@ -3712,6 +3712,71 @@ Of course, the examples above show output according to the format used by
 :func:`~logging.basicConfig`, but you can use a different formatter when you
 configure logging.
 
+Note that with the above scheme, you are somewhat at the mercy of buffering and
+the sequence of write calls which you are intercepting. For example, with the
+definition of ``LoggerWriter`` above, if you have the snippet
+
+.. code-block:: python
+
+    sys.stderr = LoggerWriter(logger, logging.WARNING)
+    1 / 0
+
+then running the script results in
+
+.. code-block:: text
+
+    WARNING:demo:Traceback (most recent call last):
+
+    WARNING:demo:  File "/home/runner/cookbook-loggerwriter/test.py", line 53, in <module>
+
+    WARNING:demo:
+    WARNING:demo:main()
+    WARNING:demo:  File "/home/runner/cookbook-loggerwriter/test.py", line 49, in main
+
+    WARNING:demo:
+    WARNING:demo:1 / 0
+    WARNING:demo:ZeroDivisionError
+    WARNING:demo::
+    WARNING:demo:division by zero
+
+As you can see, this output isn't ideal. That's because the underlying code
+which writes to ``sys.stderr`` makes mutiple writes, each of which results in a
+separate logged line (for example, the last three lines above). To get around
+this problem, you need to buffer things and only output log lines when newlines
+are seen. Let's use a slghtly better implementation of ``LoggerWriter``:
+
+.. code-block:: python
+
+    class BufferingLoggerWriter(LoggerWriter):
+        def __init__(self, logger, level):
+            super().__init__(logger, level)
+            self.buffer = ''
+
+        def write(self, message):
+            if '\n' not in message:
+                self.buffer += message
+            else:
+                parts = message.split('\n')
+                if self.buffer:
+                    s = self.buffer + parts.pop(0)
+                    self.logger.log(self.level, s)
+                self.buffer = parts.pop()
+                for part in parts:
+                    self.logger.log(self.level, part)
+
+This just buffers up stuff until a newline is seen, and then logs complete
+lines. With this approach, you get better output:
+
+.. code-block:: text
+
+    WARNING:demo:Traceback (most recent call last):
+    WARNING:demo:  File "/home/runner/cookbook-loggerwriter/main.py", line 55, in <module>
+    WARNING:demo:    main()
+    WARNING:demo:  File "/home/runner/cookbook-loggerwriter/main.py", line 52, in main
+    WARNING:demo:    1/0
+    WARNING:demo:ZeroDivisionError: division by zero
+
+
 .. patterns-to-avoid:
 
 Patterns to avoid