diff options
Diffstat (limited to 'devdocs/python~3.12/library%2Fasyncio-runner.html')
| -rw-r--r-- | devdocs/python~3.12/library%2Fasyncio-runner.html | 33 |
1 files changed, 33 insertions, 0 deletions
diff --git a/devdocs/python~3.12/library%2Fasyncio-runner.html b/devdocs/python~3.12/library%2Fasyncio-runner.html new file mode 100644 index 00000000..f0a7c008 --- /dev/null +++ b/devdocs/python~3.12/library%2Fasyncio-runner.html @@ -0,0 +1,33 @@ + <h1>Runners</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/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#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> <ul class="simple"> <li><a class="reference internal" href="#running-an-asyncio-program" id="id1">Running an asyncio Program</a></li> <li><a class="reference internal" href="#runner-context-manager" id="id2">Runner context manager</a></li> <li><a class="reference internal" href="#handling-keyboard-interruption" id="id3">Handling Keyboard Interruption</a></li> </ul> <section id="running-an-asyncio-program"> <h2>Running an asyncio Program</h2> <dl class="py function"> <dt class="sig sig-object py" id="asyncio.run"> +<code>asyncio.run(coro, *, debug=None, loop_factory=None)</code> </dt> <dd> +<p>Execute the <a class="reference internal" href="../glossary#term-coroutine"><span class="xref std std-term">coroutine</span></a> <em>coro</em> and return the result.</p> <p>This function runs the passed coroutine, 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>True</code>, the event loop will be run in debug mode. <code>False</code> disables debug mode explicitly. <code>None</code> is used to respect the global <a class="reference internal" href="asyncio-dev#asyncio-debug-mode"><span class="std std-ref">Debug Mode</span></a> settings.</p> <p>If <em>loop_factory</em> is not <code>None</code>, it is used to create a new event loop; otherwise <a class="reference internal" href="asyncio-eventloop#asyncio.new_event_loop" title="asyncio.new_event_loop"><code>asyncio.new_event_loop()</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.</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> <pre data-language="python">async def main(): + await asyncio.sleep(1) + print('hello') + +asyncio.run(main()) +</pre> <div class="versionadded"> <p><span class="versionmodified added">New 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#asyncio.loop.shutdown_default_executor" title="asyncio.loop.shutdown_default_executor"><code>loop.shutdown_default_executor()</code></a>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span><em>debug</em> is <code>None</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> </dd> +</dl> </section> <section id="runner-context-manager"> <h2>Runner context manager</h2> <dl class="py class"> <dt class="sig sig-object py" id="asyncio.Runner"> +<code>class asyncio.Runner(*, debug=None, loop_factory=None)</code> </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#asyncio-event-loop"><span class="std std-ref">event loop</span></a> and <a class="reference internal" href="contextvars#contextvars.Context" title="contextvars.Context"><code>contextvars.Context</code></a>.</p> <p>If <em>debug</em> is <code>True</code>, the event loop will be run in debug mode. <code>False</code> disables debug mode explicitly. <code>None</code> is used to respect the global <a class="reference internal" href="asyncio-dev#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#asyncio.new_event_loop" title="asyncio.new_event_loop"><code>asyncio.new_event_loop()</code></a> is used and set as current event loop with <a class="reference internal" href="asyncio-eventloop#asyncio.set_event_loop" title="asyncio.set_event_loop"><code>asyncio.set_event_loop()</code></a> if <em>loop_factory</em> is <code>None</code>.</p> <p>Basically, <a class="reference internal" href="#asyncio.run" title="asyncio.run"><code>asyncio.run()</code></a> example can be rewritten with the runner usage:</p> <pre data-language="python">async def main(): + await asyncio.sleep(1) + print('hello') + +with asyncio.Runner() as runner: + runner.run(main()) +</pre> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> <dl class="py method"> <dt class="sig sig-object py" id="asyncio.Runner.run"> +<code>run(coro, *, context=None)</code> </dt> <dd> +<p>Run a <a class="reference internal" href="../glossary#term-coroutine"><span class="xref std std-term">coroutine</span></a> <em>coro</em> in the embedded loop.</p> <p>Return the coroutine’s result or raise its exception.</p> <p>An optional keyword-only <em>context</em> argument allows specifying a custom <a class="reference internal" href="contextvars#contextvars.Context" title="contextvars.Context"><code>contextvars.Context</code></a> for the <em>coro</em> to run in. The runner’s default context is used if <code>None</code>.</p> <p>This function cannot be called when another asyncio event loop is running in the same thread.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="asyncio.Runner.close"> +<code>close()</code> </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#contextvars.Context" title="contextvars.Context"><code>contextvars.Context</code></a>.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="asyncio.Runner.get_loop"> +<code>get_loop()</code> </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><a class="reference internal" href="#asyncio.Runner" title="asyncio.Runner"><code>Runner</code></a> 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#with"><code>with</code></a> body entering or the first call of <a class="reference internal" href="#asyncio.run" title="asyncio.run"><code>run()</code></a> or <a class="reference internal" href="#asyncio.Runner.get_loop" title="asyncio.Runner.get_loop"><code>get_loop()</code></a>.</p> </div> </dd> +</dl> </section> <section id="handling-keyboard-interruption"> <h2>Handling Keyboard Interruption</h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> <p>When <a class="reference internal" href="signal#signal.SIGINT" title="signal.SIGINT"><code>signal.SIGINT</code></a> is raised by <kbd class="kbd compound docutils literal notranslate"><kbd class="kbd docutils literal notranslate">Ctrl</kbd>-<kbd class="kbd docutils literal notranslate">C</kbd></kbd>, <a class="reference internal" href="exceptions#KeyboardInterrupt" title="KeyboardInterrupt"><code>KeyboardInterrupt</code></a> exception is raised in the main thread by default. However this doesn’t work with <a class="reference internal" href="asyncio#module-asyncio" title="asyncio: Asynchronous I/O."><code>asyncio</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#module-asyncio" title="asyncio: Asynchronous I/O."><code>asyncio</code></a> handles <a class="reference internal" href="signal#signal.SIGINT" title="signal.SIGINT"><code>signal.SIGINT</code></a> as follows:</p> <ol class="arabic simple"> <li> +<a class="reference internal" href="#asyncio.Runner.run" title="asyncio.Runner.run"><code>asyncio.Runner.run()</code></a> installs a custom <a class="reference internal" href="signal#signal.SIGINT" title="signal.SIGINT"><code>signal.SIGINT</code></a> handler before any user code is executed and removes it when exiting from the function.</li> <li>The <a class="reference internal" href="#asyncio.Runner" title="asyncio.Runner"><code>Runner</code></a> creates the main task for the passed coroutine for its execution.</li> <li>When <a class="reference internal" href="signal#signal.SIGINT" title="signal.SIGINT"><code>signal.SIGINT</code></a> is raised by <kbd class="kbd compound docutils literal notranslate"><kbd class="kbd docutils literal notranslate">Ctrl</kbd>-<kbd class="kbd docutils literal notranslate">C</kbd></kbd>, the custom signal handler cancels the main task by calling <a class="reference internal" href="asyncio-task#asyncio.Task.cancel" title="asyncio.Task.cancel"><code>asyncio.Task.cancel()</code></a> which raises <a class="reference internal" href="asyncio-exceptions#asyncio.CancelledError" title="asyncio.CancelledError"><code>asyncio.CancelledError</code></a> inside the main task. This causes the Python stack to unwind, <code>try/except</code> and <code>try/finally</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>asyncio.Runner.run()</code></a> raises <a class="reference internal" href="exceptions#KeyboardInterrupt" title="KeyboardInterrupt"><code>KeyboardInterrupt</code></a>.</li> <li>A user could write a tight loop which cannot be interrupted by <a class="reference internal" href="asyncio-task#asyncio.Task.cancel" title="asyncio.Task.cancel"><code>asyncio.Task.cancel()</code></a>, in which case the second following <kbd class="kbd compound docutils literal notranslate"><kbd class="kbd docutils literal notranslate">Ctrl</kbd>-<kbd class="kbd docutils literal notranslate">C</kbd></kbd> immediately raises the <a class="reference internal" href="exceptions#KeyboardInterrupt" title="KeyboardInterrupt"><code>KeyboardInterrupt</code></a> without cancelling the main task.</li> </ol> </section> <div class="_attribution"> + <p class="_attribution-p"> + © 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br> + <a href="https://docs.python.org/3.12/library/asyncio-runner.html" class="_attribution-link">https://docs.python.org/3.12/library/asyncio-runner.html</a> + </p> +</div> |