Merge branch 'main' into pythongh-112205-doc

Doc/conf.py

@@ -245,10 +245,12 @@
     # be resolved, as the method is currently undocumented. For context, see
     # https://github.com/python/cpython/pull/103289.
     ('py:meth', '_SubParsersAction.add_parser'),
-    # Attributes that definitely should be documented better,
+    # Attributes/methods/etc. that definitely should be documented better,
     # but are deferred for now:
     ('py:attr', '__annotations__'),
+    ('py:meth', '__missing__'),
     ('py:attr', '__wrapped__'),
+    ('py:meth', 'index'),  # list.index, tuple.index, etc.
 ]
 
 # gh-106948: Copy standard C types declared in the "c:type" domain to the

Doc/library/ast.rst

@@ -2457,6 +2457,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/collections.abc.rst

@@ -22,7 +22,7 @@
 
 This module provides :term:`abstract base classes <abstract base class>` that
 can be used to test whether a class provides a particular interface; for
-example, whether it is :term:`hashable` or whether it is a mapping.
+example, whether it is :term:`hashable` or whether it is a :term:`mapping`.
 
 An :func:`issubclass` or :func:`isinstance` test for an interface works in one
 of three ways.
@@ -73,7 +73,7 @@ of the API:
    >>> isinstance(D(), Sequence)
    True
 
-In this example, class :class:`D` does not need to define
+In this example, class :class:`!D` does not need to define
 ``__contains__``, ``__iter__``, and ``__reversed__`` because the
 :ref:`in-operator <comparisons>`, the :term:`iteration <iterable>`
 logic, and the :func:`reversed` function automatically fall back to
@@ -183,14 +183,14 @@ ABC                            Inherits from          Abstract Methods        Mi
 
 .. rubric:: Footnotes
 
-.. [1] These ABCs override :meth:`object.__subclasshook__` to support
+.. [1] These ABCs override :meth:`~abc.ABCMeta.__subclasshook__` to support
    testing an interface by verifying the required methods are present
    and have not been set to :const:`None`.  This only works for simple
    interfaces.  More complex interfaces require registration or direct
    subclassing.
 
 .. [2] Checking ``isinstance(obj, Iterable)`` detects classes that are
-   registered as :class:`Iterable` or that have an :meth:`__iter__`
+   registered as :class:`Iterable` or that have an :meth:`~container.__iter__`
    method, but it does not detect classes that iterate with the
    :meth:`~object.__getitem__` method.  The only reliable way to determine
    whether an object is :term:`iterable` is to call ``iter(obj)``.
@@ -202,26 +202,27 @@ Collections Abstract Base Classes -- Detailed Descriptions
 
 .. class:: Container
 
-   ABC for classes that provide the :meth:`__contains__` method.
+   ABC for classes that provide the :meth:`~object.__contains__` method.
 
 .. class:: Hashable
 
-   ABC for classes that provide the :meth:`__hash__` method.
+   ABC for classes that provide the :meth:`~object.__hash__` method.
 
 .. class:: Sized
 
-   ABC for classes that provide the :meth:`__len__` method.
+   ABC for classes that provide the :meth:`~object.__len__` method.
 
 .. class:: Callable
 
-   ABC for classes that provide the :meth:`__call__` method.
+   ABC for classes that provide the :meth:`~object.__call__` method.
 
 .. class:: Iterable
 
-   ABC for classes that provide the :meth:`__iter__` method.
+   ABC for classes that provide the :meth:`~container.__iter__` method.
 
    Checking ``isinstance(obj, Iterable)`` detects classes that are registered
-   as :class:`Iterable` or that have an :meth:`__iter__` method, but it does
+   as :class:`Iterable` or that have an :meth:`~container.__iter__` method,
+   but it does
    not detect classes that iterate with the :meth:`~object.__getitem__` method.
    The only reliable way to determine whether an object is :term:`iterable`
    is to call ``iter(obj)``.
@@ -240,17 +241,17 @@ Collections Abstract Base Classes -- Detailed Descriptions
 
 .. class:: Reversible
 
-   ABC for iterable classes that also provide the :meth:`__reversed__`
+   ABC for iterable classes that also provide the :meth:`~object.__reversed__`
    method.
 
    .. versionadded:: 3.6
 
 .. class:: Generator
 
-   ABC for generator classes that implement the protocol defined in
-   :pep:`342` that extends iterators with the :meth:`~generator.send`,
+   ABC for :term:`generator` classes that implement the protocol defined in
+   :pep:`342` that extends :term:`iterators <iterator>` with the
+   :meth:`~generator.send`,
    :meth:`~generator.throw` and :meth:`~generator.close` methods.
-   See also the definition of :term:`generator`.
 
    .. versionadded:: 3.5
 
@@ -261,7 +262,7 @@ Collections Abstract Base Classes -- Detailed Descriptions
    ABCs for read-only and mutable :term:`sequences <sequence>`.
 
    Implementation note: Some of the mixin methods, such as
-   :meth:`__iter__`, :meth:`__reversed__` and :meth:`index`, make
+   :meth:`~container.__iter__`, :meth:`~object.__reversed__` and :meth:`index`, make
    repeated calls to the underlying :meth:`~object.__getitem__` method.
    Consequently, if :meth:`~object.__getitem__` is implemented with constant
    access speed, the mixin methods will have linear performance;
@@ -282,7 +283,7 @@ Collections Abstract Base Classes -- Detailed Descriptions
 .. class:: Set
            MutableSet
 
-   ABCs for read-only and mutable sets.
+   ABCs for read-only and mutable :ref:`sets <types-set>`.
 
 .. class:: Mapping
            MutableMapping
@@ -299,42 +300,42 @@ Collections Abstract Base Classes -- Detailed Descriptions
 .. class:: Awaitable
 
    ABC for :term:`awaitable` objects, which can be used in :keyword:`await`
-   expressions.  Custom implementations must provide the :meth:`__await__`
-   method.
+   expressions.  Custom implementations must provide the
+   :meth:`~object.__await__` method.
 
    :term:`Coroutine <coroutine>` objects and instances of the
    :class:`~collections.abc.Coroutine` ABC are all instances of this ABC.
 
    .. note::
-      In CPython, generator-based coroutines (generators decorated with
-      :func:`types.coroutine`) are
-      *awaitables*, even though they do not have an :meth:`__await__` method.
+      In CPython, generator-based coroutines (:term:`generators <generator>`
+      decorated with :func:`@types.coroutine <types.coroutine>`) are
+      *awaitables*, even though they do not have an :meth:`~object.__await__` method.
       Using ``isinstance(gencoro, Awaitable)`` for them will return ``False``.
       Use :func:`inspect.isawaitable` to detect them.
 
    .. versionadded:: 3.5
 
 .. class:: Coroutine
 
-   ABC for coroutine compatible classes.  These implement the
+   ABC for :term:`coroutine` compatible classes.  These implement the
    following methods, defined in :ref:`coroutine-objects`:
    :meth:`~coroutine.send`, :meth:`~coroutine.throw`, and
    :meth:`~coroutine.close`.  Custom implementations must also implement
-   :meth:`__await__`.  All :class:`Coroutine` instances are also instances of
-   :class:`Awaitable`.  See also the definition of :term:`coroutine`.
+   :meth:`~object.__await__`.  All :class:`Coroutine` instances are also
+   instances of :class:`Awaitable`.
 
    .. note::
-      In CPython, generator-based coroutines (generators decorated with
-      :func:`types.coroutine`) are
-      *awaitables*, even though they do not have an :meth:`__await__` method.
+      In CPython, generator-based coroutines (:term:`generators <generator>`
+      decorated with :func:`@types.coroutine <types.coroutine>`) are
+      *awaitables*, even though they do not have an :meth:`~object.__await__` method.
       Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``.
       Use :func:`inspect.isawaitable` to detect them.
 
    .. versionadded:: 3.5
 
 .. class:: AsyncIterable
 
-   ABC for classes that provide ``__aiter__`` method.  See also the
+   ABC for classes that provide an ``__aiter__`` method.  See also the
    definition of :term:`asynchronous iterable`.
 
    .. versionadded:: 3.5
@@ -348,7 +349,7 @@ Collections Abstract Base Classes -- Detailed Descriptions
 
 .. class:: AsyncGenerator
 
-   ABC for asynchronous generator classes that implement the protocol
+   ABC for :term:`asynchronous generator` classes that implement the protocol
    defined in :pep:`525` and :pep:`492`.
 
    .. versionadded:: 3.6
@@ -373,9 +374,9 @@ particular functionality, for example::
 Several of the ABCs are also useful as mixins that make it easier to develop
 classes supporting container APIs.  For example, to write a class supporting
 the full :class:`Set` API, it is only necessary to supply the three underlying
-abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
-The ABC supplies the remaining methods such as :meth:`__and__` and
-:meth:`isdisjoint`::
+abstract methods: :meth:`~object.__contains__`, :meth:`~container.__iter__`, and
+:meth:`~object.__len__`. The ABC supplies the remaining methods such as
+:meth:`!__and__` and :meth:`~frozenset.isdisjoint`::
 
     class ListBasedSet(collections.abc.Set):
         ''' Alternate set implementation favoring space over speed
@@ -403,23 +404,24 @@ Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
 
 (1)
    Since some set operations create new sets, the default mixin methods need
-   a way to create new instances from an iterable. The class constructor is
+   a way to create new instances from an :term:`iterable`. The class constructor is
    assumed to have a signature in the form ``ClassName(iterable)``.
-   That assumption is factored-out to an internal classmethod called
-   :meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set.
+   That assumption is factored-out to an internal :class:`classmethod` called
+   :meth:`!_from_iterable` which calls ``cls(iterable)`` to produce a new set.
    If the :class:`Set` mixin is being used in a class with a different
-   constructor signature, you will need to override :meth:`_from_iterable`
+   constructor signature, you will need to override :meth:`!_from_iterable`
    with a classmethod or regular method that can construct new instances from
    an iterable argument.
 
 (2)
    To override the comparisons (presumably for speed, as the
-   semantics are fixed), redefine :meth:`__le__` and :meth:`__ge__`,
+   semantics are fixed), redefine :meth:`~object.__le__` and
+   :meth:`~object.__ge__`,
    then the other operations will automatically follow suit.
 
 (3)
-   The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash value
-   for the set; however, :meth:`__hash__` is not defined because not all sets
+   The :class:`Set` mixin provides a :meth:`!_hash` method to compute a hash value
+   for the set; however, :meth:`~object.__hash__` is not defined because not all sets
    are :term:`hashable` or immutable.  To add set hashability using mixins,
    inherit from both :meth:`Set` and :meth:`Hashable`, then define
    ``__hash__ = Set._hash``.

Doc/library/csv.rst

@@ -55,10 +55,11 @@ The :mod:`csv` module defines the following functions:
 
 .. function:: reader(csvfile, dialect='excel', **fmtparams)
 
-   Return a reader object which will iterate over lines in the given *csvfile*.
-   *csvfile* can be any object which supports the :term:`iterator` protocol and returns a
-   string each time its :meth:`!__next__` method is called --- :term:`file objects
-   <file object>` and list objects are both suitable.   If *csvfile* is a file object,
+   Return a :ref:`reader object <reader-objects>` that will process
+   lines from the given *csvfile*.  A csvfile must be an iterable of
+   strings, each in the reader's defined csv format.
+   A csvfile is most commonly a file-like object or list.
+   If *csvfile* is a file object,
    it should be opened with ``newline=''``. [1]_  An optional
    *dialect* parameter can be given which is used to define a set of parameters
    specific to a particular CSV dialect.  It may be an instance of a subclass of
@@ -449,6 +450,8 @@ Dialects support the following attributes:
    When ``True``, raise exception :exc:`Error` on bad CSV input.
    The default is ``False``.
 
+.. _reader-objects:
+
 Reader Objects
 --------------
 

Doc/library/datetime.rst

@@ -1985,7 +1985,8 @@ Examples of working with a :class:`.time` object::
    American EST and EDT.
 
    Special requirement for pickling:  A :class:`tzinfo` subclass must have an
-   :meth:`__init__` method that can be called with no arguments, otherwise it can be
+   :meth:`~object.__init__` method that can be called with no arguments,
+   otherwise it can be
    pickled but possibly not unpickled again. This is a technical requirement that
    may be relaxed in the future.
 

Doc/library/email.utils.rst

@@ -58,13 +58,18 @@ of the new API.
    begins with angle brackets, they are stripped off.
 
 
-.. function:: parseaddr(address)
+.. function:: parseaddr(address, *, strict=True)
 
    Parse address -- which should be the value of some address-containing field such
    as :mailheader:`To` or :mailheader:`Cc` -- into its constituent *realname* and
    *email address* parts.  Returns a tuple of that information, unless the parse
    fails, in which case a 2-tuple of ``('', '')`` is returned.
 
+   If *strict* is true, use a strict parser which rejects malformed inputs.
+
+   .. versionchanged:: 3.13
+      Add *strict* optional parameter and reject malformed inputs by default.
+
 
 .. function:: formataddr(pair, charset='utf-8')
 
@@ -82,12 +87,15 @@ of the new API.
       Added the *charset* option.
 
 
-.. function:: getaddresses(fieldvalues)
+.. function:: getaddresses(fieldvalues, *, strict=True)
 
    This method returns a list of 2-tuples of the form returned by ``parseaddr()``.
    *fieldvalues* is a sequence of header field values as might be returned by
-   :meth:`Message.get_all <email.message.Message.get_all>`.  Here's a simple
-   example that gets all the recipients of a message::
+   :meth:`Message.get_all <email.message.Message.get_all>`.
+
+   If *strict* is true, use a strict parser which rejects malformed inputs.
+
+   Here's a simple example that gets all the recipients of a message::
 
       from email.utils import getaddresses
 
@@ -97,6 +105,9 @@ of the new API.
       resent_ccs = msg.get_all('resent-cc', [])
       all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
 
+   .. versionchanged:: 3.13
+      Add *strict* optional parameter and reject malformed inputs by default.
+
 
 .. function:: parsedate(date)
 

Doc/library/exceptions.rst

@@ -1009,9 +1009,9 @@ their subgroups based on the types of the contained exceptions.
          True
 
 
-   Note that :exc:`BaseExceptionGroup` defines :meth:`__new__`, so
+   Note that :exc:`BaseExceptionGroup` defines :meth:`~object.__new__`, so
    subclasses that need a different constructor signature need to
-   override that rather than :meth:`__init__`. For example, the following
+   override that rather than :meth:`~object.__init__`. For example, the following
    defines an exception group subclass which accepts an exit_code and
    and constructs the group's message from it. ::
 

Doc/library/fractions.rst

@@ -106,6 +106,10 @@ another rational number, or from a string.
       presentation types ``"e"``, ``"E"``, ``"f"``, ``"F"``, ``"g"``, ``"G"``
       and ``"%""``.
 
+   .. versionchanged:: 3.13
+      Formatting of :class:`Fraction` instances without a presentation type
+      now supports fill, alignment, sign handling, minimum width and grouping.
+
    .. attribute:: numerator
 
       Numerator of the Fraction in lowest term.
@@ -201,17 +205,36 @@ another rational number, or from a string.
 
    .. method:: __format__(format_spec, /)
 
-      Provides support for float-style formatting of :class:`Fraction`
-      instances via the :meth:`str.format` method, the :func:`format` built-in
-      function, or :ref:`Formatted string literals <f-strings>`. The
-      presentation types ``"e"``, ``"E"``, ``"f"``, ``"F"``, ``"g"``, ``"G"``
-      and ``"%"`` are supported. For these presentation types, formatting for a
-      :class:`Fraction` object ``x`` follows the rules outlined for
-      the :class:`float` type in the :ref:`formatspec` section.
+      Provides support for formatting of :class:`Fraction` instances via the
+      :meth:`str.format` method, the :func:`format` built-in function, or
+      :ref:`Formatted string literals <f-strings>`.
+
+      If the ``format_spec`` format specification string does not end with one
+      of the presentation types ``'e'``, ``'E'``, ``'f'``, ``'F'``, ``'g'``,
+      ``'G'`` or ``'%'`` then formatting follows the general rules for fill,
+      alignment, sign handling, minimum width, and grouping as described in the
+      :ref:`format specification mini-language <formatspec>`. The "alternate
+      form" flag ``'#'`` is supported: if present, it forces the output string
+      to always include an explicit denominator, even when the value being
+      formatted is an exact integer. The zero-fill flag ``'0'`` is not
+      supported.
+
+      If the ``format_spec`` format specification string ends with one of
+      the presentation types ``'e'``, ``'E'``, ``'f'``, ``'F'``, ``'g'``,
+      ``'G'`` or ``'%'`` then formatting follows the rules outlined for the
+      :class:`float` type in the :ref:`formatspec` section.
 
       Here are some examples::
 
          >>> from fractions import Fraction
+         >>> format(Fraction(103993, 33102), '_')
+         '103_993/33_102'
+         >>> format(Fraction(1, 7), '.^+10')
+         '...+1/7...'
+         >>> format(Fraction(3, 1), '')
+         '3'
+         >>> format(Fraction(3, 1), '#')
+         '3/1'
          >>> format(Fraction(1, 7), '.40g')
          '0.1428571428571428571428571428571428571429'
          >>> format(Fraction('1234567.855'), '_.2f')