<h1>The Request Context<aclass="headerlink"href="#the-request-context"title="Link to this heading">¶</a></h1>
<p>The request context keeps track of the request-level data during a
request. Rather than passing the request object to each function that
runs during a request, the <aclass="reference internal"href="api.html#flask.request"title="flask.request"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">request</span></code></a> and <aclass="reference internal"href="api.html#flask.session"title="flask.session"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">session</span></code></a> proxies
are accessed instead.</p>
<p>This is similar to <aclass="reference internal"href="appcontext.html"><spanclass="doc">The Application Context</span></a>, which keeps track of the
application-level data independent of a request. A corresponding
application context is pushed when a request context is pushed.</p>
<sectionid="purpose-of-the-context">
<h2>Purpose of the Context<aclass="headerlink"href="#purpose-of-the-context"title="Link to this heading">¶</a></h2>
<p>When the <aclass="reference internal"href="api.html#flask.Flask"title="flask.Flask"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">Flask</span></code></a> application handles a request, it creates a
<aclass="reference internal"href="api.html#flask.Request"title="flask.Request"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">Request</span></code></a> object based on the environment it received from the
WSGI server. Because a <em>worker</em> (thread, process, or coroutine depending
on the server) handles only one request at a time, the request data can
be considered global to that worker during that request. Flask uses the
term <em>context local</em> for this.</p>
<p>Flask automatically <em>pushes</em> a request context when handling a request.
View functions, error handlers, and other functions that run during a
request will have access to the <aclass="reference internal"href="api.html#flask.request"title="flask.request"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">request</span></code></a> proxy, which points to
the request object for the current request.</p>
</section>
<sectionid="lifetime-of-the-context">
<h2>Lifetime of the Context<aclass="headerlink"href="#lifetime-of-the-context"title="Link to this heading">¶</a></h2>
<p>When a Flask application begins handling a request, it pushes a request
context, which also pushes an <aclass="reference internal"href="appcontext.html"><spanclass="doc">app context</span></a>. When the
request ends it pops the request context then the application context.</p>
<p>The context is unique to each thread (or other worker type).
<aclass="reference internal"href="api.html#flask.request"title="flask.request"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">request</span></code></a> cannot be passed to another thread, the other thread has
a different context space and will not know about the request the parent
thread was pointing to.</p>
<p>Context locals are implemented using Python’s <aclass="reference external"href="https://docs.python.org/3/library/contextvars.html#module-contextvars"title="(in Python v3.13)"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="pre">contextvars</span></code></a> and
lifetime of context vars automatically, and local proxy wraps that
low-level interface to make the data easier to work with.</p>
</section>
<sectionid="manually-push-a-context">
<h2>Manually Push a Context<aclass="headerlink"href="#manually-push-a-context"title="Link to this heading">¶</a></h2>
<p>If you try to access <aclass="reference internal"href="api.html#flask.request"title="flask.request"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">request</span></code></a>, or anything that uses it, outside
a request context, you’ll get this error message:</p>
<divclass="highlight-pytb notranslate"><divclass="highlight"><pre><span></span><spanclass="x">RuntimeError: Working outside of request context.</span>
<spanclass="x">This typically means that you attempted to use functionality that</span>
<spanclass="x">needed an active HTTP request. Consult the documentation on testing</span>
<spanclass="x">for information about how to avoid this problem.</span>
<p>This should typically only happen when testing code that expects an
active request. One option is to use the
<aclass="reference internal"href="api.html#flask.Flask.test_client"title="flask.Flask.test_client"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">test</span><spanclass="pre">client</span></code></a> to simulate a full request. Or
you can use <aclass="reference internal"href="api.html#flask.Flask.test_request_context"title="flask.Flask.test_request_context"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">test_request_context()</span></code></a> in a <codeclass="docutils literal notranslate"><spanclass="pre">with</span></code> block, and
everything that runs in the block will have access to <aclass="reference internal"href="api.html#flask.request"title="flask.request"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">request</span></code></a>,
<h2>How the Context Works<aclass="headerlink"href="#how-the-context-works"title="Link to this heading">¶</a></h2>
<p>The <aclass="reference internal"href="api.html#flask.Flask.wsgi_app"title="flask.Flask.wsgi_app"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">Flask.wsgi_app()</span></code></a> method is called to handle each request. It
manages the contexts during the request. Internally, the request and
application contexts work like stacks. When contexts are pushed, the
proxies that depend on them are available and point at information from
the top item.</p>
<p>When the request starts, a <aclass="reference internal"href="api.html#flask.ctx.RequestContext"title="flask.ctx.RequestContext"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">RequestContext</span></code></a> is created and
pushed, which creates and pushes an <aclass="reference internal"href="api.html#flask.ctx.AppContext"title="flask.ctx.AppContext"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">AppContext</span></code></a> first if
a context for that application is not already the top context. While
these contexts are pushed, the <aclass="reference internal"href="api.html#flask.current_app"title="flask.current_app"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">current_app</span></code></a>, <aclass="reference internal"href="api.html#flask.g"title="flask.g"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">g</span></code></a>,
<aclass="reference internal"href="api.html#flask.request"title="flask.request"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">request</span></code></a>, and <aclass="reference internal"href="api.html#flask.session"title="flask.session"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">session</span></code></a> proxies are available to the
original thread handling the request.</p>
<p>Other contexts may be pushed to change the proxies during a request.
While this is not a common pattern, it can be used in advanced
applications to, for example, do internal redirects or chain different
applications together.</p>
<p>After the request is dispatched and a response is generated and sent,
the request context is popped, which then pops the application context.
Immediately before they are popped, the <aclass="reference internal"href="api.html#flask.Flask.teardown_request"title="flask.Flask.teardown_request"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">teardown_request()</span></code></a>
and <aclass="reference internal"href="api.html#flask.Flask.teardown_appcontext"title="flask.Flask.teardown_appcontext"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">teardown_appcontext()</span></code></a> functions are executed. These
execute even if an unhandled exception occurred during dispatch.</p>
</section>
<sectionid="callbacks-and-errors">
<spanid="id1"></span><h2>Callbacks and Errors<aclass="headerlink"href="#callbacks-and-errors"title="Link to this heading">¶</a></h2>
<p>Flask dispatches a request in multiple stages which can affect the
request, response, and how errors are handled. The contexts are active
during all of these stages.</p>
<p>A <aclass="reference internal"href="api.html#flask.Blueprint"title="flask.Blueprint"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">Blueprint</span></code></a> can add handlers for these events that are specific
to the blueprint. The handlers for a blueprint will run if the blueprint
owns the route that matches the request.</p>
<olclass="arabic simple">
<li><p>Before each request, <aclass="reference internal"href="api.html#flask.Flask.before_request"title="flask.Flask.before_request"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">before_request()</span></code></a> functions are
called. If one of these functions return a value, the other
functions are skipped. The return value is treated as the response
and the view function is not called.</p></li>
<li><p>If the <aclass="reference internal"href="api.html#flask.Flask.before_request"title="flask.Flask.before_request"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">before_request()</span></code></a> functions did not return a
response, the view function for the matched route is called and
returns a response.</p></li>
<li><p>The return value of the view is converted into an actual response
object and passed to the <aclass="reference internal"href="api.html#flask.Flask.after_request"title="flask.Flask.after_request"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">after_request()</span></code></a>
functions. Each function returns a modified or new response object.</p></li>
<li><p>After the response is returned, the contexts are popped, which calls
the <aclass="reference internal"href="api.html#flask.Flask.teardown_request"title="flask.Flask.teardown_request"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">teardown_request()</span></code></a> and
<aclass="reference internal"href="api.html#flask.Flask.teardown_appcontext"title="flask.Flask.teardown_appcontext"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">teardown_appcontext()</span></code></a> functions. These functions are
called even if an unhandled exception was raised at any point above.</p></li>
</ol>
<p>If an exception is raised before the teardown functions, Flask tries to
match it with an <aclass="reference internal"href="api.html#flask.Flask.errorhandler"title="flask.Flask.errorhandler"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">errorhandler()</span></code></a> function to handle the
exception and return a response. If no error handler is found, or the
handler itself raises an exception, Flask returns a generic
<codeclass="docutils literal notranslate"><spanclass="pre">500</span><spanclass="pre">Internal</span><spanclass="pre">Server</span><spanclass="pre">Error</span></code> response. The teardown functions are still
called, and are passed the exception object.</p>
<p>If debug mode is enabled, unhandled exceptions are not converted to a
<codeclass="docutils literal notranslate"><spanclass="pre">500</span></code> response and instead are propagated to the WSGI server. This
allows the development server to present the interactive debugger with
the traceback.</p>
<sectionid="teardown-callbacks">
<h3>Teardown Callbacks<aclass="headerlink"href="#teardown-callbacks"title="Link to this heading">¶</a></h3>
<p>The teardown callbacks are independent of the request dispatch, and are
instead called by the contexts when they are popped. The functions are
called even if there is an unhandled exception during dispatch, and for
manually pushed contexts. This means there is no guarantee that any
other parts of the request dispatch have run first. Be sure to write
these functions in a way that does not depend on other callbacks and
will not fail.</p>
<p>During testing, it can be useful to defer popping the contexts after the
request ends, so that their data can be accessed in the test function.
Use the <aclass="reference internal"href="api.html#flask.Flask.test_client"title="flask.Flask.test_client"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">test_client()</span></code></a> as a <codeclass="docutils literal notranslate"><spanclass="pre">with</span></code> block to preserve the
contexts until the <codeclass="docutils literal notranslate"><spanclass="pre">with</span></code> block exits.</p>
<li><p><aclass="reference internal"href="api.html#flask.request_started"title="flask.request_started"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">request_started</span></code></a> is sent before the <aclass="reference internal"href="api.html#flask.Flask.before_request"title="flask.Flask.before_request"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">before_request()</span></code></a> functions
are called.</p></li>
<li><p><aclass="reference internal"href="api.html#flask.request_finished"title="flask.request_finished"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">request_finished</span></code></a> is sent after the <aclass="reference internal"href="api.html#flask.Flask.after_request"title="flask.Flask.after_request"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">after_request()</span></code></a> functions
are called.</p></li>
<li><p><aclass="reference internal"href="api.html#flask.got_request_exception"title="flask.got_request_exception"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">got_request_exception</span></code></a> is sent when an exception begins to be handled, but
before an <aclass="reference internal"href="api.html#flask.Flask.errorhandler"title="flask.Flask.errorhandler"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">errorhandler()</span></code></a> is looked up or called.</p></li>
<li><p><aclass="reference internal"href="api.html#flask.request_tearing_down"title="flask.request_tearing_down"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">request_tearing_down</span></code></a> is sent after the <aclass="reference internal"href="api.html#flask.Flask.teardown_request"title="flask.Flask.teardown_request"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">teardown_request()</span></code></a>
