orbit-oss/flask
4
4
Fork 2
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
flask/flask-docs/async-await.html

205 lines
14 KiB
HTML
Raw Normal View History

Preparar para publicar en Read the Docs Signed-off-by: Edgar Alvarado Taleno <edgar.alvaradotaleno@ucr.ac.cr>
2025-04-10 15:52:02 -06:00
<!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">
<title>Using async and await &#8212; Flask Documentation (3.2.x)</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=6625fa76" />
<link rel="stylesheet" type="text/css" href="_static/flask.css?v=b87c8d14" />
<script src="_static/documentation_options.js?v=56528222"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script data-project="flask" data-version="3.2.x" src="_static/describe_version.js?v=fa7f30d0"></script>
<link rel="icon" href="_static/shortcut-icon.png"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="API" href="api.html" />
[pre-commit.ci lite] apply automatic fixes
2025-04-10 22:13:49 +00:00
<link rel="prev" title="Apache httpd" href="deploying/apache-httpd.html" />
Preparar para publicar en Read the Docs Signed-off-by: Edgar Alvarado Taleno <edgar.alvaradotaleno@ucr.ac.cr>
2025-04-10 15:52:02 -06:00
</head><body>
<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="api.html" title="API"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="deploying/apache-httpd.html" title="Apache httpd"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Flask Documentation (3.2.x)</a> &#187;</li>
[pre-commit.ci lite] apply automatic fixes
2025-04-10 22:13:49 +00:00
<li class="nav-item nav-item-this"><a href="">Using <code class="docutils literal notranslate"><span class="pre">async</span></code> and <code class="docutils literal notranslate"><span class="pre">await</span></code></a></li>
Preparar para publicar en Read the Docs Signed-off-by: Edgar Alvarado Taleno <edgar.alvaradotaleno@ucr.ac.cr>
2025-04-10 15:52:02 -06:00
</ul>
[pre-commit.ci lite] apply automatic fixes
2025-04-10 22:13:49 +00:00
</div>
Preparar para publicar en Read the Docs Signed-off-by: Edgar Alvarado Taleno <edgar.alvaradotaleno@ucr.ac.cr>
2025-04-10 15:52:02 -06:00
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
[pre-commit.ci lite] apply automatic fixes
2025-04-10 22:13:49 +00:00
Preparar para publicar en Read the Docs Signed-off-by: Edgar Alvarado Taleno <edgar.alvaradotaleno@ucr.ac.cr>
2025-04-10 15:52:02 -06:00
<section id="using-async-and-await">
<span id="async-await"></span><h1>Using <code class="docutils literal notranslate"><span class="pre">async</span></code> and <code class="docutils literal notranslate"><span class="pre">await</span></code><a class="headerlink" href="#using-async-and-await" title="Link to this heading"></a></h1>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified added">Added in version 2.0.</span></p>
</div>
</details><p>Routes, error handlers, before request, after request, and teardown
functions can all be coroutine functions if Flask is installed with the
<code class="docutils literal notranslate"><span class="pre">async</span></code> extra (<code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">flask[async]</span></code>). This allows views to be
defined with <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code> and use <code class="docutils literal notranslate"><span class="pre">await</span></code>.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nd">@app</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/get-data&quot;</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_data</span><span class="p">():</span>
<span class="n">data</span> <span class="o">=</span> <span class="k">await</span> <span class="n">async_db_query</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
<span class="k">return</span> <span class="n">jsonify</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
<p>Pluggable class-based views also support handlers that are implemented as
coroutines. This applies to the <a class="reference internal" href="api.html#flask.views.View.dispatch_request" title="flask.views.View.dispatch_request"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dispatch_request()</span></code></a>
method in views that inherit from the <a class="reference internal" href="api.html#flask.views.View" title="flask.views.View"><code class="xref py py-class docutils literal notranslate"><span class="pre">flask.views.View</span></code></a> class, as
well as all the HTTP method handlers in views that inherit from the
<a class="reference internal" href="api.html#flask.views.MethodView" title="flask.views.MethodView"><code class="xref py py-class docutils literal notranslate"><span class="pre">flask.views.MethodView</span></code></a> class.</p>
<div class="admonition-using-async-with-greenlet admonition">
<p class="admonition-title">Using <code class="docutils literal notranslate"><span class="pre">async</span></code> with greenlet</p>
<p>When using gevent or eventlet to serve an application or patch the
runtime, greenlet&gt;=1.0 is required. When using PyPy, PyPy&gt;=7.3.7 is
required.</p>
</div>
<section id="performance">
<h2>Performance<a class="headerlink" href="#performance" title="Link to this heading"></a></h2>
<p>Async functions require an event loop to run. Flask, as a WSGI
application, uses one worker to handle one request/response cycle.
When a request comes in to an async view, Flask will start an event loop
in a thread, run the view function there, then return the result.</p>
<p>Each request still ties up one worker, even for async views. The upside
is that you can run async code within a view, for example to make
multiple concurrent database queries, HTTP requests to an external API,
etc. However, the number of requests your application can handle at one
time will remain the same.</p>
<p><strong>Async is not inherently faster than sync code.</strong> Async is beneficial
when performing concurrent IO-bound tasks, but will probably not improve
CPU-bound tasks. Traditional Flask views will still be appropriate for
most use cases, but Flask’s async support enables writing and using
code that wasn’t possible natively before.</p>
</section>
<section id="background-tasks">
<h2>Background tasks<a class="headerlink" href="#background-tasks" title="Link to this heading"></a></h2>
<p>Async functions will run in an event loop until they complete, at
which stage the event loop will stop. This means any additional
spawned tasks that haven’t completed when the async function completes
will be cancelled. Therefore you cannot spawn background tasks, for
example via <code class="docutils literal notranslate"><span class="pre">asyncio.create_task</span></code>.</p>
<p>If you wish to use background tasks it is best to use a task queue to
trigger background work, rather than spawn tasks in a view
function. With that in mind you can spawn asyncio tasks by serving
Flask with an ASGI server and utilising the asgiref WsgiToAsgi adapter
as described in <a class="reference internal" href="deploying/asgi.html"><span class="doc">ASGI</span></a>. This works as the adapter creates
an event loop that runs continually.</p>
</section>
<section id="when-to-use-quart-instead">
<h2>When to use Quart instead<a class="headerlink" href="#when-to-use-quart-instead" title="Link to this heading"></a></h2>
<p>Flask’s async support is less performant than async-first frameworks due
to the way it is implemented. If you have a mainly async codebase it
would make sense to consider <a class="reference external" href="https://github.com/pallets/quart">Quart</a>. Quart is a reimplementation of
Flask based on the <a class="reference external" href="https://asgi.readthedocs.io/en/latest/">ASGI</a> standard instead of WSGI. This allows it to
handle many concurrent requests, long running requests, and websockets
without requiring multiple worker processes or threads.</p>
<p>It has also already been possible to run Flask with Gevent or Eventlet
to get many of the benefits of async request handling. These libraries
patch low-level Python functions to accomplish this, whereas <code class="docutils literal notranslate"><span class="pre">async</span></code>/
<code class="docutils literal notranslate"><span class="pre">await</span></code> and ASGI use standard, modern Python capabilities. Deciding
whether you should use Flask, Quart, or something else is ultimately up
to understanding the specific needs of your project.</p>
</section>
<section id="extensions">
<h2>Extensions<a class="headerlink" href="#extensions" title="Link to this heading"></a></h2>
<p>Flask extensions predating Flask’s async support do not expect async views.
If they provide decorators to add functionality to views, those will probably
not work with async views because they will not await the function or be
awaitable. Other functions they provide will not be awaitable either and
will probably be blocking if called within an async view.</p>
<p>Extension authors can support async functions by utilising the
<a class="reference internal" href="api.html#flask.Flask.ensure_sync" title="flask.Flask.ensure_sync"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flask.Flask.ensure_sync()</span></code></a> method. For example, if the extension
provides a view function decorator add <code class="docutils literal notranslate"><span class="pre">ensure_sync</span></code> before calling
the decorated function,</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">extension</span><span class="p">(</span><span class="n">func</span><span class="p">):</span>
<span class="nd">@wraps</span><span class="p">(</span><span class="n">func</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">wrapper</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="o">...</span> <span class="c1"># Extension logic</span>
<span class="k">return</span> <span class="n">current_app</span><span class="o">.</span><span class="n">ensure_sync</span><span class="p">(</span><span class="n">func</span><span class="p">)(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
<span class="k">return</span> <span class="n">wrapper</span>
</pre></div>
</div>
<p>Check the changelog of the extension you want to use to see if they’ve
implemented async support, or make a feature request or PR to them.</p>
</section>
<section id="other-event-loops">
<h2>Other event loops<a class="headerlink" href="#other-event-loops" title="Link to this heading"></a></h2>
<p>At the moment Flask only supports <a class="reference external" href="https://docs.python.org/3/library/asyncio.html#module-asyncio" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a>. It’s possible to
override <a class="reference internal" href="api.html#flask.Flask.ensure_sync" title="flask.Flask.ensure_sync"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flask.Flask.ensure_sync()</span></code></a> to change how async functions
are wrapped to use a different library.</p>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<span id="sidebar-top"></span>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
[pre-commit.ci lite] apply automatic fixes
2025-04-10 22:13:49 +00:00
Preparar para publicar en Read the Docs Signed-off-by: Edgar Alvarado Taleno <edgar.alvaradotaleno@ucr.ac.cr>
2025-04-10 15:52:02 -06:00
<p class="logo"><a href="index.html">
<img class="logo" src="_static/flask-vertical.png" alt="Logo of Flask"/>
</a></p>
[pre-commit.ci lite] apply automatic fixes
2025-04-10 22:13:49 +00:00
Preparar para publicar en Read the Docs Signed-off-by: Edgar Alvarado Taleno <edgar.alvaradotaleno@ucr.ac.cr>
2025-04-10 15:52:02 -06:00
<h3>Contents</h3>
<ul>
<li><a class="reference internal" href="#">Using <code class="docutils literal notranslate"><span class="pre">async</span></code> and <code class="docutils literal notranslate"><span class="pre">await</span></code></a><ul>
<li><a class="reference internal" href="#performance">Performance</a></li>
<li><a class="reference internal" href="#background-tasks">Background tasks</a></li>
<li><a class="reference internal" href="#when-to-use-quart-instead">When to use Quart instead</a></li>
<li><a class="reference internal" href="#extensions">Extensions</a></li>
<li><a class="reference internal" href="#other-event-loops">Other event loops</a></li>
</ul>
</li>
</ul>
<h3>Navigation</h3>
<ul>
<li><a href="index.html">Overview</a>
<ul>
<li>Previous: <a href="deploying/apache-httpd.html" title="previous chapter">Apache httpd</a>
<li>Next: <a href="api.html" title="next chapter">API</a>
</ul>
</li>
</ul>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script><div id="ethical-ad-placement"></div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2010 Pallets.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.1.3.
</div>
</body>
[pre-commit.ci lite] apply automatic fixes
2025-04-10 22:13:49 +00:00
</html>
Reference in a new issue Copy permalink