El Modelo de Contexto y WSGI de Flask

Flask es famoso por sentirse como Python plano: from flask import request y request.args se comportan como una importación y acceso a atributos ordinarios, a pesar de que la solicitud real difiere en cada llamada.

Esa sensación es deliberada y se basa en dos ideas que preceden a casi todas las demás características de Flask: Flask es una aplicación WSGI ligera, y utiliza proxies locales de contexto para que el estado por solicitud parezca un global a nivel de módulo sin serlo realmente.

Casi todo lo demás en Flask (blueprints, extensiones, g, fábricas de aplicaciones) es una consecuencia de mantener esas dos ideas mínimas y dejar que el ecosistema construya sobre ellas.

Esta página es el modelo mental detrás de ese minimalismo; Conceptos Básicos de Flask cubre el enrutamiento y las solicitudes prácticas que esta página explica desde abajo, y Ciclo de Vida de la Solicitud y Contexto cubre los hooks prácticos (before_request, teardown_request) que se derivan directamente de él.

Resumen

• Flask es una aplicación WSGI ligera envuelta alrededor del enrutamiento y las utilidades HTTP de Werkzeug, y expone el estado con ámbito de solicitud a través de proxies locales de contexto en lugar de variables globales reales.
• Por Qué Importa: Errores de depuración confusos sobre request "filtrándose" entre solicitudes, g no persistiendo, o current_app fallando fuera de una solicitud, todos se remontan a una mala comprensión de estas dos mecánicas, no a que Flask sea impredecible.
• Conceptos Clave: WSGI, Werkzeug, el contexto de aplicación, el contexto de solicitud, proxies locales de contexto, blueprints.
• Cuándo Usar Este Modelo: Para depurar errores de "trabajando fuera del contexto de aplicación", decidir si g es seguro de usar como caché, o explicar por qué las vistas asíncronas de Flask 3 no hacen que el framework sea nativo en concurrencia.
• Limitaciones / Compensaciones: Los locales de contexto simplifican el código de solicitud única, pero ocultan el hecho de que nada se comparte entre procesos de trabajador, y el núcleo WSGI síncrono de Flask limita la concurrencia sin un servidor asíncrono externo o un modelo de despliegue con hilos (threads) o greenlets.
• Temas Relacionados: ASGI y el modelo nativo asíncrono de FastAPI, la cebolla de middleware de Django, los internos del enrutamiento de Werkzeug, el despliegue de servidores WSGI (Gunicorn, uWSGI).

Fundamentos

WSGI (Web Server Gateway Interface) es un contrato simple de Python: una aplicación web es un objeto invocable que toma un diccionario environ y una función start_response, y devuelve un iterable de bytes de respuesta.

Flask no implementa este contrato por sí mismo; está construido sobre Werkzeug, un toolkit WSGI que proporciona el enrutamiento real (el mapa de URL), objetos de solicitud/respuesta, y el servidor de desarrollo, además de Jinja2 para plantillas.

La contribución propia de Flask sobre Werkzeug es comparativamente pequeña: el objeto de aplicación Flask, el azúcar de enrutamiento basado en decoradores (@app.route, @app.get), y el sistema de contexto descrito a continuación, que es coherente con la filosofía declarada de Flask de mantenerse minimalista y dejar casi todo lo demás (ORMs, autenticación, paneles de administración) a las extensiones.

La segunda idea fundamental es el proxy local de contexto. Cuando escribes from flask import request, no estás importando un objeto de solicitud, sino un objeto proxy que, cada vez que se accede a él, busca la solicitud real para el hilo o tarea asíncrona que se esté ejecutando actualmente y le reenvía el acceso.

Esa búsqueda es lo que permite que request.args se comporte como un global plano desde el punto de vista del código, mientras que en realidad resuelve datos subyacentes diferentes en cada solicitud concurrente, de forma segura, sin que tengas que pasar request como parámetro a través de cada llamada a función.

Mecánicas e Interacciones

Flask tiene en realidad dos contextos, no uno, y la distinción es una fuente común de confusión: el contexto de aplicación (que hace que current_app y g estén disponibles) y el contexto de solicitud (que hace que request y session estén disponibles, y que automáticamente empuja un contexto de aplicación junto con él).

El servidor WSGI llama a la aplicación Flask app(environ, start_response)
  -> Flask empuja un contexto de aplicación (si no hay uno activo)
  -> Flask empuja un contexto de solicitud para esta solicitud
  -> El mapa de URL (Werkzeug) resuelve la ruta de environ a una función de vista
  -> Se ejecuta la función de vista; request/g/current_app se resuelven a través de proxies
  -> Se construye y devuelve el objeto de respuesta
  -> Se ejecutan teardown_request, y luego teardown_appcontext
  -> Ambos contextos se sacan; el servidor WSGI envía los bytes de respuesta

g es un espacio de trabajo temporal por solicitud, borrado al inicio de cada contexto de solicitud y eliminado al final del mismo. Es fácil confundirlo con una caché porque sobrevive durante toda la solicitud, pero no almacena nada entre solicitudes, y mucho menos entre procesos de trabajador.

Fuera de una solicitud activa (un comando CLI, un script en segundo plano, una sesión de shell), current_app y url_for todavía necesitan un contexto de aplicación, por lo que el código invocado fuera de una solicitud explícitamente empuja uno con app.app_context(); esta es la fuente del clásico error "working outside of application context" (trabajando fuera del contexto de aplicación).

Los Blueprints registran un conjunto de rutas, manejadores de errores y carpetas estáticas/de plantillas que se fusionan en el mapa de URL de la aplicación principal en el momento de app.register_blueprint(): son una herramienta organizativa para dividir una aplicación grande en archivos, no un límite de aislamiento como lo son los sistemas de plugins con ámbito separado; un blueprint comparte la misma configuración de la aplicación, las mismas extensiones y la misma pila de contextos que todo lo demás.

from flask import Flask, g, has_app_context
 
def get_db():
    if "db" not in g:
        g.db = {"connected": True}  # creado una vez por solicitud, no una vez por aplicación
    return g.db

Consideraciones Avanzadas y Aplicaciones

El núcleo WSGI de Flask es síncrono por diseño: cada trabajador (un hilo, proceso o greenlet, dependiendo del despliegue) maneja una solicitud a la vez de principio a fin, lo que explica en gran medida por qué el despliegue WSGI escala añadiendo más trabajadores en lugar de depender de la concurrencia cooperativa dentro de un solo trabajador.

Flask 3.x soporta funciones de vista async def, pero esto no convierte a Flask en un framework nativo asíncrono como lo son los frameworks ASGI: una vista asíncrona se integra en el modelo de trabajador síncrono subyacente, por lo que todavía ocupa un trabajador durante su duración y no obtiene ningún beneficio de concurrencia a menos que el despliegue en sí utilice algo como trabajadores gevent/eventlet o un adaptador ASGI. Compárese esto con Flask vs FastAPI vs Django, donde se cubre directamente la alternativa nativa asíncrona.

Debido a que los locales de contexto están limitados por hilo (o por tarea, bajo contextvars), nada en g o en un valor predeterminado mutable a nivel de módulo se comparte entre procesos de trabajador WSGI separados. Un error común de despliegue es asumir que una caché en memoria establecida en una solicitud será visible desde una solicitud atendida por un proceso de trabajador diferente, cuando en realidad cada proceso tiene su propio intérprete y espacio de memoria.

El ecosistema de extensiones existe precisamente porque el núcleo de Flask se mantiene tan ligero: Flask-SQLAlchemy, Flask-Login, Flask-Migrate y paquetes similares se enganchan al contexto de la aplicación/solicitud y al mecanismo de registro de blueprints en lugar de requerir cambios en Flask mismo, lo que permite que el conjunto de características de una aplicación Flask escale sin que el framework principal crezca.

Conceptos Erróneos Comunes

• "request es un objeto global compartido entre todas las solicitudes." Es un proxy local de contexto: el código siempre escribe request, pero cada hilo/tarea lo resuelve a su propia solicitud actual, aislada de cualquier otra solicitud concurrente.
• "Los Blueprints crean mini-aplicaciones aisladas." Un blueprint solo agrupa rutas, manejadores de errores y carpetas estáticas/de plantillas para conveniencia organizativa; comparte la misma configuración de aplicación, extensiones y pila de contexto que el resto de la aplicación.
• "Las rutas async def de Flask 3 hacen de Flask un framework asíncrono." Se integran en el mismo modelo de trabajador síncrono WSGI; la vista todavía ocupa un trabajador durante su duración, y no se gana concurrencia sin una configuración de servidor/trabajador diferente.
• "g es un buen lugar para almacenar datos en caché entre solicitudes." Se borra al inicio y al final de cada contexto de solicitud; es un espacio temporal solo para la solicitud actual, nunca una caché entre solicitudes.
• "Solo necesito un contexto de aplicación dentro de una solicitud." El código que se ejecuta fuera de una solicitud (comandos CLI, scripts, trabajos programados) todavía necesita un app.app_context() explícito para usar current_app, url_for u otras características ligadas al contexto de la aplicación.

Preguntas Frecuentes

Relacionados

• Conceptos Básicos de Flask - rutas, solicitudes y respuestas prácticas
• Ciclo de Vida de la Solicitud y Contexto - hooks before/teardown y g en la práctica
• Fábricas de Aplicaciones y Blueprints - estructurando una aplicación más grande alrededor de este modelo
• Extensiones - cómo el ecosistema se engancha a los mecanismos de contexto y blueprint
• Flask vs FastAPI vs Django - contraste con las alternativas nativas asíncronas y "baterías incluidas"
• Despliegue de Flask - modelos de trabajadores WSGI en producción

Versiones de Stack: Esta página fue escrita para Flask 3.1 en Python 3.14 (mantenimiento: 3.13), que se basa en Werkzeug 3.