python_doc_md/Intermediate/library/asyncio-runner.md

::: currentmodule
asyncio
:::

# Runners

**Source code:** `Lib/asyncio/runners.py`{.interpreted-text role="source"}

This section outlines high-level asyncio primitives to run asyncio code.

They are built on top of an `event loop <asyncio-event-loop>`{.interpreted-text role="ref"} with the aim to simplify async code usage for common wide-spread scenarios.

::: {.contents depth="1" local=""}
:::

## Running an asyncio Program

:::::::::: function
run(coro, \*, debug=None, loop_factory=None)

Execute *coro* in an asyncio event loop and return the result.

The argument can be any awaitable object.

This function runs the awaitable, taking care of managing the asyncio event loop, *finalizing asynchronous generators*, and closing the executor.

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 `asyncio-debug-mode`{.interpreted-text role="ref"} settings.

If *loop_factory* is not `None`, it is used to create a new event loop; otherwise `asyncio.new_event_loop`{.interpreted-text role="func"} is used. The loop is closed at the end. This function should be used as a main entry point for asyncio programs, and should ideally only be called once. It is recommended to use *loop_factory* to configure the event loop instead of policies. Passing `asyncio.EventLoop`{.interpreted-text role="class"} allows running asyncio without the policy system.

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():
        await asyncio.sleep(1)
        print('hello')

    asyncio.run(main())

::: versionadded
3.7
:::

::: versionchanged
3.9 Updated to use `loop.shutdown_default_executor`{.interpreted-text role="meth"}.
:::

::: versionchanged
3.10

*debug* is `None` by default to respect the global debug mode settings.
:::

::: versionchanged
3.12

Added *loop_factory* parameter.
:::

::: versionchanged
3.14

*coro* can be any awaitable object.
:::

:::: note
::: title
Note
:::

The `!asyncio`{.interpreted-text role="mod"} policy system is deprecated and will be removed in Python 3.16; from there on, an explicit *loop_factory* is needed to configure the event loop.
::::
::::::::::

## Runner context manager

:::::::::: {.Runner(*, .debug=None, .loop_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 `event
loop <asyncio-event-loop>`{.interpreted-text role="ref"} and `contextvars.Context`{.interpreted-text role="class"}.

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 `asyncio-debug-mode`{.interpreted-text role="ref"} settings.

*loop_factory* could be used for overriding the loop creation. It is the responsibility of the *loop_factory* to set the created loop as the current one. By default `asyncio.new_event_loop`{.interpreted-text role="func"} is used and set as current event loop with `asyncio.set_event_loop`{.interpreted-text role="func"} if *loop_factory* is `None`.

Basically, `asyncio.run`{.interpreted-text role="func"} example can be rewritten with the runner usage:

    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)

Execute *coro* in the embedded event loop.

The argument can be any awaitable object.

If the argument is a coroutine, it is wrapped in a Task.

An optional keyword-only *context* argument allows specifying a custom `contextvars.Context`{.interpreted-text role="class"} for the code to run in. The runner\'s default context is used if context is `None`.

Returns the awaitable\'s result or raises an exception.

This function cannot be called when another asyncio event loop is running in the same thread.

::: versionchanged
3.14

*coro* can be any awaitable object.
:::
::::

::: method
close()

Close the runner.

Finalize asynchronous generators, shutdown default executor, close the event loop and release embedded `contextvars.Context`{.interpreted-text role="class"}.
:::

::: method
get_loop()

Return the event loop associated with the runner instance.
:::

:::: note
::: title
Note
:::

`Runner`{.interpreted-text role="class"} uses the lazy initialization strategy, its constructor doesn\'t initialize underlying low-level structures.

Embedded *loop* and *context* are created at the `with`{.interpreted-text role="keyword"} body entering or the first call of `run`{.interpreted-text role="meth"} or `get_loop`{.interpreted-text role="meth"}.
::::
::::::::::

## Handling Keyboard Interruption

::: versionadded
3.11
:::

When `signal.SIGINT`{.interpreted-text role="const"} is raised by `Ctrl-C`{.interpreted-text role="kbd"}, `KeyboardInterrupt`{.interpreted-text role="exc"} exception is raised in the main thread by default. However this doesn\'t work with `asyncio`{.interpreted-text role="mod"} because it can interrupt asyncio internals and can hang the program from exiting.

To mitigate this issue, `asyncio`{.interpreted-text role="mod"} handles `signal.SIGINT`{.interpreted-text role="const"} as follows:

1.  `asyncio.Runner.run`{.interpreted-text role="meth"} installs a custom `signal.SIGINT`{.interpreted-text role="const"} handler before any user code is executed and removes it when exiting from the function.
2.  The `~asyncio.Runner`{.interpreted-text role="class"} creates the main task for the passed coroutine for its execution.
3.  When `signal.SIGINT`{.interpreted-text role="const"} is raised by `Ctrl-C`{.interpreted-text role="kbd"}, the custom signal handler cancels the main task by calling `asyncio.Task.cancel`{.interpreted-text role="meth"} which raises `asyncio.CancelledError`{.interpreted-text role="exc"} inside the main task. This causes the Python stack to unwind, `try/except` and `try/finally` blocks can be used for resource cleanup. After the main task is cancelled, `asyncio.Runner.run`{.interpreted-text role="meth"} raises `KeyboardInterrupt`{.interpreted-text role="exc"}.
4.  A user could write a tight loop which cannot be interrupted by `asyncio.Task.cancel`{.interpreted-text role="meth"}, in which case the second following `Ctrl-C`{.interpreted-text role="kbd"} immediately raises the `KeyboardInterrupt`{.interpreted-text role="exc"} without cancelling the main task.