Merge branch 'main' into _PyMapping_LookupItem

.github/CODEOWNERS

@@ -79,7 +79,7 @@ Doc/library/time.rst          @pganssle @abalkin
 Lib/test/test_time.py         @pganssle @abalkin
 Modules/timemodule.c          @pganssle @abalkin
 Python/pytime.c               @pganssle @abalkin
-Include/pytime.h              @pganssle @abalkin
+Include/internal/pycore_time.h  @pganssle @abalkin
 
 # Email and related
 **/*mail*                     @python/email-team
@@ -173,3 +173,7 @@ Doc/c-api/stable.rst          @encukou
 
 # zipfile.Path
 **/*zipfile/*_path.py         @jaraco
+
+# Argument Clinic
+/Tools/clinic/**              @erlend-aasland @AlexWaygood
+/Lib/test/test_clinic.py      @erlend-aasland @AlexWaygood

.github/workflows/build.yml

@@ -519,3 +519,60 @@ jobs:
       run: make pythoninfo
     - name: Tests
       run: xvfb-run make buildbottest TESTOPTS="-j4 -uall,-cpu"
+
+  all-required-green:  # This job does nothing and is only used for the branch protection
+    name: All required checks pass
+    if: always()
+
+    needs:
+    - check_source  # Transitive dependency, needed to access `run_tests` value
+    - check-docs
+    - check_generated_files
+    - build_win32
+    - build_win_amd64
+    - build_macos
+    - build_ubuntu
+    - build_ubuntu_ssltests
+    - test_hypothesis
+    - build_asan
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Check whether the needed jobs succeeded or failed
+      uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe
+      with:
+        allowed-failures: >-
+          build_macos,
+          build_ubuntu_ssltests,
+          build_win32,
+          test_hypothesis,
+        allowed-skips: >-
+          ${{
+            !fromJSON(needs.check_source.outputs.run-docs)
+            && '
+            check-docs,
+            '
+            || ''
+          }}
+          ${{
+            needs.check_source.outputs.run_tests != 'true'
+            && '
+            check_generated_files,
+            build_win32,
+            build_win_amd64,
+            build_macos,
+            build_ubuntu,
+            build_ubuntu_ssltests,
+            build_asan,
+            '
+            || ''
+          }}
+          ${{
+            !fromJSON(needs.check_source.outputs.run_hypothesis)
+            && '
+            test_hypothesis,
+            '
+            || ''
+          }}
+        jobs: ${{ toJSON(needs) }}

.github/workflows/new-bugs-announce-notifier.yml

@@ -41,7 +41,10 @@ jobs:
                 url    : issue.data.html_url,
                 labels : issue.data.labels.map(label => { return label.name }).join(", "),
                 assignee : issue.data.assignees.map(assignee => { return assignee.login }),
-                body   : issue.data.body
+                // We need to truncate the body size, because the max size for
+                // the whole payload is 16kb. We want to be safe and assume that
+                // body can take up to ~8kb of space.
+                body   : issue.data.body.substring(0, 8000)
               };
 
               const data = {

.github/workflows/require-pr-label.yml

@@ -15,7 +15,7 @@ jobs:
     timeout-minutes: 10
 
     steps:
-      - uses: mheap/github-action-required-labels@v4
+      - uses: mheap/github-action-required-labels@v5
         with:
           mode: exactly
           count: 0

Doc/c-api/init.rst

@@ -87,7 +87,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    Set by the :option:`-b` option.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_DebugFlag
 
@@ -101,7 +101,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment
    variable.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_DontWriteBytecodeFlag
 
@@ -115,7 +115,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE`
    environment variable.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_FrozenFlag
 
@@ -128,7 +128,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    Private flag used by ``_freeze_module`` and ``frozenmain`` programs.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_HashRandomizationFlag
 
@@ -143,7 +143,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment
    variable to initialize the secret hash seed.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_IgnoreEnvironmentFlag
 
@@ -156,7 +156,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    Set by the :option:`-E` and :option:`-I` options.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_InspectFlag
 
@@ -171,7 +171,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment
    variable.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_InteractiveFlag
 
@@ -196,7 +196,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. versionadded:: 3.4
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_LegacyWindowsFSEncodingFlag
 
@@ -215,7 +215,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. availability:: Windows.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_LegacyWindowsStdioFlag
 
@@ -233,7 +233,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. availability:: Windows.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_NoSiteFlag
 
@@ -248,7 +248,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    Set by the :option:`-S` option.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_NoUserSiteDirectory
 
@@ -262,7 +262,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    Set by the :option:`-s` and :option:`-I` options, and the
    :envvar:`PYTHONNOUSERSITE` environment variable.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_OptimizeFlag
 
@@ -273,7 +273,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment
    variable.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_QuietFlag
 
@@ -287,7 +287,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. versionadded:: 3.2
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_UnbufferedStdioFlag
 
@@ -300,7 +300,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED`
    environment variable.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_VerboseFlag
 
@@ -316,7 +316,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    Set by the :option:`-v` option and the :envvar:`PYTHONVERBOSE` environment
    variable.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 
 Initializing and finalizing the interpreter

Doc/c-api/typeobj.rst

@@ -1143,27 +1143,27 @@ and :c:type:`PyType_Type` effectively act as defaults.)
       :const:`Py_TPFLAGS_IMMUTABLETYPE` flag set.  For extension types, it is
       inherited whenever :c:member:`~PyTypeObject.tp_descr_get` is inherited.
 
-    .. data:: Py_TPFLAGS_MANAGED_DICT
+   .. data:: Py_TPFLAGS_MANAGED_DICT
 
-       This bit indicates that instances of the class have a ``__dict__``
-       attribute, and that the space for the dictionary is managed by the VM.
+      This bit indicates that instances of the class have a ``__dict__``
+      attribute, and that the space for the dictionary is managed by the VM.
 
-       If this flag is set, :const:`Py_TPFLAGS_HAVE_GC` should also be set.
+      If this flag is set, :const:`Py_TPFLAGS_HAVE_GC` should also be set.
 
-       .. versionadded:: 3.12
+      .. versionadded:: 3.12
 
       **Inheritance:**
 
       This flag is inherited unless the
       :c:member:`~PyTypeObject.tp_dictoffset` field is set in a superclass.
 
 
-    .. data:: Py_TPFLAGS_MANAGED_WEAKREF
+   .. data:: Py_TPFLAGS_MANAGED_WEAKREF
 
-       This bit indicates that instances of the class should be weakly
-       referenceable.
+      This bit indicates that instances of the class should be weakly
+      referenceable.
 
-       .. versionadded:: 3.12
+      .. versionadded:: 3.12
 
       **Inheritance:**
 

Doc/c-api/weakref.rst

@@ -55,9 +55,11 @@ as much as it can.
 
    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.
+   * On success, set *\*pobj* to a new :term:`strong reference` to the
+     referenced object and return 1.
+   * If the reference is dead, set *\*pobj* to ``NULL`` and return 0.
+   * On error, raise an exception and return -1.
 
    .. versionadded:: 3.13
 

Doc/extending/embedding.rst

@@ -87,6 +87,13 @@ perform some operation on a file. ::
         Py_ExitStatusException(status);
    }
 
+.. note::
+
+   ``#define PY_SSIZE_T_CLEAN`` was used to indicate that ``Py_ssize_t`` should be
+   used in some APIs instead of ``int``.
+   It is not necessary since Python 3.13, but we keep it here for backward compatibility.
+   See :ref:`arg-parsing-string-and-buffers` for a description of this macro.
+
 Setting :c:member:`PyConfig.program_name` should be called before
 :c:func:`Py_InitializeFromConfig` to inform the interpreter about paths to Python run-time
 libraries.  Next, the Python interpreter is initialized with

Doc/extending/extending.rst

@@ -69,8 +69,10 @@ the module and a copyright notice if you like).
    headers on some systems, you *must* include :file:`Python.h` before any standard
    headers are included.
 
-   It is recommended to always define ``PY_SSIZE_T_CLEAN`` before including
-   ``Python.h``.  See :ref:`arg-parsing-string-and-buffers` for a description of this macro.
+   ``#define PY_SSIZE_T_CLEAN`` was used to indicate that ``Py_ssize_t`` should be
+   used in some APIs instead of ``int``.
+   It is not necessary since Python 3.13, but we keep it here for backward compatibility.
+   See :ref:`arg-parsing-string-and-buffers` for a description of this macro.
 
 All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` or
 ``PY``, except those defined in standard header files. For convenience, and

Doc/glossary.rst

@@ -1107,6 +1107,21 @@ Glossary
       when several are given, such as in ``variable_name[1:3:5]``.  The bracket
       (subscript) notation uses :class:`slice` objects internally.
 
+   soft deprecated
+      A soft deprecation can be used when using an API which should no longer
+      be used to write new code, but it remains safe to continue using it in
+      existing code. The API remains documented and tested, but will not be
+      developed further (no enhancement).
+
+      The main difference between a "soft" and a (regular) "hard" deprecation
+      is that the soft deprecation does not imply scheduling the removal of the
+      deprecated API.
+
+      Another difference is that a soft deprecation does not issue a warning.
+
+      See `PEP 387: Soft Deprecation
+      <https://peps.python.org/pep-0387/#soft-deprecation>`_.
+
    special method
       .. index:: pair: special; method
 

Doc/library/asyncio-exceptions.rst

@@ -31,7 +31,7 @@ Exceptions
 
    .. versionchanged:: 3.8
 
-      :exc:`CancelledError` is now a subclass of :class:`BaseException`.
+      :exc:`CancelledError` is now a subclass of :class:`BaseException` rather than :class:`Exception`.
 
 
 .. exception:: InvalidStateError

Doc/library/doctest.rst

@@ -409,10 +409,10 @@ Simple example::
    >>> [1, 2, 3].remove(42)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
-   ValueError: list.remove(x): x not in list
+   ValueError: 42 is not in list
 
-That doctest succeeds if :exc:`ValueError` is raised, with the ``list.remove(x):
-x not in list`` detail as shown.
+That doctest succeeds if :exc:`ValueError` is raised, with the ``42 is not in list``
+detail as shown.
 
 The expected output for an exception must start with a traceback header, which
 may be either of the following two lines, indented the same as the first line of

Doc/library/exceptions.rst

@@ -871,6 +871,8 @@ The following exceptions are used as warning categories; see the
    .. versionadded:: 3.2
 
 
+.. _lib-exception-groups:
+
 Exception groups
 ----------------
 

Doc/library/functions.rst

@@ -794,7 +794,7 @@ are always available.  They are listed here in alphabetical order.
 
       For objects with custom :meth:`__hash__` methods, note that :func:`hash`
       truncates the return value based on the bit width of the host machine.
-      See :meth:`__hash__` for details.
+      See :meth:`__hash__ <object.__hash__>` for details.
 
 .. function:: help()
               help(request)