Responder

PyPI version Supported Python versions License

Web services for humans.

A familiar HTTP Service Framework for Python — everything you need, in a single import.

import responder

api = responder.API()

@api.route("/{greeting}")
async def greet_world(req, resp, *, greeting):
    resp.text = f"{greeting}, world!"

if __name__ == "__main__":
    api.run()

Powered by Starlette, uvicorn, and good intentions. The async is optional.

Get started in five minutes

Take the tour

It’s all in the box:

Validation

Pydantic models in, typed responses out.

Define Your Models
WebSockets

Real-time and bidirectional. Built in.

WebSocket Tutorial
Content negotiation

JSON, YAML, or MessagePack — chosen automatically.

Content Negotiation
OpenAPI

A schema from your type hints, plus Swagger UI.

OpenAPI Documentation
Sessions

Signed by default. Server-side when you need it.

Sessions
Rate limiting

Throttle requests, with X-RateLimit headers.

Rate Limiting

The Idea

If you’ve ever used Flask, the routing will look familiar. If you’ve used Falcon, the request/response pattern will click immediately. And if you’ve used Requests — well, you’ll feel right at home.

Responder takes these ideas and brings them together. Every view receives a request and a response. You read from one and write to the other. No return values, no special response classes, no boilerplate.

  • resp.text sends text. resp.html sends HTML. resp.media sends JSON.

  • resp.file("path") serves a file. resp.content sends raw bytes.

  • req.headers is case-insensitive. req.params holds query parameters.

  • resp.status_code, req.method ("GET", "POST"), req.url — the familiar ones.

Set resp.media to a dict and the right thing happens. If the client asks for YAML, it gets YAML. Content negotiation is automatic.

Responder and FastAPI 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.

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.

What You Get

One pip install, batteries included:

  • Pydantic request validation and typed response models.

  • Typed parameter injection: Query, Header, Cookie, and Path.

  • Composable dependency injection with automatic teardown.

  • Mount Flask, Django, or any WSGI/ASGI app at a subroute.

  • Gzip compression, HSTS, CORS, and trusted host validation.

  • Before-request and after-request hooks for auth and logging.

  • A test client for fast, in-process testing with pytest.

  • Route parameters with f-string syntax and type convertors.

  • Lifespan context managers for startup and shutdown logic.

  • Custom exception handlers for clean error responses.

  • GraphQL with Graphene and a built-in GraphiQL IDE.

  • Server-Sent Events for real-time streaming.

  • File serving with automatic content-type detection.

  • Sync and async views — async is always optional.

  • Class-based views with on_get, on_post, on_request.

  • Built-in rate limiting with X-RateLimit headers.

  • Structured logging with per-request context.

  • Content negotiation: JSON, YAML, and MessagePack.

  • A pleasant API with a single import statement.

  • OpenAPI schema generated from your type hints, with Swagger UI.

  • Python, JavaScript, TypeScript, Ruby, and PHP clients generated from OpenAPI.

  • A production uvicorn or Granian server, ready to deploy.

  • Route groups and standalone, composable routers for API versioning.

  • Secure-by-default signed sessions, with optional server-side backends.

  • Background tasks in a thread pool.

  • WebSocket support.

Each of these gets its own treatment in the Feature Tour.

Installation

$ uv pip install responder

Install responder[server] when you want the optional Granian production server alongside the default uvicorn runner.

Python 3.11 and above. That’s it.

User Guide

Tutorials

Reference

Project