Merge branch 'main' into fix-fut-callbacks

Author: gvanrossum

Doc/README.rst

@@ -40,7 +40,7 @@ If you'd like to create the virtual environment in a different location,
 you can specify it using the ``VENVDIR`` variable.
 
 You can also skip creating the virtual environment altogether, in which case
-the Makefile will look for instances of ``sphinxbuild`` and ``blurb``
+the Makefile will look for instances of ``sphinx-build`` and ``blurb``
 installed on your process ``PATH`` (configurable with the ``SPHINXBUILD`` and
 ``BLURB`` variables).
 

Doc/glossary.rst

@@ -136,10 +136,17 @@ Glossary
       :exc:`StopAsyncIteration` exception.  Introduced by :pep:`492`.
 
    attribute
-      A value associated with an object which is referenced by name using
-      dotted expressions.  For example, if an object *o* has an attribute
+      A value associated with an object which is usually referenced by name
+      using dotted expressions.
+      For example, if an object *o* has an attribute
       *a* it would be referenced as *o.a*.
 
+      It is possible to give an object an attribute whose name is not an
+      identifier as defined by :ref:`identifiers`, for example using
+      :func:`setattr`, if the object allows it.
+      Such an attribute will not be accessible using a dotted expression,
+      and would instead need to be retrieved with :func:`getattr`.
+
    awaitable
       An object that can be used in an :keyword:`await` expression.  Can be
       a :term:`coroutine` or an object with an :meth:`__await__` method.

Doc/library/asyncio-eventloop.rst

@@ -180,18 +180,27 @@ Running and stopping the loop
 
    .. versionadded:: 3.6
 
-.. coroutinemethod:: loop.shutdown_default_executor()
+.. coroutinemethod:: loop.shutdown_default_executor(timeout=None)
 
    Schedule the closure of the default executor and wait for it to join all of
    the threads in the :class:`ThreadPoolExecutor`. After calling this method, a
    :exc:`RuntimeError` will be raised if :meth:`loop.run_in_executor` is called
    while using the default executor.
 
+   The *timeout* parameter specifies the amount of time the executor will
+   be given to finish joining. The default value is ``None``, which means the
+   executor will be given an unlimited amount of time.
+
+   If the timeout duration is reached, a warning is emitted and executor is
+   terminated without waiting for its threads to finish joining.
+
    Note that there is no need to call this function when
    :func:`asyncio.run` is used.
 
    .. versionadded:: 3.9
 
+   .. versionchanged:: 3.12
+      Added the *timeout* parameter.
 
 Scheduling callbacks
 ^^^^^^^^^^^^^^^^^^^^

Doc/library/asyncio-policy.rst

@@ -7,7 +7,7 @@
 Policies
 ========
 
-An event loop policy is a global (per-interpreter) object
+An event loop policy is a global object
 used to get and set the current :ref:`event loop <asyncio-event-loop>`,
 as well as create new event loops.
 The default policy can be :ref:`replaced <asyncio-policy-get-set>` with

Doc/library/asyncio-runner.rst

@@ -28,7 +28,7 @@ Running an asyncio Program
 
    This function runs the passed coroutine, taking care of
    managing the asyncio event loop, *finalizing asynchronous
-   generators*, and closing the threadpool.
+   generators*, and closing the executor.
 
    This function cannot be called when another asyncio event loop is
    running in the same thread.
@@ -41,6 +41,10 @@ Running an asyncio Program
    the end.  It should be used as a main entry point for asyncio
    programs, and should ideally only be called once.
 
+   The executor is given a timeout duration of 5 minutes to shutdown.
+   If the executor hasn't finished within that duration, a warning is
+   emitted and the executor is closed.
+
    Example::
 
        async def main():

Doc/library/functions.rst

@@ -397,6 +397,7 @@ are always available.  They are listed here in alphabetical order.
    string.  The string must be the name of one of the object's attributes.  The
    function deletes the named attribute, provided the object allows it.  For
    example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
+   *name* need not be a Python identifier (see :func:`setattr`).
 
 
 .. _func-dict:
@@ -738,6 +739,7 @@ are always available.  They are listed here in alphabetical order.
    value of that attribute.  For example, ``getattr(x, 'foobar')`` is equivalent to
    ``x.foobar``.  If the named attribute does not exist, *default* is returned if
    provided, otherwise :exc:`AttributeError` is raised.
+   *name* need not be a Python identifier (see :func:`setattr`).
 
    .. note::
 
@@ -1582,6 +1584,12 @@ are always available.  They are listed here in alphabetical order.
    object allows it.  For example, ``setattr(x, 'foobar', 123)`` is equivalent to
    ``x.foobar = 123``.
 
+   *name* need not be a Python identifier as defined in :ref:`identifiers`
+   unless the object chooses to enforce that, for example in a custom
+   :meth:`~object.__getattribute__` or via :attr:`~object.__slots__`.
+   An attribute whose name is not an identifier will not be accessible using
+   the dot notation, but is accessible through :func:`getattr` etc..
+
    .. note::
 
       Since :ref:`private name mangling <private-name-mangling>` happens at