Starlette 1.0.0: usuwania i poprawki

# Starlette 1.0.0: kluczowe zmiany w stabilnej wersji

Starlette osiągnął pierwszą stabilną wersję 1.0.0 po prawie ośmiu latach rozwoju. Wydanie skupia się na usunięciu przestarzałych API, naprawie błędów w obsłudze WebSocket, formularzy i plików statycznych. Framework pozostaje podstawą FastAPI i jest używany w Python MCP SDK dla aplikacji AI.

Nowe funkcje

W wersji 1.0.0 dodano śledzenie dostępu i zmian sesji w SessionMiddleware. Pozwala to middleware na rejestrowanie odczytu i modyfikacji danych sesji bez dodatkowych sztuczek.

W wydaniu 1.0.0rc1 wprowadzono generyczny stan dla WebSocket. Teraz stan połączenia jest typowany, co ułatwia pracę z TypedDict lub modelami Pydantic w asynchronicznych handlerach.

Poprawki błędów

Wydanie eliminuje kilka krytycznych problemów:

• Obsługa odrzuceń WebSocket w StreamingResponse i FileResponse: teraz odpowiedzi poprawnie zamykają połączenia bez wycieków.
• FormParser używa bytearray do akumulacji pól, zmniejszając zużycie pamięci przy parsowaniu dużych formularzy.
• MultiPartParser.parse() przenosi parser.finalize() do try/except, zapobiegając wyjątkom przy niekompletnych danych multipart.

Dodatkowe poprawki z rc1:

• Nagłówek Content-Range dla odpowiedzi 416 zawiera jednostkę bytes.
• StaticFiles obsługuje zera bajtowe w ścieżkach bez awarii.
• Parsowanie Range używa posortowanego scalania dla precyzji.
• Wiele zakresów w odpowiedzi używa Content-Type zamiast Content-Range.
• Granice multipart byterange stosują zakończenia CRLF.
• FileResponse nie modyfikuje nagłówków przy żądaniach range.
• Odpowiedzi CORS zwracają jawny origin przy credentials.
• Jinja2Templates włącza autoescape domyślnie.

Usunięte przestarzałe elementy

Starlette 1.0.0 przeprowadza czystkę API, usuwając funkcje deprecated. Migracja jest obowiązkowa dla projektów na starszych wersjach.

Oto pełna lista usunięć:

• Parametry on_startup i on_shutdown z Starlette i Router. Zastąpione przez lifespan.
• Dekorator on_event(). Użyj lifespan.
• Metoda add_event_handler(). Użyj lifespan.
• Metody startup() i shutdown() z Router.
• Dekorator @app.route(). Użyj Route w routes.
• Dekorator @app.websocket_route(). Użyj WebSocketRoute w routes.
• Dekorator @app.exception_handler(). Użyj exception_handlers.
• Dekorator @app.middleware(). Użyj middleware.
• Funkcja iscoroutinefunction_or_partial() z starlette.routing.
• Parametr **env_options z Jinja2Templates. Przekazuj gotowy jinja2.Environment przez env.
• Przestarzała sygnatura TemplateResponse(name, context). Wymagany request: TemplateResponse(request, name, ...).
• Przestarzały parametr method z FileResponse.

Zmiany w zachowaniu

Jinja2Templates teraz wymaga zainstalowanego jinja2 na etapie importu, a nie tylko przy instancjonowaniu. Przyspiesza to diagnozowanie zależności w CI/CD.

Migracja na 1.0.0

• Zastąp wszystkie on_startup/on_shutdown kontekstem lifespan:

from contextlib import asynccontextmanager

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

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

• Przenieś routy do listy routes:

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

• Zaktualizuj exception_handlers i middleware analogicznie.

• Dla Jinja2Templates przygotuj env z wyprzedzeniem:

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

Sprawdź testy na żądania range i formularze multipart po aktualizacji.

Co ważne

• Stabilność API: Usunięto wszystkie elementy deprecated, kod jest czystszy i bardziej przewidywalny.
• WebSocket i streaming: Naprawiono obsługę odrzuceń, nadaje się do produkcji.
• Formularze i pliki: Zoptymalizowano pamięć i parsowanie multipart/range.
• Zastąpienie Lifespan: Jednolity sposób na hooki cyklu życia, zgodny z ASGI 3.0+.
• Jinja2: Ścisłe wymagania co do zależności i autoescape domyślnie.

— Editorial Team