Construir

Blueprints en Flask: organizar un proyecto que crece

Cómo dividir una app Flask grande en módulos con blueprints, en lugar de un solo app.py gigante. Estructura de carpetas, registro y cómo quedan las rutas.

Al principio, toda tu app Flask cabe en un app.py. Pero cuando crece —usuarios, productos, pagos, admin—, ese archivo se vuelve un monstruo de cientos de líneas imposible de mantener. La solución de Flask son los blueprints: módulos que agrupan rutas relacionadas en archivos separados. Aquí cómo usarlos para ordenar un proyecto.

El problema que resuelven

Un app.py con todo mezclado:

@app.route("/login") ...
@app.route("/productos") ...
@app.route("/admin/usuarios") ...
@app.route("/carrito") ...
# ...y 40 rutas más

Encontrar algo es un suplicio, y dos personas no pueden trabajar sin pisarse. Los blueprints parten eso en grupos: un archivo para auth, otro para productos, otro para admin.

La estructura de carpetas

mi_app/
├── app.py              # crea la app y registra los blueprints
├── blueprints/
│   ├── auth.py         # rutas de login, registro, logout
│   ├── productos.py    # rutas de productos
│   └── admin.py        # rutas de administración
└── templates/

Crear un blueprint

Cada archivo de blueprint define su propio grupo de rutas. En blueprints/auth.py:

from flask import Blueprint, render_template, request

auth = Blueprint("auth", __name__)

@auth.route("/login", methods=["GET", "POST"])
def login():
    return render_template("login.html")

@auth.route("/logout")
def logout():
    return "Sesión cerrada"

Fíjate en el cambio clave: en vez de @app.route, usas @auth.route. El decorador cuelga de tu blueprint (auth), no de la app directamente. El Blueprint("auth", __name__) le da un nombre interno (“auth”) que luego importa para url_for.

Registrar los blueprints en la app

En app.py, creas la app e importas y registras cada blueprint:

from flask import Flask
from blueprints.auth import auth
from blueprints.productos import productos
from blueprints.admin import admin

app = Flask(__name__)

app.register_blueprint(auth)
app.register_blueprint(productos)
app.register_blueprint(admin)

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

register_blueprint conecta cada módulo con la app. Ahora app.py queda limpio: solo crea la app y ensambla las piezas, sin una sola ruta propia.

El prefijo de URL: lo más útil

Puedes poner un prefijo común a todas las rutas de un blueprint al registrarlo. Muy práctico para la sección de admin:

app.register_blueprint(admin, url_prefix="/admin")

Con eso, una ruta definida como @admin.route("/usuarios") dentro del blueprint se sirve en /admin/usuarios. No tienes que repetir /admin/ en cada ruta del archivo — lo pones una vez al registrar. Ordena las URLs y ahorra escritura.

url_for con blueprints: el detalle que confunde

Al generar enlaces con url_for, ahora debes incluir el nombre del blueprint antes del nombre de la función, separado por un punto:

# Antes (sin blueprint):
url_for("login")

# Con blueprint "auth":
url_for("auth.login")

Ese auth.login —nombre del blueprint, punto, nombre de la función— es el tropiezo número uno al migrar a blueprints. Si olvidas el prefijo, obtienes un error de “endpoint no encontrado”. Lo mismo en las plantillas: {{ url_for('auth.login') }}.

Resumen

  • Un blueprint agrupa rutas relacionadas en su propio archivo.
  • Dentro, usas @mi_blueprint.route en vez de @app.route.
  • En app.py, register_blueprint() ensambla cada uno.
  • url_prefix="/admin" pone un prefijo común a todo un grupo.
  • En url_for, usa "blueprint.funcion" (con el punto).

Con blueprints, un proyecto de 40 rutas se vuelve manejable: cada sección en su archivo, el app.py limpio, y varias personas pueden trabajar sin chocar. Es el paso natural cuando tu app deja de ser pequeña. Si aún no tienes claro cómo arrancó esa app, empieza por tu primera app Flask con SQLite.


¿Quieres que cada blueprint tenga sus propias plantillas y archivos estáticos, o manejar errores por blueprint? Escríbeme desde contacto y lo cubrimos.

← Más de Construir