Skip to content

Flask Hoja de referencia

Framework web de Python ligero (microframework).

01

Primeros pasos

Primera aplicación

Flask es un microframework — proporciona lo esencial y te deja añadir lo que necesites. debug=True habilita la autorrecarga y páginas de error detalladas.

flask
# install Flask
pip install flask

# app.py
from flask import Flask, render_template

app = Flask(__name__)

@app.route("/")
def home():
    return render_template("index.html")

if __name__ == "__main__":
    app.run(debug=True)

Ejecutar el servidor de desarrollo

Nunca uses el servidor integrado en producción. FLASK_APP apunta al módulo que contiene la instancia de la app. Usa --host=0.0.0.0 para que sea accesible en la red.

flask
# Set the entry point and enable debug mode
export FLASK_APP=app.py
export FLASK_ENV=development
flask run

# Override host and port
flask run --host=0.0.0.0 --port=5000

# Or run the module directly
python app.py

Entorno virtual

Un entorno virtual aísla las dependencias del proyecto del Python del sistema. requirements.txt registra las versiones exactas para que otros reproduzcan el entorno con pip install -r requirements.txt.

flask
# Create an isolated environment
python -m venv venv

# Activate (Linux/macOS)
source venv/bin/activate

# Activate (Windows PowerShell)
venv\Scripts\Activate.ps1

# Install dependencies
pip install flask
pip freeze > requirements.txt

Estructura del proyecto

Flask no impone un layout, pero separar archivos estáticos, plantillas y configuración es lo convencional. La carpeta instance/ guarda secretos específicos del despliegue que no deberían subir al control de versiones.

flask
myapp/
  app.py            # application factory or instance
  config.py         # configuration classes
  requirements.txt  # pinned dependencies
  instance/
    config.py       # secret instance config (not in VCS)
  static/           # CSS, JS, images
    css/style.css
  templates/        # Jinja2 templates
    base.html
    index.html
  models.py         # database models
  views.py          # route handlers

Patrón de factoría de aplicación

El patrón de factoría difiere la creación de la app hasta que se llama a una función, lo cual es esencial para múltiples instancias, pruebas y extensiones. La opción --app de Flask acepta una función que devuelve una app.

flask
from flask import Flask

def create_app(config_name="default"):
    app = Flask(__name__)
    app.config.from_object(f"config.{config_name.title()}Config")

    from .views import bp as views_bp
    app.register_blueprint(views_bp)

    @app.route("/health")
    def health():
        return {"status": "ok"}

    return app

# Run with: flask --app myapp create_app run
# or export FLASK_APP=myapp:create_app

Anatomía de la aplicación mínima

Pasar __name__ le indica a Flask dónde encontrar los archivos estáticos y las plantillas. Puedes sobrescribir las ubicaciones de carpetas con argumentos del constructor si tu layout difiere de los valores por defecto.

flask
from flask import Flask

app = Flask(
    __name__,
    static_folder="static",
    template_folder="templates",
    static_url_path="/static",
)

# __name__ lets Flask locate resources relative to the module.
# Route decorators map URL patterns to view functions.
@app.route("/")
def index():
    return "Hello, Flask!"
02

Enrutado

Reglas variables

Las secciones marcadas con <convertidor:nombre> capturan segmentos de URL. Convertidores integrados: string (por defecto), int, float, path (acepta barras), uuid. El valor se pasa como argumento de la función.

flask
from flask import Flask

app = Flask(__name__)

@app.route("/user/<username>")
def show_user(username):
    return f"User: {username}"

@app.route("/post/<int:post_id>")
def show_post(post_id):
    return f"Post #{post_id}"

@app.route("/path/<path:subpath>")
def show_path(subpath):
    return f"Path: {subpath}"

Convertidores de URL

Los convertidores validan y castea las variables de URL. Registra una subclase de BaseConverter personalizada en app.url_map.converters para aplicar un patrón regex, como códigos de producto.

flask
@app.route("/item/<int:item_id>")
def item_int(item_id):
    return f"Integer ID: {item_id}"

@app.route("/weight/<float:kg>")
def weight(kg):
    return f"{kg} kg"

@app.route("/uid/<uuid:token>")
def by_token(token):
    return str(token)

# Custom converter
from werkzeug.routing import BaseConverter

class RegexConverter(BaseConverter):
    def __init__(self, url_map, *items):
        super().__init__(url_map)
        self.regex = items[0]

app.url_map.converters["re"] = RegexConverter

@app.route("/code/<re:[a-z]{3}-[0-9]{4}:code>")
def code(code):
    return code

URLs únicas y redirección

Las barras finales importan. Una ruta que termina en '/' redirige la forma sin barra; una ruta sin '/' devuelve 404 para la forma con barra. Elige una convención por ruta y sé consistente.

flask
@app.route("/projects/")
def projects():
    return "Projects page"

# /projects/  -> 200 OK
# /projects   -> 301 redirect to /projects/

@app.route("/about")
def about():
    return "About page"

# /about    -> 200 OK
# /about/   -> 404 Not Found

Verbos HTTP

Usa el argumento methods para aceptar varios verbos, o los atajos @app.get / @app.post (Flask 2.0+) para rutas de un solo verbo. GET es el valor por defecto.

flask
from flask import request, render_template

@app.route("/login", methods=["GET", "POST"])
def login():
    if request.method == "POST":
        return do_login()
    return render_template("login.html")

# Method-specific shortcuts
@app.get("/profile")
def profile_get():
    return render_template("profile.html")

@app.post("/profile")
def profile_post():
    return update_profile()

Construcción de URLs con url_for

url_for genera URLs a partir del nombre del endpoint (el nombre de la función de vista por defecto). Sobrevive a cambios de URL y produce URLs absolutas cuando se pasa _external=True.

flask
from flask import Flask, url_for

app = Flask(__name__)

@app.route("/")
def index():
    # builds '/user/alice' instead of hardcoding
    return f'<a href="{url_for("show_user", username="alice")}">Alice</a>'

@app.route("/user/<username>")
def show_user(username):
    return f"Hello {username}"

with app.test_request_context():
    print(url_for("show_user", username="bob"))  # /user/bob

Varias reglas para una vista

add_url_rule registra una URL sin decorador. Al dar a cada regla un endpoint distinto pero la misma función de vista con valores por defecto, un solo manejador sirve múltiples formas de URL.

flask
from flask import Flask

app = Flask(__name__)

def show(id=None, name=None):
    if id is not None:
        return f"By id: {id}"
    return f"By name: {name}"

app.add_url_rule("/by-id/<int:id>", "by_id", show, defaults={"name": None})
app.add_url_rule("/by-name/<name>", "by_name", show, defaults={"id": None})

# Two endpoints share one function with different defaults.
03

Petición y respuesta

El objeto Request

request es un proxy thread-local enlazado al contexto de la petición actual. Expone la URL, el verbo, los headers, el body y la información del cliente sin pasarse explícitamente.

flask
from flask import Flask, request

app = Flask(__name__)

@app.route("/info")
def info():
    return {
        "url": request.url,
        "method": request.method,
        "remote_addr": request.remote_addr,
        "user_agent": str(request.user_agent),
        "headers": dict(request.headers),
    }

Construir una respuesta

make_response da control total sobre el estado, los headers y el body. Para casos simples, devuelve una cadena, un dict (JSON) o una tupla de (body, estado, headers).

flask
from flask import Flask, make_response

app = Flask(__name__)

@app.route("/")
def index():
    resp = make_response("Hello, World!")
    resp.status_code = 201
    resp.headers["X-Custom"] = "yes"
    resp.set_cookie("visited", "1")
    return resp

# Returning a tuple: (body, status, headers)
@app.route("/quick")
def quick():
    return "OK", 202, {"X-Quick": "1"}

Objetos Response

Usa Response cuando necesites un mimetype personalizado (por ejemplo, XML, CSV) o headers. Fjar Content-Disposition en attachment fuerza una descarga en el navegador.

flask
from flask import Response

@app.route("/xml")
def xml():
    return Response("<msg>hi</msg>", mimetype="application/xml")

@app.route("/text")
def text():
    return Response("plain text", mimetype="text/plain")

@app.route("/csv")
def csv():
    body = "a,b,c\n1,2,3\n"
    headers = {"Content-Disposition": "attachment; filename=data.csv"}
    return Response(body, mimetype="text/csv", headers=headers)

Estado y headers personalizados

Devuelve una tupla (body, estado, headers) para respuestas personalizadas concisas. Usa 204 No Content para respuestas exitosas sin body, y los códigos de estado HTTP estándar para la semántica.

flask
@app.route("/created")
def created():
    return "done", 201, {"Location": "/resource/1"}

@app.route("/no-content")
def no_content():
    return "", 204

@app.route("/teapot")
def teapot():
    return "I'm a teapot", 418

Respuestas en streaming

Un valor de retorno generador transmite datos al cliente. Útil para archivos grandes (evita cargar el archivo entero en memoria) y Server-Sent Events. Fija un mimetype apropiado.

flask
from flask import Response

def generate():
    yield "data: first\n\n"
    yield "data: second\n\n"
    yield "data: third\n\n"

@app.route("/stream")
def stream():
    return Response(generate(), mimetype="text/event-stream")

@app.route("/big-file")
def big_file():
    def chunks():
        with open("large.log", "rb") as f:
            while chunk := f.read(8192):
                yield chunk
    return Response(chunks(), mimetype="application/octet-stream")

Cookies en la respuesta

set_cookie escribe un header Set-Cookie; delete_cookie lo expira. Fija siempre httponly y samesite por seguridad. Las cookies son parte de la respuesta, no del body de la petición.

flask
from flask import make_response

@app.route("/set-theme")
def set_theme():
    resp = make_response("theme set")
    resp.set_cookie("theme", "dark", max_age=30*86400, httponly=True, samesite="Lax")
    return resp

@app.route("/clear-theme")
def clear_theme():
    resp = make_response("cleared")
    resp.delete_cookie("theme")
    return resp
04

Objeto Request (form/args/files)

Parámetros de query (args)

request.args es un MultiDict de valores de la query string. Usa get con un valor por defecto y conversión de tipo, y getlist para claves repetidas. Nunca indexes directamente — las claves ausentes lanzan 400.

flask
from flask import request

@app.route("/search")
def search():
    q = request.args.get("q", "")           # default ""
    page = request.args.get("page", 1, type=int)
    tags = request.args.getlist("tag")       # /search?tag=a&tag=b -> ["a","b"]
    return {"q": q, "page": page, "tags": tags}

Datos de formulario

request.form guarda los datos application/x-www-form-urlencoded o multipart enviados por POST. Usa .get() para evitar KeyError en campos opcionales. Las peticiones GET tienen un form vacío.

flask
from flask import request, render_template

@app.route("/login", methods=["GET", "POST"])
def login():
    if request.method == "POST":
        username = request.form.get("username")
        password = request.form.get("password")
        if not username or not password:
            return "Missing fields", 400
        return f"Welcome {username}"
    return render_template("login.html")

Subida de archivos

request.files es un MultiDict de objetos FileStorage. Pasa siempre los nombres de archivo suministrados por el usuario por secure_filename para eliminar separadores de ruta y caracteres peligrosos antes de guardar.

flask
from flask import request
from werkzeug.utils import secure_filename
import os

@app.route("/upload", methods=["POST"])
def upload():
    file = request.files.get("file")
    if not file or file.filename == "":
        return "No file", 400
    name = secure_filename(file.filename)
    file.save(os.path.join("uploads", name))
    return "saved"

Body JSON

get_json() parsea el body como JSON solo cuando el Content-Type es application/json. force=True ignora el header (úsalo con cautela). silent=True suprime los errores de parseo.

flask
from flask import request

@app.route("/api/echo", methods=["POST"])
def echo():
    data = request.get_json()        # returns None if not JSON
    if data is None:
        return "Expected JSON", 415
    return {"you_sent": data}

# Force parsing even without the right header (risky)
@app.route("/api/force")
def force():
    data = request.get_json(force=True)
    return data

Headers y cookies

request.headers es un objeto tipo diccionario EnvironHeaders; request.cookies guarda las cookies entrantes enviadas por el cliente. Ambos son de solo lectura — fija los headers/cookies de respuesta en la respuesta.

flask
from flask import request

@app.route("/inspect")
def inspect():
    auth = request.headers.get("Authorization")
    accept = request.headers.get("Accept")
    session_id = request.cookies.get("session_id")
    return {
        "auth": auth,
        "accept": accept,
        "session_id": session_id,
    }

Funciones y propiedades del Request

request expone metadatos sobre la conexión y el body. is_json comprueba el Content-Type, is_secure comprueba HTTPS, y query_string son los bytes crudos posteriores a '?'.

flask
from flask import request

@app.route("/state")
def state():
    return {
        "method": request.method,
        "is_xhr": request.is_json,
        "content_type": request.content_type,
        "content_length": request.content_length,
        "is_secure": request.is_secure,
        "scheme": request.scheme,
        "host": request.host,
        "path": request.path,
        "query_string": request.query_string.decode(),
    }
05

Plantillas Jinja2

Renderizar plantillas

render_template carga un archivo Jinja2 de la carpeta templates/ e inyecta los argumentos con nombre como variables. La sintaxis {{ }} muestra una expresión; Flask escapa el HTML automáticamente por seguridad.

flask
from flask import render_template

@app.route("/<name>")
def hello(name):
    return render_template("hello.html", name=name, title="Welcome")

# templates/hello.html
# <!DOCTYPE html>
# <html>
#   <head><title>{{ title }}</title></head>
#   <body>
#     <h1>Hello {{ name }}!</h1>
#   </body>
# </html>

Variables de plantilla

Jinja2 soporta acceso por atributo (user.name) y por ítem (user['age']). El filtro safe marca una cadena como confiable para que no se escape — úsalo solo en contenido que controles por completo.

flask
# View
@app.route("/")
def index():
    return render_template(
        "index.html",
        user={"name": "Alice", "age": 30},
        items=["apple", "banana", "cherry"],
        html_content="<b>safe?</b>",
    )

# Template
# <p>Name: {{ user.name }}</p>
# <p>Age: {{ user["age"] }}</p>
# <p>First: {{ items[0] }}</p>
# <p>Raw HTML: {{ html_content | safe }}</p>

Estructuras de control

Jinja2 soporta {% if %}, {% for %} y {% block %}. Dentro de los bucles, la variable especial loop da index, index0, first, last, length y revindex. El for-else corre cuando el iterable está vacío.

flask
{# if / elif / else #}
{% if user.age >= 18 %}
  Adult
{% elif user.age >= 13 %}
  Teen
{% else %}
  Child
{% endif %}

{# for loop #}
<ul>
{% for item in items %}
  <li>{{ loop.index }}: {{ item }}</li>
{% else %}
  <li>No items</li>
{% endfor %}
</ul>

Herencia de plantillas

extends incorpora una plantilla base y las plantillas hijas sobrescriben los blocks con nombre. Esto mantiene el layout compartido (navegación, scripts) en un solo lugar. super() renderiza el contenido del block del padre.

flask
{# templates/base.html #}
<!DOCTYPE html>
<html>
<head>
  <title>{% block title %}Default{% endblock %}</title>
</head>
<body>
  {% block content %}{% endblock %}
</body>
</html>

{# templates/child.html #}
{% extends "base.html" %}

{% block title %}Home{% endblock %}

{% block content %}
  <h1>Welcome home</h1>
{% endblock %}

Filtros

Los filtros transforman valores mediante la sintaxis de pipe (|) y aceptan argumentos. Registra filtros personalizados en app.jinja_env.filters para reutilizar lógica entre plantillas.

flask
{{ name | capitalize }}      {# alice -> Alice #}
{{ price | round(2) }}       {# 3.14159 -> 3.14 #}
{{ items | length }}         {# count #}
{{ text | truncate(20) }}    {# shorten #}
{{ tags | join(", ") }}      {# ["a","b"] -> "a, b" #}
{{ value | default("n/a") }} {# fallback #}
{{ html | striptags }}       {# remove HTML tags #}

{# Custom filter #}
def reverse_filter(s):
    return s[::-1]

app.jinja_env.filters["reverse"] = reverse_filter
{{ "hello" | reverse }}  {# olleh #}

Macros

Las macros son fragmentos de plantilla reutilizables, como funciones. Impórtalas con {% from %} o {% import %}. Mantienen el HTML repetitivo (campos de formulario, tarjetas) DRY.

flask
{# templates/macros.html #}
{% macro input(name, value="", type="text") %}
  <input type="{{ type }}" name="{{ name }}" value="{{ value }}">
{% endmacro %}

{% macro label(text, for_id) %}
  <label for="{{ for_id }}">{{ text }}</label>
{% endmacro %}

{# In another template #}
{% from "macros.html" import input, label %}

<form>
  {{ label("Username", "u") }}
  {{ input("username") }}
  {{ label("Password", "p") }}
  {{ input("password", type="password") }}
</form>
06

Archivos estáticos

Servir archivos estáticos

Flask registra automáticamente una ruta /static/<path:filename> para la carpeta static. Construye siempre las URLs con url_for para que las rutas sigan siendo correctas aunque cambie static_url_path.

flask
# Files in the static/ folder are served at /static/<filename>
# static/css/style.css -> http://localhost:5000/static/css/style.css

# Reference them in templates
# <link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}">
# <script src="{{ url_for('static', filename='js/app.js') }}"></script>
# <img src="{{ url_for('static', filename='img/logo.png') }}">

url_for para recursos estáticos

url_for('static', filename=...) resuelve la ruta de un archivo estático. Pasa _external=True para una URL absoluta (útil en correos o feeds) y argumentos de query para romper la caché.

flask
from flask import Flask, url_for

app = Flask(__name__)

with app.test_request_context():
    print(url_for("static", filename="css/style.css"))
    # /static/css/style.css
    print(url_for("static", filename="js/app.js", _external=True))
    # http://localhost/static/js/app.js

Carpeta estática personalizada

Sobrescribe static_folder (ubicación en disco) y static_url_path (prefijo de URL) para ajustarte a las convenciones de tu proyecto. El valor por defecto es carpeta='static' mapeada a /static.

flask
from flask import Flask

app = Flask(
    __name__,
    static_folder="assets",       # folder on disk
    static_url_path="/public",    # URL prefix
)

# Now files in assets/ are served at /public/<filename>
# Template: url_for('static', filename='css/style.css') -> /public/css/style.css

Favicon

Los navegadores piden /favicon.ico en la raíz por defecto. Añade una ruta explícita o enlaza el icono vía una etiqueta <link>. send_from_directory sirve un archivo de un directorio de forma segura.

flask
from flask import send_from_directory
import os

@app.route("/favicon.ico")
def favicon():
    return send_from_directory(
        os.path.join(app.root_path, "static"),
        "favicon.ico",
        mimetype="image/vnd.microsoft.icon",
    )

# Or place favicon.ico in static/ and link it:
# <link rel="icon" href="{{ url_for('static', filename='favicon.ico') }}">

Rotura de caché

Los navegadores cachean los recursos estáticos por URL. Añadir un hash de versión obliga a los clientes a obtener copias nuevas tras cambiar un archivo. Una herramienta de build (Vite, Flask-Assets) automatiza esto en proyectos mayores.

flask
# Append a version query param to force reloads
# <link href="{{ url_for('static', filename='css/app.css', v='1.2') }}">

# Or compute a hash at startup
import hashlib, os

def asset_version(filename):
    path = os.path.join(app.static_folder, filename)
    with open(path, "rb") as f:
        return hashlib.md5(f.read()).hexdigest()[:8]

@app.template_filter("bust")
def bust(filename):
    v = asset_version(filename)
    return url_for("static", filename=filename) + f"?v={v}"

# Template: <link href="{{ 'css/app.css' | bust }}">
07

Blueprints

Crear un Blueprint

Un Blueprint agrupa rutas, plantillas y archivos estáticos relacionados en un módulo. El primer argumento es el nombre del blueprint; url_prefix antepone una ruta a cada ruta que defina.

flask
# auth.py
from flask import Blueprint, render_template

bp = Blueprint("auth", __name__, url_prefix="/auth")

@bp.route("/login")
def login():
    return render_template("auth/login.html")

@bp.route("/register")
def register():
    return render_template("auth/register.html")

Registrar Blueprints

register_blueprint adjunta un blueprint a la app. Puedes sobrescribir url_prefix en el momento del registro, así que el mismo blueprint puede montarse bajo rutas distintas en apps diferentes.

flask
from flask import Flask
from auth import bp as auth_bp
from blog import bp as blog_bp

app = Flask(__name__)
app.register_blueprint(auth_bp)           # /auth/*
app.register_blueprint(blog_bp, url_prefix="/blog")  # /blog/*

# Register later, or with a name override
app.register_blueprint(auth_bp, name="alt_auth")

Blueprint con prefijo de URL

Define url_prefix en el Blueprint o en el registro. Versionar la ruta de la API (/api/v1) te permite introducir /api/v2 más tarde sin romper los clientes existentes.

flask
# api/__init__.py
from flask import Blueprint

bp = Blueprint("api", __name__, url_prefix="/api/v1")

@bp.route("/users")
def list_users():
    return {"users": []}

@bp.route("/users/<int:uid>")
def get_user(uid):
    return {"id": uid}

# All routes become /api/v1/users...

Recursos del Blueprint

Un blueprint puede llevar sus propias carpetas de plantillas y estáticos. La resolución de plantillas comprueba primero el blueprint y luego la app, así que los archivos locales del blueprint sobrescriben los globales de la app con el mismo nombre.

flask
bp = Blueprint(
    "admin",
    __name__,
    url_prefix="/admin",
    template_folder="templates",   # blueprint-local templates
    static_folder="static",        # blueprint-local static
)

# Templates: blueprint lookups first, then app templates
# render_template("admin/dashboard.html")
# Static: url_for('admin.static', filename='css/admin.css')

Manejadores de errores del Blueprint

Los manejadores de errores a nivel de blueprint solo capturan errores lanzados por las rutas de ese blueprint, dándote páginas de error específicas por sección. Los manejadores a nivel de app manejan lo no capturado.

flask
from flask import Blueprint, render_template

bp = Blueprint("blog", __name__)

@bp.errorhandler(404)
def blog_not_found(e):
    return render_template("blog/404.html"), 404

@bp.errorhandler(403)
def blog_forbidden(e):
    return render_template("blog/403.html"), 403

Blueprints anidados

Flask 2.0+ soporta anidar blueprints. Registra un blueprint hijo sobre un padre con register_blueprint; sus url_prefix se concatenan, dejándote componer apps grandes a partir de módulos pequeños.

flask
from flask import Blueprint

parent = Blueprint("parent", __name__, url_prefix="/parent")
child = Blueprint("child", __name__, url_prefix="/child")

@child.route("/info")
def info():
    return "nested info"

parent.register_blueprint(child)
app.register_blueprint(parent)

# Final URL: /parent/child/info
08

Contextos (g / session)

Contexto de aplicación

El contexto de aplicación hace disponibles current_app y g fuera de una petición (por ejemplo, en comandos CLI o tareas en segundo plano). Empújalo con app.app_context() cuando trabajes fuera de una petición.

flask
from flask import current_app, g

@app.route("/")
def index():
    app_name = current_app.name
    config_value = current_app.config["SECRET_KEY"]
    return f"Running {app_name}"

# Push a context manually (scripts, shell)
with app.app_context():
    print(current_app.config["DEBUG"])

El objeto g

g es un espacio de nombres por petición para guardar recursos compartidos como conexiones a bases de datos. Se reinicia en cada petición y se limpia en un manejador teardown_appcontext.

flask
from flask import g
import sqlite3

def get_db():
    if "db" not in g:
        g.db = sqlite3.connect("app.db")
        g.db.row_factory = sqlite3.Row
    return g.db

@app.teardown_appcontext
def close_db(exc):
    db = g.pop("db", None)
    if db is not None:
        db.close()

Contexto de petición

El contexto de petición enlaza request, session y url_for a un hilo. Usa test_request_context en pruebas y scripts para simular una petición sin servidor HTTP.

flask
from flask import request

# Flask pushes a request context automatically during dispatch.
# Push one manually to use request/url_for outside a view:
with app.test_request_context("/?q=flask"):
    print(request.args.get("q"))   # flask
    print(request.path)            # /

# request_context for real WSGI environments
from werkzeug.test import EnvironBuilder
env = EnvironBuilder("/post/1").get_environ()
with app.request_context(env):
    print(request.path)

Proxies current_app y request

current_app, request, session y g son objetos LocalProxy que reenvían el acceso a atributos al contexto activo. Nunca los capturen en una variable global — accede siempre a ellos en el momento de la llamada.

flask
from flask import current_app, request, session, g

# These are LocalProxy objects, not the real thing.
# They resolve to the current context's object at access time.

@app.route("/")
def index():
    current_app.logger.info("hit /")
    g.request_start = time.time()
    session["visited"] = True
    return current_app.config["APP_NAME"]

# Avoid storing proxies in module-level variables;
# always access them inside a context.

Objeto Session

session es un diccionario basado en cookie firmada. Fija app.secret_key para que Flask pueda firmarla. Los valores se guardan en el cliente y el usuario puede leerlos (aunque no manipularlos), así que nunca guardes secretos ahí.

flask
from flask import session

@app.route("/login")
def login():
    session["user_id"] = 42
    session["role"] = "admin"
    return "logged in"

@app.route("/who")
def who():
    uid = session.get("user_id")
    return f"user {uid}" if uid else "anonymous"

@app.route("/logout")
def logout():
    session.clear()
    return "logged out"

Ciclo de vida de los contextos

Entender el ciclo de vida es clave para usar los hooks correctamente. Los manejadores teardown_* corren siempre, incluso ante errores, así que son el lugar adecuado para cerrar conexiones de bases de datos y liberar recursos.

flask
# Per-request lifecycle:
# 1. Application context pushed
# 2. Request context pushed
# 3. before_request handlers run
# 4. View function runs
# 5. after_request handlers run (can modify response)
# 6. Request context popped
# 7. teardown_request handlers run
# 8. teardown_appcontext handlers run (close resources)

@app.before_request
def before():
    g.start = time.time()

@app.teardown_request
def teardown(exc):
    elapsed = time.time() - getattr(g, "start", time.time())
    app.logger.debug("request took %.3fs", elapsed)
09

Integración de SQLAlchemy

Configurar Flask-SQLAlchemy

Flask-SQLAlchemy envuelve SQLAlchemy y lo integra con el contexto de la app de Flask. Fija SQLALCHEMY_DATABASE_URI en la cadena de conexión y desactiva el track de modificaciones para ahorrar memoria.

flask
pip install flask-sqlalchemy

from flask import Flask
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False

db = SQLAlchemy(app)

# In a factory, init with db.init_app(app)

Definir modelos

Los modelos heredan de db.Model; las columnas son instancias de db.Column. Tipos comunes: Integer, String, Text, DateTime, Boolean. Usa unique=True y nullable=False para restricciones.

flask
from datetime import datetime

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True)
    created_at = db.Column(db.DateTime, default=datetime.utcnow)

    def __repr__(self):
        return f"<User {self.username}>"

class Post(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(200), nullable=False)
    body = db.Column(db.Text)
    user_id = db.Column(db.Integer, db.ForeignKey("user.id"))

Consultar datos

Model.query es una interfaz de consulta de conveniencia. filter_by(clave=valor) es simple; filter(expresión) soporta operadores como >, <, like, in_. paginate() devuelve los ítems más los metadatos de la página.

flask
# Fetch all
users = User.query.all()

# Primary key lookup
user = User.query.get(1)

# Filter
admins = User.query.filter_by(role="admin").all()
active = User.query.filter(User.email.isnot(None)).first()

# Order, limit, paginate
recent = User.query.order_by(User.created_at.desc()).limit(10).all()
page = User.query.paginate(page=2, per_page=20)

# Count
total = User.query.count()

Añadir y actualizar

Los cambios ocurren dentro de una única transacción vía db.session. add prepara un objeto nuevo; commit lo escribe. Ante un error, haz rollback con db.session.rollback() para mantener la sesión usable.

flask
# Create
u = User(username="alice", email="[email protected]")
db.session.add(u)
db.session.commit()

# Update
u.email = "[email protected]"
db.session.commit()

# Delete
db.session.delete(u)
db.session.commit()

# Bulk insert
db.session.add_all([User(username="b"), User(username="c")])
db.session.commit()

Relaciones

db.relationship define el enlace entre modelos. backref añade un atributo inverso. lazy='dynamic' devuelve un objeto de consulta en lugar de una lista, útil para colecciones grandes que quieras filtrar más.

flask
class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80))
    posts = db.relationship("Post", backref="author", lazy="dynamic")

class Post(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(200))
    user_id = db.Column(db.Integer, db.ForeignKey("user.id"))

# Usage
user = User.query.get(1)
user.posts.all()              # list of posts
post = Post.query.get(5)
post.author.username          # backref to user

Migraciones con Flask-Migrate

Flask-Migrate envuelve Alembic para versionar tu esquema. Ejecuta migrate para autogenerar un script a partir de los cambios de los modelos, y luego upgrade para aplicarlo. Revisa siempre los scripts autogenerados antes de subirlos.

flask
pip install flask-migrate

from flask_migrate import Migrate

migrate = Migrate(app, db)

# CLI commands
# flask db init          # create migrations folder
# flask db migrate -m "create users"
# flask db upgrade       # apply migrations
# flask db downgrade     # revert one step
# flask db current       # show current revision
10

WTForms (Flask-WTF)

Instalar Flask-WTF

Flask-WTF integra WTForms con Flask y añade protección CSRF automáticamente. Se requiere un SECRET_KEY para que el token CSRF pueda firmarse. Desactiva el CSRF solo en endpoints de API públicos.

flask
pip install flask-wtf

from flask import Flask
from flask_wtf import FlaskForm

app = Flask(__name__)
app.config["SECRET_KEY"] = "change-me-in-production"
app.config["WTF_CSRF_ENABLED"] = True

# CSRF protection is enabled by default
# when SECRET_KEY is set.

Definir un formulario

Los formularios heredan de FlaskForm. Cada campo toma una etiqueta y una lista de validadores que corren en validate(). Los validadores exigen entrada requerida, longitud, formato de correo y más.

flask
from flask_wtf import FlaskForm
from wtforms import StringField, PasswordField, SubmitField
from wtforms.validators import DataRequired, Email, Length

class LoginForm(FlaskForm):
    email = StringField("Email", validators=[DataRequired(), Email()])
    password = PasswordField("Password", validators=[DataRequired(), Length(min=8)])
    submit = SubmitField("Log In")

class RegisterForm(FlaskForm):
    username = StringField("Username", validators=[DataRequired(), Length(min=3, max=20)])
    email = StringField("Email", validators=[DataRequired(), Email()])
    submit = SubmitField("Sign Up")

Renderizar el formulario en la plantilla

form.hidden_tag() renderiza el token CSRF y cualquier campo oculto. Cada campo puede renderizar su etiqueta, input y errores por separado. Para salida rápida, {{ form.field() }} renderiza el input HTML.

flask
{# templates/login.html #}
<form method="POST">
  {{ form.hidden_tag() }}  {# CSRF token #}
  <p>
    {{ form.email.label }}
    {{ form.email() }}
    {% for err in form.email.errors %}<span class="err">{{ err }}</span>{% endfor %}
  </p>
  <p>
    {{ form.password.label }}
    {{ form.password() }}
  </p>
  {{ form.submit() }}
</form>

Validar el formulario

validate_on_submit() devuelve True solo para una petición POST donde cada validador pasa. En caso de éxito, lee los valores de los campos desde form.campo.data. En caso de fallo, vuelve a renderizar la plantilla para mostrar los errores.

flask
from flask import render_template, redirect, url_for, flash

@app.route("/login", methods=["GET", "POST"])
def login():
    form = LoginForm()
    if form.validate_on_submit():   # POST + valid
        email = form.email.data
        flash(f"Logged in as {email}")
        return redirect(url_for("dashboard"))
    return render_template("login.html", form=form)

# validate_on_submit() returns False on GET or invalid POST

Validadores integrados

Los validadores son funciones que lanzan ValidationError en caso de fallo. EqualTo es común para la confirmación de contraseñas. Encadénalos en una lista; corren en orden hasta que uno falla.

flask
from wtforms.validators import (
    DataRequired,   # field not empty
    Email,          # valid email format
    Length,         # Length(min=3, max=20)
    NumberRange,    # NumberRange(min=0, max=100)
    URL,            # valid URL
    Regexp,         # Regexp(r"^\\w+$")
    EqualTo,        # EqualTo("password") - match another field
    Optional,       # skip validation if empty
    InputRequired,  # field submitted (even if empty string)
    NoneOf,         # NoneOf(["admin", "root"])
)

password = PasswordField("Password", validators=[DataRequired(), Length(min=8)])
confirm = PasswordField("Confirm", validators=[EqualTo("password")])

FileField

Usa FileField de flask_wtf.file con FileRequired y FileAllowed para validar las subidas. El archivo subido es un objeto FileStorage disponible en form.campo.data. La etiqueta del formulario debe incluir enctype=multipart/form-data.

flask
from flask_wtf import FlaskForm
from flask_wtf.file import FileField, FileRequired, FileAllowed

class UploadForm(FlaskForm):
    image = FileField("Image", validators=[
        FileRequired(),
        FileAllowed(["jpg", "png", "gif"], "Images only!"),
    ])
    submit = SubmitField("Upload")

@app.route("/upload", methods=["GET", "POST"])
def upload():
    form = UploadForm()
    if form.validate_on_submit():
        f = form.image.data
        f.save("uploads/" + f.filename)
        return "uploaded"
    return render_template("upload.html", form=form)
11

Autenticación con Flask-Login

Configurar Flask-Login

Flask-Login gestiona las sesiones de usuario: iniciar sesión, cerrar sesión y recordar usuarios. Fija login_view para que los usuarios no autenticados sean redirigidos ahí. login_message muestra un flash en esa redirección.

flask
pip install flask-login

from flask import Flask
from flask_login import LoginManager

app = Flask(__name__)
app.config["SECRET_KEY"] = "secret"

login_manager = LoginManager()
login_manager.init_app(app)
login_manager.login_view = "login"
login_manager.login_message = "Please log in to access this page."

Modelo de usuario

El modelo de usuario debe mezclar UserMixin (que proporciona is_authenticated, is_active, get_id, etc.) e implementar un callback user_loader que devuelva un usuario por ID. Nunca guardes contraseñas en texto plano — haséalas.

flask
from flask_login import UserMixin
from werkzeug.security import generate_password_hash, check_password_hash

class User(UserMixin, db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True)
    password_hash = db.Column(db.String(256))

    def set_password(self, pw):
        self.password_hash = generate_password_hash(pw)

    def check_password(self, pw):
        return check_password_hash(self.password_hash, pw)

@login_manager.user_loader
def load_user(user_id):
    return User.query.get(int(user_id))

Vista de login

login_user carga al usuario en la sesión. Pasa remember=True para cookies persistentes. Verifica siempre la contraseña con una comprobación de hash antes de iniciar sesión, y muestra un error genérico en caso de fallo.

flask
from flask import render_template, redirect, url_for, flash
from flask_login import login_user
from forms import LoginForm

@app.route("/login", methods=["GET", "POST"])
def login():
    form = LoginForm()
    if form.validate_on_submit():
        user = User.query.filter_by(username=form.username.data).first()
        if user and user.check_password(form.password.data):
            login_user(user, remember=form.remember.data)
            return redirect(url_for("dashboard"))
        flash("Invalid username or password")
    return render_template("login.html", form=form)

Proteger rutas

El decorador @login_required rechaza a los usuarios anónimos y los redirige a login_view. current_user es un proxy al usuario conectado (o un AnonymousUserMixin) disponible en vistas y plantillas.

flask
from flask_login import login_required, current_user

@app.route("/dashboard")
@login_required
def dashboard():
    return f"Welcome {current_user.username}"

@app.route("/settings")
@login_required
def settings():
    return render_template("settings.html", user=current_user)

# Unauthenticated users redirect to login_view
# @login_required must be the innermost decorator

Logout

logout_user borra al usuario de la sesión. Protege la ruta con @login_required para que solo los usuarios conectados puedan cerrar sesión. Redirige después a una página pública (índice o login).

flask
from flask_login import logout_user, login_required
from flask import redirect, url_for, flash

@app.route("/logout")
@login_required
def logout():
    logout_user()
    flash("You have been logged out.")
    return redirect(url_for("index"))

# logout_user() clears the session and cookies

Recuérdame y current_user

remember=True fija una cookie aparte para que los usuarios sigan conectados tras cerrar el navegador. current_user funciona tanto en vistas como en plantillas, facilitando renderizar condicionalmente la UI según el estado de autenticación.

flask
from flask_login import current_user

# In the login view
login_user(user, remember=True)

# remember=True stores a separate long-lived cookie
# so the session survives a browser restart.

# current_user is available everywhere a context exists
@app.route("/")
def index():
    if current_user.is_authenticated:
        return f"Hi {current_user.username}"
    return "Welcome, guest"

# In templates:
# {% if current_user.is_authenticated %}
#   <a href="{{ url_for('logout') }}">Logout</a>
# {% endif %}
12

Manejo de errores

abort()

abort() detiene inmediatamente la vista y devuelve un error HTTP. Pasa un código de estado y un mensaje opcional. Lanza una HTTPException que Flask convierte en la respuesta de error correspondiente.

flask
from flask import abort

@app.route("/user/<int:id>")
def get_user(id):
    user = find_user(id)
    if user is None:
        abort(404)            # Not Found
    if not can_access(user):
        abort(403, "Forbidden")   # Forbidden with description
    return render_template("user.html", user=user)

# Common codes: 400 Bad Request, 401 Unauthorized,
# 403 Forbidden, 404 Not Found, 418 Teapot, 500 Server Error

Páginas de error personalizadas

Registra manejadores con @app.errorhandler(codigo). Devuelve una tupla de (plantilla, codigo_de_estado). Estos manejadores capturan tanto llamadas abort() como excepciones que se mapean a ese estado.

flask
from flask import render_template

@app.errorhandler(404)
def not_found(e):
    return render_template("errors/404.html"), 404

@app.errorhandler(403)
def forbidden(e):
    return render_template("errors/403.html"), 403

@app.errorhandler(500)
def server_error(e):
    return render_template("errors/500.html"), 500

Manejadores de errores para excepciones

Puedes registrar manejadores para clases de excepción personalizadas, no solo para códigos HTTP. Lanzar la excepción en cualquier parte de una vista dispara el manejador, centralizando las respuestas de error de dominio.

flask
from werkzeug.exceptions import HTTPException

class InvalidUsage(Exception):
    status_code = 400
    def __init__(self, message, status_code=None, payload=None):
        super().__init__()
        self.message = message
        if status_code is not None:
            self.status_code = status_code
        self.payload = payload

@app.errorhandler(InvalidUsage)
def handle_invalid_usage(e):
    return {"error": e.message}, e.status_code

@app.route("/raise")
def raise_err():
    raise InvalidUsage("Bad input", status_code=422)

Manejador 404 catch-all

Un manejador genérico de Exception es el último recurso para los 500. Relanza HTTPException para que las páginas integradas sigan funcionando, y registra el traceback. Cuida no filtrar stack traces a los usuarios en producción.

flask
@app.errorhandler(404)
def page_not_found(e):
    # Log the missing URL for analysis
    app.logger.info("404: %s", request.path)
    return render_template("errors/404.html", path=request.path), 404

@app.errorhandler(Exception)
def unhandled(e):
    # Catch any uncaught exception -> 500
    if isinstance(e, HTTPException):
        return e
    app.logger.exception("Unhandled error")
    return render_template("errors/500.html"), 500

Registrar errores

Registra los errores con exc_info=True para capturar el traceback completo. Un RotatingFileHandler evita que los archivos de log crezcan sin límite. En producción, envía los logs a un servicio centralizado.

flask
import logging
from logging.handlers import RotatingFileHandler

handler = RotatingFileHandler("app.log", maxBytes=10*1024*1024, backupCount=5)
handler.setLevel(logging.ERROR)
handler.setFormatter(logging.Formatter(
    "%(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d]"
))
app.logger.addHandler(handler)

@app.errorhandler(500)
def server_error(e):
    app.logger.error("Server error: %s", e, exc_info=True)
    return "Internal error", 500

Manejo de excepciones HTTP

HTTPException es la clase base de los errores HTTP de Werkzeug. Un manejador para HTTPException los captura a la vez, mientras que un manejador específico de subclase (NotFound) tiene precedencia para ese código.

flask
from werkzeug.exceptions import HTTPException, NotFound, BadRequest

@app.errorhandler(HTTPException)
def handle_http_exception(e):
    # All HTTP exceptions in one handler
    return render_template(
        "errors/generic.html",
        code=e.code,
        name=e.name,
        description=e.description,
    ), e.code

# Specific subclasses still work
@app.errorhandler(NotFound)
def specific_404(e):
    return "custom 404", 404
13

JSON y API

jsonify

jsonify convierte dicts/listas de Python en una respuesta JSON con el Content-Type correcto y escape seguro para ASCII. Desde Flask 2.1+ puedes pasar una lista directamente; las versiones anteriores exigen un dict.

flask
from flask import jsonify

@app.route("/api/user")
def api_user():
    return jsonify(username="alice", age=30)

@app.route("/api/users")
def api_users():
    users = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
    return jsonify(users)

# jsonify sets Content-Type: application/json
# and dumps with proper escaping

Devolver JSON

Devolver un dict o una lista directamente es la forma más simple de enviar JSON. Para códigos de estado o headers personalizados, devuelve una tupla. Usa Response + json.dumps solo cuando necesites control total de la serialización.

flask
# Returning a dict/list is auto-converted to JSON (Flask 1.1+)
@app.route("/api/quick")
def quick():
    return {"status": "ok", "count": 42}

# With custom status and headers
@app.route("/api/created", methods=["POST"])
def created():
    return {"id": 99}, 201, {"Location": "/api/99"}

# A Response with JSON body
from flask import Response
import json

@app.route("/api/raw")
def raw():
    return Response(json.dumps({"k": "v"}), mimetype="application/json")

Recibir JSON

get_json() parsea el body como JSON cuando el Content-Type es application/json. Valida siempre la estructura parseada antes de usarla — nunca confíes en la entrada del cliente. Devuelve 400/422 para payloads malformados.

flask
from flask import request, jsonify

@app.route("/api/echo", methods=["POST"])
def echo():
    data = request.get_json()
    if not data:
        return jsonify({"error": "Invalid JSON"}), 400
    return jsonify({"received": data})

# Validate the structure
@app.route("/api/signup", methods=["POST"])
def signup():
    data = request.get_json()
    if not data or "email" not in data:
        return jsonify({"error": "email required"}), 422
    return jsonify({"email": data["email"]}), 201

Blueprint de API

Agrupa las rutas de la API en un blueprint con un url_prefix versionado (/api/v1). Esto separa la lógica de la API de las rutas de páginas y hace explícito el versionado — sube a /api/v2 cuando lleguen cambios que rompan compatibilidad.

flask
from flask import Blueprint, jsonify, request

api = Blueprint("api", __name__, url_prefix="/api/v1")

@api.route("/health")
def health():
    return jsonify(status="ok")

@api.route("/items", methods=["GET", "POST"])
def items():
    if request.method == "POST":
        return jsonify(created=True), 201
    return jsonify(items=[])

# Register: app.register_blueprint(api)

CORS

flask-cors añade el header Access-Control-Allow-Origin para que los navegadores permitan peticiones entre orígenes. Restringe los orígenes a dominios de confianza en producción en lugar de usar el comodín '*'.

flask
pip install flask-cors

from flask import Flask
from flask_cors import CORS

app = Flask(__name__)

# Enable for all routes
CORS(app)

# Or restrict to specific origins
CORS(app, resources={r"/api/*": {"origins": ["https://example.com", "http://localhost:3000"]}})

# Per-route
@app.route("/api/public")
@cross_origin(origins="*")
def public():
    return {"data": "open"}

Respuestas de error de la API

Una función auxiliar mantiene las respuestas de error uniformes en los endpoints — misma forma, mismos nombres de clave. Un cuerpo de error consistente facilita mucho el manejo de errores del lado del cliente. Incluye detalles que ayuden a depurar sin filtrar secretos.

flask
from flask import jsonify, abort

def api_error(message, status=400, **extra):
    body = {"error": message}
    body.update(extra)
    return jsonify(body), status

@app.route("/api/users/<int:id>")
def get_user(id):
    user = find_user(id)
    if not user:
        return api_error("User not found", 404, user_id=id)
    return jsonify(user.serialize())

# Consistent error shape across the API:
# {"error": "User not found", "user_id": 1}
14

Subida de archivos

Subida básica

La etiqueta del formulario necesita enctype=multipart/form-data para subir archivos. Fija MAX_CONTENT_LENGTH para rechazar subidas demasiado grandes con un 413 antes de leer el body por completo — esto protege al servidor.

flask
from flask import request
import os

app.config["UPLOAD_FOLDER"] = "uploads"
app.config["MAX_CONTENT_LENGTH"] = 16 * 1024 * 1024  # 16 MB

@app.route("/upload", methods=["POST"])
def upload():
    file = request.files["file"]
    file.save(os.path.join(app.config["UPLOAD_FOLDER"], file.filename))
    return "uploaded"

# HTML form must include enctype:
# <form method="POST" enctype="multipart/form-data">
#   <input type="file" name="file">
#   <button>Upload</button>
# </form>

Nombre de archivo seguro

secure_filename elimina el directory traversal y los caracteres inseguros de los nombres de archivo suministrados por el usuario. No garantiza unicidad — añade un UUID o comprueba colisiones si sobrescribir es un riesgo.

flask
from werkzeug.utils import secure_filename
import os

@app.route("/upload", methods=["POST"])
def upload():
    f = request.files.get("file")
    if not f:
        return "no file", 400

    safe = secure_filename(f.filename)  # "my file!!/x.txt" -> "my_file__x.txt"
    if not safe:
        return "invalid filename", 400

    f.save(os.path.join("uploads", safe))
    return f"saved as {safe}"

Múltiples archivos

Usa request.files.getlist('files') con un input que tenga el atributo multiple para aceptar varios archivos a la vez. Valida la extensión y el tamaño de cada archivo antes de guardar.

flask
from flask import request

@app.route("/upload-many", methods=["POST"])
def upload_many():
    files = request.files.getlist("files")
    saved = []
    for f in files:
        if f and f.filename:
            name = secure_filename(f.filename)
            f.save(os.path.join("uploads", name))
            saved.append(name)
    return {"saved": saved}

# <form method="POST" enctype="multipart/form-data">
#   <input type="file" name="files" multiple>
# </form>

Subida con WTForms

El FileField de Flask-WTF valida la extensión y la presencia de la subida. La etiqueta del formulario debe incluir enctype=multipart/form-data. El archivo subido es accesible en form.foto.data.

flask
from flask_wtf import FlaskForm
from flask_wtf.file import FileField, FileRequired, FileAllowed

class PhotoForm(FlaskForm):
    photo = FileField("Photo", validators=[
        FileRequired(),
        FileAllowed(["jpg", "jpeg", "png"], "Images only"),
    ])
    submit = SubmitField("Upload")

@app.route("/photo", methods=["GET", "POST"])
def photo():
    form = PhotoForm()
    if form.validate_on_submit():
        f = form.photo.data
        f.save(os.path.join("uploads", secure_filename(f.filename)))
        return "uploaded"
    return render_template("photo.html", form=form)

Validar tipo y tamaño del archivo

Valida tanto la extensión como la longitud del contenido antes de guardar. MAX_CONTENT_LENGTH rechaza temprano las peticiones enormes, pero las comprobaciones por archivo dan control más fino. Para mayor seguridad, inspecciona los magic bytes del archivo, no solo la extensión.

flask
import os
from flask import request

ALLOWED = {".png", ".jpg", ".jpeg", ".gif", ".pdf"}
MAX_SIZE = 5 * 1024 * 1024  # 5 MB

@app.route("/upload", methods=["POST"])
def upload():
    f = request.files.get("file")
    if not f or not f.filename:
        return "no file", 400

    ext = os.path.splitext(f.filename)[1].lower()
    if ext not in ALLOWED:
        return "file type not allowed", 415

    f.stream.seek(0, 2)        # seek to end
    size = f.stream.tell()
    f.stream.seek(0)
    if size > MAX_SIZE:
        return "file too large", 413

    f.save(os.path.join("uploads", secure_filename(f.filename)))
    return "ok"
15

Cookies y sesiones

Fijar cookies

Las cookies se fijan en el objeto de respuesta vía set_cookie. Fija httponly=True para impedir que JavaScript las lea (defensa XSS), secure=True para solo HTTPS, y samesite='Lax' o 'Strict' para la defensa CSRF.

flask
from flask import make_response

@app.route("/set-cookie")
def set_cookie():
    resp = make_response("cookie set")
    resp.set_cookie("user", "alice", max_age=3600, httponly=True)
    resp.set_cookie("theme", "dark", path="/", secure=True, samesite="Lax")
    return resp

# max_age in seconds; expires sets a datetime
# httponly blocks JS access; secure requires HTTPS
# samesite: "Lax" (default), "Strict", or "None"

Leer cookies

request.cookies es un ImmutableMultiDict de solo lectura con las cookies enviadas por el navegador. Usa .get() con un valor por defecto en lugar de indexar, ya que una cookie puede no existir. La modificación de cookies ocurre en la respuesta.

flask
from flask import request

@app.route("/show-cookies")
def show_cookies():
    user = request.cookies.get("user", "guest")
    theme = request.cookies.get("theme", "light")
    all_cookies = request.cookies.to_dict()
    return f"user={user}, theme={theme}"

# request.cookies is a read-only dict
# use .get() with a default to avoid KeyError

Objeto Session

session es una cookie firmada que almacena un dict serializado. Como está firmada con secret_key, los usuarios no pueden manipularla, pero SÍ pueden leerla — así que nunca guardes contraseñas ni secretos en la sesión.

flask
from flask import session

app.secret_key = "a-very-secret-string"

@app.route("/login")
def login():
    session["user_id"] = 1
    session["role"] = "admin"
    return "logged in"

@app.route("/dashboard")
def dashboard():
    if "user_id" not in session:
        return "please log in", 401
    return f"user {session['user_id']}"

@app.route("/logout")
def logout():
    session.pop("user_id", None)
    return "logged out"

Clave secreta

secret_key firma las cookies de sesión y los tokens CSRF. Usa un valor largo y aleatorio, y cárgalo del entorno para que no se suba al control de código. Todas las instancias de la app deben compartir la misma clave.

flask
import os
from flask import Flask

app = Flask(__name__)

# Generate a strong random key
app.secret_key = os.urandom(32)

# Or load from environment (recommended for production)
app.secret_key = os.environ.get("SECRET_KEY")

# For multiple workers, all must share the same key
# so sessions survive being routed to different processes.
# A key of at least 32 random bytes is recommended.

Mensajes flash

flash guarda un mensaje en la sesión que sobrevive a una redirección y se muestra en la siguiente petición. Llama a get_flashed_messages en la plantilla para recuperarlos y borrarlos. with_categories permite estilizar por tipo.

flask
from flask import flash, redirect, url_for, render_template

app.secret_key = "secret"   # flash uses the session

@app.route("/save", methods=["POST"])
def save():
    flash("Saved successfully!", "success")
    return redirect(url_for("index"))

# In the template:
# {% with messages = get_flashed_messages(with_categories=true) %}
#   {% for category, message in messages %}
#     <div class="alert alert-{{ category }}">{{ message }}</div>
#   {% endfor %}
# {% endwith %}

Configuración de la sesión

Por defecto las sesiones se basan en cookies y expiran al cerrar el navegador. Fija session.permanent=True y PERMANENT_SESSION_LIFETIME para extenderlas. Flask-Session mueve el almacenamiento al servidor (Redis, sistema de archivos) para sesiones mayores o más seguras.

flask
app.config.update(
    SECRET_KEY="secret",
    SESSION_COOKIE_NAME="sid",
    SESSION_COOKIE_HTTPONLY=True,
    SESSION_COOKIE_SECURE=True,     # HTTPS only
    SESSION_COOKIE_SAMESITE="Lax",
    PERMANENT_SESSION_LIFETIME=3600,  # seconds
    SESSION_TYPE="redis",            # needs Flask-Session
)

# Mark a session as permanent
from flask import session
from datetime import timedelta

@app.route("/remember")
def remember():
    session.permanent = True
    session["user"] = "alice"
    return "remembered for 1 hour"
16

Hooks before/after request

before_request

Los manejadores before_request corren antes de cada vista. Úsalos para comprobaciones de autenticación, modo mantenimiento o cargar estado compartido en g. Devolver un valor se salta la vista y usa esa respuesta directamente.

flask
from flask import g, request

@app.before_request
def check_maintenance():
    if app.config.get("MAINTENANCE"):
        return "Site under maintenance", 503

@app.before_request
def load_user():
    token = request.headers.get("Authorization")
    if token:
        g.user = verify_token(token)

# Return a value to short-circuit the request

after_request

Los manejadores after_request corren después de la vista, recibiendo y devolviendo la respuesta. Son perfectos para añadir headers, logging o caché. Si ocurre una excepción no manejada, after_request se omite.

flask
@app.after_request
def add_security_headers(resp):
    resp.headers["X-Content-Type-Options"] = "nosniff"
    resp.headers["X-Frame-Options"] = "SAMEORIGIN"
    return resp

@app.after_request
def log_response(resp):
    app.logger.info("%s %s -> %s", request.method, request.path, resp.status_code)
    return resp

# Must take and return a Response object

teardown_request

teardown_request corre al final de cada petición, incluso ante errores — a diferencia de after_request. Recibe la excepción (o None) y es el lugar adecuado para liberar recursos como conexiones de base de datos o manejadores de archivos.

flask
import sqlite3
from flask import g

def get_db():
    if "db" not in g:
        g.db = sqlite3.connect("app.db")
    return g.db

@app.teardown_request
def close_db(exc):
    db = g.pop("db", None)
    if db is not None:
        db.close()

# teardown_request always runs, even if the view raised

before_first_request (obsoleto)

before_first_request se eliminó en Flask 2.3 porque rompe con los servidores asíncronos modernos y las configuraciones multiproceso. Ejecuta la configuración única dentro de un contexto de app en el momento de la importación o en un comando CLI.

flask
# Flask 2.3+ removed before_first_request.
# Old code:
# @app.before_first_request
# def init():
#     warm_cache()

# Modern alternative: use the app context at startup
with app.app_context():
    warm_cache()

# Or a CLI command run once during deployment
@app.cli.command("init")
def init_cmd():
    warm_cache()

Modificar la respuesta

Varios manejadores after_request se encadenan en orden inverso de registro. Cada uno debe devolver una respuesta. Son útiles para headers de seguridad, directivas de caché e IDs de trazado.

flask
@app.after_request
def no_cache(resp):
    resp.headers["Cache-Control"] = "no-store"
    resp.headers["Pragma"] = "no-cache"
    return resp

@app.after_request
def add_request_id(resp):
    rid = getattr(g, "request_id", "n/a")
    resp.headers["X-Request-ID"] = rid
    return resp

# Multiple after_request handlers run in reverse
# registration order; each receives the previous one's output.

Patrón de conexión a base de datos

Un patrón común: abrir una conexión bajo demanda en get_db (guardada en g) y cerrarla en teardown_appcontext. Esto da a cada petición su propia conexión y garantiza la limpieza incluso ante errores.

flask
import sqlite3
from flask import g, current_app

def get_db():
    if "db" not in g:
        g.db = sqlite3.connect(
            current_app.config["DATABASE"],
            detect_types=sqlite3.PARSE_DECLTYPES,
        )
        g.db.row_factory = sqlite3.Row
    return g.db

@app.teardown_appcontext
def close_db(exc):
    db = g.pop("db", None)
    if db is not None:
        db.close()

@app.route("/users")
def users():
    db = get_db()
    rows = db.execute("SELECT * FROM users").fetchall()
    return {"users": [dict(r) for r in rows]}
17

Comandos CLI

Comandos personalizados

Usa @app.cli.command para registrar un comando CLI, decorado con argumentos y opciones de click. El docstring se convierte en el texto de ayuda. Ejecuta flask --help para listar los comandos disponibles.

flask
import click
from flask import Flask

app = Flask(__name__)

@app.cli.command("create-user")
@click.argument("name")
@click.option("--admin", is_flag=True, default=False)
def create_user(name, admin):
    """Create a new user."""
    role = "admin" if admin else "user"
    click.echo(f"Created {name} as {role}")

# Run: flask create-user alice --admin

flask run

flask run arranca el servidor de desarrollo de Werkzeug. --debug habilita el recargador y el depurador interactivo. --app te permite apuntar a un módulo o factoría. Nunca uses este servidor en producción — es de un solo hilo e inseguro.

flask
# Basic
flask run

# Custom host/port
flask run --host=0.0.0.0 --port=8000

# Enable reloader and debugger
flask run --debug

# Specify the app explicitly
flask --app myapp run
flask --app myapp:create_app run

# With SSL (development)
flask run --cert=cert.pem --key=key.pem

Contexto del shell

shell_context_processor inyecta nombres en el flask shell para que puedas experimentar sin imports. Es inestimable para depurar modelos y ejecutar consultas ad-hoc contra tu app.

flask
from flask import Flask
from models import db, User

app = Flask(__name__)

@app.shell_context_processor
def make_shell_context():
    return {"db": db, "User": User, "app": app}

# flask shell
# >>> User.query.all()
# >>> db.session.add(User(username="x"))

Factoría de aplicación con CLI

Al usar el patrón de factoría, registra los comandos CLI dentro de create_app para que tengan acceso a la app configurada. La opción --app de Flask detecta la factoría y la invoca por ti.

flask
# myapp/__init__.py
from flask import Flask

def create_app():
    app = Flask(__name__)
    app.config.from_object("config.Config")

    @app.cli.command("init-db")
    def init_db():
        """Initialize the database."""
        click.echo("Initialized")

    return app

# Run: flask --app myapp init-db
# The factory is detected automatically.

Grupos de CLI

Agrupa comandos relacionados bajo un padre con @app.cli.group. Los subcomandos se registran en el grupo, manteniendo la CLI organizada: flask db init, flask db migrate, etc.

flask
import click
from flask import Flask

app = Flask(__name__)

@app.cli.group("db")
def db_group():
    """Database commands."""
    pass

@db_group.command("init")
def db_init():
    click.echo("DB initialized")

@db_group.command("drop")
def db_drop():
    click.echo("DB dropped")

# flask db init
# flask db drop

Variables de entorno

FLASK_APP y FLASK_DEBUG configuran la CLI. Usa .flaskenv para ajustes de desarrollo compartidos y .env para secretos (ambos se cargan automáticamente si python-dotenv está instalado). Mantén los secretos fuera de .flaskenv ya que normalmente se sube al repositorio.

flask
# Flask reads these env vars:
# FLASK_APP      -> module/app to run (app.py, myapp, myapp:create_app)
# FLASK_DEBUG    -> 1/0 to toggle debug mode
# FLASK_ENV      -> development/production (deprecated, use FLASK_DEBUG)
# FLASK_RUN_PORT -> default port
# FLASK_RUN_HOST -> default host

# .env or .flaskenv files are auto-loaded by python-dotenv
# .flaskenv (committed): FLASK_APP=app.py
# .env (gitignored): SECRET_KEY=..., DATABASE_URL=...

# Prefer app.config.from_envvar or from_object for app secrets.
18

Pruebas

Fundamentos del test client

test_client() devuelve un cliente que hace peticiones sin red. Fija TESTING=True para mejores mensajes de error y desactivar la captura de errores. Usa un fixture para que cada prueba obtenga una app nueva.

flask
import pytest
from myapp import create_app

@pytest.fixture()
def client():
    app = create_app()
    app.config["TESTING"] = True
    with app.test_client() as client:
        with app.app_context():
            pass  # init DB here
        yield client

def test_home(client):
    resp = client.get("/")
    assert resp.status_code == 200
    assert b"Hello" in resp.data

Hacer peticiones en las pruebas

El test client imita a un navegador: get/post/put/delete con data (formulario), json, query_string y headers. Usa resp.get_json() para parsear una respuesta JSON y resp.headers para inspeccionarlos.

flask
def test_get(client):
    resp = client.get("/users/1")
    assert resp.status_code == 200

def test_post_form(client):
    resp = client.post("/login", data={"username": "a", "password": "b"})
    assert resp.status_code == 302  # redirect

def test_post_json(client):
    resp = client.post("/api/echo", json={"key": "value"})
    assert resp.get_json() == {"received": {"key": "value"}}

def test_query(client):
    resp = client.get("/search?q=flask&page=2")
    assert resp.status_code == 200

def test_headers(client):
    resp = client.get("/", headers={"X-Test": "1"})

Probar la API JSON

Pasa json=... para enviar un body JSON con el Content-Type correcto. Haz aserciones sobre el estado, el body JSON parseado y headers como Location. Probar tanto los caminos de éxito como de error garantiza que la API se comporte consistentemente.

flask
def test_create_user(client):
    resp = client.post(
        "/api/users",
        json={"username": "alice", "email": "[email protected]"},
    )
    assert resp.status_code == 201
    body = resp.get_json()
    assert body["username"] == "alice"
    assert "id" in body
    assert resp.headers["Location"].endswith(str(body["id"]))

def test_error(client):
    resp = client.post("/api/users", json={})
    assert resp.status_code == 422
    assert "error" in resp.get_json()

Fixtures con pytest

Los fixtures proporcionan preparación reutilizable: una base de datos en memoria, un test client y un CLI runner. Entrega el recurso con yield y limpia después. test_cli_runner() invoca comandos CLI en las pruebas y comprueba su salida y código de salida.

flask
import pytest
from myapp import create_app, db

@pytest.fixture()
def app():
    app = create_app()
    app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///:memory:"
    with app.app_context():
        db.create_all()
        yield app
        db.drop_all()

@pytest.fixture()
def client(app):
    return app.test_client()

@pytest.fixture()
def runner(app):
    return app.test_cli_runner()

def test_cli(runner):
    result = runner.invoke(args=["create-user", "alice"])
    assert result.exit_code == 0

Base de datos de prueba

Usa una base de datos SQLite en memoria para pruebas rápidas y aisladas. Crea las tablas y siembra los datos dentro del fixture, y luego lo elimina por completo. Cada prueba empieza con una pizarra limpia, evitando la contaminación entre pruebas.

flask
import pytest
from myapp import create_app, db
from myapp.models import User

@pytest.fixture()
def app():
    app = create_app()
    app.config["TESTING"] = True
    app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///:memory:"
    with app.app_context():
        db.create_all()
        db.session.add(User(username="alice"))
        db.session.commit()
        yield app
        db.session.remove()
        db.drop_all()

def test_user_count(app):
    with app.app_context():
        assert User.query.count() == 1

Mocking

patch reemplaza las llamadas externas (HTTP, correo, colas) con mocks para que las pruebas sigan siendo rápidas y deterministas. Verifica que el mock fue llamado con los argumentos esperados. Parchea siempre donde se busca el nombre, no donde se define.

flask
from unittest.mock import patch, MagicMock
import myapp

def test_external_call(client):
    with patch("myapp.requests.get") as mock_get:
        mock_get.return_value = MagicMock(status_code=200, json=lambda: {"ok": True})
        resp = client.get("/proxy")
        assert resp.status_code == 200
        mock_get.assert_called_once()

def test_email(client):
    with patch("myapp.send_email") as mock_send:
        client.post("/register", data={"email": "[email protected]"})
        mock_send.assert_called_once_with("[email protected]", "Welcome!")
19

Despliegue

Advertencia sobre servidores de producción

El servidor de desarrollo de Werkzeug es de un solo hilo e inseguro — nunca lo expongas a internet. Usa un servidor WSGI de producción (Gunicorn, uWSGI, Waitress) detrás de un proxy inverso. El depurador de debug es un riesgo de ejecución remota de código.

flask
# WARNING: Flask's built-in server is for development only!
# app.run() / flask run -> single-threaded, no security, not scalable

# For production use a WSGI server:
# - Gunicorn (Linux/macOS)
# - uWSGI
# - Waitress (Windows-friendly)
# Behind a reverse proxy (Nginx, Apache, Caddy)

# The dev server also enables the interactive debugger
# when debug=True, which allows arbitrary code execution.
# NEVER deploy with debug=True.

Gunicorn

Gunicorn es el servidor WSGI más popular para Linux/macOS. La fórmula (2 × CPU + 1) workers es un buen punto de partida. Detrás de Nginx, enlaza a 127.0.0.1 y deja que el proxy maneje el TLS y los archivos estáticos.

flask
pip install gunicorn

# Basic
gunicorn "app:app"

# With factory
gunicorn "myapp:create_app()"

# Workers and binding
gunicorn -w 4 -b 0.0.0.0:8000 "app:app"

# With timeout and logging
gunicorn -w 4 -b 0.0.0.0:8000 --timeout 120 --access-logfile - "app:app"

# Recommended workers: (2 * CPU) + 1
# Use --preload to share memory, or -k gevent for async.

uWSGI

uWSGI es un servidor WSGI de alto rendimiento y muy configurable. El proceso master gestiona los workers; vacuum limpia al salir. Emparéjalo con Nginx usando el protocolo uwsgi para el mejor rendimiento.

flask
pip install uwsgi

# Command line
uwsgi --http 0.0.0.0:8000 --module app:app --processes 4 --threads 2

# INI config (uwsgi.ini)
# [uwsgi]
# module = app:app
# http = 0.0.0.0:8000
# processes = 4
# threads = 2
# master = true
# vacuum = true
# die-on-term = true

# Run: uwsgi uwsgi.ini

Proxy inverso (Nginx)

Nginx se sitúa delante de Gunicorn: sirve los archivos estáticos directamente (más rápido), termina el TLS y reenvía las peticiones al servidor WSGI. Los headers X-Forwarded-* permiten a Flask ver la IP y el esquema reales del cliente — fija ProxyFix para confiar en ellos.

flask
# /etc/nginx/sites-available/myapp
server {
    listen 80;
    server_name example.com;

    location /static/ {
        alias /path/to/app/static/;
        expires 30d;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;
    }
}

Docker

Una imagen base de Python ligera mantiene la imagen pequeña. Instala las dependencias antes de copiar el código para aprovechar la caché de capas de Docker. Pasa los secretos vía variables de entorno (--env-file), nunca los hornees en la imagen.

flask
# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "app:app"]

# .dockerignore
# __pycache__/
# venv/
# *.pyc
# .env

# Build and run
# docker build -t myapp .
# docker run -p 8000:8000 --env-file .env myapp

Configuración de entorno

Apila la configuración: valores por defecto en el código, anulaciones específicas por entorno y secretos de instancia desde variables de entorno. Esto mantiene los secretos fuera del control de código y permite que una sola base de código corra en dev, staging y producción.

flask
import os
from flask import Flask

app = Flask(__name__)
app.config.from_object("config.DefaultConfig")

# Override with environment-specific config
env = os.environ.get("FLASK_ENV", "development")
app.config.from_object(f"config.{env.title()}Config")

# Then instance-specific secrets from env vars
app.config["SECRET_KEY"] = os.environ["SECRET_KEY"]
app.config["SQLALCHEMY_DATABASE_URI"] = os.environ["DATABASE_URL"]

# Use python-dotenv for local .env files
from dotenv import load_dotenv
load_dotenv()
20

Configuración

Objeto de configuración

Define la configuración como clases que heredan de un Config base. Sobrescribe solo lo que cambia por entorno. from_object copia los atributos en mayúsculas a app.config, así que los helpers en minúsculas se ignoran.

flask
class Config:
    DEBUG = False
    TESTING = False
    SECRET_KEY = "change-me"
    SQLALCHEMY_DATABASE_URI = "sqlite:///app.db"

class DevelopmentConfig(Config):
    DEBUG = True
    SECRET_KEY = "dev-secret"

class ProductionConfig(Config):
    DEBUG = False
    SECRET_KEY = os.environ["SECRET_KEY"]

class TestingConfig(Config):
    TESTING = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"

app.config.from_object(DevelopmentConfig)

Variables de entorno

Usa os.environ para los secretos de modo que nunca vivan en el código. from_envvar carga un archivo Python apuntado por una variable de entorno — útil para anulaciones específicas del despliegue. python-dotenv carga un archivo .env para el desarrollo local.

flask
import os
from flask import Flask

app = Flask(__name__)

# Read individual values
app.config["SECRET_KEY"] = os.environ.get("SECRET_KEY", "dev")
app.config["DATABASE_URL"] = os.environ.get("DATABASE_URL", "sqlite:///app.db")

# Load a whole config file from an env var path
# export MYAPP_SETTINGS=/etc/myapp/prod.py
app.config.from_envvar("MYAPP_SETTINGS", silent=True)

# python-dotenv loads .env automatically if installed
from dotenv import load_dotenv
load_dotenv()

Carpeta de instancia

La carpeta de instancia guarda archivos específicos del despliegue (secretos, configuración) fuera del control de versiones. Fija instance_relative_config=True y carga con from_pyfile. Esto separa de forma limpia el código de la configuración del entorno.

flask
# The instance/ folder sits outside the package, not in VCS.
# Flask searches it automatically for config files.

app = Flask(__name__, instance_relative_config=True)

# Load from instance/config.py
app.config.from_pyfile("config.py", silent=True)

# instance/config.py (deployment-specific, gitignored)
# SECRET_KEY = "real-production-key"
# SQLALCHEMY_DATABASE_URI = "postgresql://user:pass@db/app"

# Access the path
print(app.instance_path)  # /abs/path/to/instance

Configuración desde archivo

from_object importa un módulo o ruta de objeto; from_pyfile carga un archivo absoluto; from_file (Flask 2.0+) usa una función cargadora, soportando JSON, TOML o YAML. Elige un formato y sé consistente.

flask
# config.py
DEBUG = True
SECRET_KEY = "dev"
SQLALCHEMY_DATABASE_URI = "sqlite:///dev.db"

# Load a Python file
app.config.from_object("config")

# Load by path
app.config.from_pyfile("/etc/myapp/config.py")

# Load from a JSON file
app.config.from_file("config.json", load=json.load)

# config.json
# { "DEBUG": true, "SECRET_KEY": "dev" }

Desarrollo vs producción

Cambia las configuraciones por variable de entorno para que el mismo código corra en todas partes. La producción debe desactivar el debug (el depurador es un agujero de seguridad) y usar una base de datos real. Registra una advertencia si el debug está activado en producción.

flask
import os
from flask import Flask

env = os.environ.get("FLASK_ENV", "development")

configs = {
    "development": DevelopmentConfig,
    "production": ProductionConfig,
    "testing": TestingConfig,
}

app = Flask(__name__)
app.config.from_object(configs[env])

# In production, never enable debug:
if app.config["DEBUG"]:
    print("WARNING: running in debug mode!")

Configuración de logging

Configura el logging solo cuando no estés en modo debug (Flask escribe en stderr por defecto en debug). RotatingFileHandler evita el crecimiento ilimitado de los logs. En producción, considera el logging JSON estructurado para los servicios de agregación.

flask
import logging
from logging.handlers import RotatingFileHandler

if not app.debug:
    handler = RotatingFileHandler("app.log", maxBytes=10*1024*1024, backupCount=5)
    handler.setFormatter(logging.Formatter(
        "%(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d]"
    ))
    handler.setLevel(logging.INFO)
    app.logger.addHandler(handler)
    app.logger.setLevel(logging.INFO)

# In a view
@app.route("/")
def index():
    app.logger.info("Index page accessed")
    return "Hello"

# Flask's logger is a standard logging.Logger

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.