Healthy — Healthy across all four use cases

• Last commit 1w ago
• 21+ active contributors
• Distributed ownership (top contributor 49% of recent commits)
• BSD-3-Clause licensed
• CI configured
• Tests present

Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against dependency CVEs from deps.dev and OpenSSF Scorecard

Starlette is a lightweight ASGI framework for building async web services in Python with minimal overhead. It provides HTTP routing, WebSocket support, middleware, background tasks, and a test client built on httpx, all in a framework designed for simplicity and performance rather than batteries-included convenience. Single-package structure under starlette/ with modular components: routing.py and endpoints.py for HTTP routing, middleware.py for middleware chain, websockets.py for WebSocket handling, background.py for task scheduling, and applications.py as the entry point. Static documentation lives in docs/ with MkDocs config (mkdocs.yml), and CI workflows in .github/workflows/.

LLM-derived; treat as a starting point, not verified fact.

Python developers building async web APIs, microservices, or real-time applications who need a thin layer over ASGI without the extra features of larger frameworks like FastAPI. Also used by framework maintainers who build higher-level tools on top of Starlette.

LLM-derived; treat as a starting point, not verified fact.

Production-ready and actively maintained. The codebase is 100% type-annotated with 100% test coverage, has comprehensive CI/CD via GitHub Actions (.github/workflows/main.yml for testing, publish.yml for releases), and maintains detailed documentation at docs/. The framework is a foundational component used by FastAPI and other projects, indicating stability and real-world adoption.

Low risk for a stable framework. Dependencies are minimal (only anyio required; optional ones are jinja2, httpx2, python-multipart). However, as a core dependency for FastAPI and other projects, any breaking changes could have wide impact. The fork status (Kludex/starlette) should be verified against the original upstream to ensure you're tracking the right branch for bugfixes.

LLM-derived; treat as a starting point, not verified fact.

Active development with security scanning (zizmor.yml workflow for vulnerability checks), automated dependency updates via Dependabot (.github/dependabot.yml), and automated publishing. The repo accepts issues and pull requests via templated GitHub workflows (.github/ISSUE_TEMPLATE/ and pull_request_template.md), suggesting ongoing maintenance.

LLM-derived; treat as a starting point, not verified fact.

git clone https://github.com/Kludex/starlette.git
cd starlette
pip install -e .[dev]
# Install optional dependencies as needed
pip install uvicorn jinja2 python-multipart httpx2

Daily commands:

# Create main.py with example from README
uvicorn main:app --reload
# Or run tests
pytest tests/
# Or run with specific ASGI server
python -m uvicorn main:app

• starlette/applications.py — Main Starlette application class that orchestrates routing, middleware, and request handling; foundational for understanding the framework.
• starlette/routing.py — Core routing system defining how requests are matched to endpoints and handlers; essential for request flow comprehension.
• starlette/middleware/base.py — Base middleware abstraction that all middleware derives from; critical for understanding request/response interception patterns.
• starlette/requests.py — Request class providing ASGI request parsing and utilities; foundational for handling incoming requests.
• starlette/responses.py — Response classes for generating various HTTP response types; essential for constructing outgoing responses.
• starlette/types.py — Type definitions for ASGI callables and middleware; reference point for understanding the framework's type contracts.
• starlette/endpoints.py — Class-based endpoint implementations defining HTTP method handlers; patterns for organizing endpoint logic.

• Starlette() (ASGI, routing, middleware) — Entry point combining routing, middleware, exception handlers, and ASGI callable interface.
  • Failure mode: Unhandled exception propagates to ASGI server; request hangs if not caught.
• Router (Path matching, regex convertors) — Matches request path patterns to endpoints; supports path parameters and regex.
  • Failure mode: No matching route returns 404; ambiguous routes may match wrong endpoint.
• Middleware (ASGI callable wrapping, context propagation) — Intercepts requests/responses for cross-cutting concerns (CORS, gzip, auth, errors).
  • Failure mode: Incorrect order or exception handling causes request loss or wrong response.
• Request (ASGI scope, body parsing, multipart) — Parses ASGI scope and body; provides form(), json(), stream() for payload access.
  • Failure mode: Body already consumed cannot be re-read; JSON parsing fails on malformed input.
• Response (ASGI send, content-type negotiation, headers) — Formats and sends HTTP response; supports streaming, templates, static files.
  • Failure mode: Multiple response sends cause ASGI protocol violation; streaming breaks on exception.
• Exception Handler (Exception registry, middleware integration) — Catches exceptions and converts them to HTTP responses (500, 404, validation errors).
  • Failure mode: Unregistered exceptions propagate; handler exception creates infinite loop.

• ASGI server → Starlette app — scope (dict), receive (callable), send (callable)
• Middleware stack → Router — Modified scope/request after middleware processing
• Router → Endpoint handler — Request object + path parameters from route match
• Endpoint → Response object — Handler returns Response instance with status, headers, body
• Response → ASGI send — Calls send() with {'type': 'http.response.start'|'body', ...}

Add a new HTTP endpoint

1. Define a route function or HTTPEndpoint class in your application (starlette/endpoints.py)
2. Register the route in Starlette() routes list using Route() constructor (starlette/routing.py)
3. Return a response object (JSONResponse, PlainTextResponse, etc.) (starlette/responses.py)
4. Write tests using TestClient from starlette.testclient (starlette/testclient.py)

Add a new middleware

1. Subclass BaseHTTPMiddleware or implement the ASGI callable directly (starlette/middleware/base.py)
2. Override dispatch() method to intercept requests and responses (starlette/middleware/base.py)
3. Register middleware in Starlette() app.add_middleware() or via constructor (starlette/applications.py)
4. Test middleware behavior with TestClient in tests/middleware/ (tests/middleware/test_base.py)

Add custom exception handling

1. Define a custom HTTPException or exception class (starlette/exceptions.py)
2. Register an exception handler via @app.exception_handler(MyException) (starlette/_exception_handler.py)
3. Handler receives request and exception, returns a response (starlette/responses.py)
4. Ensure ExceptionMiddleware is in middleware stack (starlette/middleware/exceptions.py)

Add form/multipart parsing

1. Use request.form() or request.json() in an endpoint (starlette/requests.py)
2. FormParser and MultiPartParser handle the body (starlette/formparsers.py)
3. Access parsed data via FormData structures (starlette/datastructures.py)

• ASGI — Async standard for Python web frameworks; enables concurrent request handling without threads.
• Jinja2 — Popular template engine; optional dependency for server-side template rendering.
• Pytest — Standard Python testing framework; provides fixtures and parametrization for comprehensive test coverage.

• Lightweight core without built-in ORM

  • Why: Keep framework minimal and allow developers to choose their data layer.
  • Consequence: Developers must integrate database libraries separately; simpler startup but more boilerplate.

• Synchronous TestClient wrapping async ASGI app

  • Why: Ease of testing without async/await complexity in test code.
  • Consequence: TestClient internally runs event loop; easier DX but potential race conditions if misused.

• Middleware as composable ASGI wrappers

  • Why: Flexible request/response filtering following ASGI spec.
  • Consequence: Complex middleware stacking order; requires care to avoid conflicts.

• Does not provide an ORM or built-in database layer
• Does not include form validation or serialization (use Pydantic separately)
• Does not handle authentication natively (developers add via middleware)
• Not intended as a batteries-included web framework like Django

• Avg cyclomatic complexity: ~6 — Codebase balances simplicity (minimal dependencies, clear ASGI contracts) with flexibility (pluggable middleware, exception handlers); core routing and request parsing add moderate complexity.
• Largest file: starlette/routing.py (850 lines)
• Estimated quality issues: ~3 — Type hints incomplete in some areas (middleware context dict), limited validation of ASGI scope format, some exception handlers swallow errors silently.

• Blocking calls in async handlers (High) — starlette/endpoints.py, starlette/requests.py: Using blocking I/O (requests library, file reads) in async route handlers stalls event loop; use run_in_threadpool() from starlette.concurrency.
• Consuming request body twice (High) — starlette/requests.py: Calling request.json() or request.body() twice consumes stream on first call; second call fails or returns empty.
• Middleware order assumptions (Medium) — starlette/middleware/: Middleware processes in reverse registration order; incorrect order can expose security issues (e.g., CORS before auth).
• Exception handler recursion (Medium) — starlette/_exception_handler.py, starlette/middleware/exceptions.py: Exception handler raising an exception creates infinite loop; handlers must not raise.
• Memory leak in streaming responses (Low) — starlette/responses.py: Large streaming responses not properly closed on disconnect can leak file handles or memory.

• starlette/routing.py (CPU/Algorithmic) — Path matching via regex for each route scales O(n); no trie-based prefix matching for high route counts.
• starlette/formparsers.py (Memory) — Multipart body parsing accumulates chunks in memory; large file uploads buffer entire body before processing.
• starlette/requests.py (Memory) — request.json() and request.body() require full body in memory; no streaming JSON parser.
• starlette/testclient.py (I/O) — TestClient runs event loop per request; high-volume tests accumulate loop creation overhead.

1. ASGI spec is non-obvious: understand scope/receive/send interface before modifying request/response handling. 2) Async context and task cancellation can surprise: background tasks run in a managed context that closes after response. 3) WebSocket receive() is a blocking coroutine—not yielding other tasks in that code path. 4) Middleware order matters: each wraps the next, so CORS before Auth changes behavior. 5) This is a fork (Kludex/starlette)—verify against https://github.com/encode/starlette for upstream security patches.

• ASGI (Asynchronous Server Gateway Interface) — Starlette is an ASGI framework—understanding the scope dict, receive/send callables, and lifecycle is mandatory to extend or debug request/response handling
• Middleware Pattern (Onion/Decorator Model) — Starlette's middleware wraps request/response processing in nested layers; you need to understand order and composition to avoid cross-cutting concerns interfering
• WebSocket Upgrade (HTTP to WS Protocol Switch) — Starlette's websockets.py uses ASGI's built-in upgrade mechanism to switch from HTTP to persistent bidirectional messaging; this is non-trivial and easy to misuse
• LIFO Task Lifecycle (Startup/Shutdown Events) — Starlette apps have lifespan context managers (see docs/lifespan.md) that run in LIFO order; critical for managing database connections and resources
• Background Tasks with Task Context — Starlette's background.py spawns tasks that run after response is sent, but within a managed context that closes—understanding this prevents data loss and hanging connections
• Route Pattern Matching and Path Parameters — Starlette's routing.py uses string patterns like {id:int} to extract typed path parameters; understanding the regex/matching logic is essential for debugging route conflicts
• Streaming Responses and Iterables — StreamingResponse in responses.py yields chunks; the async generator protocol and backpressure handling differ from traditional WSGI—easy to cause memory leaks if not careful

• encode/starlette — Upstream canonical Starlette repository; always sync critical security and bugfixes from here
• tiangolo/fastapi — Higher-level framework built on Starlette; good reference for how to extend Starlette with dependency injection and automatic OpenAPI generation
• encode/httpx — HTTP client library used by Starlette's TestClient; understanding its async patterns helps with integration testing
• python-trio/trio — Alternative async backend supported alongside asyncio; Starlette's anyio usage enables cross-runtime compatibility
• asgi/asgi-spec — ASGI specification itself; essential reference for understanding scope, receive, send contract that Starlette implements

• Add type narrowing for Request.path_params in routing to reduce casts in handler functions—currently retrieved as dict[str, Any] despite known keys from route pattern.
• Expand docs/staticfiles.md with concrete examples of cache-busting strategies (e.g., hash-based versioning) used in production deployments.
• Add asyncio-specific timeout examples to docs/background.md showing how to wrap BackgroundTask with asyncio.wait_for() to prevent runaway tasks.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub