Merge branch 'main' into pythongh-89812-omgtarpath

.coveragerc

@@ -7,6 +7,11 @@ exclude_lines =
     # Don't complain if non-runnable code isn't run:
     if 0:
     if __name__ == .__main__.:
+    raise AssertionError\(
+
+    # Empty bodies in protocols or abstract methods
+    ^\s*def [a-zA-Z0-9_]+\(.*\)(\s*->.*)?:\s*\.\.\.(\s*#.*)?$
+    ^\s*\.\.\.(\s*#.*)?$
 
     .*# pragma: no cover
     .*# pragma: no branch

.gitattributes

@@ -72,9 +72,12 @@ Doc/library/token-list.inc                          generated
 Include/internal/pycore_ast.h                       generated
 Include/internal/pycore_ast_state.h                 generated
 Include/internal/pycore_opcode.h                    generated
+Include/internal/pycore_opcode_metadata.h           generated
 Include/internal/pycore_*_generated.h               generated
 Include/opcode.h                                    generated
+Include/opcode_ids.h                                generated
 Include/token.h                                     generated
+Lib/_opcode_metadata.py                             generated
 Lib/keyword.py                                      generated
 Lib/test/levenshtein_examples.json                  generated
 Lib/test/test_stable_abi_ctypes.py                  generated

.github/CODEOWNERS

@@ -69,6 +69,7 @@ Python/traceback.c            @iritkatriel
 
 # Import (including importlib).
 **/*import*                   @brettcannon @ericsnowcurrently @ncoghlan @warsaw
+/Python/import.c              @kumaraditya303
 **/*importlib/resources/*      @jaraco @warsaw @FFY00
 **/importlib/metadata/*       @jaraco @warsaw
 

.github/ISSUE_TEMPLATE/bug.md

@@ -5,28 +5,46 @@ labels: "type-bug"
 ---
 
 <!--
-  If you're new to Python and you're not sure whether what you're experiencing is a bug, the CPython issue tracker is not
-  the right place to seek help. Consider the following options instead:
+  New to Python? The issue tracker isn't the right place to get help.
+  Consider instead:
 
   - reading the Python tutorial: https://docs.python.org/3/tutorial/
-  - posting in the "Users" category on discuss.python.org: https://discuss.python.org/c/users/7
-  - emailing the Python-list mailing list: https://mail.python.org/mailman/listinfo/python-list
-  - searching our issue tracker (https://github.com/python/cpython/issues) to see if
-    your problem has already been reported
+  - posting at https://discuss.python.org/c/users/7
+  - emailing https://mail.python.org/mailman/listinfo/python-list
 -->
 
 # Bug report
 
-A clear and concise description of what the bug is.
-Include a minimal, reproducible example (https://stackoverflow.com/help/minimal-reproducible-example), if possible.
+## Checklist
+
+<!-- Bugs in third-party projects (e.g. `requests`) do not belong in the CPython issue tracker -->
+
+- [ ] I am confident this is a bug in CPython, not a bug in a third-party project
+- [ ] I have searched the CPython issue tracker, and am confident this bug has not been reported before
+
+## A clear and concise description of the bug
+
+<!--
+  Include a minimal, reproducible example if possible.
+  (https://stackoverflow.com/help/minimal-reproducible-example)
+
+  Put any code blocks inside triple backticks:
+
+  ```py
+  your code here
+  ```
+
+-->
+
+
 
 # Your environment
 
-<!-- Include as many relevant details as possible about the environment you experienced the bug in -->
+<!-- Include all relevant details about the environment you experienced the bug in -->
 
 - CPython versions tested on:
 - Operating system and architecture:
 
 <!--
-You can freely edit this text. Remove any lines you believe are unnecessary.
+You can freely edit this form. Remove any lines you believe are unnecessary.
 -->

.github/ISSUE_TEMPLATE/crash.md

@@ -5,29 +5,44 @@ labels: "type-crash"
 ---
 
 <!--
-  Use this template for hard crashes of the interpreter, segmentation faults, failed C-level assertions, and similar.
-  Do not submit this form if you encounter an exception being unexpectedly raised from a Python function.
-  Most of the time, these should be filed as bugs, rather than crashes.
+  This form is for hard crashes of the Python interpreter, segmentation faults,
+  failed C-level assertions, and similar.
+  Exceptions unexpectedly raised from stdlib Python functions
+  count as bugs rather than crashes.
 
-  The CPython interpreter is itself written in a different programming language, C.
-  For CPython, a "crash" is when Python itself fails, leading to a traceback in the C stack.
+  The CPython interpreter is written in a different programming language, C.
+  A "CPython crash" is when Python itself fails, leading to a traceback in the C stack.
 -->
 
 # Crash report
 
-Tell us what happened, ideally including a minimal, reproducible example (https://stackoverflow.com/help/minimal-reproducible-example).
+<!--
+  Tell us what happened. Ideally, include a minimal, reproducible example.
+  (https://stackoverflow.com/help/minimal-reproducible-example)
+
+  Put any code blocks inside triple backticks:
+
+  ```py
+  your code here
+  ```
+
+-->
+
+
 
 # Error messages
 
-Enter any relevant error message caused by the crash, including a core dump if there is one.
+<!-- Enter any error messages caused by the crash, including a core dump if there is one -->
+
+
 
 # Your environment
 
-<!-- Include as many relevant details as possible about the environment you experienced the bug in -->
+<!-- Include all relevant details about the environment you experienced the crash in -->
 
 - CPython versions tested on:
 - Operating system and architecture:
 
 <!--
-You can freely edit this text. Remove any lines you believe are unnecessary.
+You can freely edit this form. Remove any lines you believe are unnecessary.
 -->

.github/ISSUE_TEMPLATE/feature.md

@@ -4,25 +4,47 @@ about: Submit a proposal for a new CPython feature or enhancement
 labels: "type-feature"
 ---
 
+<!--
+  Proposing a new feature for Python?
+  You'll need to demonstrate widespread support for your idea among the community.
+
+  Major feature proposals should generally be discussed at
+  https://discuss.python.org/c/ideas/6 before opening a GitHub issue.
+  Wait until it's clear that most people support your idea
+  before filling in this form.
+-->
+
 # Feature or enhancement
 
-(A clear and concise description of your proposal.)
+<!-- A clear and concise description of your proposal. -->
+
+
 
 # Pitch
 
-(Explain why this feature or enhancement should be implemented and how it would be used.
- Add examples, if applicable.)
+<!--
+  Explain why this feature or enhancement should be implemented and how it would be used.
+  Add examples, if applicable.
+
+  Put any code blocks inside triple backticks:
+
+  ```py
+  your code here
+  ```
+
+-->
+
+
 
 # Previous discussion
 
 <!--
-  New features to Python should first be discussed elsewhere before creating issues on GitHub,
-  for example in the "ideas" category (https://discuss.python.org/c/ideas/6) of discuss.python.org,
-  or the python-ideas mailing list (https://mail.python.org/mailman3/lists/python-ideas.python.org/).
-  Use this space to post links to the places where you have already discussed this feature proposal:
+  Use this space to post links to the places
+  where you have already discussed your feature proposal:
 -->
 
 
+
 <!--
-You can freely edit this text. Remove any lines you believe are unnecessary.
+You can freely edit this form. Remove any lines you believe are unnecessary.
 -->

.github/workflows/reusable-docs.yml

@@ -28,35 +28,28 @@ jobs:
         cache-dependency-path: 'Doc/requirements.txt'
     - name: 'Install build dependencies'
       run: make -C Doc/ venv
-    - name: 'Build HTML documentation'
-      run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
 
-    # Add pull request annotations for Sphinx nitpicks (missing references)
+    # To annotate PRs with Sphinx nitpicks (missing references)
     - name: 'Get list of changed files'
       if: github.event_name == 'pull_request'
       id: changed_files
       uses: Ana06/get-changed-files@v2.2.0
       with:
         filter: "Doc/**"
         format: csv  # works for paths with spaces
-    - name: 'Build changed files in nit-picky mode'
-      if: github.event_name == 'pull_request'
+    - name: 'Build HTML documentation'
       continue-on-error: true
       run: |
         set -Eeuo pipefail
-        # Mark files the pull request 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
-
-    # Ensure some files always pass Sphinx nit-picky mode (no missing references)
-    - name: 'Build known-good files in nit-picky mode'
+        # Build docs with the '-n' (nit-picky) option; write warnings to file
+        make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going -w sphinx-warnings.txt" html
+    - name: 'Check warnings'
+      if: github.event_name == 'pull_request'
       run: |
-        # Mark files that must pass nit-picky
-        python Doc/tools/touch-clean-files.py
-        # Build docs with the '-n' (nit-picky) option, convert warnings to errors (-W)
-        make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going" html 2>&1
+        python Doc/tools/check-warnings.py \
+          --check-and-annotate '${{ steps.changed_files.outputs.added_modified }}' \
+          --fail-if-regression \
+          --fail-if-improved
 
   # This build doesn't use problem matchers or check annotations
   build_doc_oldest_supported_sphinx:

.pre-commit-config.yaml

@@ -10,7 +10,7 @@ repos:
         types_or: [c, python, rst]
 
   - repo: https://github.com/sphinx-contrib/sphinx-lint
-    rev: v0.6.7
+    rev: v0.6.8
     hooks:
       - id: sphinx-lint
         args: [--enable=default-role]

Doc/c-api/allocation.rst

@@ -27,31 +27,35 @@ Allocating Objects on the Heap
    length information for a variable-size object.
 
 
-.. c:function:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
+.. c:macro:: PyObject_New(TYPE, typeobj)
 
-   Allocate a new Python object using the C structure type *TYPE* and the
-   Python type object *type*.  Fields not defined by the Python object header
-   are not initialized; the object's reference count will be one.  The size of
-   the memory allocation is determined from the :c:member:`~PyTypeObject.tp_basicsize` field of
-   the type object.
+   Allocate a new Python object using the C structure type *TYPE*
+   and the Python type object *typeobj* (``PyTypeObject*``).
+   Fields not defined by the Python object header are not initialized.
+   The caller will own the only reference to the object
+   (i.e. its reference count will be one).
+   The size of the memory allocation is determined from the
+   :c:member:`~PyTypeObject.tp_basicsize` field of the type object.
 
 
-.. c:function:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
+.. c:macro:: PyObject_NewVar(TYPE, typeobj, size)
 
    Allocate a new Python object using the C structure type *TYPE* and the
-   Python type object *type*.  Fields not defined by the Python object header
+   Python type object *typeobj* (``PyTypeObject*``).
+   Fields not defined by the Python object header
    are not initialized.  The allocated memory allows for the *TYPE* structure
-   plus *size* fields of the size given by the :c:member:`~PyTypeObject.tp_itemsize` field of
-   *type*.  This is useful for implementing objects like tuples, which are
+   plus *size* (``Py_ssize_t``) fields of the size
+   given by the :c:member:`~PyTypeObject.tp_itemsize` field of
+   *typeobj*.  This is useful for implementing objects like tuples, which are
    able to determine their size at construction time.  Embedding the array of
    fields into the same allocation decreases the number of allocations,
    improving the memory management efficiency.
 
 
 .. c:function:: void PyObject_Del(void *op)
 
-   Releases memory allocated to an object using :c:func:`PyObject_New` or
-   :c:func:`PyObject_NewVar`.  This is normally called from the
+   Releases memory allocated to an object using :c:macro:`PyObject_New` or
+   :c:macro:`PyObject_NewVar`.  This is normally called from the
    :c:member:`~PyTypeObject.tp_dealloc` handler specified in the object's type.  The fields of
    the object should not be accessed after this call as the memory is no
    longer a valid Python object.

Doc/c-api/apiabiversion.rst

@@ -60,7 +60,7 @@ See :ref:`stable` for a discussion of API and ABI stability across versions.
 
    Use this for numeric comparisons, e.g. ``#if PY_VERSION_HEX >= ...``.
 
-   This version is also available via the symbol :data:`Py_Version`.
+   This version is also available via the symbol :c:var:`Py_Version`.
 
 .. c:var:: const unsigned long Py_Version
 

Doc/c-api/arg.rst

@@ -293,8 +293,10 @@ Other objects
 
 ``O`` (object) [PyObject \*]
    Store a Python object (without any conversion) in a C object pointer.  The C
-   program thus receives the actual object that was passed.  The object's reference
-   count is not increased.  The pointer stored is not ``NULL``.
+   program thus receives the actual object that was passed.  A new
+   :term:`strong reference` to the object is not created
+   (i.e. its reference count is not increased).
+   The pointer stored is not ``NULL``.
 
 ``O!`` (object) [*typeobject*, PyObject \*]
    Store a Python object in a C object pointer.  This is similar to ``O``, but
@@ -343,7 +345,7 @@ Other objects
    *items*.  Format units for sequences may be nested.
 
 It is possible to pass "long" integers (integers whose value exceeds the
-platform's :const:`LONG_MAX`) however no proper range checking is done --- the
+platform's :c:macro:`LONG_MAX`) however no proper range checking is done --- the
 most significant bits are silently truncated when the receiving field is too
 small to receive the value (actually, the semantics are inherited from downcasts
 in C --- your mileage may vary).
@@ -378,7 +380,8 @@ inside nested parentheses.  They are:
    mutually exclude each other.
 
 Note that any Python object references which are provided to the caller are
-*borrowed* references; do not decrement their reference count!
+*borrowed* references; do not release them
+(i.e. do not decrement their reference count)!
 
 Additional arguments passed to these functions must be addresses of variables
 whose type is determined by the format string; these are used to store values
@@ -463,7 +466,7 @@ API Functions
 
    A simpler form of parameter retrieval which does not use a format string to
    specify the types of the arguments.  Functions which use this method to retrieve
-   their parameters should be declared as :const:`METH_VARARGS` in function or
+   their parameters should be declared as :c:macro:`METH_VARARGS` in function or
    method tables.  The tuple containing the actual parameters should be passed as
    *args*; it must actually be a tuple.  The length of the tuple must be at least
    *min* and no more than *max*; *min* and *max* may be equal.  Additional
@@ -477,7 +480,7 @@ API Functions
    will be set if there was a failure.
 
    This is an example of the use of this function, taken from the sources for the
-   :mod:`_weakref` helper module for weak references::
+   :mod:`!_weakref` helper module for weak references::
 
       static PyObject *
       weakref_ref(PyObject *self, PyObject *args)
@@ -555,7 +558,7 @@ Building values
       Same as ``s#``.
 
    ``u`` (:class:`str`) [const wchar_t \*]
-      Convert a null-terminated :c:expr:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
+      Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
       data to a Python Unicode object.  If the Unicode buffer pointer is ``NULL``,
       ``None`` is returned.
 
@@ -621,8 +624,10 @@ Building values
       Convert a C :c:type:`Py_complex` structure to a Python complex number.
 
    ``O`` (object) [PyObject \*]
-      Pass a Python object untouched (except for its reference count, which is
-      incremented by one).  If the object passed in is a ``NULL`` pointer, it is assumed
+      Pass a Python object untouched but create a new
+      :term:`strong reference` to it
+      (i.e. its reference count is incremented by one).
+      If the object passed in is a ``NULL`` pointer, it is assumed
       that this was caused because the call producing the argument found an error and
       set an exception. Therefore, :c:func:`Py_BuildValue` will return ``NULL`` but won't
       raise an exception.  If no exception has been raised yet, :exc:`SystemError` is
@@ -632,7 +637,7 @@ Building values
       Same as ``O``.
 
    ``N`` (object) [PyObject \*]
-      Same as ``O``, except it doesn't increment the reference count on the object.
+      Same as ``O``, except it doesn't create a new :term:`strong reference`.
       Useful when the object is created by a call to an object constructor in the
       argument list.