Merge branch 'develop' into gh42765-timit-execution-environment

Author: richardhob

.gitattributes

@@ -66,6 +66,8 @@ PCbuild/readme.txt  dos
 [attr]generated linguist-generated=true diff=generated
 
 **/clinic/*.c.h                                     generated
+**/clinic/*.cpp.h                                   generated
+**/clinic/*.h.h                                     generated
 *_db.h                                              generated
 Doc/data/stable_abi.dat                             generated
 Doc/library/token-list.inc                          generated

.github/workflows/mypy.yml

@@ -9,6 +9,7 @@ on:
     paths:
       - "Tools/clinic/**"
       - "Tools/cases_generator/**"
+      - "Tools/peg_generator/**"
       - "Tools/requirements-dev.txt"
       - ".github/workflows/mypy.yml"
   workflow_dispatch:
@@ -29,7 +30,11 @@ jobs:
   mypy:
     strategy:
       matrix:
-        target: ["Tools/cases_generator", "Tools/clinic"]
+        target: [
+          "Tools/cases_generator",
+          "Tools/clinic",
+          "Tools/peg_generator",
+        ]
     name: Run mypy on ${{ matrix.target }}
     runs-on: ubuntu-latest
     timeout-minutes: 10

Doc/c-api/stable.rst

@@ -18,7 +18,7 @@ way; see :ref:`stable-abi-platform` below).
 So, code compiled for Python 3.10.0 will work on 3.10.8 and vice versa,
 but will need to be compiled separately for 3.9.x and 3.10.x.
 
-There are two tiers of C API with different stability exepectations:
+There are two tiers of C API with different stability expectations:
 
 - :ref:`Unstable API <unstable-c-api>`, may change in minor versions without
   a deprecation period. It is marked by the ``PyUnstable`` prefix in names.

Doc/c-api/typeobj.rst

@@ -528,28 +528,6 @@ type objects) *must* have the :c:member:`~PyVarObject.ob_size` field.
    This field is inherited by subtypes.
 
 
-.. c:member:: PyObject* PyObject._ob_next
-             PyObject* PyObject._ob_prev
-
-   These fields are only present when the macro ``Py_TRACE_REFS`` is defined
-   (see the :option:`configure --with-trace-refs option <--with-trace-refs>`).
-
-   Their initialization to ``NULL`` is taken care of by the
-   ``PyObject_HEAD_INIT`` macro.  For :ref:`statically allocated objects
-   <static-types>`, these fields always remain ``NULL``.  For :ref:`dynamically
-   allocated objects <heap-types>`, these two fields are used to link the
-   object into a doubly linked list of *all* live objects on the heap.
-
-   This could be used for various debugging purposes; currently the only uses
-   are the :func:`sys.getobjects` function and to print the objects that are
-   still alive at the end of a run when the environment variable
-   :envvar:`PYTHONDUMPREFS` is set.
-
-   **Inheritance:**
-
-   These fields are not inherited by subtypes.
-
-
 PyVarObject Slots
 -----------------
 
@@ -1728,7 +1706,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    treated as read-only.
 
    Some types may not store their dictionary in this slot.
-   Use :c:func:`PyType_GetDict` to retreive the dictionary for an arbitrary
+   Use :c:func:`PyType_GetDict` to retrieve the dictionary for an arbitrary
    type.
 
    .. versionchanged:: 3.12

Doc/howto/clinic.rst

@@ -158,7 +158,7 @@ process a single source file, like this:
 The CLI supports the following options:
 
 .. program:: ./Tools/clinic/clinic.py [-h] [-f] [-o OUTPUT] [-v] \
-             [--converters] [--make] [--srcdir SRCDIR] [FILE ...]
+             [--converters] [--make] [--srcdir SRCDIR] [--limited] [FILE ...]
 
 .. option:: -h, --help
 
@@ -193,6 +193,11 @@ The CLI supports the following options:
    A file to exclude in :option:`--make` mode.
    This option can be given multiple times.
 
+.. option:: --limited
+
+    Use the :ref:`Limited API <limited-c-api>` to parse arguments in the generated C code.
+    See :ref:`clinic-howto-limited-capi`.
+
 .. option:: FILE ...
 
    The list of files to process.
@@ -1905,6 +1910,22 @@ blocks embedded in Python files look slightly different.  They look like this:
     #/*[python checksum:...]*/
 
 
+.. _clinic-howto-limited-capi:
+
+How to use the Limited C API
+----------------------------
+
+If Argument Clinic :term:`input` is located within a C source file
+that contains ``#define Py_LIMITED_API``, Argument Clinic will generate C code
+that uses the :ref:`Limited API <limited-c-api>` to parse arguments. The
+advantage of this is that the generated code will not use private functions.
+However, this *can* result in Argument Clinic generating less efficient code
+in some cases. The extent of the performance penalty will depend
+on the parameters (types, number, etc.).
+
+.. versionadded:: 3.13
+
+
 .. _clinic-howto-override-signature:
 
 How to override the generated signature

Doc/howto/enum.rst

@@ -426,10 +426,17 @@ enumeration, with the exception of special methods (:meth:`__str__`,
 :meth:`__add__`, etc.), descriptors (methods are also descriptors), and
 variable names listed in :attr:`_ignore_`.
 
-Note:  if your enumeration defines :meth:`__new__` and/or :meth:`__init__` then
+Note:  if your enumeration defines :meth:`__new__` and/or :meth:`__init__`,
 any value(s) given to the enum member will be passed into those methods.
 See `Planet`_ for an example.
 
+.. note::
+
+    The :meth:`__new__` method, if defined, is used during creation of the Enum
+    members; it is then replaced by Enum's :meth:`__new__` which is used after
+    class creation for lookup of existing members.  See :ref:`new-vs-init` for
+    more details.
+
 
 Restricted Enum subclassing
 ---------------------------
@@ -895,6 +902,8 @@ Some rules:
    :meth:`__str__` method has been reset to their data types'
    :meth:`__str__` method.
 
+.. _new-vs-init:
+
 When to use :meth:`__new__` vs. :meth:`__init__`
 ------------------------------------------------
 
@@ -927,6 +936,11 @@ want one of them to be the value::
     >>> print(Coordinate(3))
     Coordinate.VY
 
+.. warning::
+
+    *Do not* call ``super().__new__()``, as the lookup-only ``__new__`` is the one
+    that is found; instead, use the data type directly.
+
 
 Finer Points
 ^^^^^^^^^^^^
@@ -1353,6 +1367,13 @@ to handle any extra arguments::
     members; it is then replaced by Enum's :meth:`__new__` which is used after
     class creation for lookup of existing members.
 
+.. warning::
+
+    *Do not* call ``super().__new__()``, as the lookup-only ``__new__`` is the one
+    that is found; instead, use the data type directly -- e.g.::
+
+       obj = int.__new__(cls, value)
+
 
 OrderedEnum
 ^^^^^^^^^^^

Doc/howto/logging-cookbook.rst

@@ -761,7 +761,7 @@ printed on the console; on the server side, you should see something like:
 
 Note that there are some security issues with pickle in some scenarios. If
 these affect you, you can use an alternative serialization scheme by overriding
-the :meth:`~handlers.SocketHandler.makePickle` method and implementing your
+the :meth:`~SocketHandler.makePickle` method and implementing your
 alternative there, as well as adapting the above script to use your alternative
 serialization.
 
@@ -835,6 +835,8 @@ To test these files, do the following in a POSIX environment:
 You may need to tweak the configuration files in the unlikely event that the
 configured ports clash with something else in your test environment.
 
+.. currentmodule:: logging
+
 .. _context-info:
 
 Adding contextual information to your logging output
@@ -1546,7 +1548,7 @@ Sometimes you want to let a log file grow to a certain size, then open a new
 file and log to that. You may want to keep a certain number of these files, and
 when that many files have been created, rotate the files so that the number of
 files and the size of the files both remain bounded. For this usage pattern, the
-logging package provides a :class:`~handlers.RotatingFileHandler`::
+logging package provides a :class:`RotatingFileHandler`::
 
    import glob
    import logging
@@ -1594,6 +1596,8 @@ and each time it reaches the size limit it is renamed with the suffix
 Obviously this example sets the log length much too small as an extreme
 example.  You would want to set *maxBytes* to an appropriate value.
 
+.. currentmodule:: logging
+
 .. _format-styles:
 
 Use of alternative formatting styles
@@ -1840,6 +1844,7 @@ However, it should be borne in mind that each link in the chain adds run-time
 overhead to all logging operations, and the technique should only be used when
 the use of a :class:`Filter` does not provide the desired result.
 
+.. currentmodule:: logging.handlers
 
 .. _zeromq-handlers:
 
@@ -1917,6 +1922,8 @@ of queues, for example a ZeroMQ 'subscribe' socket. Here's an example::
    :ref:`A more advanced logging tutorial <logging-advanced-tutorial>`
 
 
+.. currentmodule:: logging
+
 An example dictionary-based configuration
 -----------------------------------------
 
@@ -3918,8 +3925,8 @@ that in other languages such as Java and C#, loggers are often static class
 attributes. However, this pattern doesn't make sense in Python, where the
 module (and not the class) is the unit of software decomposition.
 
-Adding handlers other than :class:`NullHandler` to a logger in a library
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Adding handlers other than :class:`~logging.NullHandler` to a logger in a library
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Configuring logging by adding handlers, formatters and filters is the
 responsibility of the application developer, not the library developer. If you

Doc/library/ast.rst

@@ -585,7 +585,7 @@ Expressions
    :class:`Name` or :class:`Attribute` object. Of the arguments:
 
    * ``args`` holds a list of the arguments passed by position.
-   * ``keywords`` holds a list of :class:`keyword` objects representing
+   * ``keywords`` holds a list of :class:`.keyword` objects representing
      arguments passed by keyword.
 
    When creating a ``Call`` node, ``args`` and ``keywords`` are required, but
@@ -2024,7 +2024,7 @@ Function and class definitions
 
    * ``name`` is a raw string for the class name
    * ``bases`` is a list of nodes for explicitly specified base classes.
-   * ``keywords`` is a list of :class:`keyword` nodes, principally for 'metaclass'.
+   * ``keywords`` is a list of :class:`.keyword` nodes, principally for 'metaclass'.
      Other keywords will be passed to the metaclass, as per `PEP-3115
      <https://peps.python.org/pep-3115/>`_.
    * ``body`` is a list of nodes representing the code within the class

Doc/library/idle.rst

@@ -479,7 +479,7 @@ Search and Replace
 
 Any selection becomes a search target.  However, only selections within
 a line work because searches are only performed within lines with the
-terminal newline removed.  If ``[x] Regular expresion`` is checked, the
+terminal newline removed.  If ``[x] Regular expression`` is checked, the
 target is interpreted according to the Python re module.
 
 .. _completions:

Doc/library/importlib.rst

@@ -1270,7 +1270,7 @@ an :term:`importer`.
 
    You can get the same effect as this function by implementing the
    basic interface of multi-phase init (:pep:`489`) and lying about
-   support for mulitple interpreters (or per-interpreter GIL).
+   support for multiple interpreters (or per-interpreter GIL).
 
    .. warning::
       Using this function to disable the check can lead to