mirror of
https://github.com/kennethreitz/responder.git
synced 2026-10-24 05:59:12 +00:00
2642 lines
376 KiB
HTML
2642 lines
376 KiB
HTML
<!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 — 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">"My Service"</span><span class="p">,</span> <span class="c1"># OpenAPI title</span>
|
||
<span class="n">version</span><span class="o">=</span><span class="s2">"1.0"</span><span class="p">,</span> <span class="c1"># OpenAPI version</span>
|
||
<span class="n">openapi</span><span class="o">=</span><span class="s2">"3.0.2"</span><span class="p">,</span> <span class="c1"># enable OpenAPI</span>
|
||
<span class="n">docs_route</span><span class="o">=</span><span class="s2">"/docs"</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">"example.com"</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="auto"</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">"import secrets; print(secrets.token_urlsafe(32))"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><code class="docutils literal notranslate"><span class="pre">secret_key="NOTASECRET"</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"><object</span> <span class="pre">object></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">"request"</span></code> (default) or <code class="docutils literal notranslate"><span class="pre">"app"</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">["GET",</span> <span class="pre">"POST"]</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">@api.after_request</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">@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">"X-Request-ID"</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">"Authorization"</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">"error"</span><span class="p">:</span> <span class="s2">"unauthorized"</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">→</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=["DELETE"])</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">"request"</span></code> (default) resolves per request;
|
||
<code class="docutils literal notranslate"><span class="pre">"app"</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">"/users/{id:int}"</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">"app"</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">"/users"</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">"error"</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">"AcmeClient"</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">"clients/acme.py"</span><span class="p">,</span> <span class="n">class_name</span><span class="o">=</span><span class="s2">"AcmeClient"</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">"clients/acme.ts"</span><span class="p">,</span>
|
||
<span class="n">class_name</span><span class="o">=</span><span class="s2">"AcmeClient"</span><span class="p">,</span>
|
||
<span class="n">language</span><span class="o">=</span><span class="s2">"typescript"</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=["GET"])</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">"stranger"</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">"Hello </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">"</span>
|
||
|
||
<span class="n">api</span><span class="o">.</span><span class="n">graphql</span><span class="p">(</span><span class="s2">"/graphql"</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">"/graphql"</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">"/v1"</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">"/users"</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">"/users/{id:int}"</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">"id"</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=["HEAD"])</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"><object</span> <span class="pre">object></span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</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">"http"</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">"X-Response-Time"</span><span class="p">]</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">"</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"</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">"http"</span></code> is supported (the default).
|
||
The decorator may also be applied bare (<code class="docutils literal notranslate"><span class="pre">@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">→</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">'startup'</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">'shutdown'</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=["OPTIONS"])</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=["PATCH"])</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">"/hello"</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">"admin"</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">"admin"</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">"/admin"</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=["POST"])</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=["PUT"])</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">→</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"><object</span> <span class="pre">object></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">"/hello"</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">"hello, world!"</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">"/items"</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">"POST"</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">"id"</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">"/items"</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">"POST"</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">-></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">{"model":</span> <span class="pre">ErrorOut,</span> <span class="pre">"description":</span> <span class="pre">"Not</span> <span class="pre">found"}}</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">"/search"</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">"q"</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">"limit"</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">"Pet"</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">"uvicorn"</span></code> (default) or <code class="docutils literal notranslate"><span class="pre">"granian"</span></code>.</p></li>
|
||
<li><p><strong>port_precedence</strong> – <code class="docutils literal notranslate"><span class="pre">"explicit"</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">"env"</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: "GET", "POST", ...</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">"POST"</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">"Authorization"</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">"X-Forwarded-For"</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Query parameters: /search?q=python&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">"q"</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">"form"</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">"files"</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">"GET"</span></code>, <code class="docutils literal notranslate"><span class="pre">"POST"</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">"GET"</span></code>.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">await</span> <span class="pre">req.media("files")</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">→</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"><input></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"><form</span> <span class="pre">method="post"></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["X-Forwarded-For"]</span></code>) returns the
|
||
last value received for a repeated header; use
|
||
<code class="docutils literal notranslate"><span class="pre">req.headers.get_list("X-Forwarded-For")</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">→</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">→</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">"/"</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">"POST"</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">"GET"</span></code>, <code class="docutils literal notranslate"><span class="pre">"POST"</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">"GET"</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">"application/json"</span><span class="p">,</span> <span class="s2">"text/csv"</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">"/upload"</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">"POST"</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">"wb"</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">"plain text"</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">"<h1>Hello</h1>"</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">"key"</span><span class="p">:</span> <span class="s2">"value"</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">"raw bytes"</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 "../" 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">"reports/q3.pdf"</span><span class="p">,</span> <span class="n">root</span><span class="o">=</span><span class="s2">"exports"</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">"exports/big.csv"</span><span class="p">,</span> <span class="n">root</span><span class="o">=</span><span class="s2">"exports"</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">"X-Custom"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"value"</span>
|
||
<span class="n">resp</span><span class="o">.</span><span class="n">cookies</span><span class="p">[</span><span class="s2">"session"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"abc123"</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">"id"</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">"/items/1"</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">"Already exists"</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">"/dashboard"</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">"/signup"</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">"POST"</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">"ok"</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">"user@example.com"</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">"id"</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">"/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">"</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">"token"</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">→</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">"/"</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">"home.html"</span><span class="p">,</span> <span class="n">user</span><span class="o">=</span><span class="s2">"kenneth"</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">"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"</span></code>).</p></li>
|
||
<li><p><strong>path</strong> – URL path the cookie applies to (default <code class="docutils literal notranslate"><span class="pre">"/"</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">"lax"</span></code> (default), <code class="docutils literal notranslate"><span class="pre">"strict"</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">"none"</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">"token"</span><span class="p">,</span> <span class="n">value</span><span class="o">=</span><span class="s2">"abc123"</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">{"comment":</span> <span class="pre">"..."}</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">"/events"</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">"data"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"n"</span><span class="p">:</span> <span class="n">i</span><span class="p">},</span> <span class="s2">"id"</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">@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">"/stream"</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">"chunk </span><span class="si">{</span><span class="n">i</span><span class="si">}</span><span class="se">\n</span><span class="s2">"</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">"Accept"</span><span class="p">,</span> <span class="s2">"Accept-Language"</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">"progress"</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">"still working"</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">"/search"</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&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">"X-Token"</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">"q"</span><span class="p">:</span> <span class="n">q</span><span class="p">,</span> <span class="s2">"limit"</span><span class="p">:</span> <span class="n">limit</span><span class="p">,</span> <span class="s2">"tags"</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">{"errors":</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="uid")</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">"/search"</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">"search term"</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">"all"</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">"/upload"</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">"POST"</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">"/srv/uploads/document.bin"</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">"name"</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">"path"</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("files")</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">["form",</span> <span class="pre"><field>]</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">"/profiles"</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">"POST"</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">"Authorization"</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">"/me"</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">"user"</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">"Authorization"</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">"Not authenticated"</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">"/private"</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">"ok"</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">"error"</span><span class="p">:</span> <span class="s2">"JSON required"</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">"/events"</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">"/v1"</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">"/users"</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">"/users"</span><span class="p">,</span> <span class="n">tags</span><span class="o">=</span><span class="p">[</span><span class="s2">"users"</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">"/{user_id:int}"</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">"id"</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">"/v1"</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"><object</span> <span class="pre">object></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">"/users"</span><span class="p">,</span> <span class="n">tags</span><span class="o">=</span><span class="p">[</span><span class="s2">"users"</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">"/{user_id:int}"</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">"id"</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">"/v1"</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">"/users"</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"><object</span> <span class="pre">object></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">→</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">→</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">@router.before_request</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">@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">→</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=["DELETE"])</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">→</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=["GET"])</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">→</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=["HEAD"])</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"><object</span> <span class="pre">object></span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</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">→</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">→</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=["OPTIONS"])</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">→</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=["PATCH"])</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">→</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=["POST"])</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">→</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=["PUT"])</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"><object</span> <span class="pre">object></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">→</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">→</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">→</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">"error"</span><span class="p">:</span> <span class="s2">"JSON required"</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">"X-Audited"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"1"</span>
|
||
|
||
<span class="nd">@api</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">"/events"</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">"s3cret"</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">"/me"</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">"user"</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">"admin"</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">"admin"</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">"/admin"</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">"user"</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">"/maybe"</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">"user"</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">"items:write"</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">"/items"</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">"user"</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">"/submit"</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">"status"</span><span class="p">:</span> <span class="s2">"accepted"</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">"user@example.com"</span><span class="p">,</span> <span class="s2">"Hello"</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">"user@example.com"</span><span class="p">,</span> <span class="s2">"Hello"</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">"user@example.com"</span><span class="p">,</span> <span class="s2">"Hello"</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&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">"X-Forwarded-For"</span><span class="p">)</span>
|
||
<span class="c1"># ["203.0.113.7", "198.51.100.2"] — 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["content-type"]</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">→</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">"X-Forwarded-For"</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">-></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">@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">"/expensive"</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">@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">"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"> -> </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">"</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">"/admin"</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">"is_admin"</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">"Forbidden"</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">"/admin"</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">"is_admin"</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">"Forbidden"</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">"Plan quota exhausted"</span><span class="p">,</span>
|
||
<span class="nb">type</span><span class="o">=</span><span class="s2">"https://api.example.com/errors/quota-exceeded"</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">"/quota"</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">"You have used all 100 requests for today."</span><span class="p">,</span>
|
||
<span class="n">title</span><span class="o">=</span><span class="s2">"Quota Exceeded"</span><span class="p">,</span>
|
||
<span class="nb">type</span><span class="o">=</span><span class="s2">"https://api.example.com/errors/quota-exceeded"</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="...",</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">"/quota"</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">"You have used all 100 requests for today."</span><span class="p">,</span>
|
||
<span class="n">title</span><span class="o">=</span><span class="s2">"Quota Exceeded"</span><span class="p">,</span>
|
||
<span class="nb">type</span><span class="o">=</span><span class="s2">"https://api.example.com/errors/quota-exceeded"</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="NOTASECRET"</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">
|
||
©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> |