Skip to content

2. Acciones, enrutamiento, respuestas

Este capítulo examina el recorrido de una solicitud, desde el navegador hasta la acción que la procesa, y la respuesta que esa acción devuelve. Las vistas no se presentarán hasta el capítulo 4: aquí, las acciones devuelven texto o JSON directamente.

2.1. Ejemplo 01: la estructura de una aplicación Flask

El primer ejemplo es la aplicación [Flask] más pequeña posible: un solo archivo.

01-structure/
└── app.py

2.1.1. El archivo app.py

# app.py: la aplicación Flask más pequeña posible
from flask import Flask

# la aplicación: un objeto de la clase Flask. __name__ (aquí "__main__" o "app")
# le indica a Flask dónde está la aplicación, para que pueda buscar sus archivos allí
app = Flask(__name__)


# una acción (Flask la llama "view"): la función invocada para la solicitud GET /
@app.get("/")
def index():
    # el valor devuelto por la función ES la respuesta enviada al navegador
    return "Hello from Flask!"


# se ejecuta solo cuando se ejecuta el archivo mismo: python app.py
if __name__ == "__main__":
    # el servidor de desarrollo: http://localhost:5000; Ctrl-C lo detiene.
    # debug=True: recarga automática tras una modificación, y una página de
    # depuración en caso de error (NUNCA en producción)
    app.run(port=5000, debug=True)

Analicemos este código:

  • línea 2: importa la clase [Flask] del paquete [flask], instalado en el entorno virtual por [pip]. En [Python], un archivo llamado [.py] es un módulo, y un módulo solo usa los nombres que ha importado o definido él mismo (aparte de las funciones integradas del lenguaje, como [print] o [len]);
  • línea 6: la aplicación, un objeto de la clase [Flask]. Recibe las solicitudes y elige la función que procesa cada una. El parámetro es el nombre del módulo actual, que [Python] guarda en la variable [__name__]: [Flask] lo usa para ubicar la carpeta de la aplicación, donde buscará más adelante las vistas (carpeta [templates]) y los archivos estáticos (carpeta [static]);
  • línea 10: [@app.get("/")] es un decorador. Un decorador se escribe [@expression], inmediatamente antes de la definición de una función (o de una clase); [Python] llama a la expresión con la función como parámetro cuando ejecuta la definición. Aquí, [app.get("/")] registra la función [index] en la aplicación: manejará las solicitudes de [GET /]. Esto es el enrutamiento. Una función asociada a una ruta de esta manera es una acción (la documentación de [Flask] la llama función de vista; vea la introducción);
  • líneas 11 a 13: la acción devuelve una cadena. El valor devuelto por una acción es la respuesta que se envía al navegador: [Flask] la coloca en el cuerpo de la respuesta HTTP. Por convención, los nombres de las funciones ([Python]) se escriben en minúsculas, con las palabras separadas por guiones bajos ([action01_post]);
  • línea 17: cuando se ejecuta el propio archivo ([python app.py]), [Python] asigna el valor ["__main__"] a la variable [__name__]; cuando otro módulo importa el módulo, se le asigna el nombre del módulo (["app"]). Esta prueba, muy común en [Python], reserva por tanto el resto del código para cuando el archivo se inicia directamente;
  • línea 21: [app.run] inicia el [Werkzeug] servidor de desarrollo, que escucha las solicitudes en el puerto 5000 de la máquina (5000 es el valor predeterminado) hasta que se lo detiene con [Ctrl-C]. [debug=True] activa el modo de depuración: el servidor vigila los archivos de la aplicación y la reinicia en cuanto se modifica uno; una excepción no controlada muestra una página de depuración (vea el ejemplo 03). Este modo está pensado para el desarrollo, y solo para el desarrollo: la página de depuración permite ejecutar código [Python] en el servidor.

2.1.2. Ejecución

En una ventana de terminal abierta en la carpeta [01-structure], con el entorno virtual de los ejemplos activado, escriba [python app.py]. [Flask] muestra sus mensajes de inicio:

1
2
3
4
5
6
7
8
 * Serving Flask app 'app'
 * Debug mode: on
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on http://127.0.0.1:5000
Press CTRL+C to quit
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 332-612-699

Los mensajes indican el nombre de la aplicación, el modo de depuración, la dirección de escucha y el puerto. [127.0.0.1] es la dirección de la propia máquina ([localhost]): el servidor solo acepta solicitudes de esta máquina, lo cual es adecuado para el desarrollo ([app.run(host="0.0.0.0")] lo abriría a otras máquinas de la red). La línea [Restarting with stat] indica el mecanismo de recarga automática: el proceso iniciado por [python app.py] se limita a vigilar los archivos; inicia la aplicación en un proceso aparte, que reinicia cada vez que hay un cambio. El “PIN” protege la consola [Python] de la página de depuración.

Hay una segunda forma de iniciar una aplicación: el comando [flask], instalado junto con [Flask] en el entorno virtual:

flask --app app run --debug

La opción [--app] indica el módulo de la aplicación ([app], es decir, el archivo [app.py]), [run] inicia el servidor de desarrollo y [--debug] activa el modo de depuración; [--port 5001] cambiaría el puerto. El propio comando localiza, dentro del módulo, el objeto [Flask] llamado [app] (o, como veremos en el ejemplo 02, una función llamada [create_app]). Con esto, la prueba [if __name__ == "__main__"] ya no es necesaria. Los ejemplos usan [python app.py], que es más fácil de recordar; el caso de estudio hará lo mismo.

Solicitemos la URL [http://localhost:5000/] con un navegador:

Image

y luego con [curl]. La opción [-i] también muestra los encabezados HTTP de la respuesta:

curl -i http://localhost:5000/
1
2
3
4
5
6
7
8
HTTP/1.1 200 OK
Server: Werkzeug/3.1.8 Python/3.13.7
Date: Sat, 26 Sep 2026 13:22:44 GMT
Content-Type: text/html; charset=utf-8
Content-Length: 17
Connection: close

Hello from Flask!

La primera línea de la respuesta contiene la versión del protocolo, el código de estado (200) y su etiqueta ([OK]). Siguen los encabezados: el nombre del servidor, la fecha, el tipo de contenido, la longitud del contenido en bytes y [Connection: close] (el servidor de desarrollo cierra la conexión después de cada respuesta). Una línea en blanco separa los encabezados del cuerpo de la respuesta. En el resto de este documento ya no incluiremos los encabezados [Server], [Date] y [Connection], ya que no cambian.

El encabezado [Content-Type: text/html; charset=utf-8] indica que la respuesta está en formato HTML, cuyos caracteres están codificados en UTF-8. Es la codificación predeterminada ([Flask]) para cualquier cadena que devuelva una acción: el navegador interpreta entonces la cadena como HTML (aquí, al no haber etiquetas, se muestra tal cual). El ejemplo 03 mostrará cómo especificar un tipo de contenido distinto.

Por cada solicitud, la consola del servidor muestra una línea de log: la dirección del cliente, la fecha, la solicitud y el código de respuesta.

127.0.0.1 - - [26/Sep/2026 15:22:44] "GET / HTTP/1.1" 200 -

2.2. Ejemplo 02: enrutamiento

El enrutamiento asocia una URL y un método (HTTP, GET, POST...) con una acción. El ejemplo 02 organiza estas acciones en dos archivos:

1
2
3
4
5
6
02-routing/
├── controllers/
│   ├── __init__.py
│   ├── first.py
│   └── home.py
└── app.py

La carpeta [controllers] es un [Python] paquete (vea la introducción). Cada uno de estos dos módulos define un blueprint: un grupo de rutas, que la aplicación registra luego. Es el equivalente en [Flask] de las clases de controlador de [Spring MVC] o [ASP.NET Core MVC].

2.2.1. La aplicación: app.py

# app.py: la aplicación, construida por una "fábrica"
from flask import Flask

from controllers.home import home
from controllers.first import first


# la fábrica: una función que construye y configura la aplicación
def create_app():
    app = Flask(__name__)
    # cada blueprint (un grupo de rutas) se registra en la aplicación
    app.register_blueprint(home)
    app.register_blueprint(first)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Líneas 4 y 5: importan los dos blueprints, los objetos [home] and [first], de los módulos [controllers/home.py] and [controllers/first.py];
  • Líneas 9 a 14: la aplicación ya no es una variable del módulo creada al importarlo; la construye una función llamada *factory* (fábrica). Este es el enfoque que recomienda la documentación de [Flask], y que seguirán todos los ejemplos siguientes: la configuración de la aplicación se concentra en un solo lugar y se pueden crear varias aplicaciones con configuraciones distintas (para las pruebas, por ejemplo). El comando [flask --app app run] lo reconoce: si no existe una variable [app], llama a la función [create_app] del módulo;
  • líneas 12 y 13: cada blueprint se registra en la aplicación; sus rutas pasan a ser las de la aplicación;
  • línea 18: se construye la aplicación y luego se inicia el servidor.

2.2.2. El blueprint "home": controllers/home.py

# controllers/home.py: la página de inicio
from flask import Blueprint

# un blueprint: un conjunto de rutas, que luego se registra en la aplicación.
# "home": su nombre; __name__: el módulo donde está definido
home = Blueprint("home", __name__)


# GET /: una página HTML que contiene enlaces a las demás acciones.
# Una cadena devuelta por una acción se envía con el tipo text/html
@home.get("/")
def index():
    return """
        <h2>Example 02 - routing</h2>
        <ul>
          <li><a href="/first">/first</a></li>
          <li><a href="/first/action01">/first/action01</a></li>
          <li><a href="/first/products/17">/first/products/17</a></li>
          <li><a href="/first/products/17/reviews/3">/first/products/17/reviews/3</a></li>
          <li><a href="/first/files/images/logo.png">/first/files/images/logo.png</a></li>
          <li><a href="/first/products/abc">/first/products/abc</a></li>
          <li><a href="/unknown">/unknown</a></li>
        </ul>
        """
  • línea 6: el blueprint. Su primer parámetro es su nombre, [home]: servirá para identificar sus acciones ([home.index], vea el ejemplo 04). El segundo parámetro, como en la aplicación, es el nombre del módulo;
  • línea 11: un blueprint tiene los mismos decoradores que la aplicación: la acción [index] procesa [GET /];
  • líneas 13 a 23: una cadena delimitada por comillas triples puede ocupar varias líneas y contener comillas. La acción devuelve HTML, que se envía con el tipo [text/html] (vea el ejemplo 01).

La acción [index] devuelve así una página HTML que contiene enlaces a las acciones del otro blueprint:

Image

2.2.3. El primer blueprint: controllers/first.py

# controllers/first.py: un blueprint cuyas rutas empiezan todas con /first
from flask import Blueprint

# url_prefix: prefijo compartido por todas las rutas del blueprint
first = Blueprint("first", __name__, url_prefix="/first")


# GET /first: la ruta "" designa el prefijo mismo
@first.get("")
def index():
    return "Action [index] of the [first] blueprint"


# GET /first/action01
@first.get("/action01")
def action01():
    return "Action [action01] of the [first] blueprint, GET request"


# POST /first/action01: misma ruta, otro método HTTP, otra función
@first.post("/action01")
def action01_post():
    return "Action [action01_post] of the [first] blueprint, POST request"


# GET /first/products/17: <int:id> es una variable de ruta;
# el convertidor [int] acepta solo dígitos y entrega un entero
@first.get("/products/<int:id>")
def product(id):
    return f"Product no. {id}"


# GET /first/products/17/reviews/3: dos variables de ruta
@first.get("/products/<int:id>/reviews/<int:number>")
def review(id, number):
    return f"Review no. {number} of product no. {id}"


# GET /first/files/...: el convertidor [path] acepta cualquier final de
# ruta, barras incluidas
@first.get("/files/<path:path>")
def file(path):
    return f"Requested file: {path}"

Analicemos este código:

  • línea 5: el parámetro [url_prefix] fija el prefijo común a todas las rutas del blueprint: sus acciones procesan las rutas URL que comienzan con [/first];
  • líneas 9 y 10: la ruta [""] designa el propio prefijo: la acción [index] procesa [GET /first]. La URL de una acción es la concatenación del prefijo del blueprint y la ruta de su declaración. El nombre de la acción ([index]) puede ser el mismo que en otro blueprint: [Flask] las distingue por el nombre del blueprint ([first.index], [home.index]);
  • líneas 15 y 16: la acción [action01] procesa [GET /first/action01];
  • líneas 21 y 22: la misma ruta, pero para el método POST: el decorador [post] reemplaza a [get]. También existen [put], [delete] y [patch], así como el decorador general [route], que acepta una lista de métodos: [@first.route("/action01", methods=["GET", "POST"])]. Dentro de un mismo módulo, dos funciones no pueden tener el mismo nombre (la segunda reemplazaría a la primera): de ahí el nombre [action01_post];
  • líneas 28 a 30: [<int:id>] es una variable de ruta: este segmento de la URL puede tomar varios valores. [int] es un convertidor: el segmento debe estar formado por dígitos; de lo contrario, la ruta no coincide; su valor se convierte en un entero y luego se pasa al parámetro de la acción que tiene el mismo nombre, [id]. Para [/first/products/17], [id] es igual al número 17. Esto es el enlace de datos (*data binding*), que el próximo capítulo examinará en detalle. Sin convertidor ([<id>]), la variable acepta cualquier texto sin barra y sigue siendo una cadena. [Werkzeug] también ofrece los convertidores [float], [uuid] y [path], y el ejemplo 12 mostrará cómo escribir uno propio;
  • línea 30: una f-string (el prefijo [f]): cada expresión entre llaves se evalúa y su valor se inserta en el texto;
  • líneas 34 a 36: dos variables de ruta, pasadas como dos parámetros a la acción;
  • líneas 41 a 43: el convertidor [path] acepta cualquier final de URL, incluido [/].

2.2.4. Ejecución

Estas son las respuestas a algunas consultas:

curl -i http://localhost:5000/first
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 39

Action [index] of the [first] blueprint
curl -i http://localhost:5000/first/products/17/reviews/3
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 30

Review no. 3 of product no. 17

El texto tiene 30 caracteres, y la respuesta también mide 30 bytes: en UTF-8, cada uno de estos caracteres (ASCII) ocupa un byte.

curl -i http://localhost:5000/first/files/images/logo.png
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 31

Requested file: images/logo.png

Para enviar una solicitud POST, use la opción [-X POST] de [curl]:

curl -i -X POST http://localhost:5000/first/action01
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 61

Action [action01_post] of the [first] blueprint, POST request

Un método HTTP que ninguna acción maneja para esta ruta produce un error 405 ([Method Not Allowed]). El encabezado [Allow] enumera los métodos aceptados; [Flask] agrega [HEAD] (la misma solicitud que GET, sin el cuerpo de la respuesta) y [OPTIONS] (la lista de métodos aceptados), que procesa por sí mismo para cualquier ruta GET:

curl -i -X PUT http://localhost:5000/first/action01
HTTP/1.1 405 METHOD NOT ALLOWED
Content-Type: text/html; charset=utf-8
Allow: HEAD, OPTIONS, POST, GET
Content-Length: 153

<!doctype html>
<html lang=en>
<title>405 Method Not Allowed</title>
<h1>Method Not Allowed</h1>
<p>The method is not allowed for the requested URL.</p>

Por último, una URL que ninguna ruta maneja produce un error 404. Es también el caso de un identificador que no es un entero: ninguna ruta coincide con [/first/products/abc].

curl -i http://localhost:5000/first/products/abc
1
2
3
4
5
6
7
8
9
HTTP/1.1 404 NOT FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 207

<!doctype html>
<html lang=en>
<title>404 Not Found</title>
<h1>Not Found</h1>
<p>The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.</p>

Las respuestas de error de [Flask] (en realidad, de [Werkzeug]) son páginas HTML breves, en inglés. En un navegador:

Image

El capítulo 7 mostrará cómo reemplazarlas por páginas propias de la aplicación. Observe también que [Flask] distingue [/first] from [/first/]: esta última URL también produce un error 404, porque ninguna ruta termina con una barra diagonal. A la inversa, una ruta declarada con una barra final ([@first.get("/list/")]) también acepta la URL sin barra, mediante una redirección.

El comando [flask routes], ejecutado en la carpeta del ejemplo, enumera todas las rutas de la aplicación:

flask --app app routes
Endpoint             Methods  Rule
-------------------  -------  ---------------------------------------------
first.action01       GET      /first/action01
first.action01_post  POST     /first/action01
first.file           GET      /first/files/<path:path>
first.index          GET      /first
first.product        GET      /first/products/<int:id>
first.review         GET      /first/products/<int:id>/reviews/<int:number>
home.index           GET      /
static               GET      /static/<path:filename>

La columna [Endpoint] enumera el nombre de cada ruta: el nombre del blueprint, un punto y el nombre de la función. La última ruta, [static], la crea [Flask] mismo: sirve los archivos de la carpeta [static] de la aplicación (vea el ejemplo 15).

2.3. Ejemplo 03: respuestas de una acción

Lo que devuelve una acción determina la respuesta HTTP. El ejemplo 03 repasa los casos principales. El archivo [app.py]:

# app.py: la aplicación del ejemplo 03
from flask import Flask

from controllers.responses import responses


def create_app():
    app = Flask(__name__)
    # el JSON producido conserva los caracteres acentuados tal cual ("é" y no
    # "é"), y las claves en su orden original (sin ordenar)
    app.json.ensure_ascii = False
    app.json.sort_keys = False
    app.register_blueprint(responses)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Líneas 11 y 12: dos ajustes del proveedor JSON ([app.json]) de la aplicación, el objeto que convierte los objetos [Python] en JSON. De forma predeterminada, escribe los caracteres no ASCII como secuencias de escape ([é] se convierte en [é], lo cual es JSON válido pero poco legible), y ordena alfabéticamente las claves de los diccionarios. Conservamos los caracteres tal cual y las claves en el orden en que las escribió la acción.

El archivo [controllers/responses.py]:

# controllers/responses.py: las diferentes respuestas de una acción
import asyncio
import time
from dataclasses import dataclass

from flask import Blueprint, Response, abort, jsonify

responses = Blueprint("responses", __name__, url_prefix="/responses")


# una cadena, anunciada como texto plano: el navegador la muestra tal cual.
# Response: la respuesta completa, construida por la propia acción
@responses.get("/text")
def text():
    return Response("<h1>Action [text]</h1>", mimetype="text/plain")


# una cadena sola: Flask la envía con el tipo text/html; el navegador la interpreta
@responses.get("/html")
def html():
    return "<h1>Action [html]</h1>"


# una dataclass: una clase de datos (vea el ejemplo 06), declarada aquí en el módulo
@dataclass
class Person:
    last_name: str
    first_name: str
    age: int


# un objeto: jsonify lo serializa a JSON, con el tipo [application/json]
@responses.get("/json")
def json():
    return jsonify(Person("Martin", "Jean", 42))


# un diccionario devuelto tal cual: Flask mismo lo serializa a JSON
@responses.get("/dictionary")
def dictionary():
    return {"last_name": "Martin", "first_name": "Jean", "age": 42}


# una lista: se serializa como un arreglo JSON
@responses.get("/list")
def list():
    return ["Mme", "Melle", "Mr"]


# una tupla (contenido, código): el código 201 (Created) en lugar de 200 (OK)
@responses.get("/created")
def created():
    return {"message": "resource created"}, 201


# sin respuesta: el código 204 (No Content) significa "nada que mostrar"
@responses.get("/empty")
def empty():
    return "", 204


# una acción asíncrona (async def): Flask espera el fin de la corrutina.
# Requiere el extra [async] de Flask: pip install "flask[async]"
@responses.get("/task")
async def task():
    start = time.perf_counter()
    await asyncio.sleep(0.5)  # una espera de 500 ms, sin bloquear el bucle de eventos
    return {"wait": f"{round((time.perf_counter() - start) * 1000)} ms"}


# un error "esperado": la tupla (contenido, 404) produce una respuesta 404
@responses.get("/not-found")
def not_found():
    return {"message": "This resource does not exist"}, 404


# lo mismo, con abort: una excepción HTTP, que Flask convierte en una respuesta 404
@responses.get("/abort")
def abort_action():
    abort(404, "This resource does not exist either")


# un error "inesperado": una excepción no controlada produce una respuesta 500
@responses.get("/exception")
def exception():
    raise RuntimeError("An unexpected error")

Comentemos este código:

  • Líneas 13 a 15: la clase [Response] representa una respuesta HTTP completa. La acción la construye por sí misma: el cuerpo y el tipo ([mimetype]), en este caso [text/plain] (texto sin formato). El navegador no interpretará las etiquetas;
  • líneas 19 a 21: la misma cadena, devuelta sola: [Flask] la envía con el tipo [text/html], y el navegador la interpreta;
  • líneas 25 a 29: una dataclass, una clase en la que solo se declaran los campos y sus tipos; el decorador [@dataclass] escribe por sí mismo el constructor ([Person("Martin", "Jean", 42)]), la representación textual y la comparación de objetos. El ejemplo 06 volverá sobre esto;
  • líneas 33 a 35: la función [jsonify] convierte su parámetro a JSON y genera una respuesta de tipo [application/json]. El proveedor JSON de [Flask] puede convertir diccionarios, listas, cadenas, números, booleanos, [None] (que se convierte en [null]), así como dataclasses, fechas y números [Decimal] (vea el ejemplo 06);
  • líneas 39 a 41: aún más simple: una acción que devuelve un diccionario (o una lista, líneas 45 a 47) produce una respuesta JSON, sin llamar a [jsonify]. En cambio, una dataclass debe pasar por [jsonify]: si se devolviera sola, provocaría un error (“The view function did not return a valid response”);
  • líneas 51 a 53: una acción puede devolver una tupla [(content, code)]: el código de estado 201 ([Created]) reemplaza al código de estado 200. Una tupla también puede contener encabezados: [(content, code, {"X-Example": "03"})];
  • líneas 57 a 59: el código 204 ([No Content]) significa “nada que mostrar”: la respuesta no tiene cuerpo;
  • líneas 64 a 68: una acción asíncrona, declarada con [async def]. La palabra clave [await] suspende la corrutina mientras espera ([asyncio.sleep]), sin bloquear el programa. [Flask] ejecuta la acción en un bucle de eventos creado para la solicitud y espera su resultado: esto es útil para lanzar varias esperas en paralelo (varias llamadas a servicios web, por ejemplo), pero no vuelve asíncrono al propio [Flask]. Es necesario instalar la extensión [[async]] de [Flask] (vea [requirements.txt]);
  • líneas 72 a 74: un error “esperado”: la tupla [(content, 404)] devuelve una respuesta 404 ([Not Found]), con un cuerpo (JSON) elegido por la acción;
  • líneas 78 a 80: el mismo error, generado por la función [abort]. [abort] no devuelve nada: lanza una excepción ([NotFound], para el código 404), que termina la acción; [Flask] la convierte en una respuesta de error, con el mensaje indicado como segundo parámetro. Es la forma más habitual de terminar una acción por un error, incluso en lo profundo de una función llamada por la acción;
  • líneas 84 a 86: un error “inesperado” (una excepción que nadie maneja) produce una respuesta 500 ([Internal Server Error]).

En un navegador, la diferencia entre [text/plain] y [text/html] es visible:

Image

Image

Estas son las respuestas de las demás acciones:

curl -i http://localhost:5000/responses/json
1
2
3
4
5
6
7
8
9
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 65

{
  "last_name": "Martin",
  "first_name": "Jean",
  "age": 42
}

La dataclass se ha convertido en el objeto JSON, con un campo por atributo. En modo de depuración, el JSON se muestra en varias líneas, con sangría; sin modo de depuración, cabe en una sola línea ([{"last_name":"Martin","first_name":"Jean","age":42}]). La acción [/responses/dictionary] produce exactamente el mismo resultado.

curl -i http://localhost:5000/responses/list
1
2
3
4
5
6
7
8
9
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 31

[
  "Mme",
  "Melle",
  "Mr"
]
curl -i http://localhost:5000/responses/created
1
2
3
4
5
6
7
HTTP/1.1 201 CREATED
Content-Type: application/json
Content-Length: 36

{
  "message": "resource created"
}
curl -i http://localhost:5000/responses/empty
HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8
curl -i http://localhost:5000/responses/task
1
2
3
4
5
6
7
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 23

{
  "wait": "501 ms"
}
curl -i http://localhost:5000/responses/not-found
1
2
3
4
5
6
7
HTTP/1.1 404 NOT FOUND
Content-Type: application/json
Content-Length: 48

{
  "message": "This resource does not exist"
}
curl -i http://localhost:5000/responses/abort
1
2
3
4
5
6
7
8
9
HTTP/1.1 404 NOT FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 122

<!doctype html>
<html lang=en>
<title>404 Not Found</title>
<h1>Not Found</h1>
<p>This resource does not exist either</p>

La respuesta de [abort] es la página de error estándar de [Werkzeug], con nuestro mensaje (insertado en la página después de escaparlo: el texto insertado en HTML no debe poder introducir etiquetas; volveremos sobre esto).

Queda la excepción no controlada. En modo de depuración, el navegador muestra la página del [Werkzeug] depurador: el tipo y el mensaje de la excepción, seguidos de la pila de llamadas (la lista de funciones que se estaban ejecutando en el momento del error), de la más antigua a la más reciente, con la línea de código correspondiente en cada caso:

Image

La última función de la pila es nuestra acción, [exception], en la línea 86 del archivo [responses.py]. Al hacer clic en una de las líneas de la pila, incluso se puede abrir una consola [Python] en el contexto de esa función, después de ingresar el PIN que se mostró al iniciar: por eso el modo de depuración nunca debe activarse en un servidor accesible para otras personas. La consola del servidor también muestra la pila de llamadas (aquí incluimos solo el final):

1
2
3
4
5
6
127.0.0.1 - - [26/Sep/2026 15:23:10] "GET /responses/exception HTTP/1.1" 500 -
Traceback (most recent call last):
  ...
  File ".../examples/03-responses/controllers/responses.py", line 86, in exception
    raise RuntimeError("An unexpected error")
RuntimeError: An unexpected error

Sin modo de depuración ([app.run(port=5000)]), la misma solicitud produce una breve página de error 500 en inglés que no revela nada del código (“Internal Server Error. The server encountered an internal error and was unable to complete your request...”); la pila de llamadas solo se escribe en la consola del servidor. El capítulo 7 mostrará cómo mostrar una página de error propia de la aplicación.

2.4. Ejemplo 04: redirecciones

Una redirección es una respuesta que indica al navegador que obtenga otra URL: un código 3xx y el encabezado [Location], que contiene la nueva dirección. El navegador envía de inmediato una segunda solicitud a esa dirección. El archivo [controllers/redirects.py]:

# controllers/redirects.py: las redirecciones
from flask import Blueprint, redirect, url_for

redirects = Blueprint("redirects", __name__)


# redirección permanente (301): la página cambió de dirección de forma permanente
@redirects.get("/old")
def old_page():
    return redirect("/new", code=301)


@redirects.get("/new")
def new_page():
    return "You are on the [new] page"


# redirección temporal (302, el código predeterminado), a una dirección calculada
# pegando trozos de texto
@redirects.get("/go/<destination>")
def go(destination):
    return redirect("/page/" + destination)


# url_for construye la dirección de una ACCIÓN, designada por su nombre
# ("blueprint.función"): el parámetro [name] se codifica correctamente para una URL
@redirects.get("/to-template/<destination>")
def to_template(destination):
    return redirect(url_for("redirects.page", name=destination))


@redirects.get("/page/<name>")
def page(name):
    return f"You are on the [{name}] page"


# redirección a otro sitio
@redirects.get("/documentation")
def documentation():
    return redirect("https://flask.palletsprojects.com/")
  • líneas 8 a 10: la función [redirect] genera una respuesta de redirección a la dirección indicada. El código de estado 301 ([Moved Permanently]) indica que la página ha cambiado de dirección de forma permanente: el navegador (y los motores de búsqueda) pueden guardar en caché la nueva;
  • líneas 20 a 22: sin el parámetro [code], [redirect] produce una redirección temporal con el código de estado 302 ([Found]). La dirección se calcula concatenando fragmentos de texto, lo que plantea un problema que examinaremos;
  • líneas 27 a 29: la función [url_for] genera la URL de una acción, identificada por su nombre (["redirects.page"]: el blueprint, un punto, la función), en lugar de por su ruta. Sus parámetros con nombre proporcionan las variables de ruta (aquí, [name]), codificadas correctamente para una URL. Si alguna vez se cambia la ruta de [page], las llamadas a [url_for] la seguirán automáticamente;
  • líneas 38 a 40: una redirección a otro sitio.

Las respuestas, con [curl] (que, sin opciones, no sigue las redirecciones):

curl -i http://localhost:5000/old
HTTP/1.1 301 MOVED PERMANENTLY
Content-Type: text/html; charset=utf-8
Content-Length: 195
Location: /new

<!doctype html>
<html lang=en>
<title>Redirecting...</title>
<h1>Redirecting...</h1>
<p>You should be redirected automatically to the target URL: <a href="/new">/new</a>. If not, click the link.

La respuesta incluye además un pequeño cuerpo HTML, para un cliente que no siguiera las redirecciones. La opción [-L] de [curl] sigue la redirección, igual que lo haría un navegador:

curl -L http://localhost:5000/old
You are on the [new] page

Comparemos ahora las dos redirecciones calculadas, con un destino que contiene un signo de interrogación, codificado como [%3F] en la URL (un [?] sin codificar iniciaría los parámetros de la URL):

curl -i http://localhost:5000/go/a%3Fb
1
2
3
4
HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 205
Location: /page/a?b
curl -i http://localhost:5000/to-template/a%3Fb
1
2
3
4
HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 209
Location: /page/a%3Fb

[Flask] decodificó la variable de ruta antes de procesarla: [destination] es igual a [a?b]. La primera acción la pega tal cual en la dirección: [/page/a?b], que el navegador interpreta como la ruta [/page/a] seguida del parámetro [b]. La segunda pasa por [url_for], que la codifica de nuevo: [/page/a%3Fb]. Siguiendo las redirecciones:

curl -L http://localhost:5000/go/a%3Fb
curl -L http://localhost:5000/to-template/a%3Fb
You are on the [a] page
You are on the [a?b] page

Solo la segunda lleva a la página correcta. De ahí la regla: una dirección que contiene el valor de una variable se genera con [url_for], nunca concatenando cadenas. En el navegador solo se ve la página final; la barra de direcciones muestra la nueva URL:

Image

Existen otros dos códigos de redirección: 303 ([See Other]) y 307 ([Temporary Redirect]), que se obtienen con [redirect(url, code=303)]. Después de una solicitud POST, los códigos 302 y 303 hacen que el navegador envíe una solicitud GET a la nueva dirección, mientras que el 307 (y el 308, su versión permanente) hacen que repita la solicitud POST. El ejemplo 20 usará una redirección después de un POST.

2.5. Ejemplo 05: los objetos de solicitud y de respuesta

Hasta ahora, las acciones solo recibían variables de ruta y devolvían un valor que [Flask] convertía en una respuesta. Una acción también puede acceder a la solicitud actual y construir ella misma la respuesta. El archivo [controllers/http.py]:

# controllers/http.py: los objetos de solicitud y de respuesta
import time

from flask import Blueprint, Response, make_response, request

http = Blueprint("http", __name__, url_prefix="/http")


# la solicitud: método, ruta, parámetros, encabezados...
# [request] es un objeto global de Flask, que designa la solicitud ACTUAL
@http.get("/request")
def request_info():
    # un diccionario de Python conserva el orden de inserción de sus claves
    return {
        "method": request.method,
        "path": request.path,
        # query_string: bytes, que decodificamos a texto
        "parameters": request.query_string.decode(),
        "browser": request.headers.get("User-Agent"),
        "ip": request.remote_addr,
    }


# la respuesta: make_response construye el objeto de respuesta a partir de lo que
# devolvería la acción; le agregamos un encabezado antes de devolverla
@http.get("/header")
def header():
    response = make_response("Response with an added header")
    response.headers["X-Example"] = "05-request-response"
    return response


# la respuesta construida "a mano": cuerpo, código, tipo
@http.get("/response")
def response():
    return Response("Response built by [Response(...)]", status=200,
                    mimetype="text/plain")


# una respuesta enviada POR FRAGMENTOS: el código y los encabezados salen con el
# primer fragmento, y ya no pueden cambiar después
@http.get("/stream")
def stream():
    def chunks():
        yield "Start of the response... "
        time.sleep(1)
        # demasiado tarde para anunciar un error: el código 200 ya salió
        raise RuntimeError("error in the middle of the response")

    return Response(chunks(), mimetype="text/plain")
  • línea 4: importación del objeto [request]. En [Flask], la solicitud actual no es un parámetro de la acción: es un objeto global, [request], que se importa del paquete [flask]. ¿Cómo puede un objeto global referirse a la solicitud actual, si el servidor procesa varias solicitudes simultáneamente en varios hilos (hilos de ejecución en paralelo)? [request] actúa como un proxy: cada vez que se usa, reenvía la operación a la solicitud del hilo actual. [Flask] llama a esto el contexto de la solicitud: mientras se procesa una solicitud, [request] se refiere a esa solicitud en particular. Fuera del procesamiento de una solicitud, usarlo provoca un error (“Working outside of request context”);
  • líneas 14 a 20: algunas propiedades de la solicitud: su método HTTP, su ruta, sus parámetros sin procesar (la parte de la URL que sigue a [?], en forma de bytes, que [decode] convierte en texto), sus encabezados ([request.headers], un diccionario, cuyo método [get] devuelve [None] para un encabezado ausente) y la dirección IP del cliente. Los parámetros, uno por uno, se tratarán en el próximo capítulo;
  • líneas 26 a 30: la función [make_response] construye el objeto de respuesta (un [Response]) a partir de lo que la acción devolvería (aquí, una cadena); la acción puede entonces modificarlo antes de devolverlo. Se le agrega un encabezado [X-Example] (por convención, los encabezados propios de una aplicación suelen comenzar con [X-]);
  • líneas 34 a 37: la respuesta “construida a mano”: el cuerpo, el código de estado y el tipo;
  • líneas 42 a 50: una respuesta enviada por fragmentos (*streaming*). La función [chunks] es un generador: cada [yield] produce un fragmento del cuerpo. Como la respuesta se construye con un generador, su longitud no se conoce de antemano: el servidor envía el código de estado y los encabezados, y luego cada fragmento en cuanto se produce. Esto es útil para una respuesta muy larga, generada poco a poco. Pero una vez enviado el primer fragmento, el código de estado ya no puede cambiar: aquí, el generador lanza una excepción después del primer fragmento. Este es el error que hay que evitar: una respuesta que ya comenzó no puede convertirse en una respuesta de error.

Respuestas:

curl -i "http://localhost:5000/http/request?name=martin&age=42"
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 135

{
  "method": "GET",
  "path": "/http/request",
  "parameters": "name=martin&age=42",
  "browser": "curl/8.5.0",
  "ip": "127.0.0.1"
}

(Las comillas alrededor de "URL" impiden que el terminal interprete el carácter "[&]"). En un navegador, el encabezado [User-Agent] es el del navegador; [Chrome] muestra el JSON sin procesar, con una casilla que lo indenta:

Image

curl -i http://localhost:5000/http/header
1
2
3
4
5
6
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 29
X-Example: 05-request-response

Response with an added header
curl -i http://localhost:5000/http/response
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 33

Response built by [Response(...)]
curl -i http://localhost:5000/http/stream
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked

Start of the response...

El encabezado [Transfer-Encoding: chunked] reemplaza a [Content-Length]: el cuerpo llega en fragmentos, cada uno precedido por su longitud. Después de un segundo, la respuesta se interrumpe: [curl] recibió un código de estado 200 y un cuerpo truncado, sin ninguna forma de saber que ocurrió un error. Solo la consola del servidor lo indica:

1
2
3
4
5
6
Error on request:
Traceback (most recent call last):
  ...
  File ".../examples/05-request-response/controllers/http.py", line 48, in chunks
    raise RuntimeError("error in the middle of the response")
RuntimeError: error in the middle of the response

2.6. Ejemplo 06: servicios compartidos e inyección de dependencias

Una acción no debe contener la lógica de la aplicación; la delega en servicios, objetos que saben realizar una tarea específica (leer productos, calcular un carrito de compras, etc.). A menudo varias acciones usan el mismo servicio. En [Spring] o [ASP.NET Core], un contenedor de inyección de dependencias crea los servicios y se los proporciona automáticamente a quienes los necesitan. [Flask] no tiene contenedor: la fábrica de la aplicación crea los servicios y las acciones se los piden a la aplicación. El ejemplo 06 organiza su código por dominio (productos, clientes) en lugar de por tipo (controladores, modelos):

06-services/
├── clients/
│   ├── __init__.py
│   └── controller.py
├── products/
│   ├── __init__.py
│   ├── controller.py
│   ├── in_memory_service.py
│   ├── product.py
│   └── service.py
└── app.py

2.6.1. El producto

# products/product.py: un producto
from dataclasses import dataclass
from decimal import Decimal


# una dataclass: Python escribe por sí mismo el constructor, __repr__, __eq__...
# frozen=True: el objeto es inmutable (sus campos los fija el constructor)
@dataclass(frozen=True)
class Product:
    id: int
    name: str
    price: Decimal  # Decimal: un número decimal exacto (sin redondeo binario)
  • Línea 8: una dataclass (vea el ejemplo 03). Con [frozen=True], el objeto es inmutable: sus campos los fija el constructor, y cualquier intento de modificarlos ([p.price = 2]) lanza una excepción. Un objeto inmutable puede compartirse sin riesgo entre varias solicitudes;
  • líneas 10 a 12: los campos, con sus tipos. [Python] no verifica los tipos en tiempo de ejecución: son anotaciones que leen las herramientas de análisis (como la de [Visual Studio Code]) y ciertas bibliotecas ([Pydantic], que se tratará en el próximo capítulo). El precio es un [Decimal], un número decimal exacto: un [float] no puede representar con exactitud 0.1 ni 3.2 (en binario, estos números tienen infinitas cifras), y una suma de precios en [float] puede dar 5.500000000000001.

2.6.2. El contrato del servicio: service.py

# products/service.py: el CONTRATO del servicio, lo que puede hacer, sin decir cómo
from abc import ABC, abstractmethod

from flask import current_app

from products.product import Product


# una clase abstracta (ABC): no se puede crear ningún objeto a partir de ella; una clase
# hija debe escribir (sobrescribir) todos los métodos marcados con @abstractmethod
class ProductsService(ABC):

    @abstractmethod
    def find_all(self) -> list[Product]: ...

    # Product | None: un producto, o None si no existe
    @abstractmethod
    def find_by_id(self, id: int) -> Product | None: ...


# el servicio de la aplicación actual (vea app.py). current_app designa
# la aplicación que atiende la solicitud actual
def products_service() -> ProductsService:
    return current_app.extensions["products_service"]
  • Líneas 11 a 18: el contrato del servicio: lo que puede hacer, sin especificar cómo. En [Python], un contrato se define mediante una clase abstracta: una clase que hereda de [ABC] ([Abstract Base Class]) y cuyos métodos marcados con [@abstractmethod] no tienen cuerpo (los tres puntos [...] sirven de cuerpo vacío). No se puede crear un objeto de esta clase; una subclase debe redefinir todos sus métodos abstractos. Esto equivale a las interfaces de [Java] y [C#];
  • línea 14: la anotación del tipo que devuelve el método (después de [->]): una lista de productos. [self] es el objeto sobre el que se llama al método (el equivalente de [this] en [Java]), que siempre figura como primer parámetro;
  • línea 18: [Product | None]: un producto, o [None] si no existe;
  • líneas 23 y 24: la función que proporciona el servicio a las acciones. [current_app] es, igual que [request], un proxy: se refiere a la aplicación que procesa la solicitud actual. [app.extensions] es un diccionario que [Flask] pone a disposición de las extensiones (las bibliotecas que se agregan a [Flask]) para que guarden allí sus objetos; lo usamos para nuestros propios servicios. La función también indica el tipo del servicio ([-> ProductsService]): [Visual Studio Code] puede entonces ofrecer sus métodos.

2.6.3. La implementación: in_memory_service.py

# products/in_memory_service.py: una IMPLEMENTACIÓN del contrato, con datos en memoria
from decimal import Decimal

from products.product import Product
from products.service import ProductsService


class InMemoryProductsService(ProductsService):

    def __init__(self):
        # una tupla: una lista que no se puede modificar
        self._products = (
            Product(1, "pen", Decimal("1.5")),
            Product(2, "notebook", Decimal("3.2")),
            Product(3, "eraser", Decimal("0.8")),
        )

    def find_all(self) -> list[Product]:
        return list(self._products)

    def find_by_id(self, id: int) -> Product | None:
        # next(generator, None): el primer producto que coincide, o None
        return next((p for p in self._products if p.id == id), None)
  • línea 8: la clase hereda el contrato y redefine sus dos métodos;
  • líneas 10 a 15: [__init__] es el constructor de la clase. Guarda los productos en el atributo [_products] del objeto; el guion bajo inicial indica, por convención, un atributo privado que el código externo a la clase no debe usar. Los productos están en una tupla (entre paréntesis): una secuencia inmutable. El precio se construye a partir de una cadena ([Decimal("1.5")]): construido a partir del [float] 1.5, heredaría sus imprecisiones;
  • líneas 18 y 19: el método devuelve una lista nueva, una copia de la tupla: quien llama puede modificarla sin afectar los datos del servicio;
  • líneas 21 a 23: [(p for p in self._products if p.id == id)] es una expresión generadora: produce, uno por uno, los productos cuyo ID coincide con el solicitado. [next] devuelve el primer elemento producto, o el valor predeterminado, [None], si no hay ninguno.

2.6.4. El blueprint de productos: controller.py

# products/controller.py: las acciones de /products
from flask import Blueprint, jsonify

from products.service import products_service

products = Blueprint("products", __name__, url_prefix="/products")


@products.get("")
def list_all():
    # el servicio se obtiene de la aplicación, en cada solicitud
    return jsonify(products_service().find_all())


@products.get("/<int:id>")
def one_product(id):
    product = products_service().find_by_id(id)
    if product is None:
        return {"message": f"Product no. {id} not found"}, 404
    return jsonify(product)
  • Línea 4: el blueprint solo conoce el contrato del servicio (el módulo [service]), no su implementación: ignora que los productos están en memoria;
  • líneas 10 a 12: la acción le pide el servicio a la aplicación y luego le delega el trabajo. [jsonify] convierte la lista de dataclasses en un arreglo JSON;
  • líneas 16 a 20: un producto desconocido devuelve una respuesta 404, con un mensaje en JSON.

2.6.5. El blueprint de clientes: controller.py

# clients/controller.py: un segundo blueprint, que usa el MISMO servicio
from dataclasses import dataclass
from decimal import Decimal

from flask import Blueprint, jsonify

from products.service import products_service

clients = Blueprint("clients", __name__, url_prefix="/clients")


# el contenido del carrito, devuelto como JSON
@dataclass
class Cart:
    client: str
    items: int
    total: Decimal


@clients.get("/cart")
def cart():
    products = products_service().find_all()
    # la suma de los precios; start=Decimal(0): sumamos valores Decimal
    total = sum((p.price for p in products), start=Decimal(0))
    return jsonify(Cart("Jean Martin", len(products), total))
  • líneas 14 a 17: el contenido del carrito de compras, devuelto como JSON;
  • línea 22: este blueprint usa el mismo servicio que el blueprint de productos: un único objeto compartido;
  • línea 24: [sum] suma los elementos de un iterable; su parámetro [start] es el valor inicial de la suma (0 de forma predeterminada). Comenzar con [Decimal(0)] en lugar del entero 0 no es esencial (un entero y un [Decimal] se pueden sumar), pero garantiza un resultado de tipo [Decimal] incluso para un carrito de compras vacío.

2.6.6. La declaración del servicio: app.py

# app.py: la aplicación del ejemplo 06
from flask import Flask

from clients.controller import clients
from products.controller import products
from products.in_memory_service import InMemoryProductsService


def create_app():
    app = Flask(__name__)
    # JSON: acentos conservados, claves en su orden original (vea el ejemplo 03)
    app.json.ensure_ascii = False
    app.json.sort_keys = False
    # el SERVICIO: un único objeto, creado una sola vez, al iniciar, y compartido por
    # todas las solicitudes. Lo guardamos en app.extensions, un diccionario que
    # Flask pone a disposición de las extensiones... y de nuestros servicios
    app.extensions["products_service"] = InMemoryProductsService()
    app.register_blueprint(products)
    app.register_blueprint(clients)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Línea 17: aquí, y solo aquí, se elige la implementación del servicio. El servicio se crea una sola vez, al iniciar, y el mismo objeto atiende todas las solicitudes de todos los usuarios: es un singleton (el ámbito predeterminado de los beans de [Spring]). Para pasar a una implementación que lea de una base de datos, bastaría con cambiar esta línea: los blueprints, que solo conocen el contrato, permanecerían sin cambios. Este es todo el sentido de la inyección de dependencias, incluso implementada “a mano”: cada parte de la aplicación depende de contratos y un único lugar determina las implementaciones.

Un servicio compartido por todas las solicitudes debe poder usarse simultáneamente por varias solicitudes: el servidor de desarrollo procesa cada solicitud en su propio hilo. Esto no plantea ningún problema: el servicio se limita a leer datos que nunca cambian. El ejemplo 20 mostrará un servicio cuyos datos cambian y las precauciones que esto exige.

2.6.7. Ejecución

curl -i http://localhost:5000/products
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 191

[
  {
    "id": 1,
    "name": "pen",
    "price": "1.5"
  },
  {
    "id": 2,
    "name": "notebook",
    "price": "3.2"
  },
  {
    "id": 3,
    "name": "eraser",
    "price": "0.8"
  }
]

Los precios se han convertido en cadenas (["1.5"]): JSON solo tiene un tipo numérico, que la mayoría de los programas interpretan como un número de punto flotante; por eso el proveedor JSON de [Flask] convierte un [Decimal] en una cadena para conservar su precisión.

curl -i http://localhost:5000/products/9
1
2
3
4
5
6
7
HTTP/1.1 404 NOT FOUND
Content-Type: application/json
Content-Length: 43

{
  "message": "Product no. 9 not found"
}
curl -i http://localhost:5000/clients/cart
1
2
3
4
5
6
7
8
9
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 62

{
  "client": "Jean Martin",
  "items": 3,
  "total": "5.5"
}