Starlette 1.0.0: deletions and fixes

# Starlette 1.0.0: Key Changes in the Stable Release

Starlette has reached its first stable version 1.0.0 after nearly eight years of development. The release focuses on removing deprecated APIs, fixing bugs in WebSocket, form, and static file handling. The framework remains the foundation of FastAPI and is used in the Python MCP SDK for AI applications.

New Features

Version 1.0.0 adds session access and change tracking in SessionMiddleware. This allows middleware to log reads and modifications of session data without extra hacks.

Release 1.0.0rc1 introduced generic state for WebSocket. Connection state is now typed, simplifying work with TypedDict or Pydantic models in async handlers.

Bug Fixes

The release fixes several critical issues:

• WebSocket failure handling in StreamingResponse and FileResponse: responses now properly close connections without leaks.
• FormParser uses bytearray for field accumulation, reducing memory usage when parsing large forms.
• MultiPartParser.parse() moves parser.finalize() into try/except, preventing exceptions with incomplete multipart data.

Additional fixes from rc1:

• Content-Range header for 416 responses includes the bytes unit.
• StaticFiles handles zero bytes in paths without crashing.
• Range parsing uses sorted merge for accuracy.
• Multiple ranges in responses use Content-Type instead of Content-Range.
• Multipart byterange boundaries apply CRLF terminations.
• FileResponse doesn't modify headers on range requests.
• CORS responses return explicit origin with credentials.
• Jinja2Templates enables autoescape by default.

Removed Deprecated Elements

Starlette 1.0.0 cleans up the API by removing deprecated functions. Migration is required for projects on older versions.

Here's the full list of removals:

• The on_startup and on_shutdown parameters from Starlette and Router. Replaced with lifespan.
• The on_event() decorator. Use lifespan.
• The add_event_handler() method. Use lifespan.
• The startup() and shutdown() methods from Router.
• The @app.route() decorator. Use Route in routes.
• The @app.websocket_route() decorator. Use WebSocketRoute in routes.
• The @app.exception_handler() decorator. Use exception_handlers.
• The @app.middleware() decorator. Use middleware.
• The iscoroutinefunction_or_partial() function from starlette.routing.
• The **env_options parameter from Jinja2Templates. Pass a ready jinja2.Environment via env.
• The deprecated TemplateResponse(name, context) signature. Requires request: TemplateResponse(request, name, ...).
• The deprecated method parameter from FileResponse.

Behavioral Changes

Jinja2Templates now requires jinja2 to be installed at import time, not just at instantiation. This speeds up dependency diagnostics in CI/CD.

Migrating to 1.0.0

• Replace all on_startup/on_shutdown with lifespan context:

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: Starlette):
    # startup
    yield
    # shutdown

app = Starlette(lifespan=lifespan, routes=[...])

• Move routes to the routes list:

routes = [
    Route("/", endpoint=home),
    WebSocketRoute("/ws", endpoint=ws_endpoint),
]

• Update exception_handlers and middleware similarly.

• For Jinja2Templates, prepare env in advance:

import jinja2
env = jinja2.Environment(autoescape=True)
templates = Jinja2Templates(env=env)

Test range requests and multipart forms after upgrading.

Key Takeaways

• API Stability: All deprecated elements removed, making the code cleaner and more predictable.
• WebSocket and Streaming: Fixed failure handling, ready for production.
• Forms and Files: Optimized memory and multipart/range parsing.
• Lifespan Replacement: Unified lifecycle hooks, compatible with ASGI 3.0+.
• Jinja2: Strict dependency requirements and autoescape by default.

— Editorial Team