kennethreitz/responder
1
0
Fork 0
mirror of https://github.com/kennethreitz/responder.git synced 2026-06-05 23:00:17 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
f28cd7001a63d3f4d89104337e5f9e6ef3b01e87
responder/index.html
T
kennethreitz f28cd7001a deploy: 226bd63ed3
2026-03-22 17:08:16 +00:00

254 lines
18 KiB
HTML
Raw 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 3.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=27fed22d" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
<link rel="stylesheet" type="text/css" href="_static/design-elements.e5416f61bae5d36adc6d722a2b6f8cff.css?v=452a8e97" />
<script src="_static/documentation_options.js?v=4f6ddb47"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/clipboard.min.js?v=a7894cd8"></script>
<script src="_static/copybutton.js?v=fd10adb8"></script>
<script>
</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 familiar HTTP Service Framework for Python.</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="s1">&#39;__main__&#39;</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>
<section id="the-idea">
<h2>The Idea<a class="headerlink" href="#the-idea" title="Link to this heading"></a></h2>
<p>Responder takes the best ideas from <a class="reference external" href="https://flask.palletsprojects.com/">Flask</a> and <a class="reference external" href="https://falconframework.org/">Falcon</a> and brings them
together into one clean framework.</p>
<p>The request and response objects are passed into every view and mutated
directly — no return values, no boilerplate. If you’ve used Requests,
you’ll feel right at home. If you’ve used Flask, the routing will look
familiar. If you’ve used Falcon, the <code class="docutils literal notranslate"><span class="pre">req</span></code> / <code class="docutils literal notranslate"><span class="pre">resp</span></code> pattern will
click immediately.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">resp.text</span></code> sends back text. <code class="docutils literal notranslate"><span class="pre">resp.html</span></code> sends back HTML.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">resp.media</span></code> sends back JSON — or YAML, if the client asks for it.</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">req.url</span></code> — the usual suspects.</p></li>
</ul>
<p>Content negotiation happens automatically. Set <code class="docutils literal notranslate"><span class="pre">resp.media</span></code> to a dict
and Responder figures out the rest.</p>
<p>Responder and <a class="reference external" href="https://fastapi.tiangolo.com/">FastAPI</a> share DNA — both are built on Starlette, both
appeared around the same time, and both pushed Python’s ASGI ecosystem
forward. FastAPI went deep on type annotations and automatic validation.
Responder went for a mutable request/response pattern and a simpler,
more familiar API. Both projects are better for the other existing, and
you should use whichever feels right for what you’re building.</p>
<p>Responder is a passion project — built for the joy of exploring what a
Python web framework can feel like when you start from scratch. It’s a
great fit for personal projects, learning ASGI, prototyping ideas, research,
and anyone who values a clean API over a large ecosystem. If you need
battle-tested production infrastructure at scale, you’ll be well served by
FastAPI or Django. If you want something small, expressive, and fun to work
with — you’re in the right place.</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>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 hooks that can short-circuit for auth guards.</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>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>A pleasant API with a single import statement.</p></li>
<li><p>OpenAPI schema generation with Swagger UI.</p></li>
<li><p>A production <a class="reference external" href="https://www.uvicorn.org/">uvicorn</a> server, ready to deploy.</p></li>
<li><p>HTTP method filtering for REST APIs.</p></li>
<li><p>Signed cookie-based sessions.</p></li>
<li><p>Background tasks in a thread pool.</p></li>
<li><p>WebSocket support.</p></li>
</ul>
</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>responder
</pre></div>
</div>
<p>Python 3.9 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>
</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#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#serving-files">Serving Files</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#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#trusted-hosts">Trusted Hosts</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#rate-limiting">Rate Limiting</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="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#uvicorn-directly">Uvicorn Directly</a></li>
<li class="toctree-l2"><a class="reference internal" href="deployment.html#reverse-proxy">Reverse Proxy</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#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-websockets">Testing WebSockets</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#tips">Tips</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API Documentation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="api.html#module-responder">Web Service (API) Class</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#requests-responses">Requests &amp; Responses</a></li>
<li class="toctree-l2"><a class="reference internal" href="api.html#utility-functions">Utility Functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="cli.html">Responder CLI</a><ul>
<li class="toctree-l2"><a class="reference internal" href="cli.html#launch-module-entrypoint">Launch Module Entrypoint</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#launch-local-file">Launch Local File</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#launch-remote-file">Launch Remote File</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#launch-with-non-standard-instance-name">Launch with Non-Standard Instance Name</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#build-javascript-application">Build JavaScript Application</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="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.
</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>
<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>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink