Merge main.

.github/workflows/reusable-change-detection.yml

@@ -1,6 +1,4 @@
----
-
-name: Change detection
+name: Reusable change detection
 
 on:  # yamllint disable-line rule:truthy
   workflow_call:

.github/workflows/reusable-docs.yml

@@ -1,4 +1,4 @@
-name: Docs
+name: Reusable Docs
 
 on:
   workflow_call:
@@ -95,7 +95,7 @@ jobs:
   # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
   doctest:
     name: 'Doctest'
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     timeout-minutes: 60
     steps:
     - uses: actions/checkout@v4

.github/workflows/reusable-macos.yml

@@ -1,3 +1,5 @@
+name: Reusable macOS
+
 on:
   workflow_call:
     inputs:

.github/workflows/reusable-tsan.yml

@@ -1,3 +1,5 @@
+name: Reusable Thread Sanitizer
+
 on:
   workflow_call:
     inputs:

.github/workflows/reusable-ubuntu.yml

@@ -1,3 +1,5 @@
+name: Reusable Ubuntu
+
 on:
   workflow_call:
     inputs:

.github/workflows/reusable-wasi.yml

@@ -1,3 +1,5 @@
+name: Reusable WASI
+
 on:
   workflow_call:
     inputs:

.github/workflows/reusable-windows-msi.yml

@@ -1,4 +1,4 @@
-name: TestsMSI
+name: Reusable Windows MSI
 
 on:
   workflow_call:

.github/workflows/reusable-windows.yml

@@ -1,3 +1,5 @@
+name: Reusable Windows
+
 on:
   workflow_call:
     inputs:

Doc/c-api/contextvars.rst

@@ -122,18 +122,24 @@ Context object management functions:
 .. c:type:: PyContextEvent
 
    Enumeration of possible context object watcher events:
-   - ``Py_CONTEXT_EVENT_ENTER``
-   - ``Py_CONTEXT_EVENT_EXIT``
+
+   - ``Py_CONTEXT_EVENT_ENTER``: A context has been entered, causing the
+     :term:`current context` to switch to it.  The object passed to the watch
+     callback is the now-current :class:`contextvars.Context` object.  Each
+     enter event will eventually have a corresponding exit event for the same
+     context object after any subsequently entered contexts have themselves been
+     exited.
+   - ``Py_CONTEXT_EVENT_EXIT``: A context is about to be exited, which will
+     cause the :term:`current context` to switch back to what it was before the
+     context was entered.  The object passed to the watch callback is the
+     still-current :class:`contextvars.Context` object.
 
    .. versionadded:: 3.14
 
 .. c:type:: int (*PyContext_WatchCallback)(PyContextEvent event, PyContext* ctx)
 
-   Type of a context object watcher callback function.
-   If *event* is ``Py_CONTEXT_EVENT_ENTER``, then the callback is invoked
-   after *ctx* has been set as the current context for the current thread.
-   Otherwise, the callback is invoked before the deactivation of *ctx* as the current context
-   and the restoration of the previous contex object for the current thread.
+   Context object watcher callback function.  The object passed to the callback
+   is event-specific; see :c:type:`PyContextEvent` for details.
 
    If the callback returns with an exception set, it must return ``-1``; this
    exception will be printed as an unraisable exception using

Doc/c-api/unicode.rst

@@ -1600,6 +1600,8 @@ object.
 
    Discard the internal Unicode buffer and destroy the writer instance.
 
+   If *writer* is ``NULL``, no operation is performed.
+
 .. c:function:: int PyUnicodeWriter_WriteChar(PyUnicodeWriter *writer, Py_UCS4 ch)
 
    Write the single Unicode character *ch* into *writer*.

Doc/conf.py

@@ -11,6 +11,8 @@
 import sys
 import time
 
+import sphinx
+
 sys.path.append(os.path.abspath('tools/extensions'))
 sys.path.append(os.path.abspath('includes'))
 
@@ -21,6 +23,7 @@
 
 extensions = [
     'audit_events',
+    'availability',
     'c_annotations',
     'glossary_search',
     'lexers',
@@ -61,7 +64,10 @@
 
 # General substitutions.
 project = 'Python'
-copyright = f"2001-{time.strftime('%Y')}, Python Software Foundation"
+if sphinx.version_info[:2] >= (8, 1):
+    copyright = "2001-%Y, Python Software Foundation"
+else:
+    copyright = f"2001-{time.strftime('%Y')}, Python Software Foundation"
 
 # We look for the Include/patchlevel.h file in the current Python source tree
 # and replace the values accordingly.
@@ -360,10 +366,14 @@
 }
 
 # This 'Last updated on:' timestamp is inserted at the bottom of every page.
-html_time = int(os.environ.get('SOURCE_DATE_EPOCH', time.time()))
-html_last_updated_fmt = time.strftime(
-    '%b %d, %Y (%H:%M UTC)', time.gmtime(html_time)
-)
+html_last_updated_fmt = '%b %d, %Y (%H:%M UTC)'
+if sphinx.version_info[:2] >= (8, 1):
+    html_last_updated_use_utc = True
+else:
+    html_time = int(os.environ.get('SOURCE_DATE_EPOCH', time.time()))
+    html_last_updated_fmt = time.strftime(
+        html_last_updated_fmt, time.gmtime(html_time)
+    )
 
 # Path to find HTML templates.
 templates_path = ['tools/templates']
@@ -595,13 +605,21 @@
 # mapping unique short aliases to a base URL and a prefix.
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
 extlinks = {
-    "cve": ("https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s", "CVE-%s"),
-    "cwe": ("https://cwe.mitre.org/data/definitions/%s.html", "CWE-%s"),
     "pypi": ("https://pypi.org/project/%s/", "%s"),
     "source": (SOURCE_URI, "%s"),
 }
 extlinks_detect_hardcoded_links = True
 
+if sphinx.version_info[:2] < (8, 1):
+    # Sphinx 8.1 has in-built CVE and CWE roles.
+    extlinks |= {
+        "cve": (
+            "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s",
+            "CVE-%s",
+        ),
+        "cwe": ("https://cwe.mitre.org/data/definitions/%s.html", "CWE-%s"),
+    }
+
 # Options for c_annotations
 # -------------------------
 

Doc/glossary.rst

@@ -265,19 +265,33 @@ Glossary
       advanced mathematical feature.  If you're not aware of a need for them,
       it's almost certain you can safely ignore them.
 
+   context
+      This term has different meanings depending on where and how it is used.
+      Some common meanings:
+
+      * The temporary state or environment established by a :term:`context
+        manager` via a :keyword:`with` statement.
+      * The collection of key­value bindings associated with a particular
+        :class:`contextvars.Context` object and accessed via
+        :class:`~contextvars.ContextVar` objects.  Also see :term:`context
+        variable`.
+      * A :class:`contextvars.Context` object.  Also see :term:`current
+        context`.
+
+   context management protocol
+      The :meth:`~object.__enter__` and :meth:`~object.__exit__` methods called
+      by the :keyword:`with` statement.  See :pep:`343`.
+
    context manager
-      An object which controls the environment seen in a :keyword:`with`
-      statement by defining :meth:`~object.__enter__` and :meth:`~object.__exit__` methods.
-      See :pep:`343`.
+      An object which implements the :term:`context management protocol` and
+      controls the environment seen in a :keyword:`with` statement.  See
+      :pep:`343`.
 
    context variable
-      A variable which can have different values depending on its context.
-      This is similar to Thread-Local Storage in which each execution
-      thread may have a different value for a variable. However, with context
-      variables, there may be several contexts in one execution thread and the
-      main usage for context variables is to keep track of variables in
+      A variable whose value depends on which context is the :term:`current
+      context`.  Values are accessed via :class:`contextvars.ContextVar`
+      objects.  Context variables are primarily used to isolate state between
       concurrent asynchronous tasks.
-      See :mod:`contextvars`.
 
    contiguous
       .. index:: C-contiguous, Fortran contiguous
@@ -311,6 +325,14 @@ Glossary
       is used when necessary to distinguish this implementation from others
       such as Jython or IronPython.
 
+   current context
+      The :term:`context` (:class:`contextvars.Context` object) that is
+      currently used by :class:`~contextvars.ContextVar` objects to access (get
+      or set) the values of :term:`context variables <context variable>`.  Each
+      thread has its own current context.  Frameworks for executing asynchronous
+      tasks (see :mod:`asyncio`) associate each task with a context which
+      becomes the current context whenever the task starts or resumes execution.
+
    decorator
       A function returning another function, usually applied as a function
       transformation using the ``@wrapper`` syntax.  Common examples for

Doc/includes/newtypes/custom2.c

@@ -23,12 +23,12 @@ Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
     CustomObject *self;
     self = (CustomObject *) type->tp_alloc(type, 0);
     if (self != NULL) {
-        self->first = PyUnicode_FromString("");
+        self->first = Py_GetConstant(Py_CONSTANT_EMPTY_STR);
         if (self->first == NULL) {
             Py_DECREF(self);
             return NULL;
         }
-        self->last = PyUnicode_FromString("");
+        self->last = Py_GetConstant(Py_CONSTANT_EMPTY_STR);
         if (self->last == NULL) {
             Py_DECREF(self);
             return NULL;

Doc/includes/newtypes/custom3.c

@@ -23,12 +23,12 @@ Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
     CustomObject *self;
     self = (CustomObject *) type->tp_alloc(type, 0);
     if (self != NULL) {
-        self->first = PyUnicode_FromString("");
+        self->first = Py_GetConstant(Py_CONSTANT_EMPTY_STR);
         if (self->first == NULL) {
             Py_DECREF(self);
             return NULL;
         }
-        self->last = PyUnicode_FromString("");
+        self->last = Py_GetConstant(Py_CONSTANT_EMPTY_STR);
         if (self->last == NULL) {
             Py_DECREF(self);
             return NULL;

Doc/includes/newtypes/custom4.c

@@ -39,12 +39,12 @@ Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
     CustomObject *self;
     self = (CustomObject *) type->tp_alloc(type, 0);
     if (self != NULL) {
-        self->first = PyUnicode_FromString("");
+        self->first = Py_GetConstant(Py_CONSTANT_EMPTY_STR);
         if (self->first == NULL) {
             Py_DECREF(self);
             return NULL;
         }
-        self->last = PyUnicode_FromString("");
+        self->last = Py_GetConstant(Py_CONSTANT_EMPTY_STR);
         if (self->last == NULL) {
             Py_DECREF(self);
             return NULL;

Doc/library/__future__.rst

@@ -66,7 +66,7 @@ language using this mechanism:
 +------------------+-------------+--------------+---------------------------------------------+
 | annotations      | 3.7.0b1     | Never [1]_   | :pep:`563`:                                 |
 |                  |             |              | *Postponed evaluation of annotations*,      |
-|                  |             |              | :pep:`649`: *Deferred evalutation of        |
+|                  |             |              | :pep:`649`: *Deferred evaluation of         |
 |                  |             |              | annotations using descriptors*              |
 +------------------+-------------+--------------+---------------------------------------------+
 

Doc/library/_thread.rst

@@ -219,9 +219,11 @@ In addition to these methods, lock objects can also be used via the
 * Calling :func:`sys.exit` or raising the :exc:`SystemExit` exception is
   equivalent to calling :func:`_thread.exit`.
 
-* It is not possible to interrupt the :meth:`~threading.Lock.acquire` method on
-  a lock --- the :exc:`KeyboardInterrupt` exception will happen after the lock
-  has been acquired.
+* It is platform-dependent whether the :meth:`~threading.Lock.acquire` method
+  on a lock can be interrupted (so that the :exc:`KeyboardInterrupt` exception
+  will happen immediately, rather than only after the lock has been acquired or
+  the operation has timed out). It can be interrupted on POSIX, but not on
+  Windows.
 
 * When the main thread exits, it is system defined whether the other threads
   survive.  On most systems, they are killed without executing

Doc/library/argparse.rst

@@ -541,7 +541,8 @@ exit_on_error
 ^^^^^^^^^^^^^
 
 Normally, when you pass an invalid argument list to the :meth:`~ArgumentParser.parse_args`
-method of an :class:`ArgumentParser`, it will exit with error info.
+method of an :class:`ArgumentParser`, it will print a *message* to :data:`sys.stderr` and exit with a status
+code of 2.
 
 If the user would like to catch errors manually, the feature can be enabled by setting
 ``exit_on_error`` to ``False``::
@@ -601,7 +602,7 @@ The add_argument() method
 The following sections describe how each of these are used.
 
 
-.. _name_or_flags:
+.. _`name or flags`:
 
 name or flags
 ^^^^^^^^^^^^^
@@ -635,6 +636,25 @@ be positional::
    usage: PROG [-h] [-f FOO] bar
    PROG: error: the following arguments are required: bar
 
+By default, argparse automatically handles the internal naming and
+display names of arguments, simplifying the process without requiring
+additional configuration.
+As such, you do not need to specify the dest_ and metavar_ parameters.
+The dest_ parameter defaults to the argument name with underscores ``_``
+replacing hyphens ``-`` . The metavar_ parameter defaults to the
+upper-cased name. For example::
+
+   >>> parser = argparse.ArgumentParser(prog='PROG')
+   >>> parser.add_argument('--foo-bar')
+   >>> parser.parse_args(['--foo-bar', 'FOO-BAR']
+   Namespace(foo_bar='FOO-BAR')
+   >>> parser.print_help()
+   usage:  [-h] [--foo-bar FOO-BAR]
+
+   optional arguments:
+    -h, --help  show this help message and exit
+    --foo-bar FOO-BAR
+
 
 .. _action:
 
@@ -731,6 +751,9 @@ how the command-line arguments should be handled. The supplied actions are:
 
   .. versionadded:: 3.8
 
+Only actions that consume command-line arguments (e.g. ``'store'``,
+``'append'`` or ``'extend'``) can be used with positional arguments.
+
 You may also specify an arbitrary action by passing an Action subclass or
 other object that implements the same interface. The ``BooleanOptionalAction``
 is available in ``argparse`` and adds support for boolean actions such as
@@ -858,6 +881,8 @@ See also :ref:`specifying-ambiguous-arguments`. The supported values are:
 If the ``nargs`` keyword argument is not provided, the number of arguments consumed
 is determined by the action_.  Generally this means a single command-line argument
 will be consumed and a single item (not a list) will be produced.
+Actions that do not consume command-line arguments (e.g.
+``'store_const'``) set ``nargs=0``.
 
 
 .. _const:

Doc/library/configparser.rst

@@ -54,6 +54,7 @@ can be customized by end users easily.
 
    import os
    os.remove("example.ini")
+   os.remove("override.ini")
 
 
 Quick Start