Improve docs

python · asvetlov · Mar 24, 2022 · Mar 9, 2022 · Mar 10, 2022 · Mar 10, 2022
commit e6be8f72e4c8be69b72999c4cbb375efca63b029
@@ -1,57 +1,109 @@
 .. currentmodule:: asyncio
 
 
-======
-Runner
-======
+=======
+Runners
+=======
 
 **Source code:** :source:`Lib/asyncio/runners.py`
 
-------------------------------------
 
+This section outlines high-level asyncio primitives to run asyncio code.
 
-:func:`asyncio.run` provides a convinient very high-level API for running asyncio code.
+They are built on top of :ref:`event loop <asyncio-event-loop>` with the aim to simplify
+async code usage for common wide-spread scenarion.
 
-It is the preferred approach that satisfies almost all use cases.
+.. contents::
+   :depth: 1
+   :local:
 
-Sometimes several top-level async calls are needed in the same loop and contextvars
-context instead of the single ``main()`` call provided by :func:`asyncio.run`.
 
-The *Runner* context manager can be used for such things:
 
-.. code:: python
+Running an asyncio Program
+==========================
 
-   with asyncio.Runner() as runner:
-       runner.run(func1())
-       runner.run(func2())
+.. function:: run(coro, *, debug=None)
 
-On the :class:`~asyncio.Runner` instantiation the new event loop is created.
+   Execute the :term:`coroutine` *coro* and return the result.
 
-All :meth:`~asyncio.Runner.run` calls share the same :class:`~contextvars.Context` and
-internal :class:`~asyncio.loop`.
+   This function runs the passed coroutine, taking care of
+   managing the asyncio event loop, *finalizing asynchronous
+   generators*, and closing the threadpool.
 
-On the exit of :keyword:`with` block all background tasks are cancelled, the embedded
-loop is closing.
+   This function cannot be called when another asyncio event loop is
+   running in the same thread.
 
+   If *debug* is ``True``, the event loop will be run in debug mode. ``False`` disables
+   debug mode explicitly. ``None`` is used to respect the global
+   :ref:`asyncio-debug-mode` settings.
+
+   This function always creates a new event loop and closes it at
+   the end.  It should be used as a main entry point for asyncio
+   programs, and should ideally only be called once.
+
+   Example::
+
+       async def main():
+           await asyncio.sleep(1)
+           print('hello')
+
+       asyncio.run(main())
+
+   .. versionadded:: 3.7
+
+   .. versionchanged:: 3.9
+      Updated to use :meth:`loop.shutdown_default_executor`.
+
+   .. versionchanged:: 3.10
+
+      *debug* is ``None`` by default to respect the global debug mode settings.
+
+
+Runner context manager
+======================
 
 .. class:: Runner(*, debug=None, factory=None)
 
+   A context manager that simplifies *multiple* async function calls in the same
+   context.
+
+   Sometimes several top-level async functions should be called in the same :ref:`event
+   loop <asyncio-event-loop>` and :class:`contextvars.Context`.
+
+   If *debug* is ``True``, the event loop will be run in debug mode. ``False`` disables
+   debug mode explicitly. ``None`` is used to respect the global
+   :ref:`asyncio-debug-mode` settings.
+
+   *factory* could be used for overriding the loop creation.
+   :func:`asyncio.new_event_loop` is used if ``None``.
+
+   Basically, :func:`asyncio.run()` example can be revealed with the runner usage:
+
+   .. block:: python
+
+        async def main():
+            await asyncio.sleep(1)
+            print('hello')
+
+        with asyncio.Runner() as runner:
+            runner.run(main())
+
+   .. versionadded:: 3.11
 
+   .. method:: run(coro, *, context=None)
 
+      Run a :term:`coroutine <coroutine>` *coro* in the embedded loop.
 
+      Return the coroutine's result or raise its exception.
 
+      An optional keyword-only *context* argument allows specifying a
+      custom :class:`contextvars.Context` for the *coro* to run in.
+      The runner's context is used if ``None``.
 
-enter
-Usually,
+   .. method:: get_loop()
 
-.. rubric:: Preface
+      Return the event loop associated with the runner instance.
 
-The event loop is the core of every asyncio application.
-Event loops run asynchronous tasks and callbacks, perform network
-IO operations, and run subprocesses.
+   .. method:: get_context()
 
-Application developers should typically use the high-level asyncio functions,
-such as :func:`asyncio.run`, and should rarely need to reference the loop
-object or call its methods.  This section is intended mostly for authors
-of lower-level code, libraries, and frameworks, who need finer control over
-the event loop behavior.
+      Return the :class:`contextvars.Context` associated with the runner object.
@@ -204,43 +204,6 @@ A good example of a low-level function that returns a Future object
 is :meth:`loop.run_in_executor`.
 
 
-Running an asyncio Program
-==========================
-
-.. function:: run(coro, *, debug=False)
-
-    Execute the :term:`coroutine` *coro* and return the result.
-
-    This function runs the passed coroutine, taking care of
-    managing the asyncio event loop, *finalizing asynchronous
-    generators*, and closing the threadpool.
-
-    This function cannot be called when another asyncio event loop is
-    running in the same thread.
-
-    If *debug* is ``True``, the event loop will be run in debug mode.
-
-    This function always creates a new event loop and closes it at
-    the end.  It should be used as a main entry point for asyncio
-    programs, and should ideally only be called once.
-
-    Example::
-
-        async def main():
-            await asyncio.sleep(1)
-            print('hello')
-
-        asyncio.run(main())
-
-    .. versionadded:: 3.7
-
-    .. versionchanged:: 3.9
-       Updated to use :meth:`loop.shutdown_default_executor`.
-
-    .. note::
-       The source code for ``asyncio.run()`` can be found in
-       :source:`Lib/asyncio/runners.py`.
-
 Creating Tasks
 ==============
 

@@ -67,6 +67,7 @@ Additionally, there are **low-level** APIs for
    :caption: High-level APIs
       :maxdepth: 1
 
+   asyncio-runner.rst
    asyncio-task.rst
    asyncio-stream.rst
    asyncio-sync.rst