1. Introducción
El PDF del documento está |AQUÍ|.
Los códigos del documento están |AQUÍ|.
Este documento es un producto de la IA Claude de Anthropic. Sigue al documento “Introducción paso a paso al framework web [Spring MVC]” (2026), que a su vez siguió a los documentos “Introducción paso a paso al framework web [ASP.NET Core MVC]” y “Introducción paso a paso al framework web [NestJS]” (2026). Este documento adapta el curso de [Spring MVC] al entorno [Python]:
- el framework [Spring MVC] y el lenguaje [Java] se reemplazan por el framework [Flask] 3.1 y el lenguaje [Python] (versión 3.12 o posterior);
- las vistas [Thymeleaf] se reemplazan por vistas [Jinja2], el motor de vistas de [Flask];
- la validación con [Bean Validation] se reemplaza por la biblioteca [Pydantic] (parámetros de las acciones) y por la biblioteca [WTForms] (formularios HTML);
- [Spring Security] se reemplaza por unas pocas decenas de líneas de código [Python] escritas para este fin, que se apoyan en las bibliotecas [PyJWT] (los tokens JWT) y [bcrypt] (el hash de contraseñas);
- el ORM [Hibernate], y [Spring Data JPA] se reemplazan por un ORM y [SQLAlchemy], siempre sobre [MySQL].
El documento sigue de cerca la estructura del curso de [Spring MVC]: primero, numerosos proyectos pequeños, cada uno centrado en un concepto específico, seguidos de un caso de estudio completo (una aplicación web para gestionar citas en un consultorio médico) con todos los archivos comentados en detalle. Los ejemplos tienen los mismos números y tratan los mismos temas que en los cursos de [Spring MVC] y [ASP.NET Core MVC]: un lector familiarizado con alguno de esos cursos puede comparar los frameworks ejemplo por ejemplo. Sin embargo, esto no es necesario: este documento se basta a sí mismo y no supone ningún conocimiento previo de [Spring] ni de [ASP.NET]. Los únicos requisitos previos son una comprensión básica de la programación web (el protocolo HTTP, el lenguaje HTML) y del lenguaje [Python] (funciones, clases, diccionarios, módulos). Un curso anterior del autor, Introducción al lenguaje Python y al framework web Flask mediante ejemplos (2020), presenta el propio lenguaje [Python], para quienes necesiten aprenderlo primero.
1.1. El papel de Flask en una aplicación web
Una aplicación web suele construirse en capas, y cada capa se comunica solo con las capas vecinas:

- la capa web recibe las solicitudes HTTP del navegador y le devuelve páginas HTML. Es la capa que [Flask] nos ayuda a escribir;
- la capa de negocio contiene las reglas de negocio de la aplicación (por ejemplo, “un paciente solo puede tener una cita próxima”). No sabe nada de la web: podría servir igualmente a una aplicación de línea de comandos;
- la capa de acceso a datos (capa [DAO], por [Data Access Object]) lee y escribe en la base de datos. Usaremos [SQLAlchemy], un ORM ([Object Relational Mapper]) que asocia las filas de las tablas con objetos [Python].
La propia capa web sigue el modelo [MVC] ([Model – View – Controller]):
- el controlador (C) es un conjunto de funciones [Python], llamadas acciones, cada una de las cuales procesa un tipo de solicitud (por ejemplo, [GET /schedule]). Una acción lee los parámetros de la solicitud, invoca la capa de negocio y luego elige la vista que se mostrará;
- el modelo (M) es el conjunto de datos que la acción pasa a la vista;
- la vista (V) es un archivo [Jinja2] (extensión [.html]): una página HTML que contiene expresiones [{{ ... }}] e instrucciones [{% ... %}] ([{% if %}], [{% for %}]...), que el motor [Jinja2] reemplaza con los datos del modelo.
Una nota sobre la terminología, para evitar confusiones: la documentación de [Flask] llama a la función que procesa una solicitud “función de vista” (“view function”) y al archivo [Jinja2] “plantilla” (“template”). Este documento usa la terminología del modelo [MVC], así como la de los cursos de [Spring MVC] y [ASP.NET Core MVC] : la función que procesa una solicitud es una acción, el archivo [Jinja2] que genera la página es una vista, y el término “plantilla” designa la vista común de la que heredan las demás páginas (capítulo 4).
El procesamiento de una solicitud sigue los pasos numerados del diagrama:
- 1: El navegador envía una solicitud, por ejemplo HTTP o [GET /schedule?doctorId=1&day=2026-09-26];
- 2: El servidor web recibe la solicitud y se la pasa a la aplicación [Flask]. Durante el desarrollo, este servidor es [Werkzeug], la biblioteca sobre la que se construye [Flask] ; en producción, será un servidor como [Waitress] o [Gunicorn]. [Werkzeug] compara la ruta solicitada con las rutas de la aplicación y selecciona la acción encargada de manejar esta solicitud: es el enrutamiento. Antes de llegar a la acción, la solicitud puede pasar aún por funciones que se ejecutan para todas las solicitudes ([before_request]), que exploraremos en los capítulos siguientes;
- 3: La acción pide a la capa de negocio los datos que necesita; si es necesario, la capa de negocio contacta a la capa [DAO], que consulta la base de datos [MySQL] mediante SQL;
- 4: La acción construye el modelo M de la vista e indica al motor [Jinja2] que genere la página (función [render_template]);
- 5: La página HTML generada por la vista es la respuesta de la acción, que [Flask] devuelve al navegador.
[Flask] es uno de los dos frameworks web más utilizados en el mundo [Python], junto con [Django]. Es libre y de código abierto, y funciona en cualquier lugar donde funcione [Python] ([Windows], [Linux], [macOS]). Es un microframework: su núcleo es deliberadamente pequeño (enrutamiento, solicitudes y respuestas, sesiones, vistas [Jinja2]), y todo lo demás (validación de formularios, acceso a bases de datos, autenticación, etc.) lo resuelven bibliotecas elegidas por el desarrollador. Mientras que [Spring Boot] configura por sí solo un conjunto coherente de componentes, [Flask] permite al desarrollador ensamblar los suyos: la aplicación es más transparente y se puede ver todo lo que ocurre en su interior. Esto es, de hecho, lo que lo convierte en una buena herramienta para aprender: casi nada está oculto. [Flask] puede crear servidores que devuelven JSON a un cliente [JavaScript] ([Angular], [React], [Flutter]...) igual que aplicaciones web tradicionales, en las que el servidor genera las páginas HTML y el navegador se limita a mostrarlas. Este documento examina este segundo caso de uso. Dos conceptos de [Python] se repiten en cada página: los decoradores ([@app.get("/")], [@app.before_request]...), que asocian una función con un rol, y el paso explícito de los objetos que necesita cada función, mientras que [Spring] los inyecta automáticamente.
1.2. Herramientas utilizadas
Los ejemplos se escribieron y probaron con las siguientes herramientas (su instalación se describe en el apéndice):
- [Python] 3.13 (sirve cualquier versión 3.12 o posterior). El instalador de [Python] también proporciona la herramienta [pip], que descarga e instala las bibliotecas, y el módulo [venv], que crea entornos virtuales (más adelante veremos qué son);
- el editor [Visual Studio Code], junto con la extensión [Python] de Microsoft (que también instala la extensión [Pylance], que analiza el código);
- un navegador reciente ([Chrome], [Firefox], [Edge]);
- la herramienta de línea de comandos [curl], que muestra las respuestas HTTP sin procesar (viene incluida en [Windows] 10 y 11);
- el SGBD [MySQL] (o [MariaDB]), por ejemplo, el de [Laragon] en [Windows], a partir del capítulo sobre acceso a datos y para el caso de estudio.
A diferencia del [JDK], que no contiene [Spring], [Python] incluye una biblioteca estándar muy completa; pero [Flask] y las demás bibliotecas del documento no vienen incluidas: [pip] las descarga del repositorio [PyPI] ([Python Package Index]) durante la instalación (por lo que ese día debe estar conectado a Internet). Cada proyecto describe sus bibliotecas en un archivo [requirements.txt]. La tabla siguiente las enumera, junto con las versiones utilizadas:
Biblioteca | Función | Versión |
[Flask] | el framework web: enrutamiento, solicitudes, respuestas, sesiones, vistas; incluye [Werkzeug] (solicitudes HTTP, servidor de desarrollo), [Jinja2] (vistas) y [itsdangerous] (firmas) | 3.1.3 |
[asgiref] | acciones asíncronas ([async def]), instalado por [Flask[async]] (ejemplo 03) | 3.12.1 |
[Pydantic] | Enlace y validación de los parámetros de las acciones (capítulo 3) | 2.13.5 |
[email-validator] | Validación de direcciones de correo electrónico, para [Pydantic] y [WTForms] | 2.3.0 |
[Flask-WTF] | los formularios HTML ([WTForms]) y la protección anti-CSRF (capítulo 4) | 1.3.0 |
[Babel] | Formato de fechas e importes según el idioma (capítulos 3 y 4) | 2.18.0 |
[PyJWT] | Tokens JWT (capítulo 8) | 2.15.0 |
[bcrypt] | Hashes de contraseñas (capítulo 8) | 5.0.0 |
[SQLAlchemy] | ORM, acceso a la base de datos (capítulo 9) | 2.1.1 |
[PyMySQL] | El controlador [MySQL], escrito en [Python] (capítulo 9) | 1.2.3 |
[Waitress] | Un servidor web de producción (caso de estudio) | 3.0.2 |
1.3. Ejecutar el caso de estudio
Nota del revisor: Aconsejo al lector ejecutar de inmediato el caso de estudio tal como se describe a continuación. Una vez que comprenda bien el papel de esta aplicación de citas, pida a su IA favorita que modifique la aplicación de la siguiente manera: a partir de ahora, cada médico podrá:
- definir sus propios horarios de citas entre dos fechas. Esto le permitirá ajustar su agenda según sus necesidades;
- quitar ciertos intervalos horarios del calendario para un día determinado, por ejemplo, si no está disponible por motivos personales;
La modificación no es sencilla porque implica un cambio en la estructura de la base de datos. Pida a la IA que le proporcione el nuevo código de la aplicación y el script SQL para crear la nueva base de datos. Para ello, deberá entregarle el archivo ZIP con el proyecto completo, así como el script SQL de la base de datos anterior.
Además, no he revisado el curso creado por Claude. Él ya había producido los cursos perfectos [NestJS], [ASP.NET Core MVC] y [Spring MVC]. Supuse que lo mismo ocurriría con este. Si tiene algún problema para entender algo, la solución es siempre la misma: pida a su IA favorita que le explique lo que no entiende. Claude, por ejemplo, es muy bueno para esto. Quizá deba “subirle” el ejemplo que no entiende.
Fin de la nota.
El caso de estudio al final de este documento es una aplicación completa. Es probable que los lectores quieran verla en funcionamiento antes de entrar en los detalles del framework: así se ejecuta. Se encuentra en la carpeta [rdvmedecins2-flask], junto a la carpeta [examples]:
Debe tener instalados [Python] (versión 3.12 o posterior), [Visual Studio Code] y [MySQL] (consulte los apéndices). Luego:
- Cree la base de datos [dbrdvmedecins2] ejecutando el script [rdvmedecins2-flask/database/dbrdvmedecins2.sql]. Con [Laragon], abra la herramienta [HeidiSQL] (botón Database) y luego ejecute el script desde el menú File / Run SQL. En la línea de comandos, desde la carpeta [rdvmedecins2-flask]:
- Abra la carpeta [rdvmedecins2-flask] en [Visual Studio Code] (menú File / Open Folder) y luego abra un terminal (menú Terminal / New Terminal);
- cree el entorno virtual de la aplicación y actívelo. Un entorno virtual es una carpeta (aquí, [.venv]) que contiene una copia del intérprete [Python] y las bibliotecas de un proyecto específico, y solo esas bibliotecas: cada proyecto tiene las suyas, en las versiones que le convienen, sin interferir con otros proyectos de la computadora. En [Windows] (símbolo del sistema o terminal de [Visual Studio Code]):
y en [Linux] y [macOS]:
- Una vez activado el entorno, el indicador del terminal comienza con [(.venv)], y los comandos [python] y [pip] son los del entorno. En [Windows], el terminal [PowerShell] a veces se niega a ejecutar el script de activación (mensaje: “Script execution is disabled on this system”): el comando [Set-ExecutionPolicy -Scope CurrentUser RemoteSigned], ingresado una sola vez, lo habilita. [Visual Studio Code] detecta el entorno y ofrece usarlo para el proyecto: debe aceptar (también puede seleccionarlo con el comando de Python: Select Interpreter, Ctrl-Shift-P); los terminales que se abran después lo activan automáticamente;
- Instale las bibliotecas de la aplicación en el entorno virtual:
- Verifique la conexión con la base de datos. La aplicación se conecta a [MySQL] en [localhost], puerto 3306, con el usuario [root] sin contraseña (la configuración predeterminada de [Laragon]). Si su cuenta [root] tiene contraseña, ingrésela en el archivo [config.py] de la aplicación, en la línea [DB_PASSWORD = ""] (por ejemplo, [DB_PASSWORD = "myPassword"]). Para evitar escribir una contraseña en un archivo del proyecto, también puede indicarla en la variable de entorno [FLASK_DB_PASSWORD], que tiene prioridad sobre el archivo: [set FLASK_DB_PASSWORD=myPassword] en [Windows] (símbolo del sistema), [$env:FLASK_DB_PASSWORD="myPassword"] en [PowerShell], [export FLASK_DB_PASSWORD=myPassword] en [Linux] y [macOS];
- inicie la aplicación (en [Linux] y [macOS], [python3] si [python] no existe):
- La aplicación lee la base de datos y luego inicia el servidor de desarrollo de [Flask]. La consola muestra los comandos SQL enviados a la base de datos (aquí se incluyeron solo los principales), seguidos de los mensajes del servidor:
Cada línea de [SQLAlchemy] comienza con la fecha y la hora (reemplazadas aquí por [...]). Muestra que la aplicación ha leído la lista de médicos y clientes (las dos solicitudes SQL), que el servidor escucha en el puerto 8081 en la dirección [127.0.0.1] (es decir, [localhost]), y que se ejecuta en modo debug: la aplicación se reinicia automáticamente cada vez que se modifica un archivo [Python] ([Restarting with stat]: el proceso que vigila los archivos reinicia la aplicación, que vuelve a leer la base de datos), y un error inesperado muestra una página de depuración (el “PIN” oculta esta página de la consola). La advertencia recuerda que este servidor está pensado para el desarrollo, no para producción (el caso de estudio explica cómo usar un servidor de producción);
- Abra la URL [http://localhost:8081] en un navegador:

- Inicie sesión con una de las cuentas de demostración, cada una de las cuales usa su nombre de usuario como contraseña: [admin] (administrador), [pelissier], [tatou], [dupont] (médicos), [martin], [durand], [bistrou], [german] (pacientes). También debe ingresar los caracteres de la imagen, en mayúsculas o minúsculas.
Al iniciarse, la aplicación lee la base de datos: si [MySQL] no está accesible, se detiene de inmediato y la consola muestra el motivo al final de un largo mensaje de error (antes de la línea “Background on this error”). Si el mensaje es [Can't connect to MySQL server on 'localhost' ([Errno 111] Connection refused)] (o [[WinError 10061]] en [Windows]), significa que [MySQL] no se ha iniciado; con [Access denied for user 'root'@'localhost'], significa que la contraseña es incorrecta; con [Unknown database 'dbrdvmedecins2'], que el script SQL no se ha ejecutado; con [ModuleNotFoundError: No module named 'flask'], que el entorno virtual no está activado (o que las bibliotecas no se han instalado en él); con [Address already in use] (o [Port 8081 is in use by another program]), que el puerto 8081 ya está en uso (por la versión [Spring MVC] de la aplicación, por ejemplo). El archivo [README.md] de la aplicación describe otros escenarios. Detenga la aplicación con [Ctrl-C] en el terminal.
El caso de estudio al final del documento muestra cómo usar la aplicación y luego explica cada uno de sus archivos.
1.4. Ejemplos
Los ejemplos se guardan en la carpeta [examples], con una subcarpeta por ejemplo:
Cada ejemplo es una pequeña aplicación ([Flask]) que se ejecuta por sí sola. Todos los ejemplos usan las mismas bibliotecas, descritas en el archivo [examples/requirements.txt]:
- línea 3: [Flask], y lo necesario para escribir acciones asíncronas (el complemento [[async]], que agrega la biblioteca [asgiref]; vea el ejemplo 03);
- líneas 4 a 7: formularios, validación y formato según el idioma;
- líneas 8 y 9: autenticación (capítulo 8);
- líneas 10 y 11: acceso a la base de datos (capítulo 9). El complemento [[rsa]] de [PyMySQL] agrega la biblioteca [cryptography], necesaria para conectarse a un servidor [MySQL] 8 mediante una cuenta protegida con contraseña.
Cada línea tiene la forma [name==version]: el operador [==] exige exactamente esa versión, con la que se probaron los ejemplos. Se podría ser menos estricto ([Flask>=3.1]: versión 3.1 o posterior); sin embargo, una versión futura de una biblioteca puede cambiar su comportamiento, y un curso debe poder reproducirse exactamente tal como está escrito. Las líneas que comienzan con [#] son comentarios.
Para ejecutar los ejemplos, primero cree el entorno virtual de los ejemplos, una sola vez, en la carpeta [examples] (consulte el caso de estudio para los detalles):
([source .venv/bin/activate] en [Linux] y [macOS]). La carpeta [common/bootstrap] contiene el CSS y el framework [Bootstrap], compartidos por los ejemplos que dan formato a sus páginas (a partir del ejemplo 15).
Casi todos los ejemplos tienen la misma estructura. Por ejemplo, la del ejemplo 13:
- [app.py]: el archivo de arranque de la aplicación, que es el que se ejecuta; construye la aplicación e inicia el servidor (vea el ejemplo 01);
- [controllers]: los controladores, es decir, los archivos que contienen las acciones. Es un paquete [Python]: una carpeta que contiene módulos (archivos [.py]), que se pueden importar ([from controllers.views import views]). El archivo [__init__.py], que aquí está vacío, convierte la carpeta en un paquete (se ejecuta la primera vez que se importa el paquete);
- [models]: las clases que describen los modelos (de las acciones y de las vistas);
- [templates]: las vistas [Jinja2] (a partir del capítulo 4). [Flask] las busca en esta carpeta, junto al archivo de la aplicación;
- [static] (a partir del ejemplo 15): archivos que se envían tal cual al navegador (hojas de estilo, imágenes, scripts [JavaScript]).
Para ejecutar un ejemplo, abra un terminal en su carpeta (en [Visual Studio Code]: haga clic derecho en la carpeta del ejemplo y seleccione “Open in the built-in terminal”) y active el entorno virtual del ejemplo si aún no está activo ([..\.venv\Scripts\activate] en [Windows], [source ../.venv/bin/activate] en [Linux], y [macOS]: el entorno se encuentra en la carpeta [examples], que es la carpeta padre de la carpeta del ejemplo), y escriba:
Todos los ejemplos escuchan en el puerto 5000: solo se puede ejecutar uno a la vez. Detenga el servidor con [Ctrl-C] en el terminal. En [macOS], el puerto 5000 a veces ya está ocupado por el “AirPlay Receiver” del sistema (mensaje [Address already in use]): puede desactivarlo en System Settings / General / AirDrop and Handoff, o cambiar el puerto en el archivo [app.py] del ejemplo ([port=5001]).
Cuando abre la carpeta [examples] en [Visual Studio Code], la extensión [Python] sugiere usar el entorno [.venv]: esto permite aprovechar el resaltado de sintaxis, la autocompletación y el reporte de errores en cada archivo. Cada ejemplo se inicia desde su propia carpeta; por eso las importaciones de un ejemplo ([from controllers.views import views]) parten de esa carpeta. [Pylance], que analiza el código a partir de la carpeta abierta ([examples]), puede entonces subrayar esas importaciones señalándolas como no encontradas: esto no afecta la ejecución. Para que [Pylance] las encuentre, basta con abrir la carpeta del propio ejemplo (menú File / Open Folder). Por último, todos los ejemplos se ejecutan en modo debug (vea el ejemplo 01): una aplicación en ejecución se reinicia automáticamente, en aproximadamente un segundo, en cuanto se modifica y guarda uno de sus archivos [Python].
Los ejemplos que usan [Bootstrap] lo encuentran en la carpeta [common/bootstrap], no en la suya: así se garantiza que exista una sola copia de los archivos. Cada uno de estos ejemplos lo invoca mediante la URL [/bootstrap/...], con unas pocas líneas en su archivo [app.py]. Por ejemplo, [15-layout/app.py]:
- Línea 11: la ruta a la carpeta [common/bootstrap]. [__file__] es la ruta del archivo que se está ejecutando ([app.py]); [Path(...).resolve()] la convierte en una ruta absoluta; [.parent] designa la carpeta que lo contiene ([15-layout]), y [.parent.parent] designa la carpeta padre ([examples]). El operador [/] de un objeto [Path] agrega un elemento a la ruta, con el separador correcto ([\] en [Windows], [/] en los demás). Así, la ruta no depende de la carpeta actual: el ejemplo encuentra [Bootstrap] sin importar desde dónde se inicie;
- líneas 20 y 21: un blueprint es un grupo de rutas almacenado en la aplicación (vea el ejemplo 02). Este blueprint no tiene rutas: sirve únicamente para publicar la carpeta [common/bootstrap] (parámetro [static_folder]) bajo la URL [/bootstrap] (parámetro [static_url_path]). Una página puede usar así la hoja de estilo [/bootstrap/css/bootstrap.min.css].
Las demás líneas de este archivo se explicarán en el ejemplo 15.
1.5. Contenido del documento
El documento está estructurado de la siguiente manera:
Capítulo | Contenido | Ejemplos |
Acciones, enrutamiento, respuestas | De la solicitud a la acción: rutas, blueprints, respuestas, redirecciones, servicios compartidos | 01 a 06 |
El modelo de la acción | Parámetros de la solicitud: enlace, conversión, validación con [Pydantic], formularios POST | 07 a 12 |
La vista y su plantilla | [Jinja2], plantilla, macros, formularios [WTForms], validación, PRG, protección anti-CSRF | 13 a 21 |
Internacionalización | Una aplicación en francés e inglés | 22 |
Ámbitos de datos | aplicación, solicitud, sesión, cliente | 23 |
El ciclo de vida de una solicitud | Middleware WSGI, [before_request], [after_request], [teardown_request], convertidores, manejadores de errores | 24 |
Autenticación y autorización | JWT en una cookie, decoradores, roles, CAPTCHA, límites de intentos | 25–27 |
Arquitectura en capas | Web / Negocio / DAO con [SQLAlchemy] y [MySQL] | 28 |
Caso de estudio | La aplicación RdvMedecins, explicada archivo por archivo | - |
Cada ejemplo introduce solo unos pocos conceptos nuevos, y los capítulos se apoyan unos en otros: lo mejor es leerlos en orden. El caso de estudio, por su parte, recurre a todos los conceptos de los capítulos anteriores: siempre que corresponde, su comentario remite al ejemplo donde se presentó el concepto. Los apéndices describen cómo instalar las herramientas: [Python], [Visual Studio Code] y su extensión [Python], [MySQL] con [Laragon] y [curl].