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.
# 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.
# 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.pyEntorno 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.
# 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.txtEstructura 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.
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 handlersPatró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.
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_appAnatomí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.
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!"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.
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.
@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 codeURLs ú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.
@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 FoundVerbos 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.
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.
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/bobVarias 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.
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.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.
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).
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.
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.
@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", 418Respuestas 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.
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.
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 respObjeto 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.
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.
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.
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.
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 dataHeaders 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.
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 '?'.
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(),
}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.
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.
# 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.
{# 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.
{# 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.
{{ 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.
{# 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>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.
# 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é.
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.jsCarpeta 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.
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.cssFavicon
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.
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.
# 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 }}">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.
# 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.
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.
# 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.
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.
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"), 403Blueprints 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.
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/infoContextos (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.
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.
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.
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.
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í.
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.
# 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)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.
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.
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.
# 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.
# 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.
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 userMigraciones 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.
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 revisionWTForms (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.
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.
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.
{# 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.
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 POSTValidadores 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.
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.
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)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.
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.
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.
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.
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 decoratorLogout
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).
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 cookiesRecué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.
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 %}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.
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 ErrorPá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.
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"), 500Manejadores 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.
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.
@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"), 500Registrar 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.
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", 500Manejo 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.
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", 404JSON 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.
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 escapingDevolver 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.
# 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.
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"]}), 201Blueprint 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.
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 '*'.
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.
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}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.
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.
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.
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.
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.
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"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.
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 requestafter_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.
@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 objectteardown_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.
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 raisedbefore_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 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.
@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.
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]}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.
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 --adminflask 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.
# 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.pemContexto 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.
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.
# 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.
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 dropVariables 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 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.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.
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.dataHacer 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.
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.
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.
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 == 0Base 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.
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() == 1Mocking
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.
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!")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.
# 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.
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.
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.iniProxy 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.
# /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.
# 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 myappConfiguració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.
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()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.
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.
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.
# 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/instanceConfiguració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.
# 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.
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.
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.LoggerFragmentos de Flask relacionados
Copy-paste ready code for common tasks.
Routing
Define routes with methods and dynamic parameters.
Request and Response
Access request data and build custom responses.
Jinja2 Templates
Render templates with context and template inheritance.
Blueprints
Organize an app into modular blueprints.
Session
Store per-user data in signed session cookies.
Error Handling
Register custom error handlers for HTTP exceptions.
Flask-SQLAlchemy
Define models and query them with Flask-SQLAlchemy.
Custom Decorators
Build decorators to gate or augment view functions.
Was this helpful?