Starlette 1.0.0: eliminaciones y correcciones

Starlette 1.0.0: Cambios clave en la versión estable

Starlette ha alcanzado su primera versión estable 1.0.0 después de casi ocho años de desarrollo. La versión se centra en eliminar APIs obsoletas, corregir errores en WebSocket, formularios y manejo de archivos estáticos. El framework sigue siendo la base de FastAPI y se utiliza en el SDK MCP de Python para aplicaciones de IA.

Nuevas características

La versión 1.0.0 añade acceso a sesiones y seguimiento de cambios en SessionMiddleware. Esto permite que el middleware registre lecturas y modificaciones de los datos de sesión sin trucos adicionales.

La versión 1.0.0rc1 introdujo estado genérico para WebSocket. El estado de la conexión ahora está tipado, lo que simplifica el trabajo con TypedDict o modelos de Pydantic en manejadores asíncronos.

Correcciones de errores

La versión corrige varios problemas críticos:

• Manejo de fallos de WebSocket en StreamingResponse y FileResponse: las respuestas ahora cierran correctamente las conexiones sin fugas.
• FormParser usa bytearray para la acumulación de campos, reduciendo el uso de memoria al analizar formularios grandes.
• MultiPartParser.parse() mueve parser.finalize() dentro de try/except, evitando excepciones con datos multipart incompletos.

Correcciones adicionales de rc1:

• El encabezado Content-Range para respuestas 416 incluye la unidad bytes.
• StaticFiles maneja cero bytes en rutas sin fallar.
• El análisis de Range usa fusión ordenada para mayor precisión.
• Múltiples rangos en respuestas usan Content-Type en lugar de Content-Range.
• Límites de byterange multipart aplican terminaciones CRLF.
• FileResponse no modifica encabezados en solicitudes de rango.
• Respuestas CORS devuelven origen explícito con credenciales.
• Jinja2Templates habilita autoescape por defecto.

Elementos obsoletos eliminados

Starlette 1.0.0 limpia la API eliminando funciones obsoletas. Es necesario migrar proyectos de versiones anteriores.

Aquí está la lista completa de eliminaciones:

• Los parámetros on_startup y on_shutdown de Starlette y Router. Reemplazados por lifespan.
• El decorador on_event(). Usa lifespan.
• El método add_event_handler(). Usa lifespan.
• Los métodos startup() y shutdown() de Router.
• El decorador @app.route(). Usa Route en routes.
• El decorador @app.websocket_route(). Usa WebSocketRoute en routes.
• El decorador @app.exception_handler(). Usa exception_handlers.
• El decorador @app.middleware(). Usa middleware.
• La función iscoroutinefunction_or_partial() de starlette.routing.
• El parámetro **env_options de Jinja2Templates. Pasa un jinja2.Environment listo vía env.
• La firma obsoleta TemplateResponse(name, context). Requiere request: TemplateResponse(request, name, ...).
• El parámetro method obsoleto de FileResponse.

Cambios de comportamiento

Jinja2Templates ahora requiere que jinja2 esté instalado en el momento de la importación, no solo en la instanciación. Esto acelera el diagnóstico de dependencias en CI/CD.

Migración a 1.0.0

• Reemplaza todos los on_startup/on_shutdown con contexto lifespan:

from contextlib import asynccontextmanager

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

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

• Mueve las rutas a la lista routes:

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

• Actualiza exception_handlers y middleware de manera similar.

• Para Jinja2Templates, prepara env con antelación:

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

Prueba solicitudes de rango y formularios multipart después de actualizar.

Resumen de lo principal

• Estabilidad de la API: Todos los elementos obsoletos eliminados, haciendo el código más limpio y predecible.
• WebSocket y Streaming: Corregido el manejo de fallos, listo para producción.
• Formularios y Archivos: Optimizada la memoria y análisis de multipart/rangos.
• Reemplazo por Lifespan: Ganchos de ciclo de vida unificados, compatibles con ASGI 3.0+.
• Jinja2: Requisitos de dependencias estrictos y autoescape por defecto.

— Editorial Team