<h1>Signals<aclass="headerlink"href="#signals"title="Link to this heading">¶</a></h1>
<p>Signals are a lightweight way to notify subscribers of certain events during the
lifecycle of the application and each request. When an event occurs, it emits the
signal, which calls each subscriber.</p>
<p>Signals are implemented by the <aclass="reference external"href="https://pypi.org/project/blinker/">Blinker</a> library. See its documentation for detailed
information. Flask provides some built-in signals. Extensions may provide their own.</p>
<p>Many signals mirror Flask’s decorator-based callbacks with similar names. For example,
the <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> signal is similar to 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>
decorator. The advantage of signals over handlers is that they can be subscribed to
temporarily, and can’t directly affect the application. This is useful for testing,
metrics, auditing, and more. For example, if you want to know what templates were
rendered at what parts of what requests, there is a signal that will notify you of that
information.</p>
<sectionid="core-signals">
<h2>Core Signals<aclass="headerlink"href="#core-signals"title="Link to this heading">¶</a></h2>
<p>See <aclass="reference internal"href="api.html#core-signals-list"><spanclass="std std-ref">Signals</span></a> for a list of all built-in signals. The <aclass="reference internal"href="lifecycle.html"><spanclass="doc">Application Structure and Lifecycle</span></a>
page also describes the order that signals and decorators execute.</p>
</section>
<sectionid="subscribing-to-signals">
<h2>Subscribing to Signals<aclass="headerlink"href="#subscribing-to-signals"title="Link to this heading">¶</a></h2>
<p>To subscribe to a signal, you can use the
<codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">connect()</span></code> method of a signal. The first
argument is the function that should be called when the signal is emitted,
the optional second argument specifies a sender. To unsubscribe from a
signal, you can use the <codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">disconnect()</span></code> method.</p>
<p>For all core Flask signals, the sender is the application that issued the
signal. When you subscribe to a signal, be sure to also provide a sender
unless you really want to listen for signals from all applications. This is
especially true if you are developing an extension.</p>
<p>For example, here is a helper context manager that can be used in a unit test
to determine which templates were rendered and what variables were passed
<p>Make sure to subscribe with an extra <codeclass="docutils literal notranslate"><spanclass="pre">**extra</span></code> argument so that your
calls don’t fail if Flask introduces new arguments to the signals.</p>
<p>All the template rendering in the code issued by the application <codeclass="code docutils literal notranslate"><spanclass="pre">app</span></code>
in the body of the <codeclass="docutils literal notranslate"><spanclass="pre">with</span></code> block will now be recorded in the <codeclass="code docutils literal notranslate"><spanclass="pre">templates</span></code>
variable. Whenever a template is rendered, the template object as well as
context are appended to it.</p>
<p>Additionally there is a convenient helper method
(<codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">connected_to()</span></code>) that allows you to
temporarily subscribe a function to a signal with a context manager on
its own. Because the return value of the context manager cannot be
specified that way, you have to pass the list in as an argument:</p>
<h2>Creating Signals<aclass="headerlink"href="#creating-signals"title="Link to this heading">¶</a></h2>
<p>If you want to use signals in your own application, you can use the
blinker library directly. The most common use case are named signals in a
custom <aclass="reference external"href="https://blinker.readthedocs.io/en/stable/#blinker.Namespace"title="(in Blinker v1.9)"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">Namespace</span></code></a>. This is what is recommended
<pclass="admonition-title">Passing Proxies as Senders</p>
<p>Never pass <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> as sender to a signal. Use
<codeclass="docutils literal notranslate"><spanclass="pre">current_app._get_current_object()</span></code> instead. The reason for this is
that <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> is a proxy and not the real application
object.</p>
</div>
</section>
<sectionid="signals-and-flask-s-request-context">
<h2>Signals and Flask’s Request Context<aclass="headerlink"href="#signals-and-flask-s-request-context"title="Link to this heading">¶</a></h2>
<p>Signals fully support <aclass="reference internal"href="reqcontext.html"><spanclass="doc">The Request Context</span></a> when receiving signals.
Context-local variables are consistently available between
<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> and <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>, so you can
rely on <aclass="reference internal"href="api.html#flask.g"title="flask.g"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">flask.g</span></code></a> and others as needed. Note the limitations described
in <aclass="reference internal"href="#signals-sending"><spanclass="std std-ref">Sending Signals</span></a> and the <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> signal.</p>
<spanclass="nb">print</span><spanclass="p">(</span><spanclass="sa">f</span><spanclass="s1">'Template </span><spanclass="si">{</span><spanclass="n">template</span><spanclass="o">.</span><spanclass="n">name</span><spanclass="si">}</span><spanclass="s1"> is rendered with </span><spanclass="si">{</span><spanclass="n">context</span><spanclass="si">}</span><spanclass="s1">'</span><spanclass="p">)</span>
