Merge branch 'main' into promote/mdiff

Author: kesara

Doc/library/ast.rst

@@ -2254,7 +2254,7 @@ and classes for traversing abstract syntax trees:
 
    In addition, if ``mode`` is ``'func_type'``, the input syntax is
    modified to correspond to :pep:`484` "signature type comments",
-   e.g. ``(str, int) -> List[str]``.
+   for example ``(str, int) -> List[str]``.
 
    Setting ``feature_version`` to a tuple ``(major, minor)`` will result in
    a "best-effort" attempt to parse using that Python version's grammar.

Doc/library/asyncio-task.rst

@@ -356,7 +356,7 @@ and reliable way to wait for all tasks in the group to finish.
       The signature matches that of :func:`asyncio.create_task`.
       If the task group is inactive (e.g. not yet entered,
       already finished, or in the process of shutting down),
-      we will close the given ``coro``.
+      we will close the given ``coro`` and raise :exc:`RuntimeError`.
 
       .. versionchanged:: 3.13
 

Doc/library/concurrent.interpreters.rst

@@ -191,7 +191,7 @@ objects are either directly shared or copied efficiently.  For example:
 * :class:`float`
 * :class:`tuple` (of similarly supported objects)
 
-There is a small number of Python types that actually share mutable
+There are a small number of Python types that actually share mutable
 data between interpreters:
 
 * :class:`memoryview`
@@ -274,7 +274,7 @@ Interpreter objects
 
    .. method:: call(callable, /, *args, **kwargs)
 
-      Return the result of calling running the given function in the
+      Return the result of running the given function in the
       interpreter (in the current thread).
 
    .. _interp-call-in-thread:

Doc/library/ctypes.rst

@@ -715,8 +715,11 @@ Specifying function pointers using type annotations
    and do not have to match the underlying C implementation.
 
    If the decorated function does not have a return type annotation, a
-   :exc:`ValueError` is raised. If the name of the function does not exist
-   in *dll*, an :exc:`AttributeError` is raised.
+   :exc:`ValueError` is raised. A :exc:`ValueError` is also raised if it has a
+   keyword-only, ``*args``, or ``**kwargs`` parameter, since
+   :attr:`~ctypes._CFuncPtr.argtypes` describes positional arguments only. If
+   the name of the function does not exist in *dll*, an :exc:`AttributeError`
+   is raised.
 
    For example::
 

Doc/library/functions.rst

@@ -65,14 +65,54 @@ are always available.  They are listed here in alphabetical order.
 
 
 .. function:: aiter(async_iterable, /)
+              aiter(callable, /, stop_value, *, stop_exception=StopAsyncIteration)
+              aiter(callable, /, *, stop_exception)
+
+   Return an :term:`asynchronous iterator` object.
+   The first argument is interpreted very differently
+   depending on the presence of the other arguments.
+   Without other arguments,
+   the single argument must be an :term:`asynchronous iterable`,
+   and the result is equivalent to calling ``x.__aiter__()``.
+
+   If *stop_value* or *stop_exception* is given,
+   then the first argument must be a callable object.
+   The asynchronous iterator created in this case
+   calls *callable* with no arguments and awaits the result
+   for each call to its :meth:`~object.__anext__` method;
+   if the awaited value is equal to *stop_value*,
+   or if the call raises an exception matching *stop_exception*,
+   :exc:`StopAsyncIteration` will be raised,
+   otherwise the value will be returned.
+   The callable is only called when the result of :meth:`~object.__anext__`
+   is awaited.
+
+   *stop_exception* is an exception class or a tuple of exception classes.
+   If *stop_value* is not specified,
+   the iteration stops only when the callable raises an exception.
+   If the callable raises :exc:`StopAsyncIteration`
+   which does not match *stop_exception*,
+   it is replaced with a :exc:`RuntimeError`,
+   as for asynchronous generators (see :pep:`525`).
+
+   For example, reading fixed-size chunks from an asynchronous stream
+   until the end of file is reached::
 
-   Return an :term:`asynchronous iterator` for an :term:`asynchronous iterable`.
-   Equivalent to calling ``x.__aiter__()``.
+      from functools import partial
+      async for chunk in aiter(partial(reader.read, 1024), b''):
+          process_chunk(chunk)
+
+   Or consuming an :class:`asyncio.Queue` until it is shut down::
 
-   Note: Unlike :func:`iter`, :func:`aiter` has no 2-argument variant.
+      from asyncio import QueueShutDown
+      async for item in aiter(queue.get, stop_exception=QueueShutDown):
+          process_item(item)
 
    .. versionadded:: 3.10
 
+   .. versionchanged:: next
+      Added the *stop_value* and *stop_exception* parameters.
+
 .. function:: all(iterable, /)
 
    Return ``True`` if all elements of the *iterable* are true (or if the iterable
@@ -1143,22 +1183,34 @@ are always available.  They are listed here in alphabetical order.
 
 
 .. function:: iter(iterable, /)
-              iter(callable, sentinel, /)
+              iter(callable, /, stop_value, *, stop_exception=StopIteration)
+              iter(callable, /, *, stop_exception)
 
    Return an :term:`iterator` object.  The first argument is interpreted very
-   differently depending on the presence of the second argument. Without a
-   second argument, the single argument must be a collection object which supports the
+   differently depending on the presence of the other arguments. Without other
+   arguments, the single argument must be a collection object which supports the
    :term:`iterable` protocol (the :meth:`~object.__iter__` method),
    or it must support
    the sequence protocol (the :meth:`~object.__getitem__` method with integer arguments
    starting at ``0``).  If it does not support either of those protocols,
-   :exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
+   :exc:`TypeError` is raised.
+
+   If *stop_value* or *stop_exception* is given,
    then the first argument must be a callable object.  The iterator created in this case
    will call *callable* with no arguments for each call to its
    :meth:`~iterator.__next__` method; if the value returned is equal to
-   *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will
+   *stop_value*, or if the call raises an exception matching *stop_exception*,
+   :exc:`StopIteration` will be raised, otherwise the value will
    be returned.
 
+   *stop_exception* is an exception class or a tuple of exception classes.
+   If *stop_value* is not specified,
+   the iteration stops only when the callable raises an exception.
+   If the callable raises :exc:`StopIteration`
+   which does not match *stop_exception*,
+   it is replaced with a :exc:`RuntimeError`,
+   as for generators (see :pep:`479`).
+
    See also :ref:`typeiter`.
 
    One useful application of the second form of :func:`iter` is to build a
@@ -1170,6 +1222,19 @@ are always available.  They are listed here in alphabetical order.
           for block in iter(partial(f.read, 64), b''):
               process_block(block)
 
+   *stop_exception* is useful for callables
+   which report exhaustion by raising an exception
+   instead of returning a special value.
+   For example, draining a queue::
+
+      import queue
+      for item in iter(input_queue.get_nowait, stop_exception=queue.Empty):
+          process_item(item)
+
+   .. versionchanged:: next
+      Added the *stop_exception* parameter
+      and allowed passing *stop_value* by keyword.
+
 
 .. function:: len(object, /)
 

Doc/library/mimetypes.rst

@@ -211,8 +211,8 @@ than one MIME-type database; it provides an interface similar to the one of the
 .. class:: MimeTypes(filenames=(), strict=True)
 
    This class represents a MIME-types database.  By default, it provides access to
-   the same database as the rest of this module. The initial database is a copy of
-   that provided by the module, and may be extended by loading additional
+   the same database as the rest of this module. The initial database is created from
+   Python's built-in MIME type tables. It may be extended by loading additional
    :file:`mime.types`\ -style files into the database using the :meth:`read` or
    :meth:`readfp` methods.  The mapping dictionaries may also be cleared before
    loading additional data if the default data is not desired.
@@ -226,30 +226,32 @@ than one MIME-type database; it provides an interface similar to the one of the
       Dictionary mapping suffixes to suffixes.  This is used to allow recognition of
       encoded files for which the encoding and the type are indicated by the same
       extension.  For example, the :file:`.tgz` extension is mapped to :file:`.tar.gz`
-      to allow the encoding and type to be recognized separately.  This is initially a
-      copy of the global :data:`suffix_map` defined in the module.
+      to allow the encoding and type to be recognized separately.
+      This is initialized with some predefined values.
 
 
    .. attribute:: MimeTypes.encodings_map
 
-      Dictionary mapping filename extensions to encoding types.  This is initially a
-      copy of the global :data:`encodings_map` defined in the module.
+      Dictionary mapping filename extensions to encoding types.
+      This is initialized with some predefined values.
 
 
    .. attribute:: MimeTypes.types_map
 
       Tuple containing two dictionaries, mapping filename extensions to MIME types:
       the first dictionary is for the non-standards types and the second one is for
-      the standard types. They are initialized by :data:`common_types` and
-      :data:`types_map`.
+      the standard types.
+      They are initialized with some predefined values and MIME type
+      information loaded from files specified by the *filenames* argument.
 
 
    .. attribute:: MimeTypes.types_map_inv
 
       Tuple containing two dictionaries, mapping MIME types to a list of filename
       extensions: the first dictionary is for the non-standards types and the
-      second one is for the standard types. They are initialized by
-      :data:`common_types` and :data:`types_map`.
+      second one is for the standard types.
+      They are initialized with some predefined values and MIME type
+      information loaded from files specified by the *filenames* argument.
 
 
    .. method:: MimeTypes.guess_extension(type, strict=True)

Doc/library/pyexpat.rst

@@ -172,6 +172,20 @@ XMLParser Objects
    or ``None`` if  :meth:`SetBase` hasn't been called.
 
 
+.. method:: xmlparser.GetSpecifiedAttributeCount()
+
+   Return the index just past the attributes given in the start tag.
+   Attributes defaulted from the DTD follow the specified ones,
+   so attributes at lower indices in the list
+   passed to :attr:`StartElementHandler` were given in the start tag.
+   Each attribute takes two items in that list,
+   its name and its value.
+   Only meaningful inside a :attr:`StartElementHandler` call,
+   and only if :attr:`ordered_attributes` is true.
+
+   .. versionadded:: next
+
+
 .. method:: xmlparser.GetInputContext()
 
    Returns the input data that generated the current event as a string. The data is

Doc/library/site.rst

@@ -453,9 +453,10 @@ Module contents
 
    Return a list containing all global site-packages directories.
 
-   For each directory present in *prefixes* (or :data:`PREFIXES` if *prefixes*
-   is ``None``), this function will find its site-packages subdirectory
-   depending on the system environment, and will return a list of full paths.
+   For each directory given in *prefixes* (or :data:`PREFIXES` if *prefixes*
+   is ``None``), this function will compute its site-packages subdirectory
+   depending on the system environment, and will return a list of full paths,
+   which are not checked for existence.
 
    .. versionadded:: 3.2
 

Doc/library/xml.dom.minidom.rst

@@ -245,21 +245,47 @@ rules apply:
   Instead, :mod:`!xml.dom.minidom` uses standard Python exceptions such as
   :exc:`TypeError` and :exc:`AttributeError`.
 
-* :class:`NodeList` objects are implemented using Python's built-in list type.
-  These objects provide the interface defined in the DOM specification, but with
-  earlier versions of Python they do not support the official API.  They are,
-  however, much more "Pythonic" than the interface defined in the W3C
-  recommendations.
+* Each of the :class:`~xml.dom.NodeList` and :class:`~xml.dom.NamedNodeMap`
+  interfaces has two implementations, which provide additional methods and
+  operations.
+
+  :attr:`~xml.dom.Node.childNodes` is a subclass of :class:`list`, or, for
+  nodes which cannot have children, a subclass of :class:`tuple`.
+  It supports iteration, concatenation, indexing and slicing.
+
+  :attr:`~xml.dom.Node.attributes` supports ``len()``, the :keyword:`in`
+  operator, subscription by a name or by a ``(namespaceURI, localName)``
+  tuple, assignment and deletion, and the methods :meth:`!get`, :meth:`!keys`,
+  :meth:`!keysNS`, :meth:`!values`, :meth:`!items` and :meth:`!itemsNS`.
+  :attr:`~xml.dom.DocumentType.entities` and
+  :attr:`~xml.dom.DocumentType.notations` are read-only and support only
+  ``len()`` and subscription by a name.
+
+* :attr:`~xml.dom.Document.strictErrorChecking` is always ``False``.
+
+  .. versionchanged:: next
+     Previously, :attr:`~xml.dom.Attr.specified` was always ``False``.
+
+* The constraints of the DOM are now enforced,
+  and the corresponding exceptions are raised.
+
+  .. versionchanged:: next
+     Previously, many invalid operations silently succeeded
+     and produced an invalid document,
+     but removing an absent attribute raised :exc:`~xml.dom.NotFoundErr`.
 
 The following interfaces have no implementation in :mod:`!xml.dom.minidom`:
 
 * :class:`DOMTimeStamp`
 
-* :class:`EntityReference`
-
-Most of these reflect information in the XML document that is not of general
+This reflects information in the XML document that is not of general
 utility to most DOM users.
 
+.. versionchanged:: next
+   :class:`~xml.dom.EntityReference` is now implemented.
+   Note that the parser expands entity references,
+   so they only occur in a document if created explicitly.
+
 .. rubric:: Footnotes
 
 .. [1] The encoding name included in the XML output should conform to