Starlette 1.0.0: Löschungen und Korrekturen

Starlette 1.0.0: Wichtige Änderungen in der stabilen Version

Starlette hat nach fast acht Jahren Entwicklung die erste stabile Version 1.0.0 erreicht. Diese Veröffentlichung konzentriert sich darauf, veraltete APIs zu entfernen und Fehler in der WebSocket-, Formular- und statischen Dateibehandlung zu beheben. Das Framework bleibt die Grundlage von FastAPI und wird im Python MCP SDK für KI-Anwendungen eingesetzt.

Neue Funktionen

Version 1.0.0 ergänzt in SessionMiddleware den Zugriff auf Sessions sowie die Änderungsverfolgung. Dadurch kann Middleware Lesezugriffe und Änderungen an Session-Daten protokollieren, ohne komplizierte Workarounds.

Release 1.0.0rc1 führte generischen State für WebSocket ein. Der Connection-State ist nun typisiert, was die Arbeit mit TypedDict oder Pydantic-Modellen in asynchronen Handlern vereinfacht.

Fehlerbehebungen

Die Version behebt mehrere kritische Probleme:

• WebSocket-Fehlerbehandlung in StreamingResponse und FileResponse: Responses schließen Verbindungen nun korrekt, ohne Leaks.
• FormParser verwendet bytearray zur Feldakkumulation und reduziert so den Speicherverbrauch bei großen Formularen.
• MultiPartParser.parse() verschiebt parser.finalize() in try/except, um Ausnahmen bei unvollständigen Multipart-Daten zu vermeiden.

Zusätzliche Korrekturen aus rc1:

• Content-Range-Header für 416-Responses enthält die Einheit bytes.
• StaticFiles behandelt Pfade mit null Bytes ohne Absturz.
• Range-Parsing nutzt sorted merge für Genauigkeit.
• Mehrere Ranges in Responses verwenden Content-Type statt Content-Range.
• Multipart-Byterange-Grenzen wenden CRLF-Terminierungen an.
• FileResponse ändert bei Range-Requests keine Header.
• CORS-Responses geben expliziten Origin mit Credentials zurück.
• Jinja2Templates aktiviert autoescape standardmäßig.

Entfernte veraltete Elemente

Starlette 1.0.0 bereinigt die API, indem veraltete Funktionen entfernt werden. Projekte auf älteren Versionen müssen migriert werden.

Hier die vollständige Liste der Entfernungen:

• Die Parameter on_startup und on_shutdown von Starlette und Router. Ersetzt durch lifespan.
• Der on_event()-Dekorator. Verwenden Sie lifespan.
• Die Methode add_event_handler(). Verwenden Sie lifespan.
• Die Methoden startup() und shutdown() von Router.
• Der @app.route()-Dekorator. Verwenden Sie Route in routes.
• Der @app.websocket_route()-Dekorator. Verwenden Sie WebSocketRoute in routes.
• Der @app.exception_handler()-Dekorator. Verwenden Sie exception_handlers.
• Der @app.middleware()-Dekorator. Verwenden Sie middleware.
• Die Funktion iscoroutinefunction_or_partial() aus starlette.routing.
• Der **env_options-Parameter von Jinja2Templates. Übergeben Sie eine fertige jinja2.Environment via env.
• Die veraltete TemplateResponse(name, context)-Signatur. Erfordert request: TemplateResponse(request, name, ...).
• Der veraltete method-Parameter von FileResponse.

Verhaltensänderungen

Jinja2Templates erfordert nun, dass jinja2 zum Zeitpunkt des Imports installiert ist, nicht erst bei der Instanziierung. Das beschleunigt die Abhängigkeitsdiagnose in CI/CD.

Migration zu 1.0.0

• Ersetzen Sie alle on_startup/on_shutdown durch lifespan-Kontext:

from contextlib import asynccontextmanager

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

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

• Verschieben Sie Routes in die routes-Liste:

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

• Passen Sie exception_handlers und middleware entsprechend an.

• Für Jinja2Templates bereiten Sie env vorab vor:

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

Testen Sie nach dem Upgrade Range-Requests und Multipart-Formulare.

Wichtige Erkenntnisse

• API-Stabilität: Alle veralteten Elemente entfernt, für sauberen und vorhersehbaren Code.
• WebSocket und Streaming: Fehlerbehandlung korrigiert, produktionsreif.
• Formulare und Dateien: Speicher optimiert, Multipart-/Range-Parsing verbessert.
• Lifespan-Ersatz: Einheitliche Lifecycle-Hooks, kompatibel mit ASGI 3.0+.
• Jinja2: Strenge Abhängigkeitsanforderungen und autoescape standardmäßig.

— Editorial Team