Merge branch 'main' into long-from-dev_t

.gitattributes

@@ -94,7 +94,6 @@ Programs/test_frozenmain.h                          generated
 Python/Python-ast.c                                 generated
 Python/executor_cases.c.h                           generated
 Python/generated_cases.c.h                          generated
-Python/abstract_interp_cases.c.h                    generated
 Python/opcode_targets.h                             generated
 Python/stdlib_module_names.h                        generated
 Tools/peg_generator/pegen/grammar_parser.py         generated

.github/CODEOWNERS

@@ -157,6 +157,8 @@ Doc/c-api/stable.rst          @encukou
 
 **/*dataclasses*              @ericvsmith
 
+**/*ensurepip*                @pfmoore @pradyunsg
+
 **/*idlelib*                  @terryjreedy
 
 **/*typing*                   @JelleZijlstra @AlexWaygood

Doc/Makefile

@@ -19,8 +19,12 @@ SPHINXERRORHANDLING = -W
 PAPEROPT_a4     = -D latex_elements.papersize=a4paper
 PAPEROPT_letter = -D latex_elements.papersize=letterpaper
 
-ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees $(PAPEROPT_$(PAPER)) -j $(JOBS) \
-                $(SPHINXOPTS) $(SPHINXERRORHANDLING) . build/$(BUILDER) $(SOURCES)
+ALLSPHINXOPTS = -b $(BUILDER) \
+                -d build/doctrees \
+                -j $(JOBS) \
+                $(PAPEROPT_$(PAPER)) \
+                $(SPHINXOPTS) $(SPHINXERRORHANDLING) \
+                . build/$(BUILDER) $(SOURCES)
 
 .PHONY: help
 help:
@@ -142,7 +146,7 @@ htmlview: html
 
 .PHONY: htmllive
 htmllive: SPHINXBUILD = $(VENVDIR)/bin/sphinx-autobuild
-htmllive: SPHINXOPTS = --re-ignore="/venv/"
+htmllive: SPHINXOPTS = --re-ignore="/venv/" --open-browser --delay 0
 htmllive: html
 
 .PHONY: clean

Doc/howto/isolating-extensions.rst

@@ -337,7 +337,7 @@ That is, heap types should:
 
 - Have the :c:macro:`Py_TPFLAGS_HAVE_GC` flag.
 - Define a traverse function using ``Py_tp_traverse``, which
-  visits the type (e.g. using :c:expr:`Py_VISIT(Py_TYPE(self))`).
+  visits the type (e.g. using ``Py_VISIT(Py_TYPE(self))``).
 
 Please refer to the the documentation of
 :c:macro:`Py_TPFLAGS_HAVE_GC` and :c:member:`~PyTypeObject.tp_traverse`
@@ -482,7 +482,7 @@ The largest roadblock is getting *the class a method was defined in*, or
 that method's "defining class" for short. The defining class can have a
 reference to the module it is part of.
 
-Do not confuse the defining class with :c:expr:`Py_TYPE(self)`. If the method
+Do not confuse the defining class with ``Py_TYPE(self)``. If the method
 is called on a *subclass* of your type, ``Py_TYPE(self)`` will refer to
 that subclass, which may be defined in different module than yours.
 

Doc/howto/logging-cookbook.rst

@@ -332,10 +332,10 @@ Suppose you configure logging with the following JSON:
         }
     }
 
-This configuration does *almost* what we want, except that ``sys.stdout`` would
-show messages of severity ``ERROR`` and above as well as ``INFO`` and
-``WARNING`` messages. To prevent this, we can set up a filter which excludes
-those messages and add it to the relevant handler. This can be configured by
+This configuration does *almost* what we want, except that ``sys.stdout`` would show messages
+of severity ``ERROR`` and only events of this severity and higher will be tracked
+as well as ``INFO`` and ``WARNING`` messages. To prevent this, we can set up a filter which
+excludes those messages and add it to the relevant handler. This can be configured by
 adding a ``filters`` section parallel to ``formatters`` and ``handlers``:
 
 .. code-block:: json

Doc/howto/logging.rst

@@ -89,9 +89,8 @@ described below (in increasing order of severity):
 |              | itself may be unable to continue running.   |
 +--------------+---------------------------------------------+
 
-The default level is ``WARNING``, which means that only events of this level
-and above will be tracked, unless the logging package is configured to do
-otherwise.
+The default level is ``WARNING``, which means that only events of this severity and higher
+will be tracked, unless the logging package is configured to do otherwise.
 
 Events that are tracked can be handled in different ways. The simplest way of
 handling tracked events is to print them to the console. Another common way

Doc/library/ast.rst

@@ -45,7 +45,7 @@ Node classes
 
    This is the base of all AST node classes.  The actual node classes are
    derived from the :file:`Parser/Python.asdl` file, which is reproduced
-   :ref:`above <abstract-grammar>`.  They are defined in the :mod:`_ast` C
+   :ref:`above <abstract-grammar>`.  They are defined in the :mod:`!_ast` C
    module and re-exported in :mod:`ast`.
 
    There is one class defined for each left-hand side symbol in the abstract
@@ -128,14 +128,14 @@ Node classes
 
 .. deprecated:: 3.8
 
-   Old classes :class:`ast.Num`, :class:`ast.Str`, :class:`ast.Bytes`,
-   :class:`ast.NameConstant` and :class:`ast.Ellipsis` are still available,
+   Old classes :class:`!ast.Num`, :class:`!ast.Str`, :class:`!ast.Bytes`,
+   :class:`!ast.NameConstant` and :class:`!ast.Ellipsis` are still available,
    but they will be removed in future Python releases.  In the meantime,
    instantiating them will return an instance of a different class.
 
 .. deprecated:: 3.9
 
-   Old classes :class:`ast.Index` and :class:`ast.ExtSlice` are still
+   Old classes :class:`!ast.Index` and :class:`!ast.ExtSlice` are still
    available, but they will be removed in future Python releases.
    In the meantime, instantiating them will return an instance of
    a different class.
@@ -1935,8 +1935,7 @@ Function and class definitions
 .. class:: arg(arg, annotation, type_comment)
 
    A single argument in a list. ``arg`` is a raw string of the argument
-   name, ``annotation`` is its annotation, such as a :class:`Str` or
-   :class:`Name` node.
+   name; ``annotation`` is its annotation, such as a :class:`Name` node.
 
    .. attribute:: type_comment
 
@@ -2210,7 +2209,7 @@ and classes for traversing abstract syntax trees:
       Added ``type_comments``, ``mode='func_type'`` and ``feature_version``.
 
    .. versionchanged:: 3.13
-      The minimum supported version for feature_version is now (3,7)
+      The minimum supported version for ``feature_version`` is now ``(3, 7)``.
       The ``optimize`` argument was added.
 
 
@@ -2286,8 +2285,8 @@ and classes for traversing abstract syntax trees:
 .. function:: get_source_segment(source, node, *, padded=False)
 
    Get source code segment of the *source* that generated *node*.
-   If some location information (:attr:`lineno`, :attr:`end_lineno`,
-   :attr:`col_offset`, or :attr:`end_col_offset`) is missing, return ``None``.
+   If some location information (:attr:`~ast.AST.lineno`, :attr:`~ast.AST.end_lineno`,
+   :attr:`~ast.AST.col_offset`, or :attr:`~ast.AST.end_col_offset`) is missing, return ``None``.
 
    If *padded* is ``True``, the first line of a multi-line statement will
    be padded with spaces to match its original position.
@@ -2298,7 +2297,7 @@ and classes for traversing abstract syntax trees:
 .. function:: fix_missing_locations(node)
 
    When you compile a node tree with :func:`compile`, the compiler expects
-   :attr:`lineno` and :attr:`col_offset` attributes for every node that supports
+   :attr:`~ast.AST.lineno` and :attr:`~ast.AST.col_offset` attributes for every node that supports
    them.  This is rather tedious to fill in for generated nodes, so this helper
    adds these attributes recursively where not already set, by setting them to
    the values of the parent node.  It works recursively starting at *node*.
@@ -2313,8 +2312,8 @@ and classes for traversing abstract syntax trees:
 
 .. function:: copy_location(new_node, old_node)
 
-   Copy source location (:attr:`lineno`, :attr:`col_offset`, :attr:`end_lineno`,
-   and :attr:`end_col_offset`) from *old_node* to *new_node* if possible,
+   Copy source location (:attr:`~ast.AST.lineno`, :attr:`~ast.AST.col_offset`, :attr:`~ast.AST.end_lineno`,
+   and :attr:`~ast.AST.end_col_offset`) from *old_node* to *new_node* if possible,
    and return *new_node*.
 
 
@@ -2360,14 +2359,18 @@ and classes for traversing abstract syntax trees:
       visited unless the visitor calls :meth:`generic_visit` or visits them
       itself.
 
+   .. method:: visit_Constant(node)
+
+      Handles all constant nodes.
+
    Don't use the :class:`NodeVisitor` if you want to apply changes to nodes
    during traversal.  For this a special visitor exists
    (:class:`NodeTransformer`) that allows modifications.
 
    .. deprecated:: 3.8
 
-      Methods :meth:`visit_Num`, :meth:`visit_Str`, :meth:`visit_Bytes`,
-      :meth:`visit_NameConstant` and :meth:`visit_Ellipsis` are deprecated
+      Methods :meth:`!visit_Num`, :meth:`!visit_Str`, :meth:`!visit_Bytes`,
+      :meth:`!visit_NameConstant` and :meth:`!visit_Ellipsis` are deprecated
       now and will not be called in future Python versions.  Add the
       :meth:`visit_Constant` method to handle all constant nodes.
 
@@ -2396,7 +2399,7 @@ and classes for traversing abstract syntax trees:
               )
 
    Keep in mind that if the node you're operating on has child nodes you must
-   either transform the child nodes yourself or call the :meth:`generic_visit`
+   either transform the child nodes yourself or call the :meth:`~ast.NodeVisitor.generic_visit`
    method for the node first.
 
    For nodes that were part of a collection of statements (that applies to all
@@ -2405,7 +2408,7 @@ and classes for traversing abstract syntax trees:
 
    If :class:`NodeTransformer` introduces new nodes (that weren't part of
    original tree) without giving them location information (such as
-   :attr:`lineno`), :func:`fix_missing_locations` should be called with
+   :attr:`~ast.AST.lineno`), :func:`fix_missing_locations` should be called with
    the new sub-tree to recalculate the location information::
 
       tree = ast.parse('foo', mode='eval')
@@ -2457,6 +2460,13 @@ effects on the compilation of a program:
    Generates and returns an abstract syntax tree instead of returning a
    compiled code object.
 
+.. data:: PyCF_OPTIMIZED_AST
+
+   The returned AST is optimized according to the *optimize* argument
+   in :func:`compile` or :func:`ast.parse`.
+
+   .. versionadded:: 3.13
+
 .. data:: PyCF_TYPE_COMMENTS
 
    Enables support for :pep:`484` and :pep:`526` style type comments

Doc/library/bisect.rst

@@ -19,9 +19,9 @@ linear searches or frequent resorting.
 The module is called :mod:`bisect` because it uses a basic bisection
 algorithm to do its work.  Unlike other bisection tools that search for a
 specific value, the functions in this module are designed to locate an
-insertion point. Accordingly, the functions never call an :meth:`__eq__`
+insertion point. Accordingly, the functions never call an :meth:`~object.__eq__`
 method to determine whether a value has been found.  Instead, the
-functions only call the :meth:`__lt__` method and will return an insertion
+functions only call the :meth:`~object.__lt__` method and will return an insertion
 point between values in an array.
 
 .. _bisect functions:
@@ -73,7 +73,7 @@ The following functions are provided:
    Insert *x* in *a* in sorted order.
 
    This function first runs :py:func:`~bisect.bisect_left` to locate an insertion point.
-   Next, it runs the :meth:`insert` method on *a* to insert *x* at the
+   Next, it runs the :meth:`!insert` method on *a* to insert *x* at the
    appropriate position to maintain sort order.
 
    To support inserting records in a table, the *key* function (if any) is
@@ -93,7 +93,7 @@ The following functions are provided:
    entries of *x*.
 
    This function first runs :py:func:`~bisect.bisect_right` to locate an insertion point.
-   Next, it runs the :meth:`insert` method on *a* to insert *x* at the
+   Next, it runs the :meth:`!insert` method on *a* to insert *x* at the
    appropriate position to maintain sort order.
 
    To support inserting records in a table, the *key* function (if any) is

Doc/library/calendar.rst

@@ -196,6 +196,13 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
       output (defaulting to the system default encoding).
 
 
+   .. method:: formatmonthname(theyear, themonth, withyear=True)
+
+      Return a month name as an HTML table row. If *withyear* is true the year
+      will be included in the row, otherwise just the month name will be
+      used.
+
+
    :class:`!HTMLCalendar` has the following attributes you can override to
    customize the CSS classes used by the calendar:
 
@@ -289,7 +296,7 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
 
 .. note::
 
-   The constructor, :meth:`formatweekday` and :meth:`formatmonthname` methods
+   The constructor, :meth:`!formatweekday` and :meth:`!formatmonthname` methods
    of these two classes temporarily change the ``LC_TIME`` locale to the given
    *locale*. Because the current locale is a process-wide setting, they are
    not thread-safe.
@@ -358,7 +365,7 @@ For simple text calendars this module provides the following functions.
 
 .. function:: month(theyear, themonth, w=0, l=0)
 
-   Returns a month's calendar in a multi-line string using the :meth:`formatmonth`
+   Returns a month's calendar in a multi-line string using the :meth:`~TextCalendar.formatmonth`
    of the :class:`TextCalendar` class.
 
 
@@ -370,7 +377,7 @@ For simple text calendars this module provides the following functions.
 .. function:: calendar(year, w=2, l=1, c=6, m=3)
 
    Returns a 3-column calendar for an entire year as a multi-line string using
-   the :meth:`formatyear` of the :class:`TextCalendar` class.
+   the :meth:`~TextCalendar.formatyear` of the :class:`TextCalendar` class.
 
 
 .. function:: timegm(tuple)

Doc/library/cmd.rst

@@ -76,27 +76,30 @@ A :class:`Cmd` instance has the following methods:
       single: ! (exclamation); in a command interpreter
 
    An interpreter instance will recognize a command name ``foo`` if and only if it
-   has a method :meth:`do_foo`.  As a special case, a line beginning with the
+   has a method :meth:`!do_foo`.  As a special case, a line beginning with the
    character ``'?'`` is dispatched to the method :meth:`do_help`.  As another
    special case, a line beginning with the character ``'!'`` is dispatched to the
-   method :meth:`do_shell` (if such a method is defined).
+   method :meth:`!do_shell` (if such a method is defined).
 
    This method will return when the :meth:`postcmd` method returns a true value.
    The *stop* argument to :meth:`postcmd` is the return value from the command's
    corresponding :meth:`!do_\*` method.
 
    If completion is enabled, completing commands will be done automatically, and
-   completing of commands args is done by calling :meth:`complete_foo` with
+   completing of commands args is done by calling :meth:`!complete_foo` with
    arguments *text*, *line*, *begidx*, and *endidx*.  *text* is the string prefix
    we are attempting to match: all returned matches must begin with it. *line* is
    the current input line with leading whitespace removed, *begidx* and *endidx*
    are the beginning and ending indexes of the prefix text, which could be used to
    provide different completion depending upon which position the argument is in.
 
-   All subclasses of :class:`Cmd` inherit a predefined :meth:`do_help`.  This
+
+.. method:: Cmd.do_help(arg)
+
+   All subclasses of :class:`Cmd` inherit a predefined :meth:`!do_help`.  This
    method, called with an argument ``'bar'``, invokes the corresponding method
-   :meth:`help_bar`, and if that is not present, prints the docstring of
-   :meth:`do_bar`, if available.  With no argument, :meth:`do_help` lists all
+   :meth:`!help_bar`, and if that is not present, prints the docstring of
+   :meth:`!do_bar`, if available.  With no argument, :meth:`!do_help` lists all
    available help topics (that is, all commands with corresponding
    :meth:`!help_\*` methods or commands that have docstrings), and also lists any
    undocumented commands.
@@ -229,8 +232,8 @@ Instances of :class:`Cmd` subclasses have some public instance variables:
 .. attribute:: Cmd.use_rawinput
 
    A flag, defaulting to true.  If true, :meth:`cmdloop` uses :func:`input` to
-   display a prompt and read the next command; if false, :meth:`sys.stdout.write`
-   and :meth:`sys.stdin.readline` are used. (This means that by importing
+   display a prompt and read the next command; if false, :data:`sys.stdout.write() <sys.stdout>`
+   and :data:`sys.stdin.readline() <sys.stdin>` are used. (This means that by importing
    :mod:`readline`, on systems that support it, the interpreter will automatically
    support :program:`Emacs`\ -like line editing  and command-history keystrokes.)
 
@@ -249,14 +252,14 @@ This section presents a simple example of how to build a shell around a few of
 the commands in the :mod:`turtle` module.
 
 Basic turtle commands such as :meth:`~turtle.forward` are added to a
-:class:`Cmd` subclass with method named :meth:`do_forward`.  The argument is
+:class:`Cmd` subclass with method named :meth:`!do_forward`.  The argument is
 converted to a number and dispatched to the turtle module.  The docstring is
 used in the help utility provided by the shell.
 
 The example also includes a basic record and playback facility implemented with
 the :meth:`~Cmd.precmd` method which is responsible for converting the input to
-lowercase and writing the commands to a file.  The :meth:`do_playback` method
-reads the file and adds the recorded commands to the :attr:`cmdqueue` for
+lowercase and writing the commands to a file.  The :meth:`!do_playback` method
+reads the file and adds the recorded commands to the :attr:`~Cmd.cmdqueue` for
 immediate playback::
 
     import cmd, sys

Doc/library/collections.abc.rst

@@ -87,7 +87,7 @@ the required methods (unless those methods have been set to
 
     class E:
         def __iter__(self): ...
-        def __next__(next): ...
+        def __next__(self): ...
 
 .. doctest::
 

Doc/library/datetime.rst

@@ -1799,6 +1799,8 @@ Other constructor:
 
    Examples::
 
+   .. doctest::
+
        >>> from datetime import time
        >>> time.fromisoformat('04:23:01')
        datetime.time(4, 23, 1)
@@ -1808,7 +1810,7 @@ Other constructor:
        datetime.time(4, 23, 1)
        >>> time.fromisoformat('04:23:01.000384')
        datetime.time(4, 23, 1, 384)
-       >>> time.fromisoformat('04:23:01,000')
+       >>> time.fromisoformat('04:23:01,000384')
        datetime.time(4, 23, 1, 384)
        >>> time.fromisoformat('04:23:01+04:00')
        datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))

Doc/library/dbm.rst

@@ -272,6 +272,13 @@ This module can be used with the "classic" ndbm interface or the GNU GDBM
 compatibility interface. On Unix, the :program:`configure` script will attempt
 to locate the appropriate header file to simplify building this module.
 
+.. warning::
+
+   The ndbm library shipped as part of macOS has an undocumented limitation on the
+   size of values, which can result in corrupted database files
+   when storing values larger than this limit. Reading such corrupted files can
+   result in a hard crash (segmentation fault).
+
 .. exception:: error
 
    Raised on :mod:`dbm.ndbm`-specific errors, such as I/O errors. :exc:`KeyError` is raised