Merge branch 'main' into better-pygettext

.coveragerc

@@ -0,0 +1,19 @@
+[run]
+branch = True
+
+[report]
+# Regexes for lines to exclude from consideration
+exclude_lines =
+    # Don't complain if non-runnable code isn't run:
+    if 0:
+    if __name__ == .__main__.:
+
+    .*# pragma: no cover
+    .*# pragma: no branch
+
+    # Additions for IDLE:
+    .*# htest #
+    if not (_htest or _utest):
+    if not .*_utest:
+    if .*_htest:
+

.gitattributes

@@ -85,6 +85,7 @@ Parser/parser.c                                     generated
 Parser/token.c                                      generated
 Programs/test_frozenmain.h                          generated
 Python/Python-ast.c                                 generated
+Python/executor_cases.c.h                           generated
 Python/generated_cases.c.h                          generated
 Python/opcode_targets.h                             generated
 Python/stdlib_module_names.h                        generated

.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
@@ -172,4 +172,9 @@ Doc/c-api/stable.rst          @encukou
 **/*pathlib*                  @barneygale
 
 # zipfile.Path
-**/*zipfile/*_path.py         @jaraco
+**/*zipfile/_path/*           @jaraco
+
+# Argument Clinic
+/Tools/clinic/**              @erlend-aasland @AlexWaygood
+/Lib/test/test_clinic.py      @erlend-aasland @AlexWaygood
+Doc/howto/clinic.rst          @erlend-aasland

.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'
@@ -531,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

.github/workflows/reusable-docs.yml

@@ -28,8 +28,6 @@ jobs:
         cache-dependency-path: 'Doc/requirements.txt'
     - name: 'Install build dependencies'
       run: make -C Doc/ venv
-    - name: 'Check documentation'
-      run: make -C Doc/ check
     - name: 'Build HTML documentation'
       run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
 
@@ -40,12 +38,14 @@ jobs:
       uses: Ana06/[email protected]
       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
@@ -59,8 +59,6 @@ jobs:
         make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going" html 2>&1
 
   # This build doesn't use problem matchers or check annotations
-  # It also does not run 'make check', as sphinx-lint is not installed into the
-  # environment.
   build_doc_oldest_supported_sphinx:
     name: 'Docs (Oldest Sphinx)'
     runs-on: ubuntu-latest

.pre-commit-config.yaml

@@ -3,5 +3,16 @@ repos:
     rev: v4.4.0
     hooks:
       - id: check-yaml
+      - id: end-of-file-fixer
+        types: [python]
+        exclude: Lib/test/coding20731.py
       - id: trailing-whitespace
         types_or: [c, python, rst]
+
+  - repo: https://github.com/sphinx-contrib/sphinx-lint
+    rev: v0.6.7
+    hooks:
+      - id: sphinx-lint
+        args: [--enable=default-role]
+        files: ^Doc/
+        types: [rst]

Doc/Makefile

@@ -216,11 +216,9 @@ dist:
 	rm dist/python-$(DISTVERSION)-docs-texinfo.tar
 
 .PHONY: check
-check:
-	# Check the docs and NEWS files with sphinx-lint.
-	# Ignore the tools and venv dirs and check that the default role is not used.
-	$(SPHINXLINT) -i tools -i $(VENVDIR) --enable default-role
-	$(SPHINXLINT) --enable default-role ../Misc/NEWS.d/next/
+check: venv
+	$(VENVDIR)/bin/python3 -m pre_commit --version > /dev/null || $(VENVDIR)/bin/python3 -m pip install pre-commit
+	$(VENVDIR)/bin/python3 -m pre_commit run --all-files
 
 .PHONY: serve
 serve:

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/call.rst

@@ -113,19 +113,6 @@ function as with any other callable.
 :c:func:`PyObject_Vectorcall` will usually be most efficient.
 
 
-.. note::
-
-   In CPython 3.8, the vectorcall API and related functions were available
-   provisionally under names with a leading underscore:
-   ``_PyObject_Vectorcall``, ``_Py_TPFLAGS_HAVE_VECTORCALL``,
-   ``_PyObject_VectorcallMethod``, ``_PyVectorcall_Function``,
-   ``_PyObject_CallOneArg``, ``_PyObject_CallMethodNoArgs``,
-   ``_PyObject_CallMethodOneArg``.
-   Additionally, ``PyObject_VectorcallDict`` was available as
-   ``_PyObject_FastCallDict``.
-   The old names are still defined as aliases of the new, non-underscored names.
-
-
 Recursion Control
 .................
 

Doc/c-api/complex.rst

@@ -127,12 +127,12 @@ Complex Numbers as Python Objects
 
    Return the :c:type:`Py_complex` value of the complex number *op*.
 
-   If *op* is not a Python complex number object but has a :meth:`__complex__`
+   If *op* is not a Python complex number object but has a :meth:`~object.__complex__`
    method, this method will first be called to convert *op* to a Python complex
-   number object.  If ``__complex__()`` is not defined then it falls back to
-   :meth:`__float__`.  If ``__float__()`` is not defined then it falls back
-   to :meth:`__index__`.  Upon failure, this method returns ``-1.0`` as a real
+   number object.  If :meth:`!__complex__` is not defined then it falls back to
+   :meth:`~object.__float__`.  If :meth:`!__float__` is not defined then it falls back
+   to :meth:`~object.__index__`.  Upon failure, this method returns ``-1.0`` as a real
    value.
 
    .. versionchanged:: 3.8
-      Use :meth:`__index__` if available.
+      Use :meth:`~object.__index__` if available.

Doc/c-api/dict.rst

@@ -98,9 +98,11 @@ Dictionary Objects
    Return the object from dictionary *p* which has a key *key*.  Return ``NULL``
    if the key *key* is not present, but *without* setting an exception.
 
-   Note that exceptions which occur while calling :meth:`__hash__` and
-   :meth:`__eq__` methods will get suppressed.
-   To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
+   .. note::
+
+      Exceptions that occur while this calls :meth:`~object.__hash__` and
+      :meth:`~object.__eq__` methods are silently ignored.
+      Prefer the :c:func:`PyDict_GetItemWithError` function instead.
 
    .. versionchanged:: 3.10
       Calling this API without :term:`GIL` held had been allowed for historical
@@ -120,10 +122,13 @@ Dictionary Objects
    This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
    :c:expr:`const char*`, rather than a :c:expr:`PyObject*`.
 
-   Note that exceptions which occur while calling :meth:`__hash__` and
-   :meth:`__eq__` methods and creating a temporary string object
-   will get suppressed.
-   To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
+   .. note::
+
+      Exceptions that occur while this calls :meth:`~object.__hash__` and
+      :meth:`~object.__eq__` methods or while creating the temporary :class:`str`
+      object are silently ignored.
+      Prefer using the :c:func:`PyDict_GetItemWithError` function with your own
+      :c:func:`PyUnicode_FromString` *key* instead.
 
 
 .. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)

Doc/c-api/float.rst

@@ -45,14 +45,14 @@ Floating Point Objects
 .. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
 
    Return a C :c:expr:`double` representation of the contents of *pyfloat*.  If
-   *pyfloat* is not a Python floating point object but has a :meth:`__float__`
+   *pyfloat* is not a Python floating point object but has a :meth:`~object.__float__`
    method, this method will first be called to convert *pyfloat* into a float.
-   If ``__float__()`` is not defined then it falls back to :meth:`__index__`.
+   If :meth:`!__float__` is not defined then it falls back to :meth:`~object.__index__`.
    This method returns ``-1.0`` upon failure, so one should call
    :c:func:`PyErr_Occurred` to check for errors.
 
    .. versionchanged:: 3.8
-      Use :meth:`__index__` if available.
+      Use :meth:`~object.__index__` if available.
 
 
 .. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)