Files
FootPrint/Python/pythoncore-3.15-64/Doc/html/library/asyncio-runner.html
T

529 lines
34 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="Runners" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/library/asyncio-runner.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="Source code: Lib/asyncio/runners.py This section outlines high-level asyncio primitives to run asyncio code. They are built on top of an event loop with the aim to simplify async code usage for com..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="Source code: Lib/asyncio/runners.py This section outlines high-level asyncio primitives to run asyncio code. They are built on top of an event loop with the aim to simplify async code usage for com..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<title>Runners &#8212; Python 3.15.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=48df1187" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
<script src="../_static/documentation_options.js?v=0fe728b1"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.15.0 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Coroutines and tasks" href="asyncio-task.html" />
<link rel="prev" title="asyncio — Asynchronous I/O" href="asyncio.html" />
<link rel="canonical" href="https://docs.python.org/3/library/asyncio-runner.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Runners</a><ul>
<li><a class="reference internal" href="#running-an-asyncio-program">Running an asyncio Program</a></li>
<li><a class="reference internal" href="#runner-context-manager">Runner context manager</a></li>
<li><a class="reference internal" href="#handling-keyboard-interruption">Handling Keyboard Interruption</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="asyncio.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code> — Asynchronous I/O</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="asyncio-task.html"
title="next chapter">Coroutines and tasks</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/asyncio-runner.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/library/asyncio-runner.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="asyncio-task.html" title="Coroutines and tasks"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="asyncio.html" title="asyncio — Asynchronous I/O"
accesskey="P">previous</a> |</li>
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python standard library</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="ipc.html" >Networking and Interprocess Communication</a> &#187;</li>
<li class="nav-item nav-item-3"><a href="asyncio.html" accesskey="U"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code> — Asynchronous I/O</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Runners</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="runners">
<h1>Runners<a class="headerlink" href="#runners" title="Link to this heading"></a></h1>
<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.15/Lib/asyncio/runners.py">Lib/asyncio/runners.py</a></p>
<p>This section outlines high-level asyncio primitives to run asyncio code.</p>
<p>They are built on top of an <a class="reference internal" href="asyncio-eventloop.html#asyncio-event-loop"><span class="std std-ref">event loop</span></a> with the aim
to simplify async code usage for common wide-spread scenarios.</p>
<nav class="contents local" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#running-an-asyncio-program" id="id1">Running an asyncio Program</a></p></li>
<li><p><a class="reference internal" href="#runner-context-manager" id="id2">Runner context manager</a></p></li>
<li><p><a class="reference internal" href="#handling-keyboard-interruption" id="id3">Handling Keyboard Interruption</a></p></li>
</ul>
</nav>
<section id="running-an-asyncio-program">
<h2><a class="toc-backref" href="#id1" role="doc-backlink">Running an asyncio Program</a><a class="headerlink" href="#running-an-asyncio-program" title="Link to this heading"></a></h2>
<dl class="py function">
<dt class="sig sig-object py" id="asyncio.run">
<span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">coro</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">debug</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">loop_factory</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.run" title="Link to this definition"></a></dt>
<dd><p>Execute <em>coro</em> in an asyncio event loop and return the result.</p>
<p>The argument can be any awaitable object.</p>
<p>This function runs the awaitable, taking care of managing the
asyncio event loop, <em>finalizing asynchronous generators</em>, and
closing the executor.</p>
<p>This function cannot be called when another asyncio event loop is
running in the same thread.</p>
<p>If <em>debug</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the event loop will be run in debug mode. <code class="docutils literal notranslate"><span class="pre">False</span></code> disables
debug mode explicitly. <code class="docutils literal notranslate"><span class="pre">None</span></code> is used to respect the global
<a class="reference internal" href="asyncio-dev.html#asyncio-debug-mode"><span class="std std-ref">Debug Mode</span></a> settings.</p>
<p>If <em>loop_factory</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, it is used to create a new event loop;
otherwise <a class="reference internal" href="asyncio-eventloop.html#asyncio.new_event_loop" title="asyncio.new_event_loop"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.new_event_loop()</span></code></a> 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
<em>loop_factory</em> to configure the event loop instead of policies.
Passing <a class="reference internal" href="asyncio-eventloop.html#asyncio.EventLoop" title="asyncio.EventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.EventLoop</span></code></a> allows running asyncio without the
policy system.</p>
<p>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.</p>
<p>Example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>
<span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">'hello'</span><span class="p">)</span>
<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.7.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.9: </span>Updated to use <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.shutdown_default_executor" title="asyncio.loop.shutdown_default_executor"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.shutdown_default_executor()</span></code></a>.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.10: </span><em>debug</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code> by default to respect the global debug mode settings.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.12: </span>Added <em>loop_factory</em> parameter.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.14: </span><em>coro</em> can be any awaitable object.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code> policy system is deprecated and will be removed
in Python 3.16; from there on, an explicit <em>loop_factory</em> is needed
to configure the event loop.</p>
</div>
</dd></dl>
</section>
<section id="runner-context-manager">
<h2><a class="toc-backref" href="#id2" role="doc-backlink">Runner context manager</a><a class="headerlink" href="#runner-context-manager" title="Link to this heading"></a></h2>
<dl class="py class">
<dt class="sig sig-object py" id="asyncio.Runner">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">Runner</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">debug</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">loop_factory</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Runner" title="Link to this definition"></a></dt>
<dd><p>A context manager that simplifies <em>multiple</em> async function calls in the same
context.</p>
<p>Sometimes several top-level async functions should be called in the same <a class="reference internal" href="asyncio-eventloop.html#asyncio-event-loop"><span class="std std-ref">event
loop</span></a> and <a class="reference internal" href="contextvars.html#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">contextvars.Context</span></code></a>.</p>
<p>If <em>debug</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the event loop will be run in debug mode. <code class="docutils literal notranslate"><span class="pre">False</span></code> disables
debug mode explicitly. <code class="docutils literal notranslate"><span class="pre">None</span></code> is used to respect the global
<a class="reference internal" href="asyncio-dev.html#asyncio-debug-mode"><span class="std std-ref">Debug Mode</span></a> settings.</p>
<p><em>loop_factory</em> could be used for overriding the loop creation.
It is the responsibility of the <em>loop_factory</em> to set the created loop as the
current one. By default <a class="reference internal" href="asyncio-eventloop.html#asyncio.new_event_loop" title="asyncio.new_event_loop"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.new_event_loop()</span></code></a> is used and set as
current event loop with <a class="reference internal" href="asyncio-eventloop.html#asyncio.set_event_loop" title="asyncio.set_event_loop"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.set_event_loop()</span></code></a> if <em>loop_factory</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
<p>Basically, <a class="reference internal" href="#asyncio.run" title="asyncio.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.run()</span></code></a> example can be rewritten with the runner usage:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>
<span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">'hello'</span><span class="p">)</span>
<span class="k">with</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">Runner</span><span class="p">()</span> <span class="k">as</span> <span class="n">runner</span><span class="p">:</span>
<span class="n">runner</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.11.</span></p>
</div>
<dl class="py method">
<dt class="sig sig-object py" id="asyncio.Runner.run">
<span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">coro</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Runner.run" title="Link to this definition"></a></dt>
<dd><p>Execute <em>coro</em> in the embedded event loop.</p>
<p>The argument can be any awaitable object.</p>
<p>If the argument is a coroutine, it is wrapped in a Task.</p>
<p>An optional keyword-only <em>context</em> argument allows specifying a
custom <a class="reference internal" href="contextvars.html#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">contextvars.Context</span></code></a> for the code to run in.
The runner’s default context is used if context is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
<p>Returns the awaitable’s result or raises an exception.</p>
<p>This function cannot be called when another asyncio event loop is
running in the same thread.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.14: </span><em>coro</em> can be any awaitable object.</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="asyncio.Runner.close">
<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Runner.close" title="Link to this definition"></a></dt>
<dd><p>Close the runner.</p>
<p>Finalize asynchronous generators, shutdown default executor, close the event loop
and release embedded <a class="reference internal" href="contextvars.html#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">contextvars.Context</span></code></a>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="asyncio.Runner.get_loop">
<span class="sig-name descname"><span class="pre">get_loop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Runner.get_loop" title="Link to this definition"></a></dt>
<dd><p>Return the event loop associated with the runner instance.</p>
</dd></dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><code class="xref py py-class docutils literal notranslate"><span class="pre">Runner</span></code> uses the lazy initialization strategy, its constructor doesn’t
initialize underlying low-level structures.</p>
<p>Embedded <em>loop</em> and <em>context</em> are created at the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> body entering
or the first call of <a class="reference internal" href="#asyncio.run" title="asyncio.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> or <a class="reference internal" href="#asyncio.Runner.get_loop" title="asyncio.Runner.get_loop"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_loop()</span></code></a>.</p>
</div>
</dd></dl>
</section>
<section id="handling-keyboard-interruption">
<h2><a class="toc-backref" href="#id3" role="doc-backlink">Handling Keyboard Interruption</a><a class="headerlink" href="#handling-keyboard-interruption" title="Link to this heading"></a></h2>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.11.</span></p>
</div>
<p>When <a class="reference internal" href="signal.html#signal.SIGINT" title="signal.SIGINT"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.SIGINT</span></code></a> is raised by <kbd class="kbd docutils literal notranslate">Ctrl</kbd>-<kbd class="kbd docutils literal notranslate">C</kbd>, <a class="reference internal" href="../builtins/exceptions.html#KeyboardInterrupt" title="KeyboardInterrupt"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code></a>
exception is raised in the main thread by default. However this doesn’t work with
<a class="reference internal" href="asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a> because it can interrupt asyncio internals and can hang the program from
exiting.</p>
<p>To mitigate this issue, <a class="reference internal" href="asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a> handles <a class="reference internal" href="signal.html#signal.SIGINT" title="signal.SIGINT"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.SIGINT</span></code></a> as follows:</p>
<ol class="arabic simple">
<li><p><a class="reference internal" href="#asyncio.Runner.run" title="asyncio.Runner.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">asyncio.Runner.run()</span></code></a> installs a custom <a class="reference internal" href="signal.html#signal.SIGINT" title="signal.SIGINT"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.SIGINT</span></code></a> handler before
any user code is executed and removes it when exiting from the function.</p></li>
<li><p>The <a class="reference internal" href="#asyncio.Runner" title="asyncio.Runner"><code class="xref py py-class docutils literal notranslate"><span class="pre">Runner</span></code></a> creates the main task for the passed coroutine for its
execution.</p></li>
<li><p>When <a class="reference internal" href="signal.html#signal.SIGINT" title="signal.SIGINT"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.SIGINT</span></code></a> is raised by <kbd class="kbd docutils literal notranslate">Ctrl</kbd>-<kbd class="kbd docutils literal notranslate">C</kbd>, the custom signal handler
cancels the main task by calling <a class="reference internal" href="asyncio-task.html#asyncio.Task.cancel" title="asyncio.Task.cancel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">asyncio.Task.cancel()</span></code></a> which raises
<a class="reference internal" href="asyncio-exceptions.html#asyncio.CancelledError" title="asyncio.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">asyncio.CancelledError</span></code></a> inside the main task. This causes the Python stack
to unwind, <code class="docutils literal notranslate"><span class="pre">try/except</span></code> and <code class="docutils literal notranslate"><span class="pre">try/finally</span></code> blocks can be used for resource
cleanup. After the main task is cancelled, <a class="reference internal" href="#asyncio.Runner.run" title="asyncio.Runner.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">asyncio.Runner.run()</span></code></a> raises
<a class="reference internal" href="../builtins/exceptions.html#KeyboardInterrupt" title="KeyboardInterrupt"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code></a>.</p></li>
<li><p>A user could write a tight loop which cannot be interrupted by
<a class="reference internal" href="asyncio-task.html#asyncio.Task.cancel" title="asyncio.Task.cancel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">asyncio.Task.cancel()</span></code></a>, in which case the second following <kbd class="kbd docutils literal notranslate">Ctrl</kbd>-<kbd class="kbd docutils literal notranslate">C</kbd>
immediately raises the <a class="reference internal" href="../builtins/exceptions.html#KeyboardInterrupt" title="KeyboardInterrupt"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code></a> without cancelling the main task.</p></li>
</ol>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Runners</a><ul>
<li><a class="reference internal" href="#running-an-asyncio-program">Running an asyncio Program</a></li>
<li><a class="reference internal" href="#runner-context-manager">Runner context manager</a></li>
<li><a class="reference internal" href="#handling-keyboard-interruption">Handling Keyboard Interruption</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="asyncio.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code> — Asynchronous I/O</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="asyncio-task.html"
title="next chapter">Coroutines and tasks</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/asyncio-runner.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/library/asyncio-runner.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="asyncio-task.html" title="Coroutines and tasks"
>next</a> |</li>
<li class="right" >
<a href="asyncio.html" title="asyncio — Asynchronous I/O"
>previous</a> |</li>
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python standard library</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="ipc.html" >Networking and Interprocess Communication</a> &#187;</li>
<li class="nav-item nav-item-3"><a href="asyncio.html" ><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code> — Asynchronous I/O</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Runners</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.
<br>
This page is licensed under the Python Software Foundation License Version 2.
<br>
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br>
See <a href="/license.html">History and License</a> for more information.<br>
<br>
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br>
<br>
Last updated on Oct 09, 2026 (11:35 UTC).
<a href="/bugs.html">Found a bug</a>?
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>