Merge branch 'main' into gh-108009

Author: savannahostrowski

.github/CODEOWNERS

@@ -38,7 +38,6 @@ Python/compile.c              @markshannon @iritkatriel
 Python/assemble.c             @markshannon @iritkatriel
 Python/flowgraph.c            @markshannon @iritkatriel
 Python/instruction_sequence.c @iritkatriel
-Python/ast_opt.c              @isidentical
 Python/bytecodes.c            @markshannon
 Python/optimizer*.c           @markshannon
 Python/optimizer_analysis.c   @Fidget-Spinner
@@ -158,10 +157,12 @@ Include/internal/pycore_time.h  @pganssle @abalkin
 /Tools/cases_generator/        @markshannon
 
 # AST
-Python/ast.c                  @isidentical @JelleZijlstra
-Parser/asdl.py                @isidentical @JelleZijlstra
-Parser/asdl_c.py              @isidentical @JelleZijlstra
-Lib/ast.py                    @isidentical @JelleZijlstra
+Python/ast.c                  @isidentical @JelleZijlstra @eclips4
+Python/ast_opt.c              @isidentical @eclips4
+Parser/asdl.py                @isidentical @JelleZijlstra @eclips4
+Parser/asdl_c.py              @isidentical @JelleZijlstra @eclips4
+Lib/ast.py                    @isidentical @JelleZijlstra @eclips4
+Lib/test/test_ast/            @eclips4
 
 # Mock
 /Lib/unittest/mock.py         @cjw296

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.4.10
+    rev: v0.6.7
     hooks:
       - id: ruff
         name: Run Ruff (lint) on Doc/

Doc/Makefile

@@ -152,7 +152,7 @@ htmlview: html
 	$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/html/index.html'))"
 
 .PHONY: htmllive
-htmllive: SPHINXBUILD = $(VENVDIR)/bin/sphinx-autobuild
+htmllive: SPHINXBUILD = PATH=$(VENVDIR)/bin:$$PATH sphinx-autobuild
 htmllive: SPHINXOPTS = --re-ignore="/venv/" --open-browser --delay 0
 htmllive: _ensure-sphinx-autobuild html
 
@@ -182,13 +182,26 @@ venv:
 		echo "The venv has been created in the $(VENVDIR) directory"; \
 	fi
 
+.PHONY: dist-no-html
+dist-no-html: dist-text dist-pdf dist-epub dist-texinfo
+
 .PHONY: dist
 dist:
 	rm -rf dist
 	mkdir -p dist
-
+	$(MAKE) dist-html
+	$(MAKE) dist-text
+	$(MAKE) dist-pdf
+	$(MAKE) dist-epub
+	$(MAKE) dist-texinfo
+
+.PHONY: dist-html
+dist-html:
 	# archive the HTML
 	@echo "Building HTML..."
+	mkdir -p dist
+	rm -rf build/html
+	find dist -name 'python-$(DISTVERSION)-docs-html*' -exec rm -rf {} \;
 	$(MAKE) html
 	cp -pPR build/html dist/python-$(DISTVERSION)-docs-html
 	tar -C dist -cf dist/python-$(DISTVERSION)-docs-html.tar python-$(DISTVERSION)-docs-html
@@ -198,8 +211,13 @@ dist:
 	rm dist/python-$(DISTVERSION)-docs-html.tar
 	@echo "Build finished and archived!"
 
+.PHONY: dist-text
+dist-text:
 	# archive the text build
 	@echo "Building text..."
+	mkdir -p dist
+	rm -rf build/text
+	find dist -name 'python-$(DISTVERSION)-docs-text*' -exec rm -rf {} \;
 	$(MAKE) text
 	cp -pPR build/text dist/python-$(DISTVERSION)-docs-text
 	tar -C dist -cf dist/python-$(DISTVERSION)-docs-text.tar python-$(DISTVERSION)-docs-text
@@ -209,9 +227,13 @@ dist:
 	rm dist/python-$(DISTVERSION)-docs-text.tar
 	@echo "Build finished and archived!"
 
+.PHONY: dist-pdf
+dist-pdf:
 	# archive the A4 latex
 	@echo "Building LaTeX (A4 paper)..."
+	mkdir -p dist
 	rm -rf build/latex
+	find dist -name 'python-$(DISTVERSION)-docs-pdf*' -exec rm -rf {} \;
 	$(MAKE) latex PAPER=a4
 	# remove zip & bz2 dependency on all-pdf,
 	# as otherwise the full latexmk process is run twice.
@@ -222,16 +244,24 @@ dist:
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
 	@echo "Build finished and archived!"
 
+.PHONY: dist-epub
+dist-epub:
 	# copy the epub build
 	@echo "Building EPUB..."
+	mkdir -p dist
 	rm -rf build/epub
+	rm -f dist/python-$(DISTVERSION)-docs.epub
 	$(MAKE) epub
 	cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub
 	@echo "Build finished and archived!"
 
+.PHONY: dist-texinfo
+dist-texinfo:
 	# archive the texinfo build
 	@echo "Building Texinfo..."
+	mkdir -p dist
 	rm -rf build/texinfo
+	find dist -name 'python-$(DISTVERSION)-docs-texinfo*' -exec rm -rf {} \;
 	$(MAKE) texinfo
 	$(MAKE) info --directory=build/texinfo
 	cp -pPR build/texinfo dist/python-$(DISTVERSION)-docs-texinfo

Doc/c-api/complex.rst

@@ -79,6 +79,8 @@ pointers.  This is consistent throughout the API.
    If *num* is null and *exp* is not a positive real number,
    this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`.
 
+   Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
+
 
 Complex Numbers as Python Objects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Doc/c-api/exceptions.rst

@@ -1004,6 +1004,7 @@ the variables:
    single: PyExc_OverflowError (C var)
    single: PyExc_PermissionError (C var)
    single: PyExc_ProcessLookupError (C var)
+   single: PyExc_PythonFinalizationError (C var)
    single: PyExc_RecursionError (C var)
    single: PyExc_ReferenceError (C var)
    single: PyExc_RuntimeError (C var)
@@ -1096,6 +1097,8 @@ the variables:
 +-----------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_ProcessLookupError`      | :exc:`ProcessLookupError`       |          |
 +-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_PythonFinalizationError` | :exc:`PythonFinalizationError`  |          |
++-----------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_RecursionError`          | :exc:`RecursionError`           |          |
 +-----------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_ReferenceError`          | :exc:`ReferenceError`           |          |

Doc/c-api/long.rst

@@ -509,6 +509,8 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    Currently, ``-1`` corresponds to
    ``Py_ASNATIVEBYTES_NATIVE_ENDIAN | Py_ASNATIVEBYTES_UNSIGNED_BUFFER``.
 
+   .. c:namespace:: NULL
+
    ============================================= ======
    Flag                                          Value
    ============================================= ======

Doc/c-api/module.rst

@@ -421,6 +421,8 @@ The available slot types are:
 
    Specifies one of the following values:
 
+   .. c:namespace:: NULL
+
    .. c:macro:: Py_MOD_GIL_USED
 
       The module depends on the presence of the global interpreter lock (GIL),

Doc/c-api/monitoring.rst

@@ -1,6 +1,6 @@
 .. highlight:: c
 
-.. _monitoring:
+.. _c-api-monitoring:
 
 Monitoring C API
 ================
@@ -133,32 +133,60 @@ Managing the Monitoring State
 Monitoring states can be managed with the help of monitoring scopes. A scope
 would typically correspond to a python function.
 
-.. :c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)
+.. c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)
 
    Enter a monitored scope. ``event_types`` is an array of the event IDs for
    events that may be fired from the scope. For example, the ID of a ``PY_START``
    event is the value ``PY_MONITORING_EVENT_PY_START``, which is numerically equal
    to the base-2 logarithm of ``sys.monitoring.events.PY_START``.
    ``state_array`` is an array with a monitoring state entry for each event in
    ``event_types``, it is allocated by the user but populated by
-   ``PyMonitoring_EnterScope`` with information about the activation state of
+   :c:func:`!PyMonitoring_EnterScope` with information about the activation state of
    the event. The size of ``event_types`` (and hence also of ``state_array``)
    is given in ``length``.
 
    The ``version`` argument is a pointer to a value which should be allocated
    by the user together with ``state_array`` and initialized to 0,
-   and then set only by ``PyMonitoring_EnterScope`` itelf. It allows this
+   and then set only by :c:func:`!PyMonitoring_EnterScope` itelf. It allows this
    function to determine whether event states have changed since the previous call,
    and to return quickly if they have not.
 
    The scopes referred to here are lexical scopes: a function, class or method.
-   ``PyMonitoring_EnterScope`` should be called whenever the lexical scope is
+   :c:func:`!PyMonitoring_EnterScope` should be called whenever the lexical scope is
    entered. Scopes can be reentered, reusing the same *state_array* and *version*,
    in situations like when emulating a recursive Python function. When a code-like's
    execution is paused, such as when emulating a generator, the scope needs to
    be exited and re-entered.
 
-
-.. :c:function:: int PyMonitoring_ExitScope(void)
-
-   Exit the last scope that was entered with ``PyMonitoring_EnterScope``.
+   The macros for *event_types* are:
+
+   .. c:namespace:: NULL
+
+   .. The table is here to make the docs searchable, and to allow automatic
+      links to the identifiers.
+
+   ================================================== =====================================
+   Macro                                              Event
+   ================================================== =====================================
+   .. c:macro:: PY_MONITORING_EVENT_BRANCH            :monitoring-event:`BRANCH`
+   .. c:macro:: PY_MONITORING_EVENT_CALL              :monitoring-event:`CALL`
+   .. c:macro:: PY_MONITORING_EVENT_C_RAISE           :monitoring-event:`C_RAISE`
+   .. c:macro:: PY_MONITORING_EVENT_C_RETURN          :monitoring-event:`C_RETURN`
+   .. c:macro:: PY_MONITORING_EVENT_EXCEPTION_HANDLED :monitoring-event:`EXCEPTION_HANDLED`
+   .. c:macro:: PY_MONITORING_EVENT_INSTRUCTION       :monitoring-event:`INSTRUCTION`
+   .. c:macro:: PY_MONITORING_EVENT_JUMP              :monitoring-event:`JUMP`
+   .. c:macro:: PY_MONITORING_EVENT_LINE              :monitoring-event:`LINE`
+   .. c:macro:: PY_MONITORING_EVENT_PY_RESUME         :monitoring-event:`PY_RESUME`
+   .. c:macro:: PY_MONITORING_EVENT_PY_RETURN         :monitoring-event:`PY_RETURN`
+   .. c:macro:: PY_MONITORING_EVENT_PY_START          :monitoring-event:`PY_START`
+   .. c:macro:: PY_MONITORING_EVENT_PY_THROW          :monitoring-event:`PY_THROW`
+   .. c:macro:: PY_MONITORING_EVENT_PY_UNWIND         :monitoring-event:`PY_UNWIND`
+   .. c:macro:: PY_MONITORING_EVENT_PY_YIELD          :monitoring-event:`PY_YIELD`
+   .. c:macro:: PY_MONITORING_EVENT_RAISE             :monitoring-event:`RAISE`
+   .. c:macro:: PY_MONITORING_EVENT_RERAISE           :monitoring-event:`RERAISE`
+   .. c:macro:: PY_MONITORING_EVENT_STOP_ITERATION    :monitoring-event:`STOP_ITERATION`
+   ================================================== =====================================
+
+.. c:function:: int PyMonitoring_ExitScope(void)
+
+   Exit the last scope that was entered with :c:func:`!PyMonitoring_EnterScope`.

Doc/c-api/time.rst

@@ -1,5 +1,7 @@
 .. highlight:: c
 
+.. _c-api-time:
+
 PyTime C API
 ============
 

Doc/c-api/type.rst

@@ -264,6 +264,24 @@ Type Objects
 
    .. versionadded:: 3.11
 
+.. c:function:: int PyType_GetBaseByToken(PyTypeObject *type, void *token, PyTypeObject **result)
+
+   Find the first superclass in *type*'s :term:`method resolution order` whose
+   :c:macro:`Py_tp_token` token is equal to the given one.
+
+   * If found, set *\*result* to a new :term:`strong reference`
+     to it and return ``1``.
+   * If not found, set *\*result* to ``NULL`` and return ``0``.
+   * On error, set *\*result* to ``NULL`` and return ``-1`` with an
+     exception set.
+
+   The *result* argument may be ``NULL``, in which case *\*result* is not set.
+   Use this if you need only the return value.
+
+   The *token* argument may not be ``NULL``.
+
+   .. versionadded:: 3.14
+
 .. c:function:: int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)
 
    Attempt to assign a version tag to the given type.
@@ -488,6 +506,11 @@ The following functions and structs are used to create
       * ``Py_nb_add`` to set :c:member:`PyNumberMethods.nb_add`
       * ``Py_sq_length`` to set :c:member:`PySequenceMethods.sq_length`
 
+      An additional slot is supported that does not correspond to a
+      :c:type:`!PyTypeObject` struct field:
+
+      * :c:data:`Py_tp_token`
+
       The following “offset” fields cannot be set using :c:type:`PyType_Slot`:
 
          * :c:member:`~PyTypeObject.tp_weaklistoffset`
@@ -538,4 +561,47 @@ The following functions and structs are used to create
       The desired value of the slot. In most cases, this is a pointer
       to a function.
 
-      Slots other than ``Py_tp_doc`` may not be ``NULL``.
+      *pfunc* values may not be ``NULL``, except for the following slots:
+
+      * ``Py_tp_doc``
+      * :c:data:`Py_tp_token` (for clarity, prefer :c:data:`Py_TP_USE_SPEC`
+        rather than ``NULL``)
+
+.. c:macro:: Py_tp_token
+
+   A :c:member:`~PyType_Slot.slot` that records a static memory layout ID
+   for a class.
+
+   If the :c:type:`PyType_Spec` of the class is statically
+   allocated, the token can be set to the spec using the special value
+   :c:data:`Py_TP_USE_SPEC`:
+
+   .. code-block:: c
+
+      static PyType_Slot foo_slots[] = {
+         {Py_tp_token, Py_TP_USE_SPEC},
+
+   It can also be set to an arbitrary pointer, but you must ensure that:
+
+   * The pointer outlives the class, so it's not reused for something else
+     while the class exists.
+   * It "belongs" to the extension module where the class lives, so it will not
+     clash with other extensions.
+
+   Use :c:func:`PyType_GetBaseByToken` to check if a class's superclass has
+   a given token -- that is, check whether the memory layout is compatible.
+
+   To get the token for a given class (without considering superclasses),
+   use :c:func:`PyType_GetSlot` with ``Py_tp_token``.
+
+   .. versionadded:: 3.14
+
+   .. c:namespace:: NULL
+
+   .. c:macro:: Py_TP_USE_SPEC
+
+      Used as a value with :c:data:`Py_tp_token` to set the token to the
+      class's :c:type:`PyType_Spec`.
+      Expands to ``NULL``.
+
+      .. versionadded:: 3.14