Merge pull request #512 from python/main

Sync Fork from Upstream Repo

Author: sthagen

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/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,9 +515,9 @@ 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.
+      .. versionchanged:: 3.11
+         Raises :exc:`TypeError` instead of :exc:`AttributeError` if *cm*
+         is not a context manager.
 
    .. method:: push(exit)
 
@@ -589,9 +589,9 @@ 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.
+      .. versionchanged:: 3.11
+         Raises :exc:`TypeError` instead of :exc:`AttributeError` if *cm*
+         is not an asynchronous context manager.
 
    .. method:: push_async_exit(exit)
 

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/traceback.rst

@@ -447,37 +447,42 @@ The output for the example would look similar to this:
    *** print_tb:
      File "<doctest...>", line 10, in <module>
        lumberjack()
+       ^^^^^^^^^^^^
    *** print_exception:
    Traceback (most recent call last):
      File "<doctest...>", line 10, in <module>
        lumberjack()
+       ^^^^^^^^^^^^
      File "<doctest...>", line 4, in lumberjack
        bright_side_of_death()
+       ^^^^^^^^^^^^^^^^^^^^^^
    IndexError: tuple index out of range
    *** print_exc:
    Traceback (most recent call last):
      File "<doctest...>", line 10, in <module>
        lumberjack()
+       ^^^^^^^^^^^^
      File "<doctest...>", line 4, in lumberjack
        bright_side_of_death()
+       ^^^^^^^^^^^^^^^^^^^^^^
    IndexError: tuple index out of range
    *** format_exc, first and last line:
    Traceback (most recent call last):
    IndexError: tuple index out of range
    *** format_exception:
    ['Traceback (most recent call last):\n',
-    '  File "<doctest...>", line 10, in <module>\n    lumberjack()\n',
-    '  File "<doctest...>", line 4, in lumberjack\n    bright_side_of_death()\n',
-    '  File "<doctest...>", line 7, in bright_side_of_death\n    return tuple()[0]\n',
+    '  File "<doctest default[0]>", line 10, in <module>\n    lumberjack()\n    ^^^^^^^^^^^^\n',
+    '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_death()\n    ^^^^^^^^^^^^^^^^^^^^^^\n',
+    '  File "<doctest default[0]>", line 7, in bright_side_of_death\n    return tuple()[0]\n           ^^^^^^^^^^\n',
     'IndexError: tuple index out of range\n']
    *** extract_tb:
    [<FrameSummary file <doctest...>, line 10 in <module>>,
     <FrameSummary file <doctest...>, line 4 in lumberjack>,
     <FrameSummary file <doctest...>, line 7 in bright_side_of_death>]
    *** format_tb:
-   ['  File "<doctest...>", line 10, in <module>\n    lumberjack()\n',
-    '  File "<doctest...>", line 4, in lumberjack\n    bright_side_of_death()\n',
-    '  File "<doctest...>", line 7, in bright_side_of_death\n    return tuple()[0]\n']
+   ['  File "<doctest default[0]>", line 10, in <module>\n    lumberjack()\n    ^^^^^^^^^^^^\n',
+    '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_death()\n    ^^^^^^^^^^^^^^^^^^^^^^\n',
+    '  File "<doctest default[0]>", line 7, in bright_side_of_death\n    return tuple()[0]\n           ^^^^^^^^^^\n']
    *** tb_lineno: 10
 
 

Doc/library/typing.rst

@@ -1232,8 +1232,13 @@ These are not used in annotations. They are building blocks for creating generic
 
    .. note::
 
-        :func:`runtime_checkable` will check only the presence of the required methods,
-        not their type signatures.
+        :func:`runtime_checkable` will check only the presence of the required
+        methods, not their type signatures. For example, :class:`ssl.SSLObject`
+        is a class, therefore it passes an :func:`issubclass`
+        check against :data:`Callable`.  However, the
+        :meth:`ssl.SSLObject.__init__` method exists only to raise a
+        :exc:`TypeError` with a more informative message, therefore making
+        it impossible to call (instantiate) :class:`ssl.SSLObject`.
 
    .. versionadded:: 3.8
 

Doc/library/unittest.mock.rst

@@ -262,7 +262,7 @@ the *new_callable* argument to :func:`patch`.
       this is a new Mock (created on first access). See the
       :attr:`return_value` attribute.
 
-    * *unsafe*: By default, accessing any attribute with name starting with
+    * *unsafe*: By default, accessing any attribute whose name starts with
       *assert*, *assret*, *asert*, *aseert* or *assrt* will raise an
       :exc:`AttributeError`. Passing ``unsafe=True`` will allow access to
       these attributes.