Files
responder/index.html
2026-07-17 21:00:53 +00:00

566 lines
44 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Responder &#8212; responder 9.2.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=5ecbeea2" />
<link rel="stylesheet" type="text/css" href="_static/basic.css?v=b08954a9" />
<link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=eb4102c5" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
<link rel="stylesheet" type="text/css" href="_static/sphinx-design.min.css?v=95c83b7e" />
<link rel="stylesheet" type="text/css" href="_static/design-elements.e5416f61bae5d36adc6d722a2b6f8cff.css?v=452a8e97" />
<script src="_static/documentation_options.js?v=e8b940be"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="_static/clipboard.min.js?v=a7894cd8"></script>
<script src="_static/copybutton.js?v=fd10adb8"></script>
<script>
</script>
<script src="_static/design-tabs.js?v=f930bc37"></script>
<script src="_static/design-elements.bbdccc18c4abea9397628f9fea3d48c2.js?v=03c7770e"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Quick Start" href="quickstart.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="responder">
<h1>Responder<a class="headerlink" href="#responder" title="Link to this heading"></a></h1>
<p><a class="reference external" href="https://pypi.org/project/responder/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/responder.svg" /></a> <a class="reference external" href="https://pypi.org/project/responder/"><img alt="Supported Python versions" src="https://img.shields.io/pypi/pyversions/responder.svg" /></a> <a class="reference external" href="https://pypi.org/project/responder/"><img alt="License" src="https://img.shields.io/pypi/l/responder.svg" /></a></p>
<p><strong>Web services for humans.</strong></p>
<p>A familiar HTTP Service Framework for Python — everything you need,
in a single import.</p>
<div class="highlight-python 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="nd">@api</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s2">&quot;/</span><span class="si">{greeting}</span><span class="s2">&quot;</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">greet_world</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">greeting</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="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">greeting</span><span class="si">}</span><span class="s2">, world!&quot;</span>
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">&quot;__main__&quot;</span><span class="p">:</span>
<span class="n">api</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
</pre></div>
</div>
<p>Powered by <a class="reference external" href="https://www.starlette.io/">Starlette</a>, <a class="reference external" href="https://www.uvicorn.org/">uvicorn</a>, and good intentions. The <code class="docutils literal notranslate"><span class="pre">async</span></code> is optional.</p>
<div class="sd-container-fluid sd-sphinx-override sd-mb-4 docutils">
<div class="sd-row sd-row-cols-2 sd-row-cols-xs-2 sd-row-cols-sm-2 sd-row-cols-md-2 sd-row-cols-lg-2 sd-g-3 sd-g-xs-3 sd-g-sm-3 sd-g-md-3 sd-g-lg-3 docutils">
<div class="sd-col sd-d-flex-column docutils">
<p><span class="sd-d-grid"><a class="sd-sphinx-override sd-btn sd-text-wrap sd-btn-primary sd-shadow-sm reference internal" href="quickstart.html"><span class="doc">Get started in five minutes</span></a></span></p>
</div>
<div class="sd-col sd-d-flex-column docutils">
<p><span class="sd-d-grid"><a class="sd-sphinx-override sd-btn sd-text-wrap sd-btn-secondary reference internal" href="tour.html"><span class="doc">Take the tour</span></a></span></p>
</div>
</div>
</div>
<p>It’s all in the box:</p>
<div class="sd-container-fluid sd-sphinx-override sd-mb-4 docutils">
<div class="sd-row sd-row-cols-1 sd-row-cols-xs-1 sd-row-cols-sm-2 sd-row-cols-md-3 sd-row-cols-lg-3 sd-g-2 sd-g-xs-2 sd-g-sm-2 sd-g-md-2 sd-g-lg-2 docutils">
<div class="sd-col sd-d-flex-row docutils">
<div class="sd-card sd-sphinx-override sd-w-100 sd-shadow-sm sd-card-hover docutils">
<div class="sd-card-body docutils">
<div class="sd-card-title sd-font-weight-bold docutils">
Validation</div>
<p class="sd-card-text">Pydantic models in, typed responses out.</p>
</div>
<a class="sd-stretched-link sd-hide-link-text reference internal" href="tutorial-rest.html#tutorial-rest-models"><span class="std std-ref">Define Your Models</span></a></div>
</div>
<div class="sd-col sd-d-flex-row docutils">
<div class="sd-card sd-sphinx-override sd-w-100 sd-shadow-sm sd-card-hover docutils">
<div class="sd-card-body docutils">
<div class="sd-card-title sd-font-weight-bold docutils">
WebSockets</div>
<p class="sd-card-text">Real-time and bidirectional. Built in.</p>
</div>
<a class="sd-stretched-link sd-hide-link-text reference internal" href="tutorial-websockets.html"><span class="doc">WebSocket Tutorial</span></a></div>
</div>
<div class="sd-col sd-d-flex-row docutils">
<div class="sd-card sd-sphinx-override sd-w-100 sd-shadow-sm sd-card-hover docutils">
<div class="sd-card-body docutils">
<div class="sd-card-title sd-font-weight-bold docutils">
Typed streams</div>
<p class="sd-card-text">Validated SSE and NDJSON, all the way to generated clients.</p>
</div>
<a class="sd-stretched-link sd-hide-link-text reference internal" href="tour.html"><span class="doc">Feature Tour</span></a></div>
</div>
<div class="sd-col sd-d-flex-row docutils">
<div class="sd-card sd-sphinx-override sd-w-100 sd-shadow-sm sd-card-hover docutils">
<div class="sd-card-body docutils">
<div class="sd-card-title sd-font-weight-bold docutils">
Content negotiation</div>
<p class="sd-card-text">JSON, YAML, or MessagePack — chosen automatically.</p>
</div>
<a class="sd-stretched-link sd-hide-link-text reference internal" href="tour.html#tour-content-negotiation"><span class="std std-ref">Content Negotiation</span></a></div>
</div>
<div class="sd-col sd-d-flex-row docutils">
<div class="sd-card sd-sphinx-override sd-w-100 sd-shadow-sm sd-card-hover docutils">
<div class="sd-card-body docutils">
<div class="sd-card-title sd-font-weight-bold docutils">
OpenAPI</div>
<p class="sd-card-text">A schema from your type hints, plus Swagger UI.</p>
</div>
<a class="sd-stretched-link sd-hide-link-text reference internal" href="tour.html#tour-openapi"><span class="std std-ref">OpenAPI Documentation</span></a></div>
</div>
<div class="sd-col sd-d-flex-row docutils">
<div class="sd-card sd-sphinx-override sd-w-100 sd-shadow-sm sd-card-hover docutils">
<div class="sd-card-body docutils">
<div class="sd-card-title sd-font-weight-bold docutils">
Sessions</div>
<p class="sd-card-text">Signed by default. Server-side when you need it.</p>
</div>
<a class="sd-stretched-link sd-hide-link-text reference internal" href="guide-config.html#guide-config-sessions"><span class="std std-ref">Sessions</span></a></div>
</div>
<div class="sd-col sd-d-flex-row docutils">
<div class="sd-card sd-sphinx-override sd-w-100 sd-shadow-sm sd-card-hover docutils">
<div class="sd-card-body docutils">
<div class="sd-card-title sd-font-weight-bold docutils">
Rate limiting</div>
<p class="sd-card-text">Throttle requests, with <code class="docutils literal notranslate"><span class="pre">X-RateLimit</span></code> headers.</p>
</div>
<a class="sd-stretched-link sd-hide-link-text reference internal" href="tour.html#tour-rate-limiting"><span class="std std-ref">Rate Limiting</span></a></div>
</div>
</div>
</div>
<section id="the-idea">
<h2>The Idea<a class="headerlink" href="#the-idea" title="Link to this heading"></a></h2>
<p>If you’ve ever used <a class="reference external" href="https://flask.palletsprojects.com/">Flask</a>, the routing will look familiar. If you’ve
used <a class="reference external" href="https://falconframework.org/">Falcon</a>, the request/response pattern will click immediately. And
if you’ve used <a class="reference external" href="https://requests.readthedocs.io/">Requests</a> — well, you’ll feel right at home.</p>
<p>Responder takes these ideas and brings them together. Every view receives
a request and a response. You can read from one and write to the other, or
return a body directly. No special response classes, no boilerplate.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">resp.text</span></code> sends text. <code class="docutils literal notranslate"><span class="pre">resp.html</span></code> sends HTML. <code class="docutils literal notranslate"><span class="pre">resp.media</span></code> sends JSON.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">resp.file(&quot;path&quot;)</span></code> serves a file. <code class="docutils literal notranslate"><span class="pre">resp.content</span></code> sends raw bytes.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">req.headers</span></code> is case-insensitive. <code class="docutils literal notranslate"><span class="pre">req.params</span></code> holds query parameters.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">resp.status_code</span></code>, <code class="docutils literal notranslate"><span class="pre">req.method</span></code> (<code class="docutils literal notranslate"><span class="pre">&quot;GET&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;POST&quot;</span></code>), <code class="docutils literal notranslate"><span class="pre">req.url</span></code> — the familiar ones.</p></li>
</ul>
<p>Set <code class="docutils literal notranslate"><span class="pre">resp.media</span></code> to a dict and the right thing happens. If the client
asks for YAML, it gets YAML. Content negotiation is automatic.</p>
<p>Responder and <a class="reference external" href="https://fastapi.tiangolo.com/">FastAPI</a> are siblings — both built on Starlette, both
born around the same time, both part of the push that made ASGI the
future of Python web services. FastAPI went deep on type annotations
and automatic validation. Responder went for simplicity and a mutable
request/response pattern. Both projects are better for the other
existing. Use whichever feels right.</p>
<p>This is a passion project. It exists because building a web framework
from scratch is one of the best ways to understand how the web works.
It’s a great fit for personal projects, prototyping, teaching, research,
and anyone who values a clean API over a sprawling ecosystem. If you
need battle-tested infrastructure at scale, FastAPI and Django will
serve you well. If you want something small, expressive, and fun to
work with — welcome.</p>
</section>
<section id="what-you-get">
<h2>What You Get<a class="headerlink" href="#what-you-get" title="Link to this heading"></a></h2>
<p>One <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span></code>, batteries included:</p>
<ul class="simple">
<li><p>Pydantic request validation and typed response models.</p></li>
<li><p>Typed parameter injection: <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>, and <code class="docutils literal notranslate"><span class="pre">Path</span></code>.</p></li>
<li><p>Composable dependency injection with automatic teardown.</p></li>
<li><p>Mount Flask, Django, or any WSGI/ASGI app at a subroute.</p></li>
<li><p>Gzip compression, HSTS, CORS, and trusted host validation.</p></li>
<li><p>Before-request and after-request hooks for auth and logging.</p></li>
<li><p>A test client for fast, in-process testing with pytest.</p></li>
<li><p>Route parameters with f-string syntax and type convertors.</p></li>
<li><p>Lifespan context managers for startup and shutdown logic.</p></li>
<li><p>Custom exception handlers for clean error responses.</p></li>
<li><p><a class="reference external" href="https://graphql.org/">GraphQL</a> with Graphene and a built-in GraphiQL IDE.</p></li>
<li><p>Server-Sent Events for real-time streaming.</p></li>
<li><p>File serving with automatic content-type detection.</p></li>
<li><p>Sync and async views — <code class="docutils literal notranslate"><span class="pre">async</span></code> is always optional.</p></li>
<li><p>Class-based views with <code class="docutils literal notranslate"><span class="pre">on_get</span></code>, <code class="docutils literal notranslate"><span class="pre">on_post</span></code>, <code class="docutils literal notranslate"><span class="pre">on_request</span></code>.</p></li>
<li><p>Built-in rate limiting with <code class="docutils literal notranslate"><span class="pre">X-RateLimit</span></code> headers.</p></li>
<li><p>Structured logging with per-request context.</p></li>
<li><p>Content negotiation: JSON, YAML, and MessagePack.</p></li>
<li><p>A pleasant API with a single import statement.</p></li>
<li><p>OpenAPI schema generated from your type hints, with Swagger UI.</p></li>
<li><p>Python, JavaScript, TypeScript, Ruby, and PHP clients generated from OpenAPI.</p></li>
<li><p>A production <a class="reference external" href="https://www.uvicorn.org/">uvicorn</a> or <a class="reference external" href="https://github.com/emmett-framework/granian">Granian</a> server, ready to deploy.</p></li>
<li><p>Route groups and standalone, composable routers for API versioning.</p></li>
<li><p>Secure-by-default signed sessions, with optional server-side backends.</p></li>
<li><p>Background tasks in a thread pool.</p></li>
<li><p>WebSocket support.</p></li>
</ul>
<p>Each of these gets its own treatment in the <a class="reference internal" href="tour.html"><span class="doc">Feature Tour</span></a>.</p>
</section>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Link to this heading"></a></h2>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>uv<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span><span class="s1">&#39;responder[orjson]&#39;</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">orjson</span></code> extra is the recommended default on standard GIL-enabled
CPython and is used automatically for faster JSON response encoding. On
free-threaded CPython (<code class="docutils literal notranslate"><span class="pre">3.14t</span></code>/<code class="docutils literal notranslate"><span class="pre">3.15t</span></code>), install the base <code class="docutils literal notranslate"><span class="pre">responder</span></code>
package instead; the standard-library encoder remains a transparent fallback.</p>
<p>Install <code class="docutils literal notranslate"><span class="pre">responder[orjson,server]</span></code> when you want the optional Granian
production server alongside the default uvicorn runner.</p>
<p>Python 3.11 and above. That’s it.</p>
<div class="toctree-wrapper compound">
<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><ul>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#create-a-web-service">Create a Web Service</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#hello-world">Hello World</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#run-the-server">Run the Server</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#route-parameters">Route Parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#sending-responses">Sending Responses</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#reading-requests">Reading Requests</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#rendering-templates">Rendering Templates</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#background-tasks">Background Tasks</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#putting-it-all-together">Putting It All Together</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tour.html">Feature Tour</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tour.html#method-filtering">Method Filtering</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#returning-values">Returning Values</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#class-based-views">Class-Based Views</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#lifespan-events">Lifespan Events</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#dependency-injection">Dependency Injection</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#serving-files">Serving Files</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#conditional-requests">Conditional Requests</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#after-response-tasks">After-Response Tasks</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#custom-error-handling">Custom Error Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#before-request-hooks">Before-Request Hooks</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#after-request-hooks">After-Request Hooks</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#websocket-support">WebSocket Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#server-sent-events-sse">Server-Sent Events (SSE)</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#graphql">GraphQL</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#openapi-documentation">OpenAPI Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#route-groups">Route Groups</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#mounting-other-apps">Mounting Other Apps</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#cookies">Cookies</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#cookie-based-sessions">Cookie-Based Sessions</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#static-files">Static Files</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#csrf-protection">CSRF Protection</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#cors">CORS</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#hsts">HSTS</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#security-headers">Security Headers</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#trusted-hosts">Trusted Hosts</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#authentication">Authentication</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#request-id">Request ID</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#request-size-limits">Request Size Limits</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#request-timeouts">Request Timeouts</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#rate-limiting">Rate Limiting</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#metrics">Metrics</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#health-checks">Health Checks</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#structured-logging">Structured Logging</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#pydantic-validation">Pydantic Validation</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#pagination">Pagination</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#content-negotiation">Content Negotiation</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#faster-json-with-orjson">Faster JSON with orjson</a></li>
<li class="toctree-l2"><a class="reference internal" href="tour.html#messagepack">MessagePack</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a><ul>
<li class="toctree-l2"><a class="reference internal" href="examples.html#running-an-example">Running an Example</a></li>
<li class="toctree-l2"><a class="reference internal" href="examples.html#where-to-start">Where to Start</a></li>
<li class="toctree-l2"><a class="reference internal" href="examples.html#focused-patterns">Focused Patterns</a></li>
<li class="toctree-l2"><a class="reference internal" href="examples.html#testing-examples">Testing Examples</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="routers.html">Composing Apps with Routers</a><ul>
<li class="toctree-l2"><a class="reference internal" href="routers.html#declaring-routes-in-a-module">Declaring Routes in a Module</a></li>
<li class="toctree-l2"><a class="reference internal" href="routers.html#nesting-routers">Nesting Routers</a></li>
<li class="toctree-l2"><a class="reference internal" href="routers.html#group-defaults-tags-dependencies-auth">Group Defaults: Tags, Dependencies, Auth</a></li>
<li class="toctree-l2"><a class="reference internal" href="routers.html#including-a-router-twice">Including a Router Twice</a></li>
<li class="toctree-l2"><a class="reference internal" href="routers.html#routers-vs-api-group">Routers vs. <code class="docutils literal notranslate"><span class="pre">api.group()</span></code></a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="guide-config.html">Configuration</a><ul>
<li class="toctree-l2"><a class="reference internal" href="guide-config.html#environment-variables">Environment Variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="guide-config.html#using-env-files">Using .env Files</a></li>
<li class="toctree-l2"><a class="reference internal" href="guide-config.html#configuration-class-pattern">Configuration Class Pattern</a></li>
<li class="toctree-l2"><a class="reference internal" href="guide-config.html#secret-key">Secret Key</a></li>
<li class="toctree-l2"><a class="reference internal" href="guide-config.html#sessions">Sessions</a></li>
<li class="toctree-l2"><a class="reference internal" href="guide-config.html#debug-mode">Debug Mode</a></li>
<li class="toctree-l2"><a class="reference internal" href="guide-config.html#allowed-hosts">Allowed Hosts</a></li>
<li class="toctree-l2"><a class="reference internal" href="guide-config.html#putting-it-all-together">Putting It All Together</a></li>
</ul>
</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><ul>
<li class="toctree-l2"><a class="reference internal" href="deployment.html#running-locally">Running Locally</a></li>
<li class="toctree-l2"><a class="reference internal" href="deployment.html#docker">Docker</a></li>
<li class="toctree-l2"><a class="reference internal" href="deployment.html#cloud-platforms">Cloud Platforms</a></li>
<li class="toctree-l2"><a class="reference internal" href="deployment.html#health-check-endpoint">Health Check Endpoint</a></li>
<li class="toctree-l2"><a class="reference internal" href="deployment.html#uvicorn-directly">Uvicorn Directly</a></li>
<li class="toctree-l2"><a class="reference internal" href="deployment.html#granian">Granian</a></li>
<li class="toctree-l2"><a class="reference internal" href="deployment.html#docker-compose">Docker Compose</a></li>
<li class="toctree-l2"><a class="reference internal" href="deployment.html#reverse-proxy">Reverse Proxy</a></li>
<li class="toctree-l2"><a class="reference internal" href="deployment.html#production-checklist">Production Checklist</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="testing.html#getting-started">Getting Started</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#using-fixtures">Using Fixtures</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#overriding-dependencies">Overriding Dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#testing-json-apis">Testing JSON APIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#testing-request-validation">Testing Request Validation</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#testing-file-uploads">Testing File Uploads</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#testing-headers-and-cookies">Testing Headers and Cookies</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#testing-sessions">Testing Sessions</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#testing-dependencies">Testing Dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#testing-websockets">Testing WebSockets</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#async-tests">Async Tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#testing-server-sent-events">Testing Server-Sent Events</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#testing-error-handling">Testing Error Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#testing-lifespan-events">Testing Lifespan Events</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#testing-before-and-after-hooks">Testing Before and After Hooks</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#testing-rate-limiting">Testing Rate Limiting</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#testing-mounted-apps">Testing Mounted Apps</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#tips">Tips</a></li>
</ul>
</li>
</ul>
</div>
<div class="toctree-wrapper compound">
<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><ul>
<li class="toctree-l2"><a class="reference internal" href="tutorial-rest.html#project-setup">Project Setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-rest.html#define-your-models">Define Your Models</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-rest.html#in-memory-storage">In-Memory Storage</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-rest.html#list-all-books">List All Books</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-rest.html#create-a-book">Create a Book</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-rest.html#get-a-single-book">Get a Single Book</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-rest.html#update-a-book">Update a Book</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-rest.html#delete-a-book">Delete a Book</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-rest.html#error-handling">Error Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-rest.html#run-it">Run It</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-rest.html#try-it-out">Try It Out</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-rest.html#what-s-next">What’s Next</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-sqlalchemy.html">Using SQLAlchemy</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tutorial-sqlalchemy.html#installation">Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-sqlalchemy.html#define-your-models">Define Your Models</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-sqlalchemy.html#database-setup">Database Setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-sqlalchemy.html#lifespan-for-startup-and-shutdown">Lifespan for Startup and Shutdown</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-sqlalchemy.html#crud-endpoints">CRUD Endpoints</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-sqlalchemy.html#run-it">Run It</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-sqlalchemy.html#using-postgresql">Using PostgreSQL</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-sqlalchemy.html#tips">Tips</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-auth.html">Authentication</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tutorial-auth.html#api-key-authentication">API Key Authentication</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-auth.html#bearer-token-authentication">Bearer Token Authentication</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-auth.html#validating-jwts-with-jwtauth">Validating JWTs with JWTAuth</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-auth.html#oauth2-and-swagger-ui-s-authorize-button">OAuth2 and Swagger UI’s Authorize Button</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-auth.html#skipping-auth-for-public-routes">Skipping Auth for Public Routes</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-auth.html#custom-exception-for-auth-errors">Custom Exception for Auth Errors</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-auth.html#using-sessions-for-web-apps">Using Sessions for Web Apps</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-auth.html#role-based-access-control">Role-Based Access Control</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-auth.html#choosing-an-auth-strategy">Choosing an Auth Strategy</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-websockets.html">WebSocket Tutorial</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tutorial-websockets.html#how-websockets-work">How WebSockets Work</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-websockets.html#echo-server">Echo Server</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-websockets.html#chat-room">Chat Room</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-websockets.html#data-formats">Data Formats</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-websockets.html#html-client">HTML Client</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-websockets.html#before-request-hooks-for-websockets">Before-Request Hooks for WebSockets</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-websockets.html#connection-lifecycle">Connection Lifecycle</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-websockets.html#testing-websockets">Testing WebSockets</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-middleware.html">Writing Middleware</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tutorial-middleware.html#hooks-vs-middleware">Hooks vs. Middleware</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-middleware.html#function-middleware">Function Middleware</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-middleware.html#using-starlette-middleware">Using Starlette Middleware</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-middleware.html#built-in-middleware">Built-in Middleware</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-middleware.html#adding-third-party-middleware">Adding Third-Party Middleware</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-middleware.html#middleware-order">Middleware Order</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-middleware.html#writing-pure-asgi-middleware">Writing Pure ASGI Middleware</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-middleware.html#when-to-use-what">When to Use What</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-flask.html">Migrating from Flask</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tutorial-flask.html#the-big-differences">The Big Differences</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-flask.html#quick-reference">Quick Reference</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-flask.html#route-parameters">Route Parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-flask.html#json-apis">JSON APIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-flask.html#templates">Templates</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-flask.html#blueprints-routers">Blueprints → Routers</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-flask.html#gradual-migration">Gradual Migration</a></li>
</ul>
</li>
</ul>
</div>
<div class="toctree-wrapper compound">
<p class="caption" role="heading"><span class="caption-text">Reference</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="api.html">API Reference</a><ul>
<li class="toctree-l2"><a class="reference internal" href="api.html#the-api-class">The API Class</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#request">Request</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#response">Response</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#typed-streams">Typed Streams</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#parameter-markers">Parameter Markers</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#route-groups">Route Groups</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#standalone-routers">Standalone Routers</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#route-local-hooks-and-auth">Route-Local Hooks and Auth</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#background-queue">Background Queue</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#query-dict">Query Dict</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#headers-dict">Headers Dict</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#rate-limiter">Rate Limiter</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#status-code-helpers">Status Code Helpers</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#errors-and-exceptions">Errors and Exceptions</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#type-aliases">Type Aliases</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="cli.html">Command Line Interface</a><ul>
<li class="toctree-l2"><a class="reference internal" href="cli.html#launching-from-a-module">Launching from a Module</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#launching-from-a-file">Launching from a File</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#launching-from-a-url">Launching from a URL</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#custom-instance-names">Custom Instance Names</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#run-options">Run Options</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#environment-variables">Environment Variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#building-frontend-assets">Building Frontend Assets</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#generating-a-client">Generating a Client</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="runtime-contracts.html">Runtime Contracts</a><ul>
<li class="toctree-l2"><a class="reference internal" href="runtime-contracts.html#error-responses">Error Responses</a></li>
<li class="toctree-l2"><a class="reference internal" href="runtime-contracts.html#authentication">Authentication</a></li>
<li class="toctree-l2"><a class="reference internal" href="runtime-contracts.html#dependency-injection">Dependency Injection</a></li>
<li class="toctree-l2"><a class="reference internal" href="runtime-contracts.html#response-contracts">Response Contracts</a></li>
<li class="toctree-l2"><a class="reference internal" href="runtime-contracts.html#typed-event-streams">Typed Event Streams</a></li>
<li class="toctree-l2"><a class="reference internal" href="runtime-contracts.html#openapi-defaults">OpenAPI Defaults</a></li>
</ul>
</li>
</ul>
</div>
<div class="toctree-wrapper compound">
<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>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper"><p class="logo">
<a href="#">
<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>
<li class="toctree-l1"><a class="reference internal" href="api.html">API Reference</a></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="#">Documentation overview</a><ul>
<li>Next: <a href="quickstart.html" title="next chapter">Quick Start</a></li>
</ul></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&#169;2018-2026, Kenneth Reitz.
|
<a href="_sources/index.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>