Merge branch 'main' into bpo-44530-code-qualname

Author: P403n1x87

Doc/c-api/memory.rst

@@ -490,7 +490,7 @@ Customize Memory Allocators
 Debug hooks on the Python memory allocators
 ===========================================
 
-When :ref:`Python is built is debug mode <debug-build>`, the
+When :ref:`Python is built in debug mode <debug-build>`, the
 :c:func:`PyMem_SetupDebugHooks` function is called at the :ref:`Python
 preinitialization <c-preinit>` to setup debug hooks on Python memory allocators
 to detect memory errors.

Doc/library/asyncio-eventloop.rst

@@ -1132,16 +1132,12 @@ Executing code in thread or process pools
 .. method:: loop.set_default_executor(executor)
 
    Set *executor* as the default executor used by :meth:`run_in_executor`.
-   *executor* should be an instance of
+   *executor* must be an instance of
    :class:`~concurrent.futures.ThreadPoolExecutor`.
 
-   .. deprecated:: 3.8
-      Using an executor that is not an instance of
-      :class:`~concurrent.futures.ThreadPoolExecutor` is deprecated and
-      will trigger an error in Python 3.9.
-
-   *executor* must be an instance of
-   :class:`concurrent.futures.ThreadPoolExecutor`.
+   .. versionchanged:: 3.11
+      *executor* must be an instance of
+      :class:`~concurrent.futures.ThreadPoolExecutor`.
 
 
 Error Handling API

Doc/library/asyncio-task.rst

@@ -148,9 +148,6 @@ other coroutines::
    * a *coroutine object*: an object returned by calling a
      *coroutine function*.
 
-asyncio also supports legacy :ref:`generator-based
-<asyncio_generator_based_coro>` coroutines.
-
 
 .. rubric:: Tasks
 
@@ -1042,60 +1039,3 @@ Task Object
       in the :func:`repr` output of a task object.
 
       .. versionadded:: 3.8
-
-
-.. _asyncio_generator_based_coro:
-
-Generator-based Coroutines
-==========================
-
-.. note::
-
-   Support for generator-based coroutines is **deprecated** and
-   is scheduled for removal in Python 3.10.
-
-Generator-based coroutines predate async/await syntax.  They are
-Python generators that use ``yield from`` expressions to await
-on Futures and other coroutines.
-
-Generator-based coroutines should be decorated with
-:func:`@asyncio.coroutine <asyncio.coroutine>`, although this is not
-enforced.
-
-
-.. decorator:: coroutine
-
-    Decorator to mark generator-based coroutines.
-
-    This decorator enables legacy generator-based coroutines to be
-    compatible with async/await code::
-
-        @asyncio.coroutine
-        def old_style_coroutine():
-            yield from asyncio.sleep(1)
-
-        async def main():
-            await old_style_coroutine()
-
-    This decorator should not be used for :keyword:`async def`
-    coroutines.
-
-    .. deprecated-removed:: 3.8 3.10
-
-       Use :keyword:`async def` instead.
-
-.. function:: iscoroutine(obj)
-
-   Return ``True`` if *obj* is a :ref:`coroutine object <coroutine>`.
-
-   This method is different from :func:`inspect.iscoroutine` because
-   it returns ``True`` for generator-based coroutines.
-
-.. function:: iscoroutinefunction(func)
-
-   Return ``True`` if *func* is a :ref:`coroutine function
-   <coroutine>`.
-
-   This method is different from :func:`inspect.iscoroutinefunction`
-   because it returns ``True`` for generator-based coroutine functions
-   decorated with :func:`@coroutine <coroutine>`.

Doc/library/atexit.rst

@@ -48,11 +48,12 @@ internal error is detected, or when :func:`os._exit` is called.
 
 .. function:: unregister(func)
 
-   Remove *func* from the list of functions to be run at interpreter
-   shutdown.  After calling :func:`unregister`, *func* is guaranteed not to be
-   called when the interpreter shuts down, even if it was registered more than
-   once.  :func:`unregister` silently does nothing if *func* was not previously
-   registered.
+   Remove *func* from the list of functions to be run at interpreter shutdown.
+   :func:`unregister` silently does nothing if *func* was not previously
+   registered.  If *func* has been registered more than once, every occurrence
+   of that function in the :mod:`atexit` call stack will be removed.  Equality
+   comparisons (``==``) are used internally during unregistration, so function
+   references do not need to have matching identities.
 
 
 .. seealso::

Doc/library/collections.abc.rst

@@ -198,7 +198,7 @@ ABC                        Inherits from          Abstract Methods        Mixin
 
    .. note::
       In CPython, generator-based coroutines (generators decorated with
-      :func:`types.coroutine` or :func:`asyncio.coroutine`) are
+      :func:`types.coroutine`) are
       *awaitables*, even though they do not have an :meth:`__await__` method.
       Using ``isinstance(gencoro, Awaitable)`` for them will return ``False``.
       Use :func:`inspect.isawaitable` to detect them.
@@ -216,7 +216,7 @@ ABC                        Inherits from          Abstract Methods        Mixin
 
    .. note::
       In CPython, generator-based coroutines (generators decorated with
-      :func:`types.coroutine` or :func:`asyncio.coroutine`) are
+      :func:`types.coroutine`) are
       *awaitables*, even though they do not have an :meth:`__await__` method.
       Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``.
       Use :func:`inspect.isawaitable` to detect them.

Doc/library/contextlib.rst

@@ -515,6 +515,10 @@ Functions and classes provided:
       These context managers may suppress exceptions just as they normally
       would if used directly as part of a :keyword:`with` statement.
 
+      .. versionchanged:: 3.11
+         Raises :exc:`TypeError` instead of :exc:`AttributeError` if *cm*
+         is not a context manager.
+
    .. method:: push(exit)
 
       Adds a context manager's :meth:`__exit__` method to the callback stack.
@@ -585,6 +589,10 @@ Functions and classes provided:
       Similar to :meth:`enter_context` but expects an asynchronous context
       manager.
 
+      .. versionchanged:: 3.11
+         Raises :exc:`TypeError` instead of :exc:`AttributeError` if *cm*
+         is not an asynchronous context manager.
+
    .. method:: push_async_exit(exit)
 
       Similar to :meth:`push` but expects either an asynchronous context manager

Doc/library/dis.rst

@@ -936,7 +936,7 @@ All of the following opcodes use their arguments.
    .. versionadded:: 3.9
 
 
-.. opcode:: DICT_MERGE
+.. opcode:: DICT_MERGE (i)
 
    Like :opcode:`DICT_UPDATE` but raises an exception for duplicate keys.
 

Doc/library/graphlib.rst

@@ -154,9 +154,10 @@
 
    .. method:: static_order()
 
-      Returns an iterable of nodes in a topological order. Using this method
-      does not require to call :meth:`TopologicalSorter.prepare` or
-      :meth:`TopologicalSorter.done`. This method is equivalent to::
+      Returns an iterator object which will iterate over nodes in a topological
+      order. When using this method, :meth:`~TopologicalSorter.prepare` and
+      :meth:`~TopologicalSorter.done` should not be called. This method is
+      equivalent to::
 
           def static_order(self):
               self.prepare()
@@ -206,4 +207,4 @@ The :mod:`graphlib` module defines the following exception classes:
    The detected cycle can be accessed via the second element in the :attr:`~CycleError.args`
    attribute of the exception instance and consists in a list of nodes, such that each node is,
    in the graph, an immediate predecessor of the next node in the list. In the reported list,
-   the first and the last node will be the same, to make it clear that it is cyclic.
+   the first and the last node will be the same, to make it clear that it is cyclic.

Doc/library/marshal.rst

@@ -66,6 +66,8 @@ The module defines these functions:
    The *version* argument indicates the data format that ``dump`` should use
    (see below).
 
+   .. audit-event:: marshal.dumps value,version marshal.dump
+
 
 .. function:: load(file)
 
@@ -74,11 +76,18 @@ The module defines these functions:
    format), raise :exc:`EOFError`, :exc:`ValueError` or :exc:`TypeError`.  The
    file must be a readable :term:`binary file`.
 
+   .. audit-event:: marshal.load "" marshal.load
+
    .. note::
 
       If an object containing an unsupported type was marshalled with :func:`dump`,
       :func:`load` will substitute ``None`` for the unmarshallable type.
 
+   .. versionchanged:: 3.10
+
+      This call used to raise a ``code.__new__`` audit event for each code object. Now
+      it raises a single ``marshal.load`` event for the entire load operation.
+
 
 .. function:: dumps(value[, version])
 
@@ -89,13 +98,22 @@ The module defines these functions:
    The *version* argument indicates the data format that ``dumps`` should use
    (see below).
 
+   .. audit-event:: marshal.dumps value,version marshal.dump
+
 
 .. function:: loads(bytes)
 
    Convert the :term:`bytes-like object` to a value.  If no valid value is found, raise
    :exc:`EOFError`, :exc:`ValueError` or :exc:`TypeError`.  Extra bytes in the
    input are ignored.
 
+   .. audit-event:: marshal.loads bytes marshal.load
+
+   .. versionchanged:: 3.10
+
+      This call used to raise a ``code.__new__`` audit event for each code object. Now
+      it raises a single ``marshal.loads`` event for the entire load operation.
+
 
 In addition, the following constants are defined:
 

Doc/library/pprint.rst

@@ -42,24 +42,36 @@ The :mod:`pprint` module defines one class:
                          compact=False, sort_dicts=True, underscore_numbers=False)
 
    Construct a :class:`PrettyPrinter` instance.  This constructor understands
-   several keyword parameters.  An output stream may be set using the *stream*
-   keyword; the only method used on the stream object is the file protocol's
-   :meth:`write` method.  If not specified, the :class:`PrettyPrinter` adopts
-   ``sys.stdout``.  The
-   amount of indentation added for each recursive level is specified by *indent*;
-   the default is one.  Other values can cause output to look a little odd, but can
-   make nesting easier to spot.  The number of levels which may be printed is
-   controlled by *depth*; if the data structure being printed is too deep, the next
-   contained level is replaced by ``...``.  By default, there is no constraint on
-   the depth of the objects being formatted.  The desired output width is
-   constrained using the *width* parameter; the default is 80 characters.  If a
-   structure cannot be formatted within the constrained width, a best effort will
-   be made.  If *compact* is false (the default) each item of a long sequence
-   will be formatted on a separate line.  If *compact* is true, as many items
-   as will fit within the *width* will be formatted on each output line. If
-   *sort_dicts* is true (the default), dictionaries will be formatted with their
-   keys sorted, otherwise they will display in insertion order.  If
-   *underscore_numbers* is true, integers will be formatted with the
+   several keyword parameters.
+
+   *stream* (default ``sys.stdout``) is a :term:`file-like object` to
+   which the output will be written by calling its :meth:`write` method.
+
+   Other values configure the manner in which nesting of complex data
+   structures is displayed.
+
+   *indent* (default 1) specifies the amount of indentation added for
+   each nesting level.
+
+   *depth* controls the number of nesting levels which may be printed; if
+   the data structure being printed is too deep, the next contained level
+   is replaced by ``...``.  By default, there is no constraint on the
+   depth of the objects being formatted.
+
+   *width* (default 80) specifies the desired maximum number of characters per
+   line in the output. If a structure cannot be formatted within the width
+   constraint, a best effort will be made.
+
+   *compact* impacts the way that long sequences (lists, tuples, sets, etc)
+   are formatted. If *compact* is false (the default) then each item of a
+   sequence will be formatted on a separate line.  If *compact* is true, as
+   many items as will fit within the *width* will be formatted on each output
+   line.
+
+   If *sort_dicts* is true (the default), dictionaries will be formatted with
+   their keys sorted, otherwise they will display in insertion order.
+
+   If *underscore_numbers* is true, integers will be formatted with the
    ``_`` character for a thousands separator, otherwise underscores are not
    displayed (the default).
 

Doc/library/venv.rst

@@ -170,11 +170,12 @@ creation according to their needs, the :class:`EnvBuilder` class.
 
     .. method:: ensure_directories(env_dir)
 
-        Creates the environment directory and all necessary directories, and
-        returns a context object.  This is just a holder for attributes (such as
-        paths), for use by the other methods. The directories are allowed to
-        exist already, as long as either ``clear`` or ``upgrade`` were
-        specified to allow operating on an existing environment directory.
+        Creates the environment directory and all necessary subdirectories that
+        don't already exist, and returns a context object.  This context object
+        is just a holder for attributes (such as paths) for use by the other
+        methods.  If the :class:`EnvBuilder` is created with the arg
+        ``clear=True``, contents of the environment directory will be cleared
+        and then all necessary subdirectories will be recreated.
 
     .. method:: create_configuration(context)
 

Doc/reference/datamodel.rst

@@ -2714,7 +2714,7 @@ are awaitable.
 .. note::
 
    The :term:`generator iterator` objects returned from generators
-   decorated with :func:`types.coroutine` or :func:`asyncio.coroutine`
+   decorated with :func:`types.coroutine`
    are also awaitable, but they do not implement :meth:`__await__`.
 
 .. method:: object.__await__(self)