API del objeto de aplicación de Flask
La clase Flask es el núcleo de todo el framework; se ejecuta como una aplicación WSGI y gestiona centralmente todas las funciones como rutas, plantillas, configuración, hooks, etc.
Forma de creación:
app = Flask(__name__)
Parámetros del constructor
A continuación se muestran todos los parámetros que se pueden pasar al crear una instancia de Flask:
| Parámetro | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
| import_name | str | Obligatorio | Nombre del módulo/paquete de la aplicación; Flask lo usa para localizar plantillas y archivos estáticos. Para un solo archivo se pasa el nombre del módulo,__name__y para un paquete se pasa el nombre del paquete. |
| static_url_path | str | None | Ruta URL expuesta para archivos estáticos. Si no se establece, se usa el nombre de carpeta de static_folder, como /static |
| static_folder | str | "static" | Ruta de la carpeta que almacena archivos estáticos (CSS, JS, imágenes), relativa a root_path o ruta absoluta. |
| static_host | str | None | Nombre de host para el enrutamiento de archivos estáticos; solo se necesita cuando host_matching=True |
| host_matching | bool | False | Si se hacen coincidir las rutas según la cabecera Host |
| subdomain_matching | bool | False | Si se habilita la coincidencia de rutas por subdominio |
| template_folder | str | "templates" | Ruta de la carpeta que almacena los archivos de plantilla Jinja2 |
| instance_path | str | None (detección automática) | Ruta de la carpeta instance, almacena archivos en tiempo de ejecución que no se envían al control de versiones. Configúrela como ruta absoluta. |
| instance_relative_config | bool | False | Cuando es True, las rutas relativas de los archivos de configuración se basan en instance_path en lugar de root_path |
| root_path | str | None (detección automática) | Ruta raíz de la aplicación, normalmente se infiere automáticamente, solo se debe configurar manualmente para paquetes de espacio de nombres (namespace packages) |
Atributos principales
| Atributo | Tipo | Descripción |
|---|---|---|
| name | str | Nombre de la aplicación. Si import_name es __main__, toma el nombre del archivo principal. |
| config | Config | Objeto diccionario de configuración, almacena todos los elementos de configuración. |
| debug | bool | Si el modo depuración está activado. Equivale a config["DEBUG"] |
| testing | bool | Si el modo prueba está activado. Equivale a config["TESTING"] |
| secret_key | str | Clave secreta, se usa para firmar la sesión. Equivale a config["SECRET_KEY"] |
| permanent_session_lifetime | timedelta | Duración de la sesión permanente, por defecto 31 días. |
| url_map | Map | Tabla de mapeo de URL de Werkzeug, almacena todas las reglas de enrutamiento. |
| view_functions | dict | Diccionario de mapeo de endpoint → función de vista |
| blueprints | dict | Mapeo de nombres de blueprint registrados → instancias de Blueprint |
| extensions | dict | Diccionario de almacenamiento de extensiones; las extensiones almacenan su propio estado por nombre de módulo. |
| logger | Logger | logging.Logger estándar de Python, el nombre de la aplicación se usa como nombre del logger. |
| jinja_env | Environment | Instancia de entorno Jinja2, controla la forma de cargar las plantillas. |
| json | JSONProvider | Instancia del proveedor de manejo JSON, se puede reemplazar por una biblioteca JSON personalizada. |
| aborter | Aborter | Lanzador de excepciones HTTP, llamado por la función abort() |
| cli | AppGroup | Grupo de comandos Click, permite agregar comandos CLI personalizados. |
| instance_path | str | Ruta absoluta de la carpeta instance |
| root_path | str | Ruta absoluta del directorio raíz de la aplicación |
Atributos de clase reescribibles
Los siguientes atributos pueden sobrescribirse en subclases para personalizar el comportamiento del framework:
| Atributo | Valor predeterminado | Descripción |
|---|---|---|
| request_class | Request | Clase utilizada para crear el objeto de solicitud |
| response_class | Response | Clase utilizada para crear el objeto de respuesta |
| session_interface | SecureCookieSessionInterface() | Interfaz de backend de sesión; se puede reemplazar por una sesión basada en Redis/base de datos. |
| jinja_environment | Environment | Clase de entorno Jinja2 |
| app_ctx_globals_class | _AppCtxGlobals | Clase del objeto g |
| config_class | Config | Clase del objeto de configuración |
| aborter_class | Aborter | Clase del lanzador de excepciones |
| json_provider_class | DefaultJSONProvider | Clase del procesador JSON |
| url_rule_class | Rule | Clase de reglas de URL (Werkzeug) |
| url_map_class | Map | Clase de la tabla de mapeo de URL (Werkzeug) |
| test_client_class | None (por defecto FlaskClient) | Clase del cliente de pruebas |
| test_cli_runner_class | None (por defecto FlaskCliRunner) | Clase del ejecutor de pruebas CLI |
| jinja_options | {} | Opciones adicionales que se pasan al entorno Jinja2 |
Métodos de enrutamiento de URL
| Método | Firma | Descripción |
|---|---|---|
| route | (rule, **options) | Decorador que vincula una regla de URL a una función de vista. |
| get | (rule, **options) | Decorador que vincula solo el método GET (equivalente a methods=["GET"]) |
| post | (rule, **options) | Decorador que vincula solo el método POST |
| put | (rule, **options) | Decorador que vincula solo el método PUT |
| delete | (rule, **options) | Decorador que vincula solo el método DELETE |
| patch | (rule, **options) | Decorador que vincula solo el método PATCH |
| add_url_rule | (rule, endpoint, view_func, provide_automatic_options, **options) | Agrega reglas de URL de forma programática. El decorador route llama internamente a este método. |
| url_for | (endpoint, *, _anchor, _method, _scheme, _external, **values) | Genera una URL según el endpoint y los parámetros. En blueprints, el endpoint debe llevar el prefijo del nombre del blueprint. |
| register_blueprint | (blueprint, **options) | Registra un blueprint; se pueden especificar parámetros de anulación como url_prefix, subdomain, etc. |
| iter_blueprints | () | Itera sobre todos los blueprints en el orden de registro. |
Las opciones admitidas por el decorador route incluyen:methods(lista de métodos HTTP),endpoint(nombre de endpoint personalizado),defaults(parámetros predeterminados),subdomain(subdominio), etc.
Enlaces (hooks) del ciclo de vida de la solicitud (decoradores)
Todos los métodos siguientes se pueden usar como decoradores para insertar lógica personalizada en diferentes etapas de la solicitud.
| Método | Momento de ejecución | Comportamiento si devuelve un valor no None | Uso típico |
|---|---|---|---|
| before_request | Antes de la distribución de la ruta | El valor de retorno se usa como respuesta final y se omite la función de vista. | Verificación de inicio de sesión, validación de permisos |
| after_request | Después de construir la respuesta, antes de enviarla | Debe recibir y devolver un objeto Response | Agregar cabeceras de seguridad, cabeceras CORS |
| teardown_request | Cuando se extrae el contexto de solicitud (request context) | El valor de retorno se ignora | Liberar recursos a nivel de solicitud |
| teardown_appcontext | Cuando se extrae el contexto de aplicación (app context) | El valor de retorno se ignora | Cerrar conexiones de base de datos |
| errorhandler | Cuando ocurre un código de estado o excepción especificados | El valor de retorno se usa como respuesta de la página de error | Personalizar páginas 404/500 |
| url_value_preprocessor | Después de extraer las variables de URL, antes de llamar a la vista | El valor de retorno se ignora | Preprocesar los parámetros de URL |
| url_defaults | Cuando url_for construye una URL | Modificar el diccionario values pasado | Agregar parámetros predeterminados a url_for |
| template_filter | — (de registro) | — | Registrar un filtro de plantilla de Jinja2 |
| template_test | — (de registro) | — | Registrar una prueba de plantilla de Jinja2 |
| template_global | — (de registro) | — | Registrar una función global de Jinja2 |
| shell_context_processor | Cuando se inicia flask shell | Devuelve un dict, se fusiona en el contexto del shell | Preimportar objetos comunes a flask shell |
Métodos de manejo de solicitudes
Los siguientes métodos se llaman internamente en el flujo de manejo de solicitudes y pueden sobrescribirse en subclases:
| Método | Descripción |
|---|---|
| preprocess_request(ctx) | Preprocesamiento de la solicitud: ejecuta las funciones before_request y los preprocesadores de URL. |
| dispatch_request(ctx) | Distribución central: hace coincidir la URL y llama a la función de vista correspondiente. |
| make_response(rv) | Convierte el valor de retorno de la función de vista en un objeto Response. |
| finalize_request(ctx, rv) | Finalización: llama a make_response y a los hooks after_request. |
| process_response(ctx, response) | Postprocesamiento de la respuesta: ejecuta las funciones after_request y guarda la sesión. |
| full_dispatch_request(ctx) | Entrada completa de despacho de solicitudes: preprocess → dispatch → finalize |
| handle_http_exception(ctx, e) | Maneja excepciones HTTP y busca el errorhandler correspondiente. |
| handle_user_exception(ctx, e) | Maneja excepciones del código de usuario, distinguiendo excepciones HTTP y excepciones normales. |
| handle_exception(ctx, e) | Manejo final de excepciones, devuelve una respuesta 500. |
| ensure_sync(func) | Garantizar la ejecución síncrona de la función. Las funciones async se envuelven como síncronas |
| make_default_options_response(ctx) | Generar respuestas OPTIONS automáticas |
| raise_routing_exception(request) | Manejar excepciones de enrutamiento (como redirección de barra final) |
Plantillas y archivos estáticos
| Método | Descripción |
|---|---|
| create_jinja_environment() | Crear y configurar el entorno Jinja2. Se llama automáticamente al acceder por primera vez a jinja_env |
| create_global_jinja_loader() | Crear el cargador global de Jinja2, que admite la distribución de plantillas para aplicaciones y blueprints |
| select_jinja_autoescape(filename) | Determinar si el archivo dado requiere escape automático. Por defecto devuelve True para .html/.htm/.xml/.xhtml/.svg |
| update_template_context(ctx, context) | Inyectar variables integradas como request, session, g, config en el contexto de la plantilla |
| send_static_file(filename) | Enviar archivos desde static_folder, registrado automáticamente como /static/ |
| get_send_file_max_age(filename) | Obtener el tiempo de caché de los archivos estáticos, usando por defecto la configuración SEND_FILE_MAX_AGE_DEFAULT |
| open_resource(resource, mode="rb") | Abrir archivos de recursos bajo root_path en modo binario |
| open_instance_resource(resource, mode="rb") | Abrir archivos de recursos bajo instance_path, admite modo de escritura |
Gestión de contexto
| Método | Descripción |
|---|---|
| app_context() | Crear el contexto de la aplicación, insertado manualmente con la instrucción with. Hace disponibles current_app y g |
| request_context(environ) | Crear el contexto de solicitud según el entorno WSGI |
| test_request_context(*args, **kwargs) | Crear un contexto de solicitud simulado para pruebas. Acepta parámetros como path, method, data, json |
| wsgi_app(environ, start_response) | Método central de la aplicación WSGI. Se puede envolver middleware mediante app.wsgi_app = Middleware(app.wsgi_app) |
Herramientas de prueba y desarrollo
| Método | Descripción |
|---|---|
| test_client(use_cookies=True, **kwargs) | Crear un cliente de prueba que simula el envío de solicitudes del navegador. Devuelve una instancia de FlaskClient |
| test_cli_runner(**kwargs) | Crear un ejecutor de pruebas CLI para probar comandos personalizados. Devuelve una instancia de FlaskCliRunner |
| run(host, port, debug, load_dotenv, **options) | Iniciar el servidor de desarrollo. En producción se debe usar Gunicorn/Waitress |
| make_shell_context() | Construir el diccionario de contexto de flask shell. Ejecuta todos los shell_context_processor |
| log_exception(ctx, exc_info) | Registrar excepciones en el logger, pasando la tupla exc_info |
Métodos de utilidad
| Método | Descripción |
|---|---|
| redirect(location, code=303) | Crear un objeto de respuesta de redirección |
| async_to_sync(func) | Convertir funciones de corrutina asíncronas en funciones síncronas |
| create_url_adapter(request) | Crear un adaptador de URL según la solicitud o la configuración, para la construcción de URL |
| inject_url_defaults(endpoint, values) | Inyectar parámetros predeterminados en el proceso de construcción de URL |
| handle_url_build_error(error, endpoint, values) | Manejar fallos en la construcción de url_for, puede devolver una URL alternativa |
| make_config(instance_relative) | Crear una instancia de Config, que puede ser sobrescrita por subclases para personalizar la configuración |
| make_aborter() | Crear una instancia de Aborter |
| trap_http_exception(e) | Determinar si las excepciones HTTP se lanzan hacia arriba como excepciones ordinarias |
| auto_find_instance_path() | Buscar automáticamente la ruta de la carpeta instance |
Ejemplo de código
Ejemplo
# Crear la aplicación, especificando las carpetas de plantillas y estáticos
app = Flask(__name__,
template_folder="templates",
static_folder="static",
instance_relative_config=True)
# Establecer la clave secreta
app.secret_key = "your-secret-key"
# Registrar rutas
@app.route("/")
def index():
return "<h1>Hello, EJEMPLO!</h1>"
# Registrar hooks before_request
@app.before_request
def check_auth():
# Verificar aquí el estado de autenticación del usuario
pass
# Registrar hooks after_request
@app.after_request
def add_header(response):
# Agregar una cabecera personalizada a cada respuesta
response.headers["X-Custom-Header"] = "EJEMPLO"
return response
# Registrar manejadores de errores
@app.errorhandler(404)
def not_found(error):
return "<h1>Página no encontrada</h1>", 404
# Registrar comandos CLI personalizados
@app.cli.command("hello")
def hello_command():
"""Imprimir un saludo"""
print("Hello from EJEMPLO Flask App!")