Files
2026-07-14 04:14:56 +00:00

2642 lines
376 KiB
HTML
Raw Permalink 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" />
<title>API Reference &#8212; responder 9.2.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=5ecbeea2" />
<link rel="stylesheet" type="text/css" href="_static/basic.css?v=b08954a9" />
<link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=eb4102c5" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
<link rel="stylesheet" type="text/css" href="_static/sphinx-design.min.css?v=95c83b7e" />
<link rel="stylesheet" type="text/css" href="_static/design-elements.e5416f61bae5d36adc6d722a2b6f8cff.css?v=452a8e97" />
<script src="_static/documentation_options.js?v=e8b940be"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="_static/clipboard.min.js?v=a7894cd8"></script>
<script src="_static/copybutton.js?v=fd10adb8"></script>
<script>
</script>
<script src="_static/design-tabs.js?v=f930bc37"></script>
<script src="_static/design-elements.bbdccc18c4abea9397628f9fea3d48c2.js?v=03c7770e"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Command Line Interface" href="cli.html" />
<link rel="prev" title="Migrating from Flask" href="tutorial-flask.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="api-reference">
<h1>API Reference<a class="headerlink" href="#api-reference" title="Link to this heading"></a></h1>
<p>This page documents Responder’s public Python API. For usage examples
and explanations, see the <a class="reference internal" href="quickstart.html"><span class="doc">Quick Start</span></a> and <a class="reference internal" href="tour.html"><span class="doc">Feature Tour</span></a>.</p>
<section id="the-api-class">
<h2>The API Class<a class="headerlink" href="#the-api-class" title="Link to this heading"></a></h2>
<p>The central object of every Responder application. It holds your routes,
middleware, templates, and configuration. Create one at the top of your
module and use it to define your entire web service.</p>
<p>Quick example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">responder</span>
<span class="n">api</span> <span class="o">=</span> <span class="n">responder</span><span class="o">.</span><span class="n">API</span><span class="p">(</span>
<span class="n">title</span><span class="o">=</span><span class="s2">&quot;My Service&quot;</span><span class="p">,</span> <span class="c1"># OpenAPI title</span>
<span class="n">version</span><span class="o">=</span><span class="s2">&quot;1.0&quot;</span><span class="p">,</span> <span class="c1"># OpenAPI version</span>
<span class="n">openapi</span><span class="o">=</span><span class="s2">&quot;3.0.2&quot;</span><span class="p">,</span> <span class="c1"># enable OpenAPI</span>
<span class="n">docs_route</span><span class="o">=</span><span class="s2">&quot;/docs&quot;</span><span class="p">,</span> <span class="c1"># Swagger UI at /docs</span>
<span class="n">cors</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="c1"># enable CORS</span>
<span class="n">allowed_hosts</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;example.com&quot;</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Cookie sessions are on by default (<code class="docutils literal notranslate"><span class="pre">sessions=&quot;auto&quot;</span></code>). With no key set,
Responder mints a random per-process signing key at startup and logs a
warning — fine for a single dev process, but multi-worker or multi-instance
deploys need a <em>stable</em> key so signed cookies validate everywhere. Set one
with <code class="docutils literal notranslate"><span class="pre">secret_key=</span></code> or the <code class="docutils literal notranslate"><span class="pre">RESPONDER_SECRET_KEY</span></code> environment variable:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">c</span> <span class="s2">&quot;import secrets; print(secrets.token_urlsafe(32))&quot;</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">secret_key=&quot;NOTASECRET&quot;</span></code> (the old public default) now raises
<a class="reference internal" href="#responder.ext.sessions.SessionConfigError" title="responder.ext.sessions.SessionConfigError"><code class="xref py py-class docutils literal notranslate"><span class="pre">SessionConfigError</span></code></a>, and <code class="docutils literal notranslate"><span class="pre">sessions=True</span></code>
with no key raises as well. Pass <code class="docutils literal notranslate"><span class="pre">sessions=False</span></code> for a stateless service.
See <a class="reference internal" href="guide-config.html"><span class="doc">Configuration</span></a> for the full secret-key and session-cookie story.</p>
</div>
<dl class="py class" id="module-responder">
<dt class="sig sig-object py" id="responder.API">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">API</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">*</span></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">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">title</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">version</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">description</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">terms_of_service</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">contact</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">license</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">openapi</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">openapi_servers</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">openapi_route</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'/schema.yml'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">static_dir</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">&lt;object</span> <span class="pre">object&gt;</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">static_route</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'/static'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">implicit_static_fallback</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">templates_dir</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'templates'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">auto_escape</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">secret_key</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">enable_hsts</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">security_headers</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">docs_route</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">cors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cors_params</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">{'allow_credentials':</span> <span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">'allow_headers'</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="p"><span class="pre">(</span></span><span class="p"><span class="pre">)</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">'allow_methods'</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">('GET'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">)</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">'allow_origin_regex'</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">'allow_origins'</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="p"><span class="pre">(</span></span><span class="p"><span class="pre">)</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">'expose_headers'</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="p"><span class="pre">(</span></span><span class="p"><span class="pre">)</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">'max_age'</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">600}</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">allowed_hosts</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">openapi_theme</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'swagger_ui'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">lifespan</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">gzip</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">request_id</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">enable_logging</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">trust_proxy_headers</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">csrf</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">redirect_slashes</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">max_request_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">104857600</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">auto_etag</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">auto_vary</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">request_timeout</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">ws_idle_timeout</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">trace_dispatch</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sessions</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'auto'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">session_backend</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">session_cookie</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">session_https_only</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">session_same_site</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'lax'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">session_max_age</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1209600</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">metrics_route</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">metrics_buckets</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">health_route</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">encoder</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">json_ensure_ascii</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">json_decimal</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'string'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">problem_details</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">problem_handler</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">auth</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="reference internal" href="_modules/responder/api.html#API"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API" title="Link to this definition"></a></dt>
<dd><p>The primary web-service class.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>static_dir</strong> – The directory to use for static files (default <code class="docutils literal notranslate"><span class="pre">static</span></code>). Mounted at <code class="docutils literal notranslate"><span class="pre">static_route</span></code> only if it exists — it is never created for you. Passing a <code class="docutils literal notranslate"><span class="pre">static_dir</span></code> explicitly that doesn’t exist raises <code class="docutils literal notranslate"><span class="pre">FileNotFoundError</span></code>.</p></li>
<li><p><strong>templates_dir</strong> – The directory to use for templates (default <code class="docutils literal notranslate"><span class="pre">templates</span></code>). It is not created for you.</p></li>
<li><p><strong>auto_escape</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code>, HTML and XML templates will automatically be escaped.</p></li>
<li><p><strong>enable_hsts</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code>, redirect HTTP requests to HTTPS and send a <code class="docutils literal notranslate"><span class="pre">Strict-Transport-Security</span></code> header.</p></li>
<li><p><strong>security_headers</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code>, add common security headers (nosniff, X-Frame-Options, Referrer-Policy) to every response; pass a dict of <code class="docutils literal notranslate"><span class="pre">SecurityHeadersMiddleware</span></code> options to customize (e.g. <code class="docutils literal notranslate"><span class="pre">content_security_policy</span></code>).</p></li>
<li><p><strong>gzip</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default), compress responses with GZip.</p></li>
<li><p><strong>openapi_theme</strong> – OpenAPI documentation theme, must be one of <code class="docutils literal notranslate"><span class="pre">elements</span></code>, <code class="docutils literal notranslate"><span class="pre">rapidoc</span></code>, <code class="docutils literal notranslate"><span class="pre">redoc</span></code>, <code class="docutils literal notranslate"><span class="pre">swagger_ui</span></code></p></li>
</ul>
</dd>
</dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.add_dependency">
<span class="sig-name descname"><span class="pre">add_dependency</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">provider</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">scope</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'request'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.add_dependency"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.add_dependency" title="Link to this definition"></a></dt>
<dd><p>Register a dependency provider under an explicit name.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>name</strong> – The view parameter name to inject as.</p></li>
<li><p><strong>provider</strong> – The provider function (sync/async function or generator).</p></li>
<li><p><strong>scope</strong> – <code class="docutils literal notranslate"><span class="pre">&quot;request&quot;</span></code> (default) or <code class="docutils literal notranslate"><span class="pre">&quot;app&quot;</span></code>.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.add_event_handler">
<span class="sig-name descname"><span class="pre">add_event_handler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">event_type</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">handler</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.add_event_handler"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.add_event_handler" title="Link to this definition"></a></dt>
<dd><p>Adds an event handler to the API.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>event_type</strong> – A string in (“startup”, “shutdown”)</p></li>
<li><p><strong>handler</strong> – The function to run. Can be either a function or a coroutine.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.add_exception_handler">
<span class="sig-name descname"><span class="pre">add_exception_handler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">exc_class_or_status_code</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">handler</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.add_exception_handler"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.add_exception_handler" title="Link to this definition"></a></dt>
<dd><p>Register a handler for an exception type or status code.</p>
<p><code class="docutils literal notranslate"><span class="pre">handler</span></code> is a Responder-style <code class="docutils literal notranslate"><span class="pre">(req,</span> <span class="pre">resp,</span> <span class="pre">exc)</span></code> callable (sync or
async). A handler for <code class="docutils literal notranslate"><span class="pre">500</span></code>/<code class="docutils literal notranslate"><span class="pre">Exception</span></code> installs the catch-all
server-error handler (ignored under <code class="docutils literal notranslate"><span class="pre">debug=True</span></code>, which shows the
traceback); any other exception/status routes through the exception
middleware.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.add_health_check">
<span class="sig-name descname"><span class="pre">add_health_check</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">check</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.add_health_check"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.add_health_check" title="Link to this definition"></a></dt>
<dd><p>Register a readiness check run by the health endpoint.</p>
<p><code class="docutils literal notranslate"><span class="pre">check</span></code> is a sync or async callable; it passes unless it returns
<code class="docutils literal notranslate"><span class="pre">False</span></code> or raises. The endpoint returns <code class="docutils literal notranslate"><span class="pre">200</span></code> when every check
passes and <code class="docutils literal notranslate"><span class="pre">503</span></code> otherwise, with per-check JSON. The route (default
<code class="docutils literal notranslate"><span class="pre">/health</span></code>, or the <code class="docutils literal notranslate"><span class="pre">health_route=</span></code> you set) is added on first use.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>name</strong> – A label for the check, used as its key in the JSON body.</p></li>
<li><p><strong>check</strong> – The check callable.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.add_middleware">
<span class="sig-name descname"><span class="pre">add_middleware</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">middleware_cls</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">middleware_config</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.add_middleware"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.add_middleware" title="Link to this definition"></a></dt>
<dd><p>Add ASGI middleware to the application (valid after construction).</p>
<p>User middleware sits just inside <code class="docutils literal notranslate"><span class="pre">ServerErrorMiddleware</span></code> (so its
errors are caught and rendered) and the most-recently-added runs first.
To wrap <em>everything</em> (including error rendering), wrap the API object:
<code class="docutils literal notranslate"><span class="pre">asgi</span> <span class="pre">=</span> <span class="pre">MyMiddleware(api)</span></code>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>middleware_cls</strong> – A Starlette-compatible middleware class.</p></li>
<li><p><strong>middleware_config</strong> – Keyword arguments passed to the constructor.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.add_route">
<span class="sig-name descname"><span class="pre">add_route</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</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">endpoint</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="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">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">static</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">check_existing</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">websocket</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">before_request</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">methods</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">name</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="reference internal" href="_modules/responder/api.html#API.add_route"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.add_route" title="Link to this definition"></a></dt>
<dd><p>Adds a route to the API.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>route</strong> – A string representation of the route.</p></li>
<li><p><strong>endpoint</strong> – The endpoint for the route – can be a callable, or a class.</p></li>
<li><p><strong>default</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code>, all unknown requests will route to this view.</p></li>
<li><p><strong>static</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code> and no endpoint was passed, render
<code class="docutils literal notranslate"><span class="pre">static/index.html</span></code> as a legacy default route only
when <code class="docutils literal notranslate"><span class="pre">implicit_static_fallback=True</span></code>.</p></li>
<li><p><strong>methods</strong> – Optional list of HTTP methods (e.g. <code class="docutils literal notranslate"><span class="pre">[&quot;GET&quot;,</span> <span class="pre">&quot;POST&quot;]</span></code>).</p></li>
<li><p><strong>name</strong> – Optional route name for <a class="reference internal" href="#responder.API.url_for" title="responder.API.url_for"><code class="xref py py-meth docutils literal notranslate"><span class="pre">url_for()</span></code></a> reverse lookup.</p></li>
</ul>
</dd>
</dl>
<p>Calling <code class="docutils literal notranslate"><span class="pre">add_route()</span></code> without an <code class="docutils literal notranslate"><span class="pre">endpoint</span></code> now raises by default.
Pass an endpoint explicitly, or serve static assets via
<code class="docutils literal notranslate"><span class="pre">static_dir</span></code>/<code class="docutils literal notranslate"><span class="pre">static_route</span></code>. Apps that need the old fallback
during migration can pass <code class="docutils literal notranslate"><span class="pre">API(implicit_static_fallback=True)</span></code>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.add_security_scheme">
<span class="sig-name descname"><span class="pre">add_security_scheme</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">scheme</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="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">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.add_security_scheme"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.add_security_scheme" title="Link to this definition"></a></dt>
<dd><p>Register an OpenAPI security scheme (enables Swagger’s Authorize button).</p>
<p>Accepts either an auth helper carrying its own definition
(<code class="docutils literal notranslate"><span class="pre">add_security_scheme(BearerAuth(...))</span></code>) or an explicit <code class="docutils literal notranslate"><span class="pre">name</span></code> plus a
scheme dict. With <code class="docutils literal notranslate"><span class="pre">default=True</span></code> the scheme becomes a global
requirement applied to every documented operation.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>name</strong> – The scheme name, or an auth helper object.</p></li>
<li><p><strong>scheme</strong> – The OpenAPI security-scheme dict (omit when passing a helper).</p></li>
<li><p><strong>default</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code>, require this scheme on all operations.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.after_request">
<span class="sig-name descname"><span class="pre">after_request</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">f</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="reference internal" href="_modules/responder/api.html#API.after_request"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.after_request" title="Link to this definition"></a></dt>
<dd><p>Register a function to run after every request.</p>
<p>Works both bare and called: <code class="docutils literal notranslate"><span class="pre">&#64;api.after_request</span></code> or
<code class="docutils literal notranslate"><span class="pre">&#64;api.after_request()</span></code>.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">after_request</span>
<span class="k">def</span><span class="w"> </span><span class="nf">add_request_id</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s2">&quot;X-Request-ID&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">uuid</span><span class="o">.</span><span class="n">uuid4</span><span class="p">())</span>
</pre></div>
</div>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.API.app">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">app</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="pre">MutableMapping</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Any</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Awaitable</span><span class="p"><span class="pre">[</span></span><span class="pre">MutableMapping</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Any</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="pre">MutableMapping</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Any</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Awaitable</span><span class="p"><span class="pre">[</span></span><span class="pre">None</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Awaitable</span><span class="p"><span class="pre">[</span></span><span class="pre">None</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span><a class="headerlink" href="#responder.API.app" title="Link to this definition"></a></dt>
<dd><p>The assembled ASGI middleware stack, built lazily on first access.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.API.async_requests">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">async_requests</span></span><a class="headerlink" href="#responder.API.async_requests" title="Link to this definition"></a></dt>
<dd><p>An async test client wired to the ASGI app (<code class="docutils literal notranslate"><span class="pre">httpx.AsyncClient</span></code>).</p>
<p>The async mirror of <a class="reference internal" href="#responder.API.requests" title="responder.API.requests"><code class="xref py py-attr docutils literal notranslate"><span class="pre">requests</span></code></a>; <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code> also runs the
app’s lifespan. See <code class="xref py py-class docutils literal notranslate"><span class="pre">responder.testing.AsyncTestClient</span></code>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.before_request">
<span class="sig-name descname"><span class="pre">before_request</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">websocket</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.before_request"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.before_request" title="Link to this definition"></a></dt>
<dd><p>Register a function to run before every request.</p>
<p>If the hook sets <code class="docutils literal notranslate"><span class="pre">resp.status_code</span></code>, the route handler is skipped
and the response is sent immediately (short-circuiting).</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>websocket</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code>, register as a WebSocket before-request hook instead of HTTP.</p>
</dd>
</dl>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">before_request</span><span class="p">()</span>
<span class="k">def</span><span class="w"> </span><span class="nf">check_auth</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="k">if</span> <span class="s2">&quot;Authorization&quot;</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">req</span><span class="o">.</span><span class="n">headers</span><span class="p">:</span>
<span class="n">resp</span><span class="o">.</span><span class="n">status_code</span> <span class="o">=</span> <span class="mi">401</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;error&quot;</span><span class="p">:</span> <span class="s2">&quot;unauthorized&quot;</span><span class="p">}</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.build_middleware_stack">
<span class="sig-name descname"><span class="pre">build_middleware_stack</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="pre">MutableMapping</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Any</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Awaitable</span><span class="p"><span class="pre">[</span></span><span class="pre">MutableMapping</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Any</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="pre">MutableMapping</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Any</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Awaitable</span><span class="p"><span class="pre">[</span></span><span class="pre">None</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Awaitable</span><span class="p"><span class="pre">[</span></span><span class="pre">None</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span></span><a class="reference internal" href="_modules/responder/api.html#API.build_middleware_stack"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.build_middleware_stack" title="Link to this definition"></a></dt>
<dd><p>Assemble the full ASGI stack from the collected configuration.</p>
<p>Outermost → innermost: logging/request-id → metrics → ServerError →
user middleware → trusted-host → hsts → cors → sessions → gzip →
ExceptionMiddleware → router. ServerErrorMiddleware is the outermost
<em>application</em> layer (it catches errors from every middleware below it),
while the observability tier wraps even it so a rendered 500 still
carries <code class="docutils literal notranslate"><span class="pre">X-Request-ID</span></code> and is logged with its real status.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.delete">
<span class="sig-name descname"><span class="pre">delete</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</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="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.delete"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.delete" title="Link to this definition"></a></dt>
<dd><p>Register a route for <code class="docutils literal notranslate"><span class="pre">DELETE</span></code> (sugar for <code class="docutils literal notranslate"><span class="pre">route(methods=[&quot;DELETE&quot;])</span></code>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.dependency">
<span class="sig-name descname"><span class="pre">dependency</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</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="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">scope</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'request'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.dependency"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.dependency" title="Link to this definition"></a></dt>
<dd><p>Register a dependency provider, injected into views by parameter name.</p>
<p>Any view parameter (beyond <code class="docutils literal notranslate"><span class="pre">req</span></code> and <code class="docutils literal notranslate"><span class="pre">resp</span></code>) whose name matches a
registered dependency receives the provider’s value. Providers may be
sync or async functions, or generators — code after <code class="docutils literal notranslate"><span class="pre">yield</span></code> runs as
teardown once the response is sent. Providers accepting a parameter
receive the current <a class="reference internal" href="#responder.Request" title="responder.Request"><code class="xref py py-class docutils literal notranslate"><span class="pre">Request</span></code></a>. Each dependency is resolved at
most once per request. Path parameters take precedence over
dependencies of the same name.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>name</strong> – The injection name. Defaults to the provider’s <code class="docutils literal notranslate"><span class="pre">__name__</span></code>.</p></li>
<li><p><strong>scope</strong> – <code class="docutils literal notranslate"><span class="pre">&quot;request&quot;</span></code> (default) resolves per request;
<code class="docutils literal notranslate"><span class="pre">&quot;app&quot;</span></code> resolves once on first use and caches for the
application’s lifetime — generator teardown then runs at
shutdown. App-scoped providers cannot take parameters.</p></li>
</ul>
</dd>
</dl>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">dependency</span><span class="p">()</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">db</span><span class="p">():</span>
<span class="n">conn</span> <span class="o">=</span> <span class="k">await</span> <span class="n">create_connection</span><span class="p">()</span>
<span class="k">yield</span> <span class="n">conn</span>
<span class="k">await</span> <span class="n">conn</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/users/{id:int}&quot;</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_user</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="nb">id</span><span class="p">,</span> <span class="n">db</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="k">await</span> <span class="n">db</span><span class="o">.</span><span class="n">fetch_user</span><span class="p">(</span><span class="nb">id</span><span class="p">)</span>
</pre></div>
</div>
<p>An app-scoped dependency, shared across all requests:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">dependency</span><span class="p">(</span><span class="n">scope</span><span class="o">=</span><span class="s2">&quot;app&quot;</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">pool</span><span class="p">():</span>
<span class="n">pool</span> <span class="o">=</span> <span class="k">await</span> <span class="n">create_pool</span><span class="p">()</span>
<span class="k">yield</span> <span class="n">pool</span>
<span class="k">await</span> <span class="n">pool</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> <span class="c1"># runs at application shutdown</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.dependency_overrides">
<span class="sig-name descname"><span class="pre">dependency_overrides</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">overrides</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.dependency_overrides"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.dependency_overrides" title="Link to this definition"></a></dt>
<dd><p>Temporarily override dependencies (for tests); restores on exit.</p>
<p>Each value may be a provider (a callable, with full sub-dependency and
request injection) or a bare value, which is wrapped automatically.
Overrides are request-scoped, so they replace and bypass the cache of an
<code class="docutils literal notranslate"><span class="pre">app</span></code>-scoped dependency too:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">api</span><span class="o">.</span><span class="n">dependency_overrides</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="n">fake_db</span><span class="p">):</span>
<span class="n">api</span><span class="o">.</span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/users&quot;</span><span class="p">)</span>
</pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>overrides</strong> – <code class="docutils literal notranslate"><span class="pre">name=provider_or_value</span></code> pairs to override.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.exception_handler">
<span class="sig-name descname"><span class="pre">exception_handler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">exception_cls</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.exception_handler"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.exception_handler" title="Link to this definition"></a></dt>
<dd><p>Register a handler for a specific exception type.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">exception_handler</span><span class="p">(</span><span class="ne">ValueError</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">handle_value_error</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="n">exc</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">status_code</span> <span class="o">=</span> <span class="mi">400</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;error&quot;</span><span class="p">:</span> <span class="nb">str</span><span class="p">(</span><span class="n">exc</span><span class="p">)}</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.generate_client">
<span class="sig-name descname"><span class="pre">generate_client</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</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="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">class_name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'APIClient'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">language</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'python'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.generate_client"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.generate_client" title="Link to this definition"></a></dt>
<dd><p>Generate a client from this app’s OpenAPI schema.</p>
<p>Returns source code by default. When <code class="docutils literal notranslate"><span class="pre">path</span></code> is provided, writes the
client module there and returns the resulting <code class="docutils literal notranslate"><span class="pre">Path</span></code>.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">source</span> <span class="o">=</span> <span class="n">api</span><span class="o">.</span><span class="n">generate_client</span><span class="p">(</span><span class="n">class_name</span><span class="o">=</span><span class="s2">&quot;AcmeClient&quot;</span><span class="p">)</span>
<span class="n">api</span><span class="o">.</span><span class="n">generate_client</span><span class="p">(</span><span class="s2">&quot;clients/acme.py&quot;</span><span class="p">,</span> <span class="n">class_name</span><span class="o">=</span><span class="s2">&quot;AcmeClient&quot;</span><span class="p">)</span>
<span class="n">api</span><span class="o">.</span><span class="n">generate_client</span><span class="p">(</span>
<span class="s2">&quot;clients/acme.ts&quot;</span><span class="p">,</span>
<span class="n">class_name</span><span class="o">=</span><span class="s2">&quot;AcmeClient&quot;</span><span class="p">,</span>
<span class="n">language</span><span class="o">=</span><span class="s2">&quot;typescript&quot;</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.get">
<span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</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="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.get"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.get" title="Link to this definition"></a></dt>
<dd><p>Register a route for <code class="docutils literal notranslate"><span class="pre">GET</span></code> (sugar for <code class="docutils literal notranslate"><span class="pre">route(methods=[&quot;GET&quot;])</span></code>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.graphql">
<span class="sig-name descname"><span class="pre">graphql</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'/graphql'</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">schema</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">graphiql</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">introspection</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">max_depth</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">partial_data_status</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">200</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.graphql"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.graphql" title="Link to this definition"></a></dt>
<dd><p>Mount a GraphQL API at the given route.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">graphene</span>
<span class="k">class</span><span class="w"> </span><span class="nc">Query</span><span class="p">(</span><span class="n">graphene</span><span class="o">.</span><span class="n">ObjectType</span><span class="p">):</span>
<span class="n">hello</span> <span class="o">=</span> <span class="n">graphene</span><span class="o">.</span><span class="n">String</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="n">graphene</span><span class="o">.</span><span class="n">String</span><span class="p">(</span><span class="n">default_value</span><span class="o">=</span><span class="s2">&quot;stranger&quot;</span><span class="p">))</span>
<span class="k">def</span><span class="w"> </span><span class="nf">resolve_hello</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">info</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
<span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;Hello </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">&quot;</span>
<span class="n">api</span><span class="o">.</span><span class="n">graphql</span><span class="p">(</span><span class="s2">&quot;/graphql&quot;</span><span class="p">,</span> <span class="n">schema</span><span class="o">=</span><span class="n">graphene</span><span class="o">.</span><span class="n">Schema</span><span class="p">(</span><span class="n">query</span><span class="o">=</span><span class="n">Query</span><span class="p">))</span>
</pre></div>
</div>
<p>For production, disable the in-browser IDE and introspection and cap
query depth:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">api</span><span class="o">.</span><span class="n">graphql</span><span class="p">(</span>
<span class="s2">&quot;/graphql&quot;</span><span class="p">,</span> <span class="n">schema</span><span class="o">=</span><span class="n">schema</span><span class="p">,</span>
<span class="n">graphiql</span><span class="o">=</span><span class="n">api</span><span class="o">.</span><span class="n">debug</span><span class="p">,</span> <span class="n">introspection</span><span class="o">=</span><span class="n">api</span><span class="o">.</span><span class="n">debug</span><span class="p">,</span> <span class="n">max_depth</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>route</strong> – The URL path for the GraphQL endpoint.</p></li>
<li><p><strong>schema</strong> – A Graphene schema instance.</p></li>
<li><p><strong>graphiql</strong> – Serve the in-browser GraphiQL IDE for HTML <code class="docutils literal notranslate"><span class="pre">GET</span></code>
requests (default <code class="docutils literal notranslate"><span class="pre">True</span></code>).</p></li>
<li><p><strong>introspection</strong> – Allow schema-introspection queries (default <code class="docutils literal notranslate"><span class="pre">True</span></code>).</p></li>
<li><p><strong>max_depth</strong> – Reject queries nested deeper than this (default unlimited).</p></li>
<li><p><strong>partial_data_status</strong> – HTTP status for GraphQL responses that
contain both <code class="docutils literal notranslate"><span class="pre">data</span></code> and <code class="docutils literal notranslate"><span class="pre">errors</span></code>. <code class="docutils literal notranslate"><span class="pre">200</span></code> (default) follows
the GraphQL-over-HTTP spec; <code class="docutils literal notranslate"><span class="pre">400</span></code> preserves Responder 8.x
behavior.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.group">
<span class="sig-name descname"><span class="pre">group</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prefix</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.group"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.group" title="Link to this definition"></a></dt>
<dd><p>Create a route group with a shared URL prefix.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">v1</span> <span class="o">=</span> <span class="n">api</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="s2">&quot;/v1&quot;</span><span class="p">)</span>
<span class="nd">@v1</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/users&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">list_users</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">[]</span>
<span class="nd">@v1</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/users/{id:int}&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">get_user</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="nb">id</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;id&quot;</span><span class="p">:</span> <span class="nb">id</span><span class="p">}</span>
</pre></div>
</div>
<p>For routes declared in separate modules (without an <code class="docutils literal notranslate"><span class="pre">API</span></code> instance),
use <a class="reference internal" href="#responder.Router" title="responder.Router"><code class="xref py py-class docutils literal notranslate"><span class="pre">responder.Router</span></code></a> with <a class="reference internal" href="#responder.API.include_router" title="responder.API.include_router"><code class="xref py py-meth docutils literal notranslate"><span class="pre">include_router()</span></code></a> instead.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.head">
<span class="sig-name descname"><span class="pre">head</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</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="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.head"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.head" title="Link to this definition"></a></dt>
<dd><p>Register a route for <code class="docutils literal notranslate"><span class="pre">HEAD</span></code> (sugar for <code class="docutils literal notranslate"><span class="pre">route(methods=[&quot;HEAD&quot;])</span></code>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.include_router">
<span class="sig-name descname"><span class="pre">include_router</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">router</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#responder.Router" title="responder.routing.Router"><span class="pre">Router</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">prefix</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tags</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dependencies</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">auth</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">&lt;object</span> <span class="pre">object&gt;</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">None</span></span></span><a class="reference internal" href="_modules/responder/api.html#API.include_router"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.include_router" title="Link to this definition"></a></dt>
<dd><p>Attach a standalone <a class="reference internal" href="#responder.Router" title="responder.Router"><code class="xref py py-class docutils literal notranslate"><span class="pre">responder.Router</span></code></a>’s recorded declarations.</p>
<p>Each recorded route is replayed through <a class="reference internal" href="#responder.API.route" title="responder.API.route"><code class="xref py py-meth docutils literal notranslate"><span class="pre">route()</span></code></a>, so auth
inheritance, <code class="docutils literal notranslate"><span class="pre">Depends</span></code> guards, and OpenAPI metadata behave exactly as
if the route had been declared on the API directly. Group-level values
compose: prefixes concatenate, <code class="docutils literal notranslate"><span class="pre">tags</span></code> merge (group tags first),
<code class="docutils literal notranslate"><span class="pre">dependencies</span></code> run before route-level ones, and a route’s own
<code class="docutils literal notranslate"><span class="pre">auth=</span></code> wins over the router’s, which wins over the one given here.</p>
<p>Inclusion is a snapshot — routes declared on the router afterwards are
not picked up. Including the same router at two prefixes is fine, but
including the same <em>view function</em> twice with different effective
auth/tags/dependencies raises, since route metadata is attached to the
view itself.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>router</strong> – The <a class="reference internal" href="#responder.Router" title="responder.Router"><code class="xref py py-class docutils literal notranslate"><span class="pre">responder.Router</span></code></a> to include.</p></li>
<li><p><strong>prefix</strong> – URL prefix prepended to the router’s own prefix.</p></li>
<li><p><strong>tags</strong> – OpenAPI tags merged into every included route.</p></li>
<li><p><strong>dependencies</strong> – <code class="docutils literal notranslate"><span class="pre">Depends(...)</span></code> guards run before every included
route.</p></li>
<li><p><strong>auth</strong> – Auth helper(s) for included routes that don’t set their own.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.middleware">
<span class="sig-name descname"><span class="pre">middleware</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">middleware_type</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'http'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.middleware"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.middleware" title="Link to this definition"></a></dt>
<dd><p>Register function-style HTTP middleware (decorator).</p>
<p>The decorated function receives the Starlette <code class="docutils literal notranslate"><span class="pre">Request</span></code> and a
<code class="docutils literal notranslate"><span class="pre">call_next</span></code> callable, and returns the response to send — no ASGI
class boilerplate required:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">time</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">middleware</span><span class="p">(</span><span class="s2">&quot;http&quot;</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">add_timing</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">call_next</span><span class="p">):</span>
<span class="n">start</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">perf_counter</span><span class="p">()</span>
<span class="n">response</span> <span class="o">=</span> <span class="k">await</span> <span class="n">call_next</span><span class="p">(</span><span class="n">request</span><span class="p">)</span>
<span class="n">elapsed</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">perf_counter</span><span class="p">()</span> <span class="o">-</span> <span class="n">start</span>
<span class="n">response</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s2">&quot;X-Response-Time&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">elapsed</span><span class="si">:</span><span class="s2">.4f</span><span class="si">}</span><span class="s2">s&quot;</span>
<span class="k">return</span> <span class="n">response</span>
</pre></div>
</div>
<p>Synchronous functions work too: they are offloaded to the threadpool
(like sync views), and the <code class="docutils literal notranslate"><span class="pre">call_next</span></code> they receive is a plain
blocking callable.</p>
<p>Function middleware registers through the same stack as
<a class="reference internal" href="#responder.API.add_middleware" title="responder.API.add_middleware"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_middleware()</span></code></a>, so the two compose freely. <strong>Order:</strong> among
user middleware — function-style or class-based alike — the
most-recently-registered is the outermost and sees the request first
(and the response last). Non-HTTP traffic (WebSockets, lifespan)
passes through untouched.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>middleware_type</strong> – Only <code class="docutils literal notranslate"><span class="pre">&quot;http&quot;</span></code> is supported (the default).
The decorator may also be applied bare (<code class="docutils literal notranslate"><span class="pre">&#64;api.middleware</span></code>).</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.mount">
<span class="sig-name descname"><span class="pre">mount</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">app</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.mount"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.mount" title="Link to this definition"></a></dt>
<dd><p>Mounts an WSGI / ASGI application at a given route.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>route</strong> – String representation of the route to be used
(shouldn’t be parameterized).</p></li>
<li><p><strong>app</strong> – The other WSGI / ASGI app.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.ndjson">
<span class="sig-name descname"><span class="pre">ndjson</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</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="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">item_model</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="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.ndjson"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.ndjson" title="Link to this definition"></a></dt>
<dd><p>Register a typed newline-delimited JSON <code class="docutils literal notranslate"><span class="pre">GET</span></code> route.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.on_event">
<span class="sig-name descname"><span class="pre">on_event</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">event_type</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">args</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">...</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Any</span><span class="p"><span class="pre">]</span></span></span></span><a class="reference internal" href="_modules/responder/api.html#API.on_event"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.on_event" title="Link to this definition"></a></dt>
<dd><p>Decorator for registering functions or coroutines to run at certain events
Supported events: startup, shutdown</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">on_event</span><span class="p">(</span><span class="s1">&#39;startup&#39;</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">open_database_connection_pool</span><span class="p">():</span>
<span class="o">...</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">on_event</span><span class="p">(</span><span class="s1">&#39;shutdown&#39;</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">close_database_connection_pool</span><span class="p">():</span>
<span class="o">...</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.options">
<span class="sig-name descname"><span class="pre">options</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</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="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.options"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.options" title="Link to this definition"></a></dt>
<dd><p>Register a route for <code class="docutils literal notranslate"><span class="pre">OPTIONS</span></code> (sugar for <code class="docutils literal notranslate"><span class="pre">route(methods=[&quot;OPTIONS&quot;])</span></code>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.patch">
<span class="sig-name descname"><span class="pre">patch</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</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="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.patch"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.patch" title="Link to this definition"></a></dt>
<dd><p>Register a route for <code class="docutils literal notranslate"><span class="pre">PATCH</span></code> (sugar for <code class="docutils literal notranslate"><span class="pre">route(methods=[&quot;PATCH&quot;])</span></code>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.path_matches_route">
<span class="sig-name descname"><span class="pre">path_matches_route</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.path_matches_route"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.path_matches_route" title="Link to this definition"></a></dt>
<dd><p>Given a path portion of a URL, tests that it matches against any registered route.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>path</strong> – The path portion of a URL (e.g. <code class="docutils literal notranslate"><span class="pre">&quot;/hello&quot;</span></code>), to test all
known routes against. An ASGI scope mapping is also accepted.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.policy">
<span class="sig-name descname"><span class="pre">policy</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">auth</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.policy"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.policy" title="Link to this definition"></a></dt>
<dd><p>Create and register a named auth policy.</p>
<p>The returned policy can be passed anywhere <code class="docutils literal notranslate"><span class="pre">auth=</span></code> accepts an auth
helper. Naming a policy makes route declarations describe intent while
preserving the wrapped auth scheme’s runtime and OpenAPI behavior:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">admin</span> <span class="o">=</span> <span class="n">api</span><span class="o">.</span><span class="n">policy</span><span class="p">(</span><span class="s2">&quot;admin&quot;</span><span class="p">,</span> <span class="n">bearer</span><span class="o">.</span><span class="n">requires</span><span class="p">(</span><span class="s2">&quot;admin&quot;</span><span class="p">))</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/admin&quot;</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">admin</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">dashboard</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">user</span><span class="p">):</span> <span class="o">...</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.post">
<span class="sig-name descname"><span class="pre">post</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</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="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.post"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.post" title="Link to this definition"></a></dt>
<dd><p>Register a route for <code class="docutils literal notranslate"><span class="pre">POST</span></code> (sugar for <code class="docutils literal notranslate"><span class="pre">route(methods=[&quot;POST&quot;])</span></code>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.put">
<span class="sig-name descname"><span class="pre">put</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</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="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.put"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.put" title="Link to this definition"></a></dt>
<dd><p>Register a route for <code class="docutils literal notranslate"><span class="pre">PUT</span></code> (sugar for <code class="docutils literal notranslate"><span class="pre">route(methods=[&quot;PUT&quot;])</span></code>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.redirect">
<span class="sig-name descname"><span class="pre">redirect</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">resp</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#responder.Response" title="responder.models.Response"><span class="pre">Response</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">location</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</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">set_text</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">status_code</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">permanent</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">allow_external</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">None</span></span></span><a class="reference internal" href="_modules/responder/api.html#API.redirect"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.redirect" title="Link to this definition"></a></dt>
<dd><p>Redirects a given response to a given location.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>resp</strong> – The Response to mutate.</p></li>
<li><p><strong>location</strong> – The location of the redirect.</p></li>
<li><p><strong>set_text</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code>, sets the Redirect body content automatically.</p></li>
<li><p><strong>status_code</strong> – an <cite>API.status_codes</cite> attribute, or an integer,
representing the HTTP status code of the redirect.
Defaults to <code class="docutils literal notranslate"><span class="pre">307</span></code> (<code class="docutils literal notranslate"><span class="pre">308</span></code> with <code class="docutils literal notranslate"><span class="pre">permanent=True</span></code>).</p></li>
<li><p><strong>permanent</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code>, send a <code class="docutils literal notranslate"><span class="pre">308</span> <span class="pre">Permanent</span> <span class="pre">Redirect</span></code> instead
of the default <code class="docutils literal notranslate"><span class="pre">307</span></code>.</p></li>
<li><p><strong>allow_external</strong> – If <code class="docutils literal notranslate"><span class="pre">False</span></code>, refuse (with a <code class="docutils literal notranslate"><span class="pre">400</span></code>) to redirect to
an external URL — pass this for user-supplied locations.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.API.requests">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">requests</span></span><a class="headerlink" href="#responder.API.requests" title="Link to this definition"></a></dt>
<dd><p>A test client connected to the ASGI app. Lazily initialized.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.route">
<span class="sig-name descname"><span class="pre">route</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</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">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">response_model</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">params_model</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">include_in_schema</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">security</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">tags</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">summary</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">description</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">operation_id</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">deprecated</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">responses</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">examples</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">response_examples</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">openapi_extra</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">status_code</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">before</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">after</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">auth</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">&lt;object</span> <span class="pre">object&gt;</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">csrf</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">dependencies</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">_stream_mode</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">_stream_model</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">_stream_heartbeat</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">**options</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.route"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.route" title="Link to this definition"></a></dt>
<dd><p>Decorator for creating new routes around function and class definitions.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/hello&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">hello</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">text</span> <span class="o">=</span> <span class="s2">&quot;hello, world!&quot;</span>
</pre></div>
</div>
<p>A route can declare its default success status with <code class="docutils literal notranslate"><span class="pre">status_code=</span></code>;
<code class="docutils literal notranslate"><span class="pre">resp.status_code</span></code> is pre-seeded with it before the handler runs
(assigning <code class="docutils literal notranslate"><span class="pre">resp.status_code</span></code> in the handler still wins), and the
OpenAPI document keys the success response under it instead of
<code class="docutils literal notranslate"><span class="pre">200</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/items&quot;</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;POST&quot;</span><span class="p">],</span> <span class="n">status_code</span><span class="o">=</span><span class="mi">201</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_item</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">item</span><span class="p">:</span> <span class="n">ItemIn</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;id&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="o">**</span><span class="n">item</span><span class="o">.</span><span class="n">model_dump</span><span class="p">()}</span>
</pre></div>
</div>
<p>Return annotations provide response validation and OpenAPI
documentation without repeating the model in the decorator:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseModel</span>
<span class="k">class</span><span class="w"> </span><span class="nc">ItemIn</span><span class="p">(</span><span class="n">BaseModel</span><span class="p">):</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">price</span><span class="p">:</span> <span class="nb">float</span>
<span class="k">class</span><span class="w"> </span><span class="nc">ItemOut</span><span class="p">(</span><span class="n">BaseModel</span><span class="p">):</span>
<span class="nb">id</span><span class="p">:</span> <span class="nb">int</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">price</span><span class="p">:</span> <span class="nb">float</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/items&quot;</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;POST&quot;</span><span class="p">])</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_item</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">item</span><span class="p">:</span> <span class="n">ItemIn</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">ItemOut</span><span class="p">:</span>
<span class="k">return</span> <span class="n">ItemOut</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="o">**</span><span class="n">item</span><span class="o">.</span><span class="n">model_dump</span><span class="p">())</span>
</pre></div>
</div>
<p>Pydantic <code class="docutils literal notranslate"><span class="pre">TypeAdapter</span></code>-compatible annotations such as
<code class="docutils literal notranslate"><span class="pre">list[ItemOut]</span></code> and <code class="docutils literal notranslate"><span class="pre">ItemOut</span> <span class="pre">|</span> <span class="pre">ErrorOut</span></code> also infer. Pass
<code class="docutils literal notranslate"><span class="pre">response_model=False</span></code> to disable inference for one route.</p>
<p>Additional statuses can declare their own validated contract with
<code class="docutils literal notranslate"><span class="pre">responses={404:</span> <span class="pre">ErrorOut}</span></code>. Use
<code class="docutils literal notranslate"><span class="pre">responses={404:</span> <span class="pre">{&quot;model&quot;:</span> <span class="pre">ErrorOut,</span> <span class="pre">&quot;description&quot;:</span> <span class="pre">&quot;Not</span> <span class="pre">found&quot;}}</span></code>
to add OpenAPI metadata to that contract.</p>
<p>Query parameters validate the same way with <code class="docutils literal notranslate"><span class="pre">params_model</span></code> —
invalid queries get a <code class="docutils literal notranslate"><span class="pre">422</span></code>, valid ones land on
<code class="docutils literal notranslate"><span class="pre">req.state.validated_params</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">SearchParams</span><span class="p">(</span><span class="n">BaseModel</span><span class="p">):</span>
<span class="n">q</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/search&quot;</span><span class="p">,</span> <span class="n">params_model</span><span class="o">=</span><span class="n">SearchParams</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">search</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="n">params</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">state</span><span class="o">.</span><span class="n">validated_params</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;q&quot;</span><span class="p">:</span> <span class="n">params</span><span class="o">.</span><span class="n">q</span><span class="p">,</span> <span class="s2">&quot;limit&quot;</span><span class="p">:</span> <span class="n">params</span><span class="o">.</span><span class="n">limit</span><span class="p">}</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.run">
<span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.run"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.run" title="Link to this definition"></a></dt>
<dd><p>Run the application. Shorthand for <a class="reference internal" href="#responder.API.serve" title="responder.API.serve"><code class="xref py py-meth docutils literal notranslate"><span class="pre">serve()</span></code></a> that inherits the <code class="docutils literal notranslate"><span class="pre">debug</span></code> setting.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>kwargs</strong> – Keyword arguments passed through to <a class="reference internal" href="#responder.API.serve" title="responder.API.serve"><code class="xref py py-meth docutils literal notranslate"><span class="pre">serve()</span></code></a>.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.schema">
<span class="sig-name descname"><span class="pre">schema</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.schema"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.schema" title="Link to this definition"></a></dt>
<dd><p>Decorator for creating new routes around function and class definitions.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">marshmallow</span><span class="w"> </span><span class="kn">import</span> <span class="n">Schema</span><span class="p">,</span> <span class="n">fields</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">schema</span><span class="p">(</span><span class="s2">&quot;Pet&quot;</span><span class="p">)</span>
<span class="k">class</span><span class="w"> </span><span class="nc">PetSchema</span><span class="p">(</span><span class="n">Schema</span><span class="p">):</span>
<span class="n">name</span> <span class="o">=</span> <span class="n">fields</span><span class="o">.</span><span class="n">Str</span><span class="p">()</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.serve">
<span class="sig-name descname"><span class="pre">serve</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">address</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">port</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">debug</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">server</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'uvicorn'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">port_precedence</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'explicit'</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.serve"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.serve" title="Link to this definition"></a></dt>
<dd><p>Run the application with an ASGI server.</p>
<p>If the <code class="docutils literal notranslate"><span class="pre">PORT</span></code> environment variable is set and no explicit <code class="docutils literal notranslate"><span class="pre">port=</span></code>
is provided, requests will be served on that port automatically to all
known hosts. If both are set and disagree, the explicit <code class="docutils literal notranslate"><span class="pre">port=</span></code> wins
by default.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>address</strong> – The address to bind to.</p></li>
<li><p><strong>port</strong> – The port to bind to. If none is provided, one will be selected at random.</p></li>
<li><p><strong>debug</strong> – Whether to run application in debug mode.</p></li>
<li><p><strong>server</strong> – Server backend to use: <code class="docutils literal notranslate"><span class="pre">&quot;uvicorn&quot;</span></code> (default) or <code class="docutils literal notranslate"><span class="pre">&quot;granian&quot;</span></code>.</p></li>
<li><p><strong>port_precedence</strong> – <code class="docutils literal notranslate"><span class="pre">&quot;explicit&quot;</span></code> (default) lets an explicit <code class="docutils literal notranslate"><span class="pre">port=</span></code> win over a conflicting <code class="docutils literal notranslate"><span class="pre">PORT</span></code> environment variable; <code class="docutils literal notranslate"><span class="pre">&quot;env&quot;</span></code> preserves the legacy behavior.</p></li>
<li><p><strong>options</strong> – Additional keyword arguments to send to the selected server.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.sse">
<span class="sig-name descname"><span class="pre">sse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</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="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">event_model</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">heartbeat</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="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.sse"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.sse" title="Link to this definition"></a></dt>
<dd><p>Register a typed Server-Sent Events <code class="docutils literal notranslate"><span class="pre">GET</span></code> route.</p>
<p>The event data contract is inferred from <code class="docutils literal notranslate"><span class="pre">AsyncIterator[Item]</span></code> or
<code class="docutils literal notranslate"><span class="pre">AsyncIterator[SSE[Item]]</span></code>. Pass <code class="docutils literal notranslate"><span class="pre">event_model=Item</span></code> when the return
annotation cannot express it.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="responder.API.state">
<span class="sig-name descname"><span class="pre">state</span></span><a class="headerlink" href="#responder.API.state" title="Link to this definition"></a></dt>
<dd><p>Application-level state. Set values at startup, read them anywhere
(handlers can reach it via <code class="docutils literal notranslate"><span class="pre">req.api.state</span></code>).</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.API.static_app">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">static_app</span></span><a class="headerlink" href="#responder.API.static_app" title="Link to this definition"></a></dt>
<dd><p>The Starlette <code class="docutils literal notranslate"><span class="pre">StaticFiles</span></code> application for serving static assets.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.template">
<span class="sig-name descname"><span class="pre">template</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.template"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.template" title="Link to this definition"></a></dt>
<dd><p>Render a Jinja2 template file with the provided values.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>filename</strong> – The filename of the jinja2 template, in <code class="docutils literal notranslate"><span class="pre">templates_dir</span></code>.</p></li>
<li><p><strong>*args</strong> – Data to pass into the template.</p></li>
<li><p><strong>**kwargs</strong> – Data to pass into the template.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.template_string">
<span class="sig-name descname"><span class="pre">template_string</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">source</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.template_string"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.template_string" title="Link to this definition"></a></dt>
<dd><p>Render a Jinja2 template string with the provided values.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>source</strong> – The template to use, a Jinja2 template string.</p></li>
<li><p><strong>*args</strong> – Data to pass into the template.</p></li>
<li><p><strong>**kwargs</strong> – Data to pass into the template.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.test_client">
<span class="sig-name descname"><span class="pre">test_client</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">base_url</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'http://;'</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.test_client"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.test_client" title="Link to this definition"></a></dt>
<dd><p>Return a Starlette <code class="docutils literal notranslate"><span class="pre">TestClient</span></code> connected to this app.</p>
<p>This is the configurable form of <a class="reference internal" href="#responder.API.requests" title="responder.API.requests"><code class="xref py py-attr docutils literal notranslate"><span class="pre">requests</span></code></a>; pass normal
Starlette <code class="docutils literal notranslate"><span class="pre">TestClient</span></code> options such as
<code class="docutils literal notranslate"><span class="pre">raise_server_exceptions=False</span></code> or a custom <code class="docutils literal notranslate"><span class="pre">base_url</span></code>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.url_for">
<span class="sig-name descname"><span class="pre">url_for</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">endpoint</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">params</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.url_for"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.url_for" title="Link to this definition"></a></dt>
<dd><p>Given an endpoint, returns a rendered URL for its route.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>endpoint</strong> – The route endpoint you’re searching for.</p></li>
<li><p><strong>params</strong> – Data to pass into the URL generator (for parameterized URLs).</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.API.websocket_route">
<span class="sig-name descname"><span class="pre">websocket_route</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</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="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#API.websocket_route"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.API.websocket_route" title="Link to this definition"></a></dt>
<dd><p>Register a WebSocket route (sugar for <code class="docutils literal notranslate"><span class="pre">route(websocket=True)</span></code>).</p>
</dd></dl>
</dd></dl>
</section>
<section id="request">
<h2>Request<a class="headerlink" href="#request" title="Link to this heading"></a></h2>
<p>The request object is passed into every view as the first argument. It
gives you access to everything the client sent — headers, query
parameters, the request body, cookies, and more.</p>
<p>Most properties are synchronous, but reading the body requires <code class="docutils literal notranslate"><span class="pre">await</span></code>
because it involves I/O.</p>
<p>Common patterns:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># The request method — UPPERCASE: &quot;GET&quot;, &quot;POST&quot;, ...</span>
<span class="k">if</span> <span class="n">req</span><span class="o">.</span><span class="n">method</span> <span class="o">==</span> <span class="s2">&quot;POST&quot;</span><span class="p">:</span>
<span class="o">...</span>
<span class="c1"># Headers (case-insensitive)</span>
<span class="n">token</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">headers</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;Authorization&quot;</span><span class="p">)</span>
<span class="c1"># Every raw line of a repeated header, in order</span>
<span class="n">hops</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">headers</span><span class="o">.</span><span class="n">get_list</span><span class="p">(</span><span class="s2">&quot;X-Forwarded-For&quot;</span><span class="p">)</span>
<span class="c1"># Query parameters: /search?q=python&amp;page=2</span>
<span class="n">query</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">params</span><span class="p">[</span><span class="s2">&quot;q&quot;</span><span class="p">]</span>
<span class="c1"># JSON body (async handlers)</span>
<span class="n">data</span> <span class="o">=</span> <span class="k">await</span> <span class="n">req</span><span class="o">.</span><span class="n">media</span><span class="p">()</span>
<span class="c1"># ...or synchronously, from a sync handler</span>
<span class="n">data</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">media_sync</span><span class="p">()</span>
<span class="n">body</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">text_sync</span>
<span class="c1"># Form data and file uploads</span>
<span class="n">form</span> <span class="o">=</span> <span class="k">await</span> <span class="n">req</span><span class="o">.</span><span class="n">media</span><span class="p">(</span><span class="s2">&quot;form&quot;</span><span class="p">)</span>
<span class="n">files</span> <span class="o">=</span> <span class="k">await</span> <span class="n">req</span><span class="o">.</span><span class="n">media</span><span class="p">(</span><span class="s2">&quot;files&quot;</span><span class="p">)</span>
<span class="c1"># Client info</span>
<span class="n">ip</span><span class="p">,</span> <span class="n">port</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">client</span>
<span class="n">is_https</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">is_secure</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><code class="docutils literal notranslate"><span class="pre">req.method</span></code> is a plain UPPERCASE <code class="docutils literal notranslate"><span class="pre">str</span></code> (<code class="docutils literal notranslate"><span class="pre">&quot;GET&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;POST&quot;</span></code>).
Comparisons are case-sensitive, so compare against uppercase literals:
<code class="docutils literal notranslate"><span class="pre">req.method</span> <span class="pre">==</span> <span class="pre">&quot;GET&quot;</span></code>.</p>
<p><code class="docutils literal notranslate"><span class="pre">await</span> <span class="pre">req.media(&quot;files&quot;)</span></code> returns <code class="docutils literal notranslate"><span class="pre">{name:</span> <span class="pre">UploadFile}</span></code> (streamed,
spooled to disk). See <a class="reference internal" href="#parameter-markers">Parameter Markers</a> for the typed <code class="docutils literal notranslate"><span class="pre">File()</span></code> form.</p>
</div>
<p>For reading typed query parameters, headers, and cookies straight off the
signature, see <a class="reference internal" href="#parameter-markers">Parameter Markers</a> below.</p>
<dl class="py class">
<dt class="sig sig-object py" id="responder.Request">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">Request</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">scope</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">receive</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">api</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">formats</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="reference internal" href="_modules/responder/models.html#Request"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Request" title="Link to this definition"></a></dt>
<dd><p>An HTTP request, passed to each view as the first argument.</p>
<p>Provides access to headers, cookies, query parameters, the request body,
session data, and more. Most properties are synchronous; reading the body
(via <a class="reference internal" href="#responder.Request.content" title="responder.Request.content"><code class="xref py py-attr docutils literal notranslate"><span class="pre">content</span></code></a>, <a class="reference internal" href="#responder.Request.text" title="responder.Request.text"><code class="xref py py-attr docutils literal notranslate"><span class="pre">text</span></code></a>, or <a class="reference internal" href="#responder.Request.media" title="responder.Request.media"><code class="xref py py-meth docutils literal notranslate"><span class="pre">media()</span></code></a>) requires <code class="docutils literal notranslate"><span class="pre">await</span></code>.</p>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Request.accepts">
<span class="sig-name descname"><span class="pre">accepts</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">content_type</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">bool</span></span></span><a class="reference internal" href="_modules/responder/models.html#Request.accepts"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Request.accepts" title="Link to this definition"></a></dt>
<dd><p>Whether the client’s <code class="docutils literal notranslate"><span class="pre">Accept</span></code> header allows <code class="docutils literal notranslate"><span class="pre">content_type</span></code>.</p>
<p>Honors media ranges (<code class="docutils literal notranslate"><span class="pre">*/*</span></code>, <code class="docutils literal notranslate"><span class="pre">type/*</span></code>) and q-values. Per RFC 9110
§12.5.1 the <em>most specific</em> matching range governs, so an explicit
<code class="docutils literal notranslate"><span class="pre">q=0</span></code> range (not acceptable) excludes the type even when a broader
range (<code class="docutils literal notranslate"><span class="pre">*/*</span></code> or <code class="docutils literal notranslate"><span class="pre">type/*</span></code>) would match. An absent <code class="docutils literal notranslate"><span class="pre">Accept</span></code> header
accepts anything. <code class="docutils literal notranslate"><span class="pre">content_type</span></code> may be a full media type
(<code class="docutils literal notranslate"><span class="pre">application/json</span></code>) or a bare subtype token (<code class="docutils literal notranslate"><span class="pre">json</span></code>).</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.apparent_encoding">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">apparent_encoding</span></span><a class="headerlink" href="#responder.Request.apparent_encoding" title="Link to this definition"></a></dt>
<dd><p>The apparent encoding, detected automatically. Must be awaited.</p>
<p>Valid UTF-8 bodies (the overwhelmingly common case) are recognized
with a cheap strict decode. Otherwise, uses chardet for detection if
installed (off the event loop, since detection is CPU-bound), falling
back to UTF-8.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.client">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">client</span></span><a class="headerlink" href="#responder.Request.client" title="Link to this definition"></a></dt>
<dd><p>The client’s address as a (host, port) named tuple, or None.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.content">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">content</span></span><a class="headerlink" href="#responder.Request.content" title="Link to this definition"></a></dt>
<dd><p>The Request body, as bytes. Must be awaited.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.cookies">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">cookies</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">dict</span></span><a class="headerlink" href="#responder.Request.cookies" title="Link to this definition"></a></dt>
<dd><p>The cookies sent in the Request, as a dictionary.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.csrf_input">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">csrf_input</span></span><a class="headerlink" href="#responder.Request.csrf_input" title="Link to this definition"></a></dt>
<dd><p>A hidden <code class="docutils literal notranslate"><span class="pre">&lt;input&gt;</span></code> carrying <a class="reference internal" href="#responder.Request.csrf_token" title="responder.Request.csrf_token"><code class="xref py py-attr docutils literal notranslate"><span class="pre">csrf_token</span></code></a>, for HTML forms.</p>
<p>Returns markup-safe HTML, so it renders unescaped in autoescaped
Jinja templates: pass the request into the template context and drop
<code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">req.csrf_input</span> <span class="pre">}}</span></code> inside each <code class="docutils literal notranslate"><span class="pre">&lt;form</span> <span class="pre">method=&quot;post&quot;&gt;</span></code>.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.csrf_token">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">csrf_token</span></span><a class="headerlink" href="#responder.Request.csrf_token" title="Link to this definition"></a></dt>
<dd><p>The session’s CSRF token, minted on first access.</p>
<p>Embed it in responses (or read it client-side) and send it back on
unsafe requests in an <code class="docutils literal notranslate"><span class="pre">X-CSRF-Token</span></code> header or <code class="docutils literal notranslate"><span class="pre">csrf_token</span></code> form
field. Requires sessions; see <a class="reference internal" href="#responder.Request.session" title="responder.Request.session"><code class="xref py py-attr docutils literal notranslate"><span class="pre">session</span></code></a>.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.encoding">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">encoding</span></span><a class="headerlink" href="#responder.Request.encoding" title="Link to this definition"></a></dt>
<dd><p>The encoding of the Request’s body. Can be set, manually. Must be awaited.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.full_url">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">full_url</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">str</span></span><a class="headerlink" href="#responder.Request.full_url" title="Link to this definition"></a></dt>
<dd><p>The full URL of the Request, query parameters and all.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.headers">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">headers</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="#responder.models.CaseInsensitiveDict" title="responder.models.CaseInsensitiveDict"><span class="pre">CaseInsensitiveDict</span></a></span><a class="headerlink" href="#responder.Request.headers" title="Link to this definition"></a></dt>
<dd><p>A case-insensitive dictionary, containing all headers sent in the Request.</p>
<p>Single-value access (<code class="docutils literal notranslate"><span class="pre">req.headers[&quot;X-Forwarded-For&quot;]</span></code>) returns the
last value received for a repeated header; use
<code class="docutils literal notranslate"><span class="pre">req.headers.get_list(&quot;X-Forwarded-For&quot;)</span></code> to read every raw line,
in order.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.is_json">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">is_json</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">bool</span></span><a class="headerlink" href="#responder.Request.is_json" title="Link to this definition"></a></dt>
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if the request content type is JSON.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.is_secure">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">is_secure</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">bool</span></span><a class="headerlink" href="#responder.Request.is_secure" title="Link to this definition"></a></dt>
<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if the request was made over HTTPS.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.last_event_id">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">last_event_id</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><a class="headerlink" href="#responder.Request.last_event_id" title="Link to this definition"></a></dt>
<dd><p>The SSE <code class="docutils literal notranslate"><span class="pre">Last-Event-ID</span></code> header sent by a reconnecting client.</p>
<p>Use it to resume an event stream from where the client left off.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Request.media">
<span class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">media</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">format</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">Callable</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Any</span></span></span><a class="reference internal" href="_modules/responder/models.html#Request.media"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Request.media" title="Link to this definition"></a></dt>
<dd><p>Renders incoming json/yaml/form data as Python objects. Must be awaited.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>format</strong> – The name of the format being used.
Alternatively, accepts a custom callable for the format type.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Request.media_sync">
<span class="sig-name descname"><span class="pre">media_sync</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">format</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">Callable</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Any</span></span></span><a class="reference internal" href="_modules/responder/models.html#Request.media_sync"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Request.media_sync" title="Link to this definition"></a></dt>
<dd><p>Synchronous <a class="reference internal" href="#responder.Request.media" title="responder.Request.media"><code class="xref py py-meth docutils literal notranslate"><span class="pre">media()</span></code></a>, for use from <strong>sync</strong> handlers.</p>
<p>Responder runs sync handlers in a worker thread, so this safely bridges
to the event loop to read and parse the body. Calling it from an
<code class="docutils literal notranslate"><span class="pre">async</span></code> handler raises — use <code class="docutils literal notranslate"><span class="pre">await</span> <span class="pre">req.media()</span></code> there instead.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/&quot;</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;POST&quot;</span><span class="p">])</span>
<span class="k">def</span><span class="w"> </span><span class="nf">create</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="n">data</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">media_sync</span><span class="p">()</span>
</pre></div>
</div>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.method">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">method</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">str</span></span><a class="headerlink" href="#responder.Request.method" title="Link to this definition"></a></dt>
<dd><p>The HTTP method, UPPER-cased (<code class="docutils literal notranslate"><span class="pre">&quot;GET&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;POST&quot;</span></code>, …).</p>
<p>Comparisons are case-sensitive; compare against uppercase literals
(<code class="docutils literal notranslate"><span class="pre">req.method</span> <span class="pre">==</span> <span class="pre">&quot;GET&quot;</span></code>). Use <code class="docutils literal notranslate"><span class="pre">.lower()</span></code> for the lowercase string.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.mimetype">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">mimetype</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">str</span></span><a class="headerlink" href="#responder.Request.mimetype" title="Link to this definition"></a></dt>
<dd><p>The MIME type of the request body, from the <code class="docutils literal notranslate"><span class="pre">Content-Type</span></code> header.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.params">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">params</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="#responder.models.QueryDict" title="responder.models.QueryDict"><span class="pre">QueryDict</span></a></span><a class="headerlink" href="#responder.Request.params" title="Link to this definition"></a></dt>
<dd><p>A dictionary of the parsed query parameters used for the Request.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.path_params">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">path_params</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">dict</span></span><a class="headerlink" href="#responder.Request.path_params" title="Link to this definition"></a></dt>
<dd><p>The path parameters extracted from the URL route.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Request.preferred_media_type">
<span class="sig-name descname"><span class="pre">preferred_media_type</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">candidates</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Request.preferred_media_type"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Request.preferred_media_type" title="Link to this definition"></a></dt>
<dd><p>Pick the candidate media type the client’s <code class="docutils literal notranslate"><span class="pre">Accept</span></code> header prefers.</p>
<p>Candidates are ranked by the q-value of the most specific matching
media range (RFC 9110 §12.5.1); ties — and requests without an
<code class="docutils literal notranslate"><span class="pre">Accept</span></code> header — keep the order of <code class="docutils literal notranslate"><span class="pre">candidates</span></code>, so put the
server’s preferred default first. Returns <code class="docutils literal notranslate"><span class="pre">None</span></code> when the client
accepts none of them.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">preferred</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">preferred_media_type</span><span class="p">(</span>
<span class="p">[</span><span class="s2">&quot;application/json&quot;</span><span class="p">,</span> <span class="s2">&quot;text/csv&quot;</span><span class="p">]</span>
<span class="p">)</span>
</pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>candidates</strong> – An iterable of media types (<code class="docutils literal notranslate"><span class="pre">application/json</span></code>)
or bare subtype tokens (<code class="docutils literal notranslate"><span class="pre">json</span></code>).</p>
</dd>
</dl>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.session">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">session</span></span><a class="headerlink" href="#responder.Request.session" title="Link to this definition"></a></dt>
<dd><p>The session data, in dict form, from the Request.</p>
<p>Requires sessions enabled (a <code class="docutils literal notranslate"><span class="pre">secret_key</span></code> or <code class="docutils literal notranslate"><span class="pre">session_backend</span></code>,
with <code class="docutils literal notranslate"><span class="pre">sessions</span> <span class="pre">!=</span> <span class="pre">False</span></code>); raises <code class="docutils literal notranslate"><span class="pre">RuntimeError</span></code> otherwise.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.state">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">state</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">State</span></span><a class="headerlink" href="#responder.Request.state" title="Link to this definition"></a></dt>
<dd><p>Use the state to store additional information.</p>
<p>This can be a very helpful feature, if you want to hand over
information from a middelware or a route decorator to the
actual route handler.</p>
<p>Usage: <code class="docutils literal notranslate"><span class="pre">request.state.time_started</span> <span class="pre">=</span> <span class="pre">time.time()</span></code></p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Request.stream">
<span class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">stream</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Request.stream"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Request.stream" title="Link to this definition"></a></dt>
<dd><p>Iterate over the raw request body in chunks, without buffering.</p>
<p>Useful for large uploads. Once streamed, the body cannot be read
again via <a class="reference internal" href="#responder.Request.content" title="responder.Request.content"><code class="xref py py-attr docutils literal notranslate"><span class="pre">content</span></code></a>, <a class="reference internal" href="#responder.Request.text" title="responder.Request.text"><code class="xref py py-attr docutils literal notranslate"><span class="pre">text</span></code></a>, or <a class="reference internal" href="#responder.Request.media" title="responder.Request.media"><code class="xref py py-meth docutils literal notranslate"><span class="pre">media()</span></code></a>.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/upload&quot;</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;POST&quot;</span><span class="p">])</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">upload</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="k">async</span> <span class="k">with</span> <span class="k">await</span> <span class="n">anyio</span><span class="o">.</span><span class="n">open_file</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="s2">&quot;wb&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
<span class="k">async</span> <span class="k">for</span> <span class="n">chunk</span> <span class="ow">in</span> <span class="n">req</span><span class="o">.</span><span class="n">stream</span><span class="p">():</span>
<span class="k">await</span> <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">chunk</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.text">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">text</span></span><a class="headerlink" href="#responder.Request.text" title="Link to this definition"></a></dt>
<dd><p>The Request body, as unicode. Must be awaited.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.text_sync">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">text_sync</span></span><a class="headerlink" href="#responder.Request.text_sync" title="Link to this definition"></a></dt>
<dd><p>Synchronous <a class="reference internal" href="#responder.Request.text" title="responder.Request.text"><code class="xref py py-attr docutils literal notranslate"><span class="pre">text</span></code></a>, for use from <strong>sync</strong> handlers (see
<a class="reference internal" href="#responder.Request.media_sync" title="responder.Request.media_sync"><code class="xref py py-meth docutils literal notranslate"><span class="pre">media_sync()</span></code></a>).</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Request.url">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">url</span></span><a class="headerlink" href="#responder.Request.url" title="Link to this definition"></a></dt>
<dd><p>The parsed URL of the Request.</p>
</dd></dl>
</dd></dl>
</section>
<section id="response">
<h2>Response<a class="headerlink" href="#response" title="Link to this heading"></a></h2>
<p>The response object is passed into every view as the second argument.
Mutate it to control what gets sent back to the client — the body,
status code, headers, and cookies.</p>
<p>Common patterns:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">resp</span><span class="o">.</span><span class="n">text</span> <span class="o">=</span> <span class="s2">&quot;plain text&quot;</span> <span class="c1"># text/plain</span>
<span class="n">resp</span><span class="o">.</span><span class="n">html</span> <span class="o">=</span> <span class="s2">&quot;&lt;h1&gt;Hello&lt;/h1&gt;&quot;</span> <span class="c1"># text/html</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;key&quot;</span><span class="p">:</span> <span class="s2">&quot;value&quot;</span><span class="p">}</span> <span class="c1"># application/json</span>
<span class="n">resp</span><span class="o">.</span><span class="n">content</span> <span class="o">=</span> <span class="sa">b</span><span class="s2">&quot;raw bytes&quot;</span> <span class="c1"># application/octet-stream</span>
<span class="c1"># Serve files. Pass root= to jail a user-supplied path under a directory —</span>
<span class="c1"># a &quot;../&quot; or symlink escape returns 404 instead of leaking the filesystem:</span>
<span class="n">resp</span><span class="o">.</span><span class="n">file</span><span class="p">(</span><span class="s2">&quot;reports/q3.pdf&quot;</span><span class="p">,</span> <span class="n">root</span><span class="o">=</span><span class="s2">&quot;exports&quot;</span><span class="p">)</span> <span class="c1"># auto content-type</span>
<span class="n">resp</span><span class="o">.</span><span class="n">stream_file</span><span class="p">(</span><span class="s2">&quot;exports/big.csv&quot;</span><span class="p">,</span> <span class="n">root</span><span class="o">=</span><span class="s2">&quot;exports&quot;</span><span class="p">)</span> <span class="c1"># streamed</span>
<span class="n">resp</span><span class="o">.</span><span class="n">status_code</span> <span class="o">=</span> <span class="mi">201</span>
<span class="n">resp</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s2">&quot;X-Custom&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;value&quot;</span>
<span class="n">resp</span><span class="o">.</span><span class="n">cookies</span><span class="p">[</span><span class="s2">&quot;session&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;abc123&quot;</span>
<span class="c1"># Common response helpers:</span>
<span class="n">resp</span><span class="o">.</span><span class="n">created</span><span class="p">({</span><span class="s2">&quot;id&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">location</span><span class="o">=</span><span class="s2">&quot;/items/1&quot;</span><span class="p">)</span> <span class="c1"># 201 + Location</span>
<span class="n">resp</span><span class="o">.</span><span class="n">no_content</span><span class="p">()</span> <span class="c1"># 204 + empty body</span>
<span class="n">resp</span><span class="o">.</span><span class="n">problem</span><span class="p">(</span><span class="mi">409</span><span class="p">,</span> <span class="s2">&quot;Already exists&quot;</span><span class="p">)</span> <span class="c1"># application/problem+json</span>
<span class="c1"># Redirect (external targets allowed by default; pass</span>
<span class="c1"># allow_external=False to refuse off-site URLs):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">redirect</span><span class="p">(</span><span class="s2">&quot;/dashboard&quot;</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Handlers can also <em>return</em> the body Flask-style instead of mutating
<code class="docutils literal notranslate"><span class="pre">resp</span></code>: <code class="docutils literal notranslate"><span class="pre">return</span> <span class="pre">body</span></code>, <code class="docutils literal notranslate"><span class="pre">return</span> <span class="pre">body,</span> <span class="pre">status</span></code>, or
<code class="docutils literal notranslate"><span class="pre">return</span> <span class="pre">body,</span> <span class="pre">status,</span> <span class="pre">headers</span></code>. Pydantic models and dataclasses serialize
natively. A supported return annotation validates the body and supplies its
OpenAPI/generated-client type; use <code class="docutils literal notranslate"><span class="pre">response_model=False</span></code> to opt out.
Status-specific contracts use <code class="docutils literal notranslate"><span class="pre">responses={404:</span> <span class="pre">ErrorModel}</span></code>, or a mapping
with <code class="docutils literal notranslate"><span class="pre">model</span></code> plus additional OpenAPI metadata.
<code class="docutils literal notranslate"><span class="pre">resp.session</span></code> is a read/write view of <code class="docutils literal notranslate"><span class="pre">req.session</span></code> and raises
<code class="docutils literal notranslate"><span class="pre">RuntimeError</span></code> when the app is built with <code class="docutils literal notranslate"><span class="pre">sessions=False</span></code>.</p>
</div>
<dl class="py class">
<dt class="sig sig-object py" id="responder.Response">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">Response</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">req</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">formats</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">auto_etag</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">auto_vary</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Response"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response" title="Link to this definition"></a></dt>
<dd><p>An HTTP response, passed to each view as the second argument.</p>
<p>Mutate this object to control what gets sent back to the client. Set
<code class="xref py py-attr docutils literal notranslate"><span class="pre">text</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">html</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">media</span></code>, or <code class="xref py py-attr docutils literal notranslate"><span class="pre">content</span></code> to define
the body. Use <code class="xref py py-attr docutils literal notranslate"><span class="pre">headers</span></code> and <a class="reference internal" href="#responder.Response.set_cookie" title="responder.Response.set_cookie"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_cookie()</span></code></a> to control metadata.</p>
<dl class="field-list simple">
<dt class="field-odd">Variables<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>text</strong> – Set the response body as plain text (sets <code class="docutils literal notranslate"><span class="pre">Content-Type:</span> <span class="pre">text/plain</span></code>).</p></li>
<li><p><strong>html</strong> – Set the response body as HTML (sets <code class="docutils literal notranslate"><span class="pre">Content-Type:</span> <span class="pre">text/html</span></code>).</p></li>
<li><p><strong>media</strong> – Set a Python object (dict, list) to be serialized as JSON (or negotiated format).</p></li>
<li><p><strong>content</strong> – Set the raw response body as bytes.</p></li>
<li><p><strong>status_code</strong> – The HTTP status code (e.g. <code class="docutils literal notranslate"><span class="pre">200</span></code>, <code class="docutils literal notranslate"><span class="pre">404</span></code>). Defaults to <code class="docutils literal notranslate"><span class="pre">200</span></code> if not set.</p></li>
<li><p><strong>headers</strong> – A case-insensitive (case-preserving) dict of response headers.</p></li>
<li><p><strong>cookies</strong> – A <code class="docutils literal notranslate"><span class="pre">SimpleCookie</span></code> holding cookies to set on the response.</p></li>
<li><p><strong>session</strong> – A dict of session data. Changes are persisted in a signed cookie.</p></li>
<li><p><strong>etag</strong> – Entity tag for the response. When the request’s <code class="docutils literal notranslate"><span class="pre">If-None-Match</span></code> matches on <code class="docutils literal notranslate"><span class="pre">GET</span></code>/<code class="docutils literal notranslate"><span class="pre">HEAD</span></code>, an automatic <code class="docutils literal notranslate"><span class="pre">304</span> <span class="pre">Not</span> <span class="pre">Modified</span></code> is sent instead of the body. On state-changing methods, <code class="docutils literal notranslate"><span class="pre">If-Match</span></code> / <code class="docutils literal notranslate"><span class="pre">If-None-Match</span></code> preconditions are enforced against it with an automatic <code class="docutils literal notranslate"><span class="pre">412</span> <span class="pre">Precondition</span> <span class="pre">Failed</span></code>.</p></li>
<li><p><strong>last_modified</strong> – A <code class="docutils literal notranslate"><span class="pre">datetime</span></code> (or HTTP-date string) for <code class="docutils literal notranslate"><span class="pre">Last-Modified</span></code>. Honors <code class="docutils literal notranslate"><span class="pre">If-Modified-Since</span></code> with automatic <code class="docutils literal notranslate"><span class="pre">304</span></code> responses, and <code class="docutils literal notranslate"><span class="pre">If-Unmodified-Since</span></code> on state-changing methods with automatic <code class="docutils literal notranslate"><span class="pre">412</span></code> responses.</p></li>
</ul>
</dd>
</dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.background">
<span class="sig-name descname"><span class="pre">background</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Response.background"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.background" title="Link to this definition"></a></dt>
<dd><p>Schedule a task to run after the response has been sent.</p>
<p>Unlike <code class="docutils literal notranslate"><span class="pre">api.background</span></code> (which runs immediately in a thread pool),
tasks scheduled here are deferred until the client has the response,
so they never delay it. Sync and async functions both work. Multiple
tasks run in the order scheduled.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/signup&quot;</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;POST&quot;</span><span class="p">])</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">signup</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;ok&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="n">resp</span><span class="o">.</span><span class="n">background</span><span class="p">(</span><span class="n">send_welcome_email</span><span class="p">,</span> <span class="s2">&quot;user@example.com&quot;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.cache_control">
<span class="sig-name descname"><span class="pre">cache_control</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">directives</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Response.cache_control"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.cache_control" title="Link to this definition"></a></dt>
<dd><p>Set the <code class="docutils literal notranslate"><span class="pre">Cache-Control</span></code> header from keyword directives.</p>
<p>Underscores become hyphens; <code class="docutils literal notranslate"><span class="pre">True</span></code> renders a bare directive,
other values render <code class="docutils literal notranslate"><span class="pre">name=value</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">resp</span><span class="o">.</span><span class="n">cache_control</span><span class="p">(</span><span class="n">public</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">max_age</span><span class="o">=</span><span class="mi">3600</span><span class="p">)</span>
<span class="c1"># Cache-Control: public, max-age=3600</span>
<span class="n">resp</span><span class="o">.</span><span class="n">cache_control</span><span class="p">(</span><span class="n">no_store</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="c1"># Cache-Control: no-store</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.created">
<span class="sig-name descname"><span class="pre">created</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">media</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="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">location</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">headers</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="reference internal" href="_modules/responder/models.html#Response.created"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.created" title="Link to this definition"></a></dt>
<dd><p>Mark the response as <code class="docutils literal notranslate"><span class="pre">201</span> <span class="pre">Created</span></code>.</p>
<p>Optionally set a JSON-serializable body and a <code class="docutils literal notranslate"><span class="pre">Location</span></code> header:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">resp</span><span class="o">.</span><span class="n">created</span><span class="p">({</span><span class="s2">&quot;id&quot;</span><span class="p">:</span> <span class="n">item</span><span class="o">.</span><span class="n">id</span><span class="p">},</span> <span class="n">location</span><span class="o">=</span><span class="sa">f</span><span class="s2">&quot;/items/</span><span class="si">{</span><span class="n">item</span><span class="o">.</span><span class="n">id</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.delete_cookie">
<span class="sig-name descname"><span class="pre">delete_cookie</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</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">path</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'/'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">domain</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">secure</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">httponly</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">samesite</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'lax'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Response.delete_cookie"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.delete_cookie" title="Link to this definition"></a></dt>
<dd><p>Expire a cookie on the client (empty value, <code class="docutils literal notranslate"><span class="pre">Max-Age=0</span></code>).</p>
<p>Pass the same <code class="docutils literal notranslate"><span class="pre">path</span></code>/<code class="docutils literal notranslate"><span class="pre">domain</span></code> the cookie was set with so the browser
matches and drops it.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">resp</span><span class="o">.</span><span class="n">delete_cookie</span><span class="p">(</span><span class="s2">&quot;token&quot;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.download">
<span class="sig-name descname"><span class="pre">download</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</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">filename</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">content_type</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">root</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">conditional</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Response.download"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.download" title="Link to this definition"></a></dt>
<dd><p>Serve a file as an attachment, prompting the browser to download.</p>
<p>Streams the file (with range support, so downloads are resumable)
and sets <code class="docutils literal notranslate"><span class="pre">Content-Disposition</span></code>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>path</strong> – Path to the file to serve.</p></li>
<li><p><strong>filename</strong> – Download name presented to the client.
Defaults to the file’s own name.</p></li>
<li><p><strong>content_type</strong> – Optional MIME type override.</p></li>
<li><p><strong>root</strong> – If given, <code class="docutils literal notranslate"><span class="pre">path</span></code> is resolved under this directory and any
escape attempt yields a <code class="docutils literal notranslate"><span class="pre">404</span></code> (see <a class="reference internal" href="#responder.Response.file" title="responder.Response.file"><code class="xref py py-meth docutils literal notranslate"><span class="pre">file()</span></code></a>).</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.file">
<span class="sig-name descname"><span class="pre">file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</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">content_type</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">root</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">conditional</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Response.file"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.file" title="Link to this definition"></a></dt>
<dd><p>Serve a file from disk as the response.</p>
<p>Supports HTTP range requests (<code class="docutils literal notranslate"><span class="pre">Range:</span> <span class="pre">bytes=...</span></code>) with <code class="docutils literal notranslate"><span class="pre">206</span></code>
partial responses. The file’s bytes are read in a worker thread when
the response is sent, so calling this from an <code class="docutils literal notranslate"><span class="pre">async</span></code> handler never
blocks the event loop.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>path</strong> – Path to the file to serve.</p></li>
<li><p><strong>content_type</strong> – Optional MIME type override.</p></li>
<li><p><strong>root</strong> – If given, <code class="docutils literal notranslate"><span class="pre">path</span></code> is resolved under this directory and any
attempt to escape it (via <code class="docutils literal notranslate"><span class="pre">..</span></code> or a symlink) yields a
<code class="docutils literal notranslate"><span class="pre">404</span></code> — use this whenever <code class="docutils literal notranslate"><span class="pre">path</span></code> is built from user input.</p></li>
<li><p><strong>conditional</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code> (default), set a stat-based ETag and
<code class="docutils literal notranslate"><span class="pre">Last-Modified</span></code> so conditional requests get a <code class="docutils literal notranslate"><span class="pre">304</span></code>
(and the file’s bytes aren’t read to compute it).</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.no_content">
<span class="sig-name descname"><span class="pre">no_content</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">headers</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="reference internal" href="_modules/responder/models.html#Response.no_content"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.no_content" title="Link to this definition"></a></dt>
<dd><p>Mark the response as <code class="docutils literal notranslate"><span class="pre">204</span> <span class="pre">No</span> <span class="pre">Content</span></code> and clear any response body.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Response.ok">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">ok</span></span><a class="headerlink" href="#responder.Response.ok" title="Link to this definition"></a></dt>
<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if the status code is in the 2xx range (success).</p>
<p>Reads as <code class="docutils literal notranslate"><span class="pre">200</span></code> until a status code has been set, so it never raises.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.problem">
<span class="sig-name descname"><span class="pre">problem</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">status_code</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">detail</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="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">title</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">type</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">instance</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">errors</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">headers</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="o"><span class="pre">**</span></span><span class="n"><span class="pre">extensions</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Response.problem"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.problem" title="Link to this definition"></a></dt>
<dd><p>Send an RFC 9457 <code class="docutils literal notranslate"><span class="pre">application/problem+json</span></code> response.</p>
<p>API-level <code class="docutils literal notranslate"><span class="pre">problem_handler</span></code> enrichment and request IDs are applied,
then explicit helper arguments and extension members are layered on top.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.redirect">
<span class="sig-name descname"><span class="pre">redirect</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">location</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</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">set_text</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">status_code</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">permanent</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">allow_external</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">None</span></span></span><a class="reference internal" href="_modules/responder/models.html#Response.redirect"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.redirect" title="Link to this definition"></a></dt>
<dd><p>Redirect the client to a different URL.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>location</strong> – The URL to redirect to.</p></li>
<li><p><strong>set_text</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code>, set a default redirect message as the body.</p></li>
<li><p><strong>status_code</strong> – An explicit HTTP status code. When omitted, the
redirect is a method-preserving <code class="docutils literal notranslate"><span class="pre">307</span> <span class="pre">Temporary</span>
<span class="pre">Redirect</span></code> (or <code class="docutils literal notranslate"><span class="pre">308</span> <span class="pre">Permanent</span> <span class="pre">Redirect</span></code> with
<code class="docutils literal notranslate"><span class="pre">permanent=True</span></code>).</p></li>
<li><p><strong>permanent</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code>, send a <code class="docutils literal notranslate"><span class="pre">308</span> <span class="pre">Permanent</span> <span class="pre">Redirect</span></code>
instead of the default <code class="docutils literal notranslate"><span class="pre">307</span></code>. Ignored when an
explicit <code class="docutils literal notranslate"><span class="pre">status_code</span></code> is given.</p></li>
<li><p><strong>allow_external</strong> – If <code class="docutils literal notranslate"><span class="pre">False</span></code>, refuse (with a <code class="docutils literal notranslate"><span class="pre">400</span></code>) to redirect
to an absolute or protocol-relative URL — pass
this whenever <code class="docutils literal notranslate"><span class="pre">location</span></code> comes from user input,
to prevent open redirects.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.render">
<span class="sig-name descname"><span class="pre">render</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">template</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Response.render"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.render" title="Link to this definition"></a></dt>
<dd><p>Render a Jinja2 template as the HTML response body.</p>
<p>Shorthand for <code class="docutils literal notranslate"><span class="pre">resp.html</span> <span class="pre">=</span> <span class="pre">api.template(...)</span></code>, using the owning
API’s <code class="docutils literal notranslate"><span class="pre">templates_dir</span></code>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>template</strong> – The template filename.</p></li>
<li><p><strong>*args</strong> – Data to pass into the template.</p></li>
<li><p><strong>**kwargs</strong> – Data to pass into the template.</p></li>
</ul>
</dd>
</dl>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">home</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s2">&quot;home.html&quot;</span><span class="p">,</span> <span class="n">user</span><span class="o">=</span><span class="s2">&quot;kenneth&quot;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.reset_for_error">
<span class="sig-name descname"><span class="pre">reset_for_error</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Response.reset_for_error"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.reset_for_error" title="Link to this definition"></a></dt>
<dd><p>Discard a previously prepared success response before framework errors.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Response.session">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">session</span></span><a class="headerlink" href="#responder.Response.session" title="Link to this definition"></a></dt>
<dd><p>The session dict (delegates to the request; requires sessions on).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.set_cookie">
<span class="sig-name descname"><span class="pre">set_cookie</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">expires</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">path</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'/'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">domain</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">max_age</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">secure</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">httponly</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">samesite</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'lax'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Response.set_cookie"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.set_cookie" title="Link to this definition"></a></dt>
<dd><p>Set a cookie on the response with full control over directives.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>key</strong> – The cookie name.</p></li>
<li><p><strong>value</strong> – The cookie value.</p></li>
<li><p><strong>expires</strong> – Expiration date string (e.g. <code class="docutils literal notranslate"><span class="pre">&quot;Thu,</span> <span class="pre">01</span> <span class="pre">Jan</span> <span class="pre">2026</span> <span class="pre">00:00:00</span> <span class="pre">GMT&quot;</span></code>).</p></li>
<li><p><strong>path</strong> – URL path the cookie applies to (default <code class="docutils literal notranslate"><span class="pre">&quot;/&quot;</span></code>).</p></li>
<li><p><strong>domain</strong> – Domain the cookie is valid for.</p></li>
<li><p><strong>max_age</strong> – Maximum age in seconds before the cookie expires.</p></li>
<li><p><strong>secure</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code>, cookie is only sent over HTTPS.</p></li>
<li><p><strong>httponly</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code> (default), cookie is inaccessible to JavaScript.</p></li>
<li><p><strong>samesite</strong> – Cross-site behavior: <code class="docutils literal notranslate"><span class="pre">&quot;lax&quot;</span></code> (default), <code class="docutils literal notranslate"><span class="pre">&quot;strict&quot;</span></code>,
<code class="docutils literal notranslate"><span class="pre">&quot;none&quot;</span></code>, or <code class="docutils literal notranslate"><span class="pre">None</span></code> to omit the directive.</p></li>
</ul>
</dd>
</dl>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">resp</span><span class="o">.</span><span class="n">set_cookie</span><span class="p">(</span>
<span class="s2">&quot;token&quot;</span><span class="p">,</span> <span class="n">value</span><span class="o">=</span><span class="s2">&quot;abc123&quot;</span><span class="p">,</span>
<span class="n">max_age</span><span class="o">=</span><span class="mi">3600</span><span class="p">,</span> <span class="n">secure</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">httponly</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.sse">
<span class="sig-name descname"><span class="pre">sse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</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="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">heartbeat</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="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Response.sse"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.sse" title="Link to this definition"></a></dt>
<dd><p>Set up a Server-Sent Events response from an async generator.</p>
<p>Each yielded value becomes one event:</p>
<ul class="simple">
<li><p>a <code class="docutils literal notranslate"><span class="pre">dict</span></code> with any of <code class="docutils literal notranslate"><span class="pre">data</span></code>, <code class="docutils literal notranslate"><span class="pre">event</span></code>, <code class="docutils literal notranslate"><span class="pre">id</span></code>, <code class="docutils literal notranslate"><span class="pre">retry</span></code>
(<code class="docutils literal notranslate"><span class="pre">data</span></code> that is a <code class="docutils literal notranslate"><span class="pre">dict</span></code>/<code class="docutils literal notranslate"><span class="pre">list</span></code> is JSON-encoded);</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">{&quot;comment&quot;:</span> <span class="pre">&quot;...&quot;}</span></code> for a comment/keepalive line;</p></li>
<li><p>a <code class="docutils literal notranslate"><span class="pre">str</span></code> (or anything else) is sent as the <code class="docutils literal notranslate"><span class="pre">data</span></code> field;</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">bytes</span></code> are written verbatim (pre-formatted frame).</p></li>
</ul>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/events&quot;</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">events</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="nd">@resp</span><span class="o">.</span><span class="n">sse</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">stream</span><span class="p">():</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>
<span class="k">yield</span> <span class="p">{</span><span class="s2">&quot;data&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;n&quot;</span><span class="p">:</span> <span class="n">i</span><span class="p">},</span> <span class="s2">&quot;id&quot;</span><span class="p">:</span> <span class="n">i</span><span class="p">}</span>
</pre></div>
</div>
<p>Pass <code class="docutils literal notranslate"><span class="pre">heartbeat=</span></code> (seconds) to emit a keepalive comment during idle
periods, so proxies don’t drop the connection:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@resp</span><span class="o">.</span><span class="n">sse</span><span class="p">(</span><span class="n">heartbeat</span><span class="o">=</span><span class="mi">15</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">stream</span><span class="p">():</span> <span class="o">...</span>
</pre></div>
</div>
<p>On reconnect the client sends the last id it saw; read it with
<a class="reference internal" href="#responder.Request.last_event_id" title="responder.Request.last_event_id"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Request.last_event_id</span></code></a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>func</strong> – The async generator function (or omit when using the
<code class="docutils literal notranslate"><span class="pre">&#64;resp.sse(heartbeat=...)</span></code> form).</p></li>
<li><p><strong>heartbeat</strong> – Idle keepalive interval in seconds (<code class="docutils literal notranslate"><span class="pre">None</span></code> = off).</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py" id="responder.Response.status_code_safe">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">status_code_safe</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">int</span></span><a class="headerlink" href="#responder.Response.status_code_safe" title="Link to this definition"></a></dt>
<dd><p>Return the status code, raising <code class="docutils literal notranslate"><span class="pre">RuntimeError</span></code> if it hasn’t been set.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.stream">
<span class="sig-name descname"><span class="pre">stream</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Response.stream"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.stream" title="Link to this definition"></a></dt>
<dd><p>Set up a streaming response from an async generator function.</p>
<p>The generator yields chunks of bytes that are sent to the client
as they are produced, without buffering the full response in memory.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/stream&quot;</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">stream_data</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="nd">@resp</span><span class="o">.</span><span class="n">stream</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">body</span><span class="p">():</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>
<span class="k">yield</span> <span class="sa">f</span><span class="s2">&quot;chunk </span><span class="si">{</span><span class="n">i</span><span class="si">}</span><span class="se">\n</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">encode</span><span class="p">()</span>
</pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>func</strong> – An async generator function that yields response chunks.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.stream_file">
<span class="sig-name descname"><span class="pre">stream_file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</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">content_type</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">chunk_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">8192</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">root</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">conditional</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Response.stream_file"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.stream_file" title="Link to this definition"></a></dt>
<dd><p>Stream a file without loading it entirely into memory.</p>
<p>Supports HTTP range requests (<code class="docutils literal notranslate"><span class="pre">Range:</span> <span class="pre">bytes=...</span></code>) with <code class="docutils literal notranslate"><span class="pre">206</span></code>
partial responses, enabling video seeking and resumable downloads.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>path</strong> – Path to the file.</p></li>
<li><p><strong>content_type</strong> – Optional MIME type override.</p></li>
<li><p><strong>chunk_size</strong> – Size of chunks to read (default 8192 bytes).</p></li>
<li><p><strong>root</strong> – If given, <code class="docutils literal notranslate"><span class="pre">path</span></code> is resolved under this directory and any
attempt to escape it (via <code class="docutils literal notranslate"><span class="pre">..</span></code> or a symlink) yields a
<code class="docutils literal notranslate"><span class="pre">404</span></code> — use this whenever <code class="docutils literal notranslate"><span class="pre">path</span></code> is built from user input.</p></li>
<li><p><strong>conditional</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code> (default), set a stat-based ETag and
<code class="docutils literal notranslate"><span class="pre">Last-Modified</span></code> so conditional requests get a <code class="docutils literal notranslate"><span class="pre">304</span></code>.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Response.vary">
<span class="sig-name descname"><span class="pre">vary</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">values</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#Response.vary"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Response.vary" title="Link to this definition"></a></dt>
<dd><p>Add one or more field names to the response <code class="docutils literal notranslate"><span class="pre">Vary</span></code> header.</p>
<p>Tokens are merged with any existing <code class="docutils literal notranslate"><span class="pre">Vary</span></code> value and de-duplicated
case-insensitively:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">resp</span><span class="o">.</span><span class="n">vary</span><span class="p">(</span><span class="s2">&quot;Accept&quot;</span><span class="p">,</span> <span class="s2">&quot;Accept-Language&quot;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
</dd></dl>
</section>
<section id="typed-streams">
<h2>Typed Streams<a class="headerlink" href="#typed-streams" title="Link to this heading"></a></h2>
<p>Use <a class="reference internal" href="#responder.API.sse" title="responder.API.sse"><code class="xref py py-meth docutils literal notranslate"><span class="pre">API.sse()</span></code></a> and <a class="reference internal" href="#responder.API.ndjson" title="responder.API.ndjson"><code class="xref py py-meth docutils literal notranslate"><span class="pre">API.ndjson()</span></code></a> for item-by-item validation,
serialization, OpenAPI schemas, and generated streaming clients. <code class="docutils literal notranslate"><span class="pre">SSE</span></code> is
the optional metadata envelope for a typed Server-Sent Event.</p>
<dl class="py class">
<dt class="sig sig-object py" id="responder.SSE">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">SSE</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">T</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">event</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">retry</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">comment</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/streaming.html#SSE"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.SSE" title="Link to this definition"></a></dt>
<dd><p>One typed Server-Sent Event with optional protocol metadata.</p>
<p>Yield the data model directly when no metadata is needed. Use <code class="docutils literal notranslate"><span class="pre">SSE</span></code> for
named events, resumable ids, retry hints, or comment-only keepalives:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">yield</span> <span class="n">SSE</span><span class="p">(</span><span class="n">BuildEvent</span><span class="p">(</span><span class="o">...</span><span class="p">),</span> <span class="n">event</span><span class="o">=</span><span class="s2">&quot;progress&quot;</span><span class="p">,</span> <span class="nb">id</span><span class="o">=</span><span class="n">build</span><span class="o">.</span><span class="n">id</span><span class="p">)</span>
<span class="k">yield</span> <span class="n">SSE</span><span class="p">(</span><span class="n">comment</span><span class="o">=</span><span class="s2">&quot;still working&quot;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
</section>
<section id="parameter-markers">
<h2>Parameter Markers<a class="headerlink" href="#parameter-markers" title="Link to this heading"></a></h2>
<p>Inject validated query parameters, headers, cookies, and path parameters
straight into a handler’s signature. A marker goes in the <em>default</em> slot of a
keyword-only argument — it is not a decorator:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">responder</span><span class="w"> </span><span class="kn">import</span> <span class="n">Query</span><span class="p">,</span> <span class="n">Header</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/search&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">search</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span>
<span class="n">q</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Query</span><span class="p">(</span><span class="o">...</span><span class="p">),</span> <span class="c1"># required</span>
<span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="n">Query</span><span class="p">(</span><span class="mi">10</span><span class="p">),</span> <span class="c1"># optional, defaults to 10</span>
<span class="n">tags</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="n">Query</span><span class="p">(</span><span class="o">...</span><span class="p">),</span> <span class="c1"># repeated keys: ?tags=a&amp;tags=b</span>
<span class="n">token</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Header</span><span class="p">(</span><span class="kc">None</span><span class="p">,</span> <span class="n">alias</span><span class="o">=</span><span class="s2">&quot;X-Token&quot;</span><span class="p">)):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;q&quot;</span><span class="p">:</span> <span class="n">q</span><span class="p">,</span> <span class="s2">&quot;limit&quot;</span><span class="p">:</span> <span class="n">limit</span><span class="p">,</span> <span class="s2">&quot;tags&quot;</span><span class="p">:</span> <span class="n">tags</span><span class="p">}</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">Query(...)</span></code> (an Ellipsis) marks a required parameter; <code class="docutils literal notranslate"><span class="pre">Query(value)</span></code>
supplies a default. Each value is coerced to the parameter’s type annotation
with Pydantic; a missing required value or a coercion failure returns
<code class="docutils literal notranslate"><span class="pre">422</span> <span class="pre">Unprocessable</span> <span class="pre">Entity</span></code> with a body of <code class="docutils literal notranslate"><span class="pre">{&quot;errors&quot;:</span> <span class="pre">[...]}</span></code> aggregating
every failing parameter.</p>
<ul class="simple">
<li><p><a class="reference internal" href="#responder.Query" title="responder.Query"><code class="xref py py-func docutils literal notranslate"><span class="pre">Query()</span></code></a> reads the query string. A <code class="docutils literal notranslate"><span class="pre">list</span></code> / <code class="docutils literal notranslate"><span class="pre">list[int]</span></code>
annotation collects repeated keys.</p></li>
<li><p><a class="reference internal" href="#responder.Header" title="responder.Header"><code class="xref py py-func docutils literal notranslate"><span class="pre">Header()</span></code></a> reads request headers; the parameter name is
matched with underscores converted to dashes (<code class="docutils literal notranslate"><span class="pre">user_agent</span></code> →
<code class="docutils literal notranslate"><span class="pre">user-agent</span></code>) unless you pass <code class="docutils literal notranslate"><span class="pre">alias=</span></code>.</p></li>
<li><p><a class="reference internal" href="#responder.Cookie" title="responder.Cookie"><code class="xref py py-func docutils literal notranslate"><span class="pre">Cookie()</span></code></a> reads cookies by name (no underscore conversion).</p></li>
<li><p><a class="reference internal" href="#responder.Path" title="responder.Path"><code class="xref py py-func docutils literal notranslate"><span class="pre">Path()</span></code></a> re-validates or renames a path parameter
(<code class="docutils literal notranslate"><span class="pre">Path(...,</span> <span class="pre">alias=&quot;uid&quot;)</span></code>). A path parameter always wins over a same-named
query/header/cookie marker.</p></li>
</ul>
<p>Markers also accept Pydantic field constraints, which are enforced at runtime
(returning <code class="docutils literal notranslate"><span class="pre">422</span></code> on violation) and emitted into the schema, along with
<code class="docutils literal notranslate"><span class="pre">description=</span></code> and <code class="docutils literal notranslate"><span class="pre">deprecated=</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/search&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">search</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span>
<span class="n">q</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Query</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">min_length</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">description</span><span class="o">=</span><span class="s2">&quot;search term&quot;</span><span class="p">),</span>
<span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="n">Query</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="n">ge</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">le</span><span class="o">=</span><span class="mi">100</span><span class="p">)):</span>
<span class="o">...</span>
</pre></div>
</div>
<p>An unknown keyword (a typo such as <code class="docutils literal notranslate"><span class="pre">Query(dafault=5)</span></code>) raises immediately.</p>
<p>Markers may also be written in <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0593/"><strong>PEP 593</strong></a> <code class="docutils literal notranslate"><span class="pre">Annotated</span></code> form, which keeps the
parameter’s default value in the usual slot:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Annotated</span>
<span class="k">def</span><span class="w"> </span><span class="nf">search</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">q</span><span class="p">:</span> <span class="n">Annotated</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Query</span><span class="p">(</span><span class="n">min_length</span><span class="o">=</span><span class="mi">3</span><span class="p">)]</span> <span class="o">=</span> <span class="s2">&quot;all&quot;</span><span class="p">):</span>
<span class="o">...</span>
</pre></div>
</div>
<p>Markers also drive the generated OpenAPI <code class="docutils literal notranslate"><span class="pre">parameters</span></code> and add an automatic
<code class="docutils literal notranslate"><span class="pre">422</span></code> to validating routes. For full request/response validation with
Pydantic models, see <a class="reference internal" href="tutorial-rest.html"><span class="doc">Building a REST API</span></a>.</p>
<section id="file-uploads-and-form-fields">
<h3>File uploads and form fields<a class="headerlink" href="#file-uploads-and-form-fields" title="Link to this heading"></a></h3>
<p><a class="reference internal" href="#responder.File" title="responder.File"><code class="xref py py-func docutils literal notranslate"><span class="pre">File()</span></code></a> injects an uploaded file as an
<code class="xref py py-class docutils literal notranslate"><span class="pre">UploadFile</span></code> (read it with <code class="docutils literal notranslate"><span class="pre">await</span> <span class="pre">f.read()</span></code>, or stream it
in chunks — large uploads are spooled to disk, not held in memory).
<a class="reference internal" href="#responder.Form" title="responder.Form"><code class="xref py py-func docutils literal notranslate"><span class="pre">Form()</span></code></a> injects a form field (urlencoded or multipart),
coerced and validated like <a class="reference internal" href="#responder.Query" title="responder.Query"><code class="xref py py-func docutils literal notranslate"><span class="pre">Query()</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">responder</span><span class="w"> </span><span class="kn">import</span> <span class="n">File</span><span class="p">,</span> <span class="n">Form</span><span class="p">,</span> <span class="n">UploadFile</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/upload&quot;</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;POST&quot;</span><span class="p">])</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">upload</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span>
<span class="n">document</span><span class="p">:</span> <span class="n">UploadFile</span> <span class="o">=</span> <span class="n">File</span><span class="p">(</span><span class="o">...</span><span class="p">),</span>
<span class="n">title</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Form</span><span class="p">(</span><span class="o">...</span><span class="p">),</span>
<span class="n">tags</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="n">Form</span><span class="p">([])):</span>
<span class="n">saved</span> <span class="o">=</span> <span class="k">await</span> <span class="n">document</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="s2">&quot;/srv/uploads/document.bin&quot;</span><span class="p">)</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="n">document</span><span class="o">.</span><span class="n">filename</span><span class="p">,</span> <span class="s2">&quot;path&quot;</span><span class="p">:</span> <span class="nb">str</span><span class="p">(</span><span class="n">saved</span><span class="p">)}</span>
</pre></div>
</div>
<p>A sequence annotation (<code class="docutils literal notranslate"><span class="pre">list[UploadFile]</span></code>) collects multiple files sent under
one field name. These routes generate a <code class="docutils literal notranslate"><span class="pre">multipart/form-data</span></code> (or
<code class="docutils literal notranslate"><span class="pre">application/x-www-form-urlencoded</span></code>) request body in OpenAPI, so the
interactive docs show a file picker. <code class="docutils literal notranslate"><span class="pre">await</span> <span class="pre">req.media(&quot;files&quot;)</span></code> returns the
same <code class="docutils literal notranslate"><span class="pre">UploadFile</span></code> objects keyed by field name.</p>
<p><code class="docutils literal notranslate"><span class="pre">UploadFile.save(path)</span></code> streams the upload to disk and returns the resulting
<code class="docutils literal notranslate"><span class="pre">Path</span></code>. Pass <code class="docutils literal notranslate"><span class="pre">create_parents=True</span></code> to create the parent directory first, or
<code class="docutils literal notranslate"><span class="pre">seek_start=False</span></code> if you intentionally want to save from the file’s current
read position.</p>
</section>
<section id="binding-a-whole-form-to-a-pydantic-model">
<h3>Binding a whole form to a Pydantic model<a class="headerlink" href="#binding-a-whole-form-to-a-pydantic-model" title="Link to this heading"></a></h3>
<p>Instead of one marker per field, a parameter annotated with a Pydantic model
and a <code class="docutils literal notranslate"><span class="pre">Form(...)</span></code> default binds the <em>entire</em> parsed form (urlencoded or
multipart) in one shot — fields are coerced by the model, model defaults
apply, and a validation failure returns the same <code class="docutils literal notranslate"><span class="pre">422</span></code> payload as JSON body
models, with each error located at <code class="docutils literal notranslate"><span class="pre">[&quot;form&quot;,</span> <span class="pre">&lt;field&gt;]</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseModel</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">responder</span><span class="w"> </span><span class="kn">import</span> <span class="n">Form</span>
<span class="k">class</span><span class="w"> </span><span class="nc">ProfileForm</span><span class="p">(</span><span class="n">BaseModel</span><span class="p">):</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">age</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">tags</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span> <span class="c1"># repeated form keys collect into lists</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/profiles&quot;</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;POST&quot;</span><span class="p">])</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">profile</span><span class="p">:</span> <span class="n">ProfileForm</span> <span class="o">=</span> <span class="n">Form</span><span class="p">(</span><span class="o">...</span><span class="p">)):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="n">profile</span><span class="o">.</span><span class="n">model_dump</span><span class="p">()</span>
</pre></div>
</div>
<p>Uploaded files bind to model fields declared as <code class="docutils literal notranslate"><span class="pre">UploadFile</span></code> — Pydantic
requires <code class="docutils literal notranslate"><span class="pre">arbitrary_types_allowed</span></code> for that:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">ConfigDict</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">responder</span><span class="w"> </span><span class="kn">import</span> <span class="n">UploadFile</span>
<span class="k">class</span><span class="w"> </span><span class="nc">AvatarForm</span><span class="p">(</span><span class="n">BaseModel</span><span class="p">):</span>
<span class="n">model_config</span> <span class="o">=</span> <span class="n">ConfigDict</span><span class="p">(</span><span class="n">arbitrary_types_allowed</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">avatar</span><span class="p">:</span> <span class="n">UploadFile</span>
</pre></div>
</div>
<p>Field aliases are honored (the form key is the alias), and <code class="docutils literal notranslate"><span class="pre">Form(None)</span></code>
makes the whole model optional: an empty form yields the default instead of a
<code class="docutils literal notranslate"><span class="pre">422</span></code>. Markers — including form models — work identically on class-based
view methods, and <code class="docutils literal notranslate"><span class="pre">Query</span></code>/<code class="docutils literal notranslate"><span class="pre">Header</span></code>/<code class="docutils literal notranslate"><span class="pre">Cookie</span></code>/<code class="docutils literal notranslate"><span class="pre">Path</span></code> markers also
resolve on WebSocket handlers from the handshake request (a validation
failure there closes the socket with code <code class="docutils literal notranslate"><span class="pre">1008</span></code>).</p>
</section>
<section id="explicit-dependencies">
<h3>Explicit dependencies<a class="headerlink" href="#explicit-dependencies" title="Link to this heading"></a></h3>
<p>Use <a class="reference internal" href="#responder.Depends" title="responder.Depends"><code class="xref py py-func docutils literal notranslate"><span class="pre">Depends()</span></code></a> when one route needs a local provider and you
don’t want to register it app-wide with <code class="docutils literal notranslate"><span class="pre">api.dependency</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">responder</span><span class="w"> </span><span class="kn">import</span> <span class="n">Depends</span>
<span class="k">def</span><span class="w"> </span><span class="nf">current_user</span><span class="p">(</span><span class="n">req</span><span class="p">):</span>
<span class="k">return</span> <span class="n">decode_user</span><span class="p">(</span><span class="n">req</span><span class="o">.</span><span class="n">headers</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;Authorization&quot;</span><span class="p">))</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/me&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">me</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">user</span><span class="o">=</span><span class="n">Depends</span><span class="p">(</span><span class="n">current_user</span><span class="p">)):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;user&quot;</span><span class="p">:</span> <span class="n">user</span><span class="p">}</span>
</pre></div>
</div>
<p>The provider follows the same rules as registered dependencies: it may be sync,
async, a generator, or an async generator, and it may receive the current
request or registered dependencies.</p>
<p>Use <code class="docutils literal notranslate"><span class="pre">dependencies=[Depends(...)]</span></code> when a dependency is a guard or setup step
and the handler does not need its return value. It participates in
dependency registration/caching, sub-dependency resolution, and generator
teardown:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">require_user</span><span class="p">(</span><span class="n">req</span><span class="p">):</span>
<span class="k">if</span> <span class="s2">&quot;Authorization&quot;</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">req</span><span class="o">.</span><span class="n">headers</span><span class="p">:</span>
<span class="n">responder</span><span class="o">.</span><span class="n">abort</span><span class="p">(</span><span class="mi">401</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Not authenticated&quot;</span><span class="p">)</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/private&quot;</span><span class="p">,</span> <span class="n">dependencies</span><span class="o">=</span><span class="p">[</span><span class="n">Depends</span><span class="p">(</span><span class="n">require_user</span><span class="p">)])</span>
<span class="k">def</span><span class="w"> </span><span class="nf">private</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;ok&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
</pre></div>
</div>
<p>Use <code class="docutils literal notranslate"><span class="pre">before=</span></code> / <code class="docutils literal notranslate"><span class="pre">after=</span></code> for raw route hooks: imperative code that should
run around the handler without entering the dependency graph. Hooks may
short-circuit by setting <code class="docutils literal notranslate"><span class="pre">resp.status_code</span></code> and are best for request/response
mutation or simple guards that do not need dependency caching, sub-dependencies,
OpenAPI security integration, or generator teardown:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">require_json</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">req</span><span class="o">.</span><span class="n">is_json</span><span class="p">:</span>
<span class="n">resp</span><span class="o">.</span><span class="n">status_code</span> <span class="o">=</span> <span class="mi">415</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;error&quot;</span><span class="p">:</span> <span class="s2">&quot;JSON required&quot;</span><span class="p">}</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/events&quot;</span><span class="p">,</span> <span class="n">before</span><span class="o">=</span><span class="n">require_json</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">events</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">headers</span>
</pre></div>
</div>
<p>The three paths are intentionally distinct:</p>
<ul class="simple">
<li><p>Handler parameters with <code class="docutils literal notranslate"><span class="pre">Depends(...)</span></code> resolve a value and pass it into the
handler.</p></li>
<li><p>Route <code class="docutils literal notranslate"><span class="pre">dependencies=[Depends(...)]</span></code> resolve graph-aware providers for their
side effects and ignore the return value.</p></li>
<li><p>Route <code class="docutils literal notranslate"><span class="pre">before=</span></code> / <code class="docutils literal notranslate"><span class="pre">after=</span></code> hooks are raw hooks; they are not dependency
providers.</p></li>
</ul>
<p>Execution order for a route is:</p>
<ol class="arabic simple">
<li><p>Global <code class="docutils literal notranslate"><span class="pre">before_request</span></code> hooks</p></li>
<li><p>Per-route <code class="docutils literal notranslate"><span class="pre">before</span></code> hooks</p></li>
<li><p>Per-route auth helpers</p></li>
<li><p>Route validation/input parsing</p></li>
<li><p>Side-effect <code class="docutils literal notranslate"><span class="pre">dependencies</span></code></p></li>
<li><p>Handler view(s)</p></li>
<li><p>Response-model validation</p></li>
<li><p>Per-route and global <code class="docutils literal notranslate"><span class="pre">after</span></code> hooks</p></li>
</ol>
<dl class="py function">
<dt class="sig sig-object py" id="responder.Query">
<span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">Query</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">Ellipsis</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/params.html#Query"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Query" title="Link to this definition"></a></dt>
<dd><p>Mark a parameter as coming from the query string.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="responder.Header">
<span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">Header</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">Ellipsis</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/params.html#Header"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Header" title="Link to this definition"></a></dt>
<dd><p>Mark a parameter as coming from a request header (<code class="docutils literal notranslate"><span class="pre">_</span></code> → <code class="docutils literal notranslate"><span class="pre">-</span></code> by default).</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="responder.Cookie">
<span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">Cookie</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">Ellipsis</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/params.html#Cookie"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Cookie" title="Link to this definition"></a></dt>
<dd><p>Mark a parameter as coming from a request cookie.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="responder.Path">
<span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">Path</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">Ellipsis</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/params.html#Path"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Path" title="Link to this definition"></a></dt>
<dd><p>Mark a parameter as coming from a path parameter.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="responder.Form">
<span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">Form</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">Ellipsis</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/params.html#Form"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Form" title="Link to this definition"></a></dt>
<dd><p>Mark a parameter as a form field (urlencoded or multipart body).</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="responder.File">
<span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">File</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">Ellipsis</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/params.html#File"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.File" title="Link to this definition"></a></dt>
<dd><p>Mark a parameter as an uploaded file; injects an <code class="docutils literal notranslate"><span class="pre">UploadFile</span></code> (or a
<code class="docutils literal notranslate"><span class="pre">list</span></code> of them for a sequence annotation).</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="responder.Depends">
<span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">Depends</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">provider</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/params.html#Depends"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Depends" title="Link to this definition"></a></dt>
<dd><p>Inject the value returned by <code class="docutils literal notranslate"><span class="pre">provider</span></code> into a handler parameter.</p>
<p>Unlike named <code class="docutils literal notranslate"><span class="pre">api.dependency(...)</span></code> providers, <code class="docutils literal notranslate"><span class="pre">Depends</span></code> is local to one
handler and does not require registration on the app.</p>
</dd></dl>
</section>
</section>
<section id="route-groups">
<h2>Route Groups<a class="headerlink" href="#route-groups" title="Link to this heading"></a></h2>
<p>Group related routes under a shared URL prefix — useful for API versioning
and organizing large applications:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">v1</span> <span class="o">=</span> <span class="n">api</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="s2">&quot;/v1&quot;</span><span class="p">)</span>
<span class="nd">@v1</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/users&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">list_users</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">[]</span>
</pre></div>
</div>
<dl class="py class">
<dt class="sig sig-object py" id="responder.api.RouteGroup">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.api.</span></span><span class="sig-name descname"><span class="pre">RouteGroup</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">api</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">prefix</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#RouteGroup"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.api.RouteGroup" title="Link to this definition"></a></dt>
<dd><p>A group of routes with a shared URL prefix.</p>
<p>Before-request hooks registered on a group only run for requests whose
path falls under the group’s prefix.</p>
<dl class="py method">
<dt class="sig sig-object py" id="responder.api.RouteGroup.before_request">
<span class="sig-name descname"><span class="pre">before_request</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">websocket</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#RouteGroup.before_request"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.api.RouteGroup.before_request" title="Link to this definition"></a></dt>
<dd><p>Register a hook that runs before requests under this group’s prefix.</p>
</dd></dl>
</dd></dl>
</section>
<section id="standalone-routers">
<h2>Standalone Routers<a class="headerlink" href="#standalone-routers" title="Link to this heading"></a></h2>
<p><a class="reference internal" href="#responder.Router" title="responder.Router"><code class="xref py py-class docutils literal notranslate"><span class="pre">responder.Router</span></code></a> records route declarations without an <code class="docutils literal notranslate"><span class="pre">API</span></code>
instance, so routes can live in separate modules (like Flask blueprints)
and be attached later — with prefix composition, nesting, and group-level
<code class="docutils literal notranslate"><span class="pre">tags</span></code> / <code class="docutils literal notranslate"><span class="pre">dependencies</span></code> / <code class="docutils literal notranslate"><span class="pre">auth</span></code>. See <a class="reference internal" href="routers.html"><span class="doc">Composing Apps with Routers</span></a> for the guide.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">responder</span><span class="w"> </span><span class="kn">import</span> <span class="n">Router</span>
<span class="n">router</span> <span class="o">=</span> <span class="n">Router</span><span class="p">(</span><span class="n">prefix</span><span class="o">=</span><span class="s2">&quot;/users&quot;</span><span class="p">,</span> <span class="n">tags</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;users&quot;</span><span class="p">])</span>
<span class="nd">@router</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/{user_id:int}&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">get_user</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">user_id</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;id&quot;</span><span class="p">:</span> <span class="n">user_id</span><span class="p">}</span>
<span class="n">api</span><span class="o">.</span><span class="n">include_router</span><span class="p">(</span><span class="n">router</span><span class="p">,</span> <span class="n">prefix</span><span class="o">=</span><span class="s2">&quot;/v1&quot;</span><span class="p">)</span>
</pre></div>
</div>
<dl class="py class">
<dt class="sig sig-object py" id="responder.Router">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">Router</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prefix</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tags</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Iterable</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dependencies</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">auth</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">&lt;object</span> <span class="pre">object&gt;</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/routing.html#Router"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router" title="Link to this definition"></a></dt>
<dd><p>A standalone, composable collection of route declarations.</p>
<p>Unlike <code class="docutils literal notranslate"><span class="pre">api.group()</span></code>, a <code class="docutils literal notranslate"><span class="pre">Router</span></code> needs no <a class="reference internal" href="#responder.API" title="responder.API"><code class="xref py py-class docutils literal notranslate"><span class="pre">API</span></code></a> at
creation: it records declarations and replays them when included, so routes
can be declared in separate modules without circular imports:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># users.py</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">responder</span><span class="w"> </span><span class="kn">import</span> <span class="n">Router</span>
<span class="n">router</span> <span class="o">=</span> <span class="n">Router</span><span class="p">(</span><span class="n">prefix</span><span class="o">=</span><span class="s2">&quot;/users&quot;</span><span class="p">,</span> <span class="n">tags</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;users&quot;</span><span class="p">])</span>
<span class="nd">@router</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/{user_id:int}&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">get_user</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">user_id</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;id&quot;</span><span class="p">:</span> <span class="n">user_id</span><span class="p">}</span>
<span class="c1"># app.py</span>
<span class="n">api</span><span class="o">.</span><span class="n">include_router</span><span class="p">(</span><span class="n">users</span><span class="o">.</span><span class="n">router</span><span class="p">,</span> <span class="n">prefix</span><span class="o">=</span><span class="s2">&quot;/v1&quot;</span><span class="p">)</span> <span class="c1"># GET /v1/users/{user_id}</span>
</pre></div>
</div>
<p>Routers nest via <a class="reference internal" href="#responder.Router.include_router" title="responder.Router.include_router"><code class="xref py py-meth docutils literal notranslate"><span class="pre">include_router()</span></code></a>; prefixes compose, <code class="docutils literal notranslate"><span class="pre">tags</span></code> merge
(group tags first, duplicates dropped), <code class="docutils literal notranslate"><span class="pre">dependencies</span></code> concatenate (group
guards run first), and the innermost explicit <code class="docutils literal notranslate"><span class="pre">auth</span></code> wins. Inclusion is a
snapshot: routes declared after a router has been included are not picked up
by that earlier inclusion.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>prefix</strong> – URL prefix for every route in this router (e.g. <code class="docutils literal notranslate"><span class="pre">&quot;/users&quot;</span></code>).</p></li>
<li><p><strong>tags</strong> – OpenAPI tags applied to every route in this router.</p></li>
<li><p><strong>dependencies</strong> – <code class="docutils literal notranslate"><span class="pre">Depends(...)</span></code> guards run before every route in this
router.</p></li>
<li><p><strong>auth</strong> – Auth helper(s) required by every route in this router
(individual routes may still override with their own <code class="docutils literal notranslate"><span class="pre">auth=</span></code>).</p></li>
</ul>
</dd>
</dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Router.add_route">
<span class="sig-name descname"><span class="pre">add_route</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">endpoint</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tags</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Iterable</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dependencies</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">auth</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">&lt;object</span> <span class="pre">object&gt;</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">before_request</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">websocket</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">**options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">None</span></span></span><a class="reference internal" href="_modules/responder/routing.html#Router.add_route"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router.add_route" title="Link to this definition"></a></dt>
<dd><p>Record a route declaration (imperative form of <a class="reference internal" href="#responder.Router.route" title="responder.Router.route"><code class="xref py py-meth docutils literal notranslate"><span class="pre">route()</span></code></a>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Router.before_request">
<span class="sig-name descname"><span class="pre">before_request</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">websocket</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span></span></span><a class="reference internal" href="_modules/responder/routing.html#Router.before_request"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router.before_request" title="Link to this definition"></a></dt>
<dd><p>Record a before-request hook scoped to this router’s mounted prefix.</p>
<p>Works both bare and called (<code class="docutils literal notranslate"><span class="pre">&#64;router.before_request</span></code> or
<code class="docutils literal notranslate"><span class="pre">&#64;router.before_request()</span></code>). Once included, the hook only runs for
request paths under the prefix the router was mounted at; if the
composed prefix is empty, it runs for every request.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>websocket</strong> – If <code class="docutils literal notranslate"><span class="pre">True</span></code>, register as a WebSocket hook instead of
HTTP.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Router.delete">
<span class="sig-name descname"><span class="pre">delete</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span></span></span><a class="reference internal" href="_modules/responder/routing.html#Router.delete"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router.delete" title="Link to this definition"></a></dt>
<dd><p>Record a <code class="docutils literal notranslate"><span class="pre">DELETE</span></code> route (sugar for <code class="docutils literal notranslate"><span class="pre">route(methods=[&quot;DELETE&quot;])</span></code>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Router.get">
<span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span></span></span><a class="reference internal" href="_modules/responder/routing.html#Router.get"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router.get" title="Link to this definition"></a></dt>
<dd><p>Record a <code class="docutils literal notranslate"><span class="pre">GET</span></code> route (sugar for <code class="docutils literal notranslate"><span class="pre">route(methods=[&quot;GET&quot;])</span></code>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Router.head">
<span class="sig-name descname"><span class="pre">head</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span></span></span><a class="reference internal" href="_modules/responder/routing.html#Router.head"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router.head" title="Link to this definition"></a></dt>
<dd><p>Record a <code class="docutils literal notranslate"><span class="pre">HEAD</span></code> route (sugar for <code class="docutils literal notranslate"><span class="pre">route(methods=[&quot;HEAD&quot;])</span></code>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Router.include_router">
<span class="sig-name descname"><span class="pre">include_router</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">router</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#responder.Router" title="responder.routing.Router"><span class="pre">Router</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">prefix</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tags</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Iterable</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dependencies</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">auth</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">&lt;object</span> <span class="pre">object&gt;</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">None</span></span></span><a class="reference internal" href="_modules/responder/routing.html#Router.include_router"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router.include_router" title="Link to this definition"></a></dt>
<dd><p>Nest another router’s declarations under this one.</p>
<p>The child’s declarations are copied at call time (a snapshot): routes
added to the child afterwards are not seen. Prefixes compose, <code class="docutils literal notranslate"><span class="pre">tags</span></code>
merge, <code class="docutils literal notranslate"><span class="pre">dependencies</span></code> concatenate, and a child route’s own <code class="docutils literal notranslate"><span class="pre">auth</span></code>
wins over the values given here.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>router</strong> – The <a class="reference internal" href="#responder.Router" title="responder.Router"><code class="xref py py-class docutils literal notranslate"><span class="pre">Router</span></code></a> to include.</p></li>
<li><p><strong>prefix</strong> – Extra URL prefix, prepended to the child’s own prefix.</p></li>
<li><p><strong>tags</strong> – OpenAPI tags to merge into the included routes.</p></li>
<li><p><strong>dependencies</strong> – <code class="docutils literal notranslate"><span class="pre">Depends(...)</span></code> guards prepended to the included
routes’ dependencies.</p></li>
<li><p><strong>auth</strong> – Auth helper(s) for included routes that don’t set their own.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Router.ndjson">
<span class="sig-name descname"><span class="pre">ndjson</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</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">item_model</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span></span></span><a class="reference internal" href="_modules/responder/routing.html#Router.ndjson"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router.ndjson" title="Link to this definition"></a></dt>
<dd><p>Record a typed newline-delimited JSON route.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Router.options">
<span class="sig-name descname"><span class="pre">options</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span></span></span><a class="reference internal" href="_modules/responder/routing.html#Router.options"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router.options" title="Link to this definition"></a></dt>
<dd><p>Record an <code class="docutils literal notranslate"><span class="pre">OPTIONS</span></code> route (sugar for <code class="docutils literal notranslate"><span class="pre">route(methods=[&quot;OPTIONS&quot;])</span></code>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Router.patch">
<span class="sig-name descname"><span class="pre">patch</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span></span></span><a class="reference internal" href="_modules/responder/routing.html#Router.patch"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router.patch" title="Link to this definition"></a></dt>
<dd><p>Record a <code class="docutils literal notranslate"><span class="pre">PATCH</span></code> route (sugar for <code class="docutils literal notranslate"><span class="pre">route(methods=[&quot;PATCH&quot;])</span></code>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Router.post">
<span class="sig-name descname"><span class="pre">post</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span></span></span><a class="reference internal" href="_modules/responder/routing.html#Router.post"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router.post" title="Link to this definition"></a></dt>
<dd><p>Record a <code class="docutils literal notranslate"><span class="pre">POST</span></code> route (sugar for <code class="docutils literal notranslate"><span class="pre">route(methods=[&quot;POST&quot;])</span></code>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Router.put">
<span class="sig-name descname"><span class="pre">put</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span></span></span><a class="reference internal" href="_modules/responder/routing.html#Router.put"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router.put" title="Link to this definition"></a></dt>
<dd><p>Record a <code class="docutils literal notranslate"><span class="pre">PUT</span></code> route (sugar for <code class="docutils literal notranslate"><span class="pre">route(methods=[&quot;PUT&quot;])</span></code>).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Router.route">
<span class="sig-name descname"><span class="pre">route</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tags</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Iterable</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dependencies</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">auth</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">&lt;object</span> <span class="pre">object&gt;</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">**options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span></span></span><a class="reference internal" href="_modules/responder/routing.html#Router.route"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router.route" title="Link to this definition"></a></dt>
<dd><p>Decorator recording a route declaration; matches <code class="docutils literal notranslate"><span class="pre">API.route()</span></code>.</p>
<p>All keyword options (<code class="docutils literal notranslate"><span class="pre">methods=</span></code>, <code class="docutils literal notranslate"><span class="pre">response_model=</span></code>, <code class="docutils literal notranslate"><span class="pre">summary=</span></code>,
…) are stored and replayed through <code class="docutils literal notranslate"><span class="pre">API.route()</span></code> at inclusion time.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Router.sse">
<span class="sig-name descname"><span class="pre">sse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</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">event_model</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">heartbeat</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span></span></span><a class="reference internal" href="_modules/responder/routing.html#Router.sse"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router.sse" title="Link to this definition"></a></dt>
<dd><p>Record a typed Server-Sent Events route.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.Router.websocket_route">
<span class="sig-name descname"><span class="pre">websocket_route</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">route</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span></span></span><a class="reference internal" href="_modules/responder/routing.html#Router.websocket_route"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Router.websocket_route" title="Link to this definition"></a></dt>
<dd><p>Record a WebSocket route (sugar for <code class="docutils literal notranslate"><span class="pre">route(websocket=True)</span></code>).</p>
</dd></dl>
</dd></dl>
</section>
<section id="route-local-hooks-and-auth">
<h2>Route-Local Hooks and Auth<a class="headerlink" href="#route-local-hooks-and-auth" title="Link to this heading"></a></h2>
<p>Use global <code class="docutils literal notranslate"><span class="pre">before_request</span></code> / <code class="docutils literal notranslate"><span class="pre">after_request</span></code> hooks for behavior that
applies to the whole app. For behavior that belongs to one endpoint, pass
<code class="docutils literal notranslate"><span class="pre">before=</span></code> and <code class="docutils literal notranslate"><span class="pre">after=</span></code> to the route decorator:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">require_json</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">req</span><span class="o">.</span><span class="n">is_json</span><span class="p">:</span>
<span class="n">resp</span><span class="o">.</span><span class="n">status_code</span> <span class="o">=</span> <span class="mi">415</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;error&quot;</span><span class="p">:</span> <span class="s2">&quot;JSON required&quot;</span><span class="p">}</span>
<span class="k">def</span><span class="w"> </span><span class="nf">add_audit_header</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s2">&quot;X-Audited&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;1&quot;</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/events&quot;</span><span class="p">,</span> <span class="n">before</span><span class="o">=</span><span class="n">require_json</span><span class="p">,</span> <span class="n">after</span><span class="o">=</span><span class="n">add_audit_header</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">events</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="k">await</span> <span class="n">req</span><span class="o">.</span><span class="n">media</span><span class="p">()</span>
</pre></div>
</div>
<p>Authentication helpers from <code class="xref py py-mod docutils literal notranslate"><span class="pre">responder.ext.auth</span></code> can be attached directly
with <code class="docutils literal notranslate"><span class="pre">auth=</span></code>. Responder enforces the scheme, registers OpenAPI security when
OpenAPI is enabled, stores the principal on <code class="docutils literal notranslate"><span class="pre">req.state.user</span></code> /
<code class="docutils literal notranslate"><span class="pre">req.state.auth</span></code>, and injects it into a <code class="docutils literal notranslate"><span class="pre">user</span></code>, <code class="docutils literal notranslate"><span class="pre">principal</span></code>, or <code class="docutils literal notranslate"><span class="pre">auth</span></code>
handler parameter:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">responder.ext.auth</span><span class="w"> </span><span class="kn">import</span> <span class="n">BearerAuth</span>
<span class="n">bearer</span> <span class="o">=</span> <span class="n">BearerAuth</span><span class="p">(</span><span class="n">tokens</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;s3cret&quot;</span><span class="p">])</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/me&quot;</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">bearer</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">me</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">user</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;user&quot;</span><span class="p">:</span> <span class="n">user</span><span class="p">}</span>
</pre></div>
</div>
<p>Use <code class="docutils literal notranslate"><span class="pre">API(auth=bearer)</span></code> when most routes share the same auth scheme. Routes
inherit the app auth by default; pass <code class="docutils literal notranslate"><span class="pre">auth=None</span></code> on public routes such as
<code class="docutils literal notranslate"><span class="pre">/login</span></code> or <code class="docutils literal notranslate"><span class="pre">/health</span></code>.</p>
<p>Use <code class="docutils literal notranslate"><span class="pre">api.policy(name,</span> <span class="pre">auth)</span></code> to give a reusable auth requirement an
application-facing name while keeping the wrapped scheme’s runtime and OpenAPI
behavior unchanged:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">admin</span> <span class="o">=</span> <span class="n">api</span><span class="o">.</span><span class="n">policy</span><span class="p">(</span><span class="s2">&quot;admin&quot;</span><span class="p">,</span> <span class="n">bearer</span><span class="o">.</span><span class="n">requires</span><span class="p">(</span><span class="s2">&quot;admin&quot;</span><span class="p">))</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/admin&quot;</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">admin</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">admin_dashboard</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">user</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;user&quot;</span><span class="p">:</span> <span class="n">user</span><span class="p">}</span>
</pre></div>
</div>
<p>Use <code class="docutils literal notranslate"><span class="pre">auth.optional()</span></code> when credentials should be accepted but not required.
Missing credentials inject <code class="docutils literal notranslate"><span class="pre">None</span></code> into <code class="docutils literal notranslate"><span class="pre">user</span></code> / <code class="docutils literal notranslate"><span class="pre">principal</span></code> / <code class="docutils literal notranslate"><span class="pre">auth</span></code>;
invalid credentials still return <code class="docutils literal notranslate"><span class="pre">401</span></code>. OpenAPI documents both anonymous and
authenticated access:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">optional</span> <span class="o">=</span> <span class="n">bearer</span><span class="o">.</span><span class="n">optional</span><span class="p">()</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/maybe&quot;</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">optional</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">maybe</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">user</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;user&quot;</span><span class="p">:</span> <span class="n">user</span><span class="p">}</span>
</pre></div>
</div>
<p>Use <code class="docutils literal notranslate"><span class="pre">auth.requires(...)</span></code> or <code class="docutils literal notranslate"><span class="pre">ScopedAuth</span></code> when a route needs lightweight
scope or role checks after authentication. Scopes are read from a principal’s
<code class="docutils literal notranslate"><span class="pre">scopes</span></code> or <code class="docutils literal notranslate"><span class="pre">roles</span></code> attribute/key, either as a space-delimited string or an
iterable. Missing scopes return <code class="docutils literal notranslate"><span class="pre">403</span></code> and OpenAPI security requirements include
the required scopes:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">admin</span> <span class="o">=</span> <span class="n">bearer</span><span class="o">.</span><span class="n">requires</span><span class="p">(</span><span class="s2">&quot;items:write&quot;</span><span class="p">)</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/items&quot;</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">admin</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">create_item</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">user</span><span class="p">):</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;user&quot;</span><span class="p">:</span> <span class="n">user</span><span class="p">}</span>
</pre></div>
</div>
</section>
<section id="background-queue">
<h2>Background Queue<a class="headerlink" href="#background-queue" title="Link to this heading"></a></h2>
<p>Run tasks in background threads without blocking the response. Available
as <code class="docutils literal notranslate"><span class="pre">api.background</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/submit&quot;</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">submit</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="n">data</span> <span class="o">=</span> <span class="k">await</span> <span class="n">req</span><span class="o">.</span><span class="n">media</span><span class="p">()</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">background</span><span class="o">.</span><span class="n">task</span>
<span class="k">def</span><span class="w"> </span><span class="nf">process</span><span class="p">(</span><span class="n">data</span><span class="p">):</span>
<span class="c1"># runs in a thread pool</span>
<span class="o">...</span>
<span class="n">process</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="n">resp</span><span class="o">.</span><span class="n">media</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;accepted&quot;</span><span class="p">}</span>
</pre></div>
</div>
<dl class="py class">
<dt class="sig sig-object py" id="responder.background.BackgroundQueue">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.background.</span></span><span class="sig-name descname"><span class="pre">BackgroundQueue</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">n</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="reference internal" href="_modules/responder/background.html#BackgroundQueue"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.background.BackgroundQueue" title="Link to this definition"></a></dt>
<dd><p>A queue for running tasks in background threads.</p>
<p>Uses a <code class="docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code> sized to the number of CPUs. Access it
via <code class="docutils literal notranslate"><span class="pre">api.background</span></code>.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># As a decorator — fire and forget</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">background</span><span class="o">.</span><span class="n">task</span>
<span class="k">def</span><span class="w"> </span><span class="nf">send_email</span><span class="p">(</span><span class="n">to</span><span class="p">,</span> <span class="n">subject</span><span class="p">):</span>
<span class="o">...</span>
<span class="n">send_email</span><span class="p">(</span><span class="s2">&quot;user@example.com&quot;</span><span class="p">,</span> <span class="s2">&quot;Hello&quot;</span><span class="p">)</span>
<span class="c1"># Async functions work too — run via ``asyncio.run`` on the worker</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">background</span><span class="o">.</span><span class="n">task</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">refresh_cache</span><span class="p">():</span>
<span class="o">...</span>
<span class="c1"># Direct submission</span>
<span class="n">future</span> <span class="o">=</span> <span class="n">api</span><span class="o">.</span><span class="n">background</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">send_email</span><span class="p">,</span> <span class="s2">&quot;user@example.com&quot;</span><span class="p">,</span> <span class="s2">&quot;Hello&quot;</span><span class="p">)</span>
<span class="c1"># As a callable (supports async functions)</span>
<span class="k">await</span> <span class="n">api</span><span class="o">.</span><span class="n">background</span><span class="p">(</span><span class="n">send_email</span><span class="p">,</span> <span class="s2">&quot;user@example.com&quot;</span><span class="p">,</span> <span class="s2">&quot;Hello&quot;</span><span class="p">)</span>
</pre></div>
</div>
<dl class="py method">
<dt class="sig sig-object py" id="responder.background.BackgroundQueue.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">f</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/background.html#BackgroundQueue.run"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.background.BackgroundQueue.run" title="Link to this definition"></a></dt>
<dd><p>Submit a function to run in a background thread.</p>
<p>Async functions are supported: they are driven to completion on the
worker thread via <code class="docutils literal notranslate"><span class="pre">asyncio.run</span></code> (previously they silently produced a
never-awaited coroutine and the job never ran).</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>f</strong> – The function to run.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>A <code class="docutils literal notranslate"><span class="pre">concurrent.futures.Future</span></code> for the result.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.background.BackgroundQueue.shutdown">
<span class="sig-name descname"><span class="pre">shutdown</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">wait</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/background.html#BackgroundQueue.shutdown"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.background.BackgroundQueue.shutdown" title="Link to this definition"></a></dt>
<dd><p>Stop accepting new tasks and, by default, drain in-flight ones.</p>
<p>Called automatically at application shutdown so fire-and-forget tasks
submitted via <a class="reference internal" href="#responder.background.BackgroundQueue.run" title="responder.background.BackgroundQueue.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a>/<a class="reference internal" href="#responder.background.BackgroundQueue.task" title="responder.background.BackgroundQueue.task"><code class="xref py py-meth docutils literal notranslate"><span class="pre">task()</span></code></a> are given a chance to finish
rather than being abandoned when the process exits.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>wait</strong> – Block until running tasks complete (default <code class="docutils literal notranslate"><span class="pre">True</span></code>).</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.background.BackgroundQueue.task">
<span class="sig-name descname"><span class="pre">task</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">f</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/background.html#BackgroundQueue.task"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.background.BackgroundQueue.task" title="Link to this definition"></a></dt>
<dd><p>Decorator that wraps a function to run in the background thread pool.</p>
<p>The decorated function returns a <code class="docutils literal notranslate"><span class="pre">Future</span></code> instead of blocking.
Exceptions are printed to stderr via traceback.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>f</strong> – The function to wrap.</p>
</dd>
</dl>
</dd></dl>
</dd></dl>
</section>
<section id="query-dict">
<h2>Query Dict<a class="headerlink" href="#query-dict" title="Link to this heading"></a></h2>
<p>A dictionary subclass for query string parameters with multi-value support.
Behaves like a normal dict for single values, but supports <code class="docutils literal notranslate"><span class="pre">getlist()</span></code>
for parameters that appear multiple times (e.g. <code class="docutils literal notranslate"><span class="pre">?tag=a&amp;tag=b</span></code>).</p>
<dl class="py class">
<dt class="sig sig-object py" id="responder.models.QueryDict">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.models.</span></span><span class="sig-name descname"><span class="pre">QueryDict</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">query_string</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#QueryDict"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.models.QueryDict" title="Link to this definition"></a></dt>
<dd><p>A dictionary for query string parameters that handles multi-value keys.</p>
<p>Single-value access returns the last value for a key. Use <a class="reference internal" href="#responder.models.QueryDict.get_list" title="responder.models.QueryDict.get_list"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_list()</span></code></a>
to retrieve all values for a multi-value parameter.</p>
<dl class="py method">
<dt class="sig sig-object py" id="responder.models.QueryDict.get">
<span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</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="reference internal" href="_modules/responder/models.html#QueryDict.get"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.models.QueryDict.get" title="Link to this definition"></a></dt>
<dd><p>Return the last data value for the passed key. If key doesn’t exist
or value is an empty list, return <cite>default</cite>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.models.QueryDict.get_list">
<span class="sig-name descname"><span class="pre">get_list</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</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="reference internal" href="_modules/responder/models.html#QueryDict.get_list"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.models.QueryDict.get_list" title="Link to this definition"></a></dt>
<dd><p>Return the list of values for the key. If key doesn’t exist, return a
default value.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.models.QueryDict.items">
<span class="sig-name descname"><span class="pre">items</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#QueryDict.items"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.models.QueryDict.items" title="Link to this definition"></a></dt>
<dd><p>Yield (key, value) pairs, where value is the last item in the list
associated with the key.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.models.QueryDict.items_list">
<span class="sig-name descname"><span class="pre">items_list</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#QueryDict.items_list"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.models.QueryDict.items_list" title="Link to this definition"></a></dt>
<dd><p>Yield (key, value) pairs, where value is the the list.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.models.QueryDict.setdefault">
<span class="sig-name descname"><span class="pre">setdefault</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</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="reference internal" href="_modules/responder/models.html#QueryDict.setdefault"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.models.QueryDict.setdefault" title="Link to this definition"></a></dt>
<dd><p>Like <code class="docutils literal notranslate"><span class="pre">dict.setdefault</span></code>, but stores scalars via <code class="xref py py-meth docutils literal notranslate"><span class="pre">__setitem__()</span></code>
so single-value reads return them unchanged.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.models.QueryDict.update">
<span class="sig-name descname"><span class="pre">update</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</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="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#QueryDict.update"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.models.QueryDict.update" title="Link to this definition"></a></dt>
<dd><p>Update from a mapping/iterable and keyword args, storing scalar
values via <code class="xref py py-meth docutils literal notranslate"><span class="pre">__setitem__()</span></code> (lists are stored as-is). Merging
from another <a class="reference internal" href="#responder.models.QueryDict" title="responder.models.QueryDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">QueryDict</span></code></a> copies each key’s full stored
list, so multi-value parameters survive intact.</p>
</dd></dl>
</dd></dl>
</section>
<section id="headers-dict">
<h2>Headers Dict<a class="headerlink" href="#headers-dict" title="Link to this heading"></a></h2>
<p>The case-insensitive (case-preserving) mapping behind <code class="docutils literal notranslate"><span class="pre">req.headers</span></code> and
<code class="docutils literal notranslate"><span class="pre">resp.headers</span></code>. Lookups match header names case-insensitively; on request
headers, single-value access returns the last value received for a repeated
header, while <code class="docutils literal notranslate"><span class="pre">get_list()</span></code> returns every raw line, in order:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">hops</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">headers</span><span class="o">.</span><span class="n">get_list</span><span class="p">(</span><span class="s2">&quot;X-Forwarded-For&quot;</span><span class="p">)</span>
<span class="c1"># [&quot;203.0.113.7&quot;, &quot;198.51.100.2&quot;] — one entry per proxy hop</span>
</pre></div>
</div>
<dl class="py class">
<dt class="sig sig-object py" id="responder.models.CaseInsensitiveDict">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.models.</span></span><span class="sig-name descname"><span class="pre">CaseInsensitiveDict</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/models.html#CaseInsensitiveDict"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.models.CaseInsensitiveDict" title="Link to this definition"></a></dt>
<dd><p>A case-insensitive, case-preserving dict for HTTP headers.</p>
<p>Lookups, membership tests, deletion, and updates match keys
case-insensitively, while iteration preserves the casing each key was
last set with — so <code class="docutils literal notranslate"><span class="pre">d[&quot;content-type&quot;]</span> <span class="pre">=</span> <span class="pre">...</span></code> replaces an existing
<code class="docutils literal notranslate"><span class="pre">Content-Type</span></code> entry rather than adding a second one.</p>
<p>HTTP allows the same header name to appear on multiple lines; when the
mapping is built from such raw pairs (as <code class="docutils literal notranslate"><span class="pre">req.headers</span></code> is), single-value
access returns the last value while <a class="reference internal" href="#responder.models.CaseInsensitiveDict.get_list" title="responder.models.CaseInsensitiveDict.get_list"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_list()</span></code></a> returns every value,
in the order received.</p>
<dl class="py method">
<dt class="sig sig-object py" id="responder.models.CaseInsensitiveDict.get_list">
<span class="sig-name descname"><span class="pre">get_list</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Any</span></span></span><a class="reference internal" href="_modules/responder/models.html#CaseInsensitiveDict.get_list"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.models.CaseInsensitiveDict.get_list" title="Link to this definition"></a></dt>
<dd><p>Return every value received for <code class="docutils literal notranslate"><span class="pre">key</span></code>, in order.</p>
<p>HTTP permits a header to appear on multiple lines (proxies append
separate <code class="docutils literal notranslate"><span class="pre">X-Forwarded-For</span></code>/<code class="docutils literal notranslate"><span class="pre">Via</span></code> lines; HTTP/2 clients may split
headers similarly), and single-value access returns only the last
one. This returns them all, in the order they arrived. A missing key
returns <code class="docutils literal notranslate"><span class="pre">default</span></code> (or <code class="docutils literal notranslate"><span class="pre">[]</span></code> when no default is given).</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">hops</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">headers</span><span class="o">.</span><span class="n">get_list</span><span class="p">(</span><span class="s2">&quot;X-Forwarded-For&quot;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
</dd></dl>
</section>
<section id="rate-limiter">
<h2>Rate Limiter<a class="headerlink" href="#rate-limiter" title="Link to this heading"></a></h2>
<p>Sliding-window rate limiter (fixed-window with the Redis backends). Limits
requests per client IP address — or per anything, via <code class="docutils literal notranslate"><span class="pre">key=</span></code> — and returns
<code class="docutils literal notranslate"><span class="pre">429</span> <span class="pre">Too</span> <span class="pre">Many</span> <span class="pre">Requests</span></code> when exceeded:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">responder.ext.ratelimit</span><span class="w"> </span><span class="kn">import</span> <span class="n">RateLimiter</span>
<span class="n">limiter</span> <span class="o">=</span> <span class="n">RateLimiter</span><span class="p">(</span><span class="n">requests</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">period</span><span class="o">=</span><span class="mi">60</span><span class="p">)</span> <span class="c1"># 100 req/min</span>
<span class="n">limiter</span><span class="o">.</span><span class="n">install</span><span class="p">(</span><span class="n">api</span><span class="p">)</span>
</pre></div>
</div>
<p>Response headers: <code class="docutils literal notranslate"><span class="pre">X-RateLimit-Limit</span></code>, <code class="docutils literal notranslate"><span class="pre">X-RateLimit-Remaining</span></code>,
<code class="docutils literal notranslate"><span class="pre">X-RateLimit-Reset</span></code> (seconds until the window resets), and <code class="docutils literal notranslate"><span class="pre">Retry-After</span></code>
(when limited).</p>
<p>Pass <code class="docutils literal notranslate"><span class="pre">key=</span></code> (a <code class="docutils literal notranslate"><span class="pre">req</span> <span class="pre">-&gt;</span> <span class="pre">str</span></code> callable) to bucket by API key or user
instead of client IP, and <code class="docutils literal notranslate"><span class="pre">fail_open=True</span></code> to let requests through with a
warning when the backend is unreachable (the default answers <code class="docutils literal notranslate"><span class="pre">503</span></code>).</p>
<p>The in-memory backend is per-process. For multi-worker or distributed deploys,
pass a shared store via <code class="docutils literal notranslate"><span class="pre">backend=</span></code> —
<code class="xref py py-class docutils literal notranslate"><span class="pre">RedisBackend</span></code> (sync) or
<code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncRedisBackend</span></code> (async, via
<code class="docutils literal notranslate"><span class="pre">redis.asyncio</span></code>):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">responder.ext.ratelimit</span><span class="w"> </span><span class="kn">import</span> <span class="n">RateLimiter</span><span class="p">,</span> <span class="n">AsyncRedisBackend</span>
<span class="n">limiter</span> <span class="o">=</span> <span class="n">RateLimiter</span><span class="p">(</span><span class="n">requests</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">period</span><span class="o">=</span><span class="mi">60</span><span class="p">,</span> <span class="n">backend</span><span class="o">=</span><span class="n">AsyncRedisBackend</span><span class="p">())</span>
</pre></div>
</div>
<dl class="py class">
<dt class="sig sig-object py" id="responder.ext.ratelimit.RateLimiter">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.ext.ratelimit.</span></span><span class="sig-name descname"><span class="pre">RateLimiter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">requests</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">100</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">period</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">60</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">backend</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">trust_proxy_headers</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">key</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">fail_open</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/ext/ratelimit.html#RateLimiter"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.ext.ratelimit.RateLimiter" title="Link to this definition"></a></dt>
<dd><p>Per-client request rate limiter.</p>
<p>The limiting algorithm depends on the backend: <code class="xref py py-class docutils literal notranslate"><span class="pre">MemoryBackend</span></code>
(the default) is a sliding window over the last <code class="docutils literal notranslate"><span class="pre">period</span></code> seconds,
while <code class="xref py py-class docutils literal notranslate"><span class="pre">RedisBackend</span></code>/<code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncRedisBackend</span></code> count within
fixed windows.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">responder.ext.ratelimit</span><span class="w"> </span><span class="kn">import</span> <span class="n">RateLimiter</span>
<span class="n">limiter</span> <span class="o">=</span> <span class="n">RateLimiter</span><span class="p">(</span><span class="n">requests</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">period</span><span class="o">=</span><span class="mi">60</span><span class="p">)</span> <span class="c1"># 100 req/min</span>
<span class="n">limiter</span><span class="o">.</span><span class="n">install</span><span class="p">(</span><span class="n">api</span><span class="p">)</span>
</pre></div>
</div>
<p>Enforcement can also be hand-rolled in a before-request hook when you
need custom logic around it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="n">before_request</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">rate_limit</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="n">limiter</span><span class="o">.</span><span class="n">check</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">)</span>
</pre></div>
</div>
<p>Prefer <a class="reference internal" href="#responder.ext.ratelimit.RateLimiter.install" title="responder.ext.ratelimit.RateLimiter.install"><code class="xref py py-meth docutils literal notranslate"><span class="pre">install()</span></code></a> (or <a class="reference internal" href="#responder.ext.ratelimit.RateLimiter.limit" title="responder.ext.ratelimit.RateLimiter.limit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">limit()</span></code></a>) when you don’t: they enforce
the same way, but a manual <code class="docutils literal notranslate"><span class="pre">check()</span></code> call is invisible to the OpenAPI
generator, so the schema won’t document the <code class="docutils literal notranslate"><span class="pre">429</span></code>/<code class="docutils literal notranslate"><span class="pre">503</span></code> responses.</p>
<p>To rate-limit a single route, apply <a class="reference internal" href="#responder.ext.ratelimit.RateLimiter.limit" title="responder.ext.ratelimit.RateLimiter.limit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">limit()</span></code></a> beneath <code class="docutils literal notranslate"><span class="pre">&#64;api.route</span></code>.
Give each route its own <code class="docutils literal notranslate"><span class="pre">RateLimiter</span></code> for an independent budget:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">expensive_limiter</span> <span class="o">=</span> <span class="n">RateLimiter</span><span class="p">(</span><span class="n">requests</span><span class="o">=</span><span class="mi">5</span><span class="p">,</span> <span class="n">period</span><span class="o">=</span><span class="mi">60</span><span class="p">)</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/expensive&quot;</span><span class="p">)</span>
<span class="nd">@expensive_limiter</span><span class="o">.</span><span class="n">limit</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">expensive</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="o">...</span>
</pre></div>
</div>
<dl class="py method">
<dt class="sig sig-object py" id="responder.ext.ratelimit.RateLimiter.acheck">
<span class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">acheck</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">req</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">resp</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/ext/ratelimit.html#RateLimiter.acheck"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.ext.ratelimit.RateLimiter.acheck" title="Link to this definition"></a></dt>
<dd><p>Check the rate limit, awaiting an async backend (or off-loading a
sync one to a thread). Works with any backend.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.ext.ratelimit.RateLimiter.check">
<span class="sig-name descname"><span class="pre">check</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">req</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">resp</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/ext/ratelimit.html#RateLimiter.check"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.ext.ratelimit.RateLimiter.check" title="Link to this definition"></a></dt>
<dd><p>Check the rate limit synchronously. Sets a <code class="docutils literal notranslate"><span class="pre">429</span></code> if exceeded.</p>
<p>Requires a sync backend (<code class="docutils literal notranslate"><span class="pre">hit</span></code>); use <a class="reference internal" href="#responder.ext.ratelimit.RateLimiter.acheck" title="responder.ext.ratelimit.RateLimiter.acheck"><code class="xref py py-meth docutils literal notranslate"><span class="pre">acheck()</span></code></a> for async-only
backends.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.ext.ratelimit.RateLimiter.install">
<span class="sig-name descname"><span class="pre">install</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">api</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/ext/ratelimit.html#RateLimiter.install"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.ext.ratelimit.RateLimiter.install" title="Link to this definition"></a></dt>
<dd><p>Install as a before_request hook on the API (async, any backend).</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="responder.ext.ratelimit.RateLimiter.limit">
<span class="sig-name descname"><span class="pre">limit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">f</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/ext/ratelimit.html#RateLimiter.limit"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.ext.ratelimit.RateLimiter.limit" title="Link to this definition"></a></dt>
<dd><p>Decorator that rate-limits a single route handler.</p>
<p>Apply beneath <code class="docutils literal notranslate"><span class="pre">&#64;api.route()</span></code>. When the limit is exceeded, the
handler is skipped and a 429 response is returned. Works on both
function views <code class="docutils literal notranslate"><span class="pre">(req,</span> <span class="pre">resp)</span></code> and class-based-view methods
<code class="docutils literal notranslate"><span class="pre">(self,</span> <span class="pre">req,</span> <span class="pre">resp)</span></code> — the request/response are located by type
among the positional arguments, so a bound method’s leading <code class="docutils literal notranslate"><span class="pre">self</span></code>
does not shift them.</p>
</dd></dl>
</dd></dl>
</section>
<section id="status-code-helpers">
<h2>Status Code Helpers<a class="headerlink" href="#status-code-helpers" title="Link to this heading"></a></h2>
<p>Convenience functions for checking which category a status code falls
into. Useful in middleware and after-request hooks:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">responder.status_codes</span><span class="w"> </span><span class="kn">import</span> <span class="n">is_200</span><span class="p">,</span> <span class="n">is_400</span><span class="p">,</span> <span class="n">is_500</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">after_request</span><span class="p">()</span>
<span class="k">def</span><span class="w"> </span><span class="nf">log_errors</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="k">if</span> <span class="n">is_400</span><span class="p">(</span><span class="n">resp</span><span class="o">.</span><span class="n">status_code</span><span class="p">)</span> <span class="ow">or</span> <span class="n">is_500</span><span class="p">(</span><span class="n">resp</span><span class="o">.</span><span class="n">status_code</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Error: </span><span class="si">{</span><span class="n">req</span><span class="o">.</span><span class="n">method</span><span class="si">}</span><span class="s2"> </span><span class="si">{</span><span class="n">req</span><span class="o">.</span><span class="n">url</span><span class="o">.</span><span class="n">path</span><span class="si">}</span><span class="s2"> -&gt; </span><span class="si">{</span><span class="n">resp</span><span class="o">.</span><span class="n">status_code</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
</pre></div>
</div>
<dl class="py function">
<dt class="sig sig-object py" id="responder.status_codes.is_100">
<span class="sig-prename descclassname"><span class="pre">responder.status_codes.</span></span><span class="sig-name descname"><span class="pre">is_100</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">status_code</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/status_codes.html#is_100"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.status_codes.is_100" title="Link to this definition"></a></dt>
<dd></dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="responder.status_codes.is_200">
<span class="sig-prename descclassname"><span class="pre">responder.status_codes.</span></span><span class="sig-name descname"><span class="pre">is_200</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">status_code</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/status_codes.html#is_200"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.status_codes.is_200" title="Link to this definition"></a></dt>
<dd></dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="responder.status_codes.is_300">
<span class="sig-prename descclassname"><span class="pre">responder.status_codes.</span></span><span class="sig-name descname"><span class="pre">is_300</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">status_code</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/status_codes.html#is_300"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.status_codes.is_300" title="Link to this definition"></a></dt>
<dd></dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="responder.status_codes.is_400">
<span class="sig-prename descclassname"><span class="pre">responder.status_codes.</span></span><span class="sig-name descname"><span class="pre">is_400</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">status_code</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/status_codes.html#is_400"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.status_codes.is_400" title="Link to this definition"></a></dt>
<dd></dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="responder.status_codes.is_500">
<span class="sig-prename descclassname"><span class="pre">responder.status_codes.</span></span><span class="sig-name descname"><span class="pre">is_500</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">status_code</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/status_codes.html#is_500"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.status_codes.is_500" title="Link to this definition"></a></dt>
<dd></dd></dl>
</section>
<section id="errors-and-exceptions">
<h2>Errors and Exceptions<a class="headerlink" href="#errors-and-exceptions" title="Link to this heading"></a></h2>
<p>Use <a class="reference internal" href="#responder.abort" title="responder.abort"><code class="xref py py-func docutils literal notranslate"><span class="pre">abort()</span></code></a> to short-circuit a request with a rendered HTTP
error from anywhere in a handler, hook, or dependency — no Starlette import
required. Unlike setting <code class="docutils literal notranslate"><span class="pre">resp.status_code</span></code>, it halts the handler:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">responder</span><span class="w"> </span><span class="kn">import</span> <span class="n">abort</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/admin&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">admin</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">req</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;is_admin&quot;</span><span class="p">):</span>
<span class="n">abort</span><span class="p">(</span><span class="mi">403</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Forbidden&quot;</span><span class="p">)</span>
</pre></div>
</div>
<dl class="py function">
<dt class="sig sig-object py" id="responder.abort">
<span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">abort</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">status_code</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">detail</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">headers</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">title</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">type</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">instance</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">errors</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="o"><span class="pre">**</span></span><span class="n"><span class="pre">extensions</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/api.html#abort"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.abort" title="Link to this definition"></a></dt>
<dd><p>Short-circuit the request with an HTTP error response.</p>
<p>Raises an <code class="docutils literal notranslate"><span class="pre">HTTPException</span></code> that Responder renders (as JSON or text per the
client’s <code class="docutils literal notranslate"><span class="pre">Accept</span></code> header). Use it to bail out from anywhere in a handler
or dependency without importing Starlette directly.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">responder</span><span class="w"> </span><span class="kn">import</span> <span class="n">abort</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/admin&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">admin</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">req</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;is_admin&quot;</span><span class="p">):</span>
<span class="n">abort</span><span class="p">(</span><span class="mi">403</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Forbidden&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>Passing any of the RFC 9457 members — <code class="docutils literal notranslate"><span class="pre">title</span></code>, <code class="docutils literal notranslate"><span class="pre">type</span></code>, <code class="docutils literal notranslate"><span class="pre">instance</span></code>,
<code class="docutils literal notranslate"><span class="pre">errors</span></code>, or extension keywords — raises <a class="reference internal" href="#responder.Problem" title="responder.Problem"><code class="xref py py-class docutils literal notranslate"><span class="pre">Problem</span></code></a>
instead, carrying them into the rendered problem-details payload:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">abort</span><span class="p">(</span>
<span class="mi">409</span><span class="p">,</span>
<span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Plan quota exhausted&quot;</span><span class="p">,</span>
<span class="nb">type</span><span class="o">=</span><span class="s2">&quot;https://api.example.com/errors/quota-exceeded&quot;</span><span class="p">,</span>
<span class="n">balance</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>status_code</strong> – The HTTP status code (e.g. <code class="docutils literal notranslate"><span class="pre">404</span></code>).</p></li>
<li><p><strong>detail</strong> – Optional error message; defaults to the status phrase.</p></li>
<li><p><strong>headers</strong> – Optional dict of headers to attach to the error response.</p></li>
<li><p><strong>title</strong> – Optional problem summary; defaults to the status phrase.</p></li>
<li><p><strong>type</strong> – Optional URI identifying the problem type.</p></li>
<li><p><strong>instance</strong> – Optional URI for this occurrence; defaults to the
request path in the rendered payload.</p></li>
<li><p><strong>errors</strong> – Optional list of structured error dicts.</p></li>
<li><p><strong>extensions</strong> – Extra keyword arguments become top-level extension
members of the problem payload.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<p>For typed problem catalogs, raise <a class="reference internal" href="#responder.Problem" title="responder.Problem"><code class="xref py py-class docutils literal notranslate"><span class="pre">Problem</span></code></a> — an
<code class="docutils literal notranslate"><span class="pre">HTTPException</span></code> subclass carrying the full set of RFC 9457 members
(<code class="docutils literal notranslate"><span class="pre">type</span></code>, <code class="docutils literal notranslate"><span class="pre">title</span></code>, <code class="docutils literal notranslate"><span class="pre">instance</span></code>, and arbitrary extension members) into the
rendered <code class="docutils literal notranslate"><span class="pre">application/problem+json</span></code> payload. It flows through the same
machinery as framework errors, including <code class="docutils literal notranslate"><span class="pre">API(problem_handler=...)</span></code>
enrichment and the app’s JSON encoder:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">responder</span><span class="w"> </span><span class="kn">import</span> <span class="n">Problem</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/quota&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">quota</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="k">raise</span> <span class="n">Problem</span><span class="p">(</span>
<span class="mi">409</span><span class="p">,</span>
<span class="s2">&quot;You have used all 100 requests for today.&quot;</span><span class="p">,</span>
<span class="n">title</span><span class="o">=</span><span class="s2">&quot;Quota Exceeded&quot;</span><span class="p">,</span>
<span class="nb">type</span><span class="o">=</span><span class="s2">&quot;https://api.example.com/errors/quota-exceeded&quot;</span><span class="p">,</span>
<span class="n">balance</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Passing any RFC 9457 member to <a class="reference internal" href="#responder.abort" title="responder.abort"><code class="xref py py-func docutils literal notranslate"><span class="pre">abort()</span></code></a> raises a <code class="docutils literal notranslate"><span class="pre">Problem</span></code>
for you, so <code class="docutils literal notranslate"><span class="pre">abort(409,</span> <span class="pre">type=&quot;...&quot;,</span> <span class="pre">balance=0)</span></code> is equivalent.</p>
<dl class="py class">
<dt class="sig sig-object py" id="responder.Problem">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">Problem</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">status_code</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">detail</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</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">title</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">type</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">instance</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">dict</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">headers</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">dict</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">extensions</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/responder/errors.html#Problem"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.Problem" title="Link to this definition"></a></dt>
<dd><p>A raisable RFC 9457 problem-details error.</p>
<p>Raise it from any view, hook, or dependency to short-circuit the request
with a full <code class="docutils literal notranslate"><span class="pre">application/problem+json</span></code> response, rendered through the
same pipeline as framework errors — content negotiation, API-level
<code class="docutils literal notranslate"><span class="pre">problem_handler</span></code> enrichment, request IDs, and the app’s JSON encoder:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">responder</span><span class="w"> </span><span class="kn">import</span> <span class="n">Problem</span>
<span class="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/quota&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">quota</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">resp</span><span class="p">):</span>
<span class="k">raise</span> <span class="n">Problem</span><span class="p">(</span>
<span class="mi">409</span><span class="p">,</span>
<span class="s2">&quot;You have used all 100 requests for today.&quot;</span><span class="p">,</span>
<span class="n">title</span><span class="o">=</span><span class="s2">&quot;Quota Exceeded&quot;</span><span class="p">,</span>
<span class="nb">type</span><span class="o">=</span><span class="s2">&quot;https://api.example.com/errors/quota-exceeded&quot;</span><span class="p">,</span>
<span class="n">balance</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Because it subclasses Starlette’s <code class="docutils literal notranslate"><span class="pre">HTTPException</span></code>, existing exception
handlers and middleware treat it exactly like <a class="reference internal" href="#responder.abort" title="responder.abort"><code class="xref py py-func docutils literal notranslate"><span class="pre">abort()</span></code></a>.
When <code class="docutils literal notranslate"><span class="pre">instance</span></code> is omitted, the rendered payload defaults it to the
request path per the RFC 9457 recommendation. With
<code class="docutils literal notranslate"><span class="pre">API(problem_details=False)</span></code> the legacy content-negotiated error format
is used instead and only <code class="docutils literal notranslate"><span class="pre">status_code</span></code>/<code class="docutils literal notranslate"><span class="pre">detail</span></code> apply.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>status_code</strong> – The HTTP status code (e.g. <code class="docutils literal notranslate"><span class="pre">409</span></code>).</p></li>
<li><p><strong>detail</strong> – Human-readable explanation of this occurrence; defaults to
the status phrase.</p></li>
<li><p><strong>title</strong> – Short summary of the problem type; defaults to the status
phrase.</p></li>
<li><p><strong>type</strong> – URI identifying the problem type (default <code class="docutils literal notranslate"><span class="pre">about:blank</span></code>).</p></li>
<li><p><strong>instance</strong> – URI for this specific occurrence; defaults to the
request path when rendered.</p></li>
<li><p><strong>errors</strong> – Optional list of structured error dicts (the same shape
validation failures use).</p></li>
<li><p><strong>headers</strong> – Optional dict of headers to attach to the error response.</p></li>
<li><p><strong>extensions</strong> – Any extra keyword arguments become top-level extension
members of the problem payload.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<p>Dependency injection raises the following at request time when a provider graph
is misconfigured — cycles, illegal scopes, or unresolvable parameters. Catch
the base <a class="reference internal" href="#responder.DependencyError" title="responder.DependencyError"><code class="xref py py-class docutils literal notranslate"><span class="pre">DependencyError</span></code></a> to cover all four. (Registration
mistakes, such as a reserved name or a bad scope, raise plain <code class="docutils literal notranslate"><span class="pre">ValueError</span></code>
instead.) See the <a class="reference internal" href="tour.html"><span class="doc">Feature Tour</span></a> for the dependency-injection guide.</p>
<dl class="py exception">
<dt class="sig sig-object py" id="responder.DependencyError">
<span class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">DependencyError</span></span><a class="reference internal" href="_modules/responder/routes.html#DependencyError"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.DependencyError" title="Link to this definition"></a></dt>
<dd><p>Base class for dependency-injection configuration/resolution errors.</p>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py" id="responder.DependencyCycleError">
<span class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">DependencyCycleError</span></span><a class="reference internal" href="_modules/responder/routes.html#DependencyCycleError"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.DependencyCycleError" title="Link to this definition"></a></dt>
<dd><p>A dependency depends on itself (directly or transitively).</p>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py" id="responder.DependencyScopeError">
<span class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">DependencyScopeError</span></span><a class="reference internal" href="_modules/responder/routes.html#DependencyScopeError"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.DependencyScopeError" title="Link to this definition"></a></dt>
<dd><p>An app-scoped dependency illegally depends on the request or a
request-scoped dependency.</p>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py" id="responder.DependencyResolutionError">
<span class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.</span></span><span class="sig-name descname"><span class="pre">DependencyResolutionError</span></span><a class="reference internal" href="_modules/responder/routes.html#DependencyResolutionError"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.DependencyResolutionError" title="Link to this definition"></a></dt>
<dd><p>A dependency parameter is neither the request nor a registered
dependency.</p>
</dd></dl>
<p>The sessions extension raises
<a class="reference internal" href="#responder.ext.sessions.SessionConfigError" title="responder.ext.sessions.SessionConfigError"><code class="xref py py-class docutils literal notranslate"><span class="pre">SessionConfigError</span></code></a> for an unsafe or
contradictory configuration — for example <code class="docutils literal notranslate"><span class="pre">secret_key=&quot;NOTASECRET&quot;</span></code>, or
<code class="docutils literal notranslate"><span class="pre">sessions=True</span></code> with no key set.</p>
<dl class="py exception">
<dt class="sig sig-object py" id="responder.ext.sessions.SessionConfigError">
<span class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">responder.ext.sessions.</span></span><span class="sig-name descname"><span class="pre">SessionConfigError</span></span><a class="reference internal" href="_modules/responder/ext/sessions.html#SessionConfigError"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#responder.ext.sessions.SessionConfigError" title="Link to this definition"></a></dt>
<dd><p>Raised for an unsafe or contradictory session configuration.</p>
</dd></dl>
</section>
<section id="type-aliases">
<h2>Type Aliases<a class="headerlink" href="#type-aliases" title="Link to this heading"></a></h2>
<p>Convenience aliases in <code class="xref py py-mod docutils literal notranslate"><span class="pre">responder.types</span></code> for annotating your own
handlers, hooks, and dependency providers:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">responder.types</span><span class="w"> </span><span class="kn">import</span> <span class="n">Handler</span><span class="p">,</span> <span class="n">Hook</span><span class="p">,</span> <span class="n">Dependency</span>
</pre></div>
</div>
<dl class="py data">
<dt class="sig sig-object py" id="responder.types.Handler">
<span class="sig-prename descclassname"><span class="pre">responder.types.</span></span><span class="sig-name descname"><span class="pre">Handler</span></span><a class="headerlink" href="#responder.types.Handler" title="Link to this definition"></a></dt>
<dd><p>A view handler. Receives <code class="docutils literal notranslate"><span class="pre">(req,</span> <span class="pre">resp,</span> <span class="pre">**extras)</span></code> and may return <code class="docutils literal notranslate"><span class="pre">None</span></code> or
a body value (JSON scalar/<code class="docutils literal notranslate"><span class="pre">dict</span></code>/<code class="docutils literal notranslate"><span class="pre">list</span></code>/<code class="docutils literal notranslate"><span class="pre">str</span></code>/<code class="docutils literal notranslate"><span class="pre">bytes</span></code>/model, or a
Flask-style <code class="docutils literal notranslate"><span class="pre">(body,</span> <span class="pre">status[,</span> <span class="pre">headers])</span></code> tuple). Sync or async.</p>
<p>alias of <code class="xref py py-class docutils literal notranslate"><span class="pre">Callable</span></code>[[…], <code class="xref py py-obj docutils literal notranslate"><span class="pre">Any</span></code>]</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="responder.types.Hook">
<span class="sig-prename descclassname"><span class="pre">responder.types.</span></span><span class="sig-name descname"><span class="pre">Hook</span></span><a class="headerlink" href="#responder.types.Hook" title="Link to this definition"></a></dt>
<dd><p>A before/after-request hook, called <code class="docutils literal notranslate"><span class="pre">(req,</span> <span class="pre">resp)</span></code>. Sync or async.</p>
<p>alias of <code class="xref py py-class docutils literal notranslate"><span class="pre">Callable</span></code>[[<a class="reference internal" href="#responder.Request" title="responder.models.Request"><code class="xref py py-class docutils literal notranslate"><span class="pre">Request</span></code></a>, <a class="reference internal" href="#responder.Response" title="responder.models.Response"><code class="xref py py-class docutils literal notranslate"><span class="pre">Response</span></code></a>], <code class="xref py py-obj docutils literal notranslate"><span class="pre">Any</span></code>]</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="responder.types.Dependency">
<span class="sig-prename descclassname"><span class="pre">responder.types.</span></span><span class="sig-name descname"><span class="pre">Dependency</span></span><a class="headerlink" href="#responder.types.Dependency" title="Link to this definition"></a></dt>
<dd><p>A dependency provider. Called with no arguments or the current <code class="docutils literal notranslate"><span class="pre">Request</span></code>;
may be a function, coroutine, or (async) generator with teardown.</p>
<p>alias of <code class="xref py py-class docutils literal notranslate"><span class="pre">Callable</span></code>[[…], <code class="xref py py-obj docutils literal notranslate"><span class="pre">Any</span></code>]</p>
</dd></dl>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper"><p class="logo">
<a href="index.html">
<img class="logo" src="_static/responder.png" />
</a>
</p>
<p>
<strong>Responder</strong> — a familiar HTTP service framework for Python.
<br />
<small>v9.2.0</small>
</p>
<h3>Useful Links</h3>
<ul>
<li><a href="https://github.com/kennethreitz/responder">Responder @ GitHub</a></li>
<li><a href="https://pypi.org/project/responder/">Responder @ PyPI</a></li>
<li><a href="https://github.com/kennethreitz/responder/issues">Issue Tracker</a></li>
</ul><h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">User Guide</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick Start</a></li>
<li class="toctree-l1"><a class="reference internal" href="tour.html">Feature Tour</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="routers.html">Composing Apps with Routers</a></li>
<li class="toctree-l1"><a class="reference internal" href="guide-config.html">Configuration</a></li>
<li class="toctree-l1"><a class="reference internal" href="clientgen.html">Generated Clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="deployment.html">Deployment</a></li>
<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="tutorial-rest.html">Building a REST API</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-sqlalchemy.html">Using SQLAlchemy</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-auth.html">Authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-websockets.html">WebSocket Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-middleware.html">Writing Middleware</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-flask.html">Migrating from Flask</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Reference</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">API Reference</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#the-api-class">The API Class</a></li>
<li class="toctree-l2"><a class="reference internal" href="#request">Request</a></li>
<li class="toctree-l2"><a class="reference internal" href="#response">Response</a></li>
<li class="toctree-l2"><a class="reference internal" href="#typed-streams">Typed Streams</a></li>
<li class="toctree-l2"><a class="reference internal" href="#parameter-markers">Parameter Markers</a></li>
<li class="toctree-l2"><a class="reference internal" href="#route-groups">Route Groups</a></li>
<li class="toctree-l2"><a class="reference internal" href="#standalone-routers">Standalone Routers</a></li>
<li class="toctree-l2"><a class="reference internal" href="#route-local-hooks-and-auth">Route-Local Hooks and Auth</a></li>
<li class="toctree-l2"><a class="reference internal" href="#background-queue">Background Queue</a></li>
<li class="toctree-l2"><a class="reference internal" href="#query-dict">Query Dict</a></li>
<li class="toctree-l2"><a class="reference internal" href="#headers-dict">Headers Dict</a></li>
<li class="toctree-l2"><a class="reference internal" href="#rate-limiter">Rate Limiter</a></li>
<li class="toctree-l2"><a class="reference internal" href="#status-code-helpers">Status Code Helpers</a></li>
<li class="toctree-l2"><a class="reference internal" href="#errors-and-exceptions">Errors and Exceptions</a></li>
<li class="toctree-l2"><a class="reference internal" href="#type-aliases">Type Aliases</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="cli.html">Command Line Interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="runtime-contracts.html">Runtime Contracts</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Project</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="changes.html">Changelog</a></li>
<li class="toctree-l1"><a class="reference internal" href="migration-v9.html">Migrating to v9</a></li>
<li class="toctree-l1"><a class="reference internal" href="migration-v8.html">Migrating to v8</a></li>
<li class="toctree-l1"><a class="reference internal" href="migration-v7.html">Migrating to v7</a></li>
<li class="toctree-l1"><a class="reference internal" href="migration-v6.html">Migrating to v6</a></li>
<li class="toctree-l1"><a class="reference internal" href="migration-v5.html">Migrating to v5</a></li>
<li class="toctree-l1"><a class="reference internal" href="sandbox.html">Sandbox</a></li>
<li class="toctree-l1"><a class="reference internal" href="backlog.html">Backlog</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="tutorial-flask.html" title="previous chapter">Migrating from Flask</a></li>
<li>Next: <a href="cli.html" title="next chapter">Command Line Interface</a></li>
</ul></li>
</ul>
</div>
<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>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&#169;2018-2026, Kenneth Reitz.
|
<a href="_sources/api.rst.txt"
rel="nofollow">Page source</a>
</div>
<a href="https://github.com/kennethreitz/responder" class="github">
<img src="_static/forkme_right_darkblue.png" alt="Fork me on GitHub" class="github"/>
</a>
</body>
</html>