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/Rutas
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

from flask import Flask

# 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!")

Documentación relacionada

Otras extensiones