Skip to content

3. El modelo de la vista

Una vista necesita información enviada por el navegador: los parámetros de la URL ([?name=martin&age=42]), los campos de un formulario, el cuerpo de la solicitud y, a veces, un encabezado de la solicitud. El curso original se refiere a toda esta información como el modelo de la acción; aquí lo llamaremos el modelo de la vista. Este capítulo muestra cómo una vista de [Django] obtiene esta información, la convierte al tipo correcto y la valida. Este proceso se denomina enlace de datos (data binding).

[Django] da acceso a la información de la solicitud mediante el objeto [HttpRequest] (ejemplo 05), en forma de cadenas de caracteres. Para convertirlas y validarlas, dispone de una única herramienta central: los formularios del módulo [django.forms]. Un formulario de [Django] es una clase que describe los datos esperados, campo por campo: cada campo puede convertir la cadena recibida a su tipo de datos (un entero, una fecha, una lista, etc.) y verificar restricciones (“obligatorio”, “un entero entre 0 y 150”, etc.). A pesar de su nombre, los formularios no se limitan a los formularios HTML: también validan los parámetros de una URL o un documento JSON. Primero leeremos los parámetros manualmente (ejemplo 07) y luego usaremos formularios para manejar su conversión y validación (ejemplos 08 a 12). En el próximo capítulo, estos mismos formularios también se mostrarán en HTML.

Observe la terminología: la palabra “modelo” tiene un significado específico en [Django], pues se refiere a las clases del ORM (capítulo 7). El modelo de una vista, tal como se define en este capítulo, es lo que esta recibe de la solicitud. Organizaremos las clases que lo describen en archivos [viewmodels.py], nunca en [models.py], que está reservado para el ORM.

Los ejemplos 07 a 12 se ejecutan de la misma manera que los del capítulo anterior: abra un terminal en el directorio del ejemplo, con el entorno virtual activado ([python manage.py runserver]); [Ctrl-C] detiene el servidor. La mayoría usa el middleware [ReadableJson] del ejemplo 03, lo que produce un JSON legible. Solo comentaremos sus archivos de configuración cuando introduzcan algo nuevo.

3.1. Ejemplo 07: los parámetros de la URL

Los parámetros de la URL son la parte que sigue a [?]: [?name=martin&age=42]. Esta parte se denomina cadena de consulta (query string). Cada parámetro es un par [name=value]; los pares se separan con [&]. Vistas de la aplicación [parameters]:

# parameters/views.py: los parámetros de la URL (la "cadena de consulta")

from django.core.exceptions import BadRequest
from django.http import HttpResponse, JsonResponse
from django.views.decorators.http import require_GET


# /parameters/action01?name=martin: request.GET contiene los parámetros de la URL;
# get devuelve el valor de un parámetro, o None si está ausente
@require_GET
def action01(request):
    name = request.GET.get("name")
    return HttpResponse(f"name = [{name}], of type {type(name).__name__}")


# /parameters/action02?age=42: el valor de un parámetro es SIEMPRE una cadena
@require_GET
def action02(request):
    age = request.GET.get("age")
    return HttpResponse(f"age = [{age}], of type {type(age).__name__}")


# /parameters/action03?age=42: un parámetro OBLIGATORIO, convertido a mano; su
# ausencia, o un valor que no es un entero, produce una respuesta 400
@require_GET
def action03(request):
    text = request.GET.get("age")
    if text is None:
        # una excepción que Django convierte en una respuesta 400 (Bad Request)
        raise BadRequest("the [age] parameter is required")
    try:
        # int convierte la cadena en un entero, o lanza la excepción ValueError
        age = int(text)
    except ValueError:
        raise BadRequest(f"[{text}] is not an integer")
    return HttpResponse(f"age = [{age}], of type {type(age).__name__}")


# /parameters/action04?page=2: un valor predeterminado si falta el parámetro
@require_GET
def action04(request):
    page = request.GET.get("page", "1")
    return HttpResponse(f"page = [{page}]")


# /parameters/action05?q=django: el nombre del parámetro de la URL no es necesariamente
# el de la variable de Python
@require_GET
def action05(request):
    search = request.GET.get("q")
    return HttpResponse(f"search = [{search}]")


# /parameters/action06?name=martin&age=42: todos los parámetros a la vez, como un diccionario
@require_GET
def action06(request):
    return JsonResponse(request.GET.dict())
  • Línea 12: el atributo [GET] de la solicitud contiene los parámetros de la URL. Su nombre induce a error: existe sin importar el método de la solicitud, incluso para una solicitud POST cuya URL tiene parámetros. Es un objeto [QueryDict], un diccionario cuyo método [get] devuelve el valor de un parámetro (ya decodificado) o [None] si está ausente;
  • Línea 13: la vista muestra el valor y su tipo: [type(name)] devuelve la clase del valor, y [__name__] devuelve el nombre de esa clase. Un valor obtenido de la URL es siempre una cadena ([str]);
  • líneas 26–36: un parámetro obligatorio y una conversión manual que distingue entre los dos errores posibles. El operador [is] verifica la identidad; [text is None] es la forma correcta de comprobar la ausencia de un valor. [raise BadRequest(message)] termina la vista con una respuesta 400 (Bad Request: la solicitud no es válida), así como [Http404] terminaba la vista con una respuesta 404 (ejemplo 03). La función [int] convierte una cadena en un entero y lanza la excepción [ValueError] si la cadena no es un entero: el bloque [try] / [except] captura esta excepción para devolver nuestro propio error;
  • línea 42: el segundo parámetro de [get] es un valor predeterminado, que se usa si falta el parámetro. Es un caso típico para el número de página de una lista. Observe que el valor predeterminado es una cadena, ["1"], igual que lo sería el valor recibido;
  • línea 50: no es obligatorio que la variable de [Python] se llame igual que el parámetro de la URL. Los motores de búsqueda suelen usar un parámetro corto, como [q] (query);
  • línea 57: [dict()] devuelve todos los parámetros de la URL en un diccionario estándar de [Python], que la vista convierte a JSON (ejemplo 03).

Probemos cada vista con [curl]. Un parámetro presente y luego ausente:

curl -i "http://localhost:8000/parameters/action01?name=martin"
curl "http://localhost:8000/parameters/action01"
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

name = [martin], of type str
name = [None], of type NoneType

Las comillas alrededor de la URL son necesarias en un terminal: sin ellas, el shell interpretaría [&] (que ejecuta un comando en segundo plano en [Linux]) y [?]. El valor [None], al insertarse en una f-string, se convierte en el texto [None]. Un valor que contenga espacios o caracteres especiales debe codificarse para la URL: un espacio se convierte en [%20] (o [+]), y [&] se convierte en [%26] (de lo contrario, separaría dos parámetros). El navegador lo hace automáticamente; con [curl], hay que escribirlo explícitamente. [Django] decodifica el valor antes de que la vista lo lea:

curl "http://localhost:8000/parameters/action01?name=jean%20dupont%20%26%20sons"
name = [jean dupont & sons], of type str

Un parámetro que existe pero está vacío ([?name=]) devuelve una cadena vacía, no [None]: la vista puede distinguir entre los dos casos. El valor de la edad, seguido de la conversión manual (exitosa, sin parámetro y fallida):

1
2
3
4
curl "http://localhost:8000/parameters/action02?age=42"
curl "http://localhost:8000/parameters/action03?age=42"
curl -i http://localhost:8000/parameters/action03
curl -i "http://localhost:8000/parameters/action03?age=abc"
age = [42], of type str
age = [42], of type int
HTTP/1.1 400 Bad Request
Content-Type: text/html

<!DOCTYPE html>
...
HTTP/1.1 400 Bad Request
Content-Type: text/html

<!DOCTYPE html>
...

El valor [42] recibido por la vista 02 es una cadena; el valor de la vista 03, después de la conversión, es un entero. La función [int] tolera los espacios: [?age=%2042] (“42” precedido por un espacio) también devuelve 42. Ambos errores producen una respuesta 400. En modo de depuración, esta es la página de error de [Django], que muestra nuestro mensaje:

Image

El valor predeterminado y el parámetro renombrado:

1
2
3
curl http://localhost:8000/parameters/action04
curl "http://localhost:8000/parameters/action04?page=3"
curl "http://localhost:8000/parameters/action05?q=django"
1
2
3
page = [1]
page = [3]
search = [django]

Todos los parámetros a la vez. El parámetro [name] aparece dos veces:

curl "http://localhost:8000/parameters/action06?name=martin&age=42&name=durand"
1
2
3
4
{
    "name": "durand",
    "age": "42"
}

El parámetro [name] conserva en el diccionario solo su valor más reciente. Veremos en el ejemplo 10 que [request.GET], en cambio, los ha conservado todos. La edad siguió siendo una cadena (["42"], entre comillas en JSON): no se solicitó ninguna conversión. En un navegador (aquí, [Chromium]), el JSON se muestra exactamente como lo formateó el servidor; la casilla “Pretty-print” lo indentaría si no lo estuviera ya. La barra de direcciones también muestra la codificación de los caracteres acentuados en la URL ([é] se convierte en [%C3%A9], con sus dos bytes en [UTF-8]):

Image

Este primer ejemplo ilustra las limitaciones del enfoque manual: para cada parámetro, hay que escribir la lectura, la conversión y el manejo de los valores ausentes y de los errores. Con diez parámetros, el código de la vista quedaría sepultado bajo estas verificaciones, y no habría forma de expresar las reglas (“una cadena de 2 a 20 caracteres”). Es mejor describir lo que se espera y dejar que el framework lo verifique. Ese es el propósito del siguiente ejemplo.

3.2. Ejemplo 08: un modelo de vista descrito por una clase

Un modelo de vista puede describirse mediante una clase: un formulario de [Django], con un campo por cada parámetro esperado. El tipo de campo especifica cómo convertir la cadena recibida, y sus parámetros especifican las restricciones que debe cumplir. [Django] ofrece unas treinta clases de campo: [CharField] (una cadena), [IntegerField], [DecimalField], [FloatField], [BooleanField], [DateField], [EmailField], [URLField], [ChoiceField] (un valor de una lista), [MultipleChoiceField], [FileField]...

3.2.1. El modelo: persons/viewmodels.py

# persons/viewmodels.py: el modelo de la vista, una clase que describe los
# parámetros esperados, su tipo y sus RESTRICCIONES

from django import forms


# un FORMULARIO de Django (forms.Form): cada atributo es un CAMPO, que sabe convertir
# el valor recibido (una cadena) a su tipo y verificar sus restricciones
class PersonModel(forms.Form):
    # obligatorio (es el valor predeterminado: required=True), una cadena de 2 a 20 caracteres
    name = forms.CharField(min_length=2, max_length=20)
    # obligatorio, un entero entre 0 y 150
    age = forms.IntegerField(min_value=0, max_value=150)
    # obligatorio, uno solo de estos tres valores: pares (valor, etiqueta)
    title = forms.ChoiceField(choices=[("Mr", "Mr"), ("Mme", "Mme"), ("Melle", "Melle")])
    # opcional; si está presente, una dirección de correo electrónico válida
    email = forms.EmailField(required=False)
  • Línea 4: importa el módulo [forms] de [Django]. Esta es la práctica habitual: los campos se llamarán [forms.CharField], [forms.IntegerField]...;
  • línea 9: un formulario es una clase que hereda de [forms.Form];
  • líneas 11–17: los campos, escritos como atributos de la clase (no del objeto: se definen en el cuerpo de la clase, fuera de cualquier método). [Django] los descubre examinando la clase; su orden es el mismo de la declaración. Todos los campos son obligatorios de forma predeterminada ([required=True]): un parámetro ausente o vacío es un error;
  • línea 11: el nombre debe tener entre 2 y 20 caracteres. Un [CharField] también elimina los espacios que rodean al valor (parámetro [strip], cuyo valor predeterminado es [True]) antes de validarlo;
  • línea 13: la edad es un entero entre 0 y 150. El campo convierte la cadena en un entero: es la función de la vista 03 del ejemplo 07, en una sola línea;
  • línea 15: el título debe ser uno de los tres valores indicados. Las opciones son pares (valor, etiqueta): la etiqueta se usará cuando el campo se muestre en una página (ejemplo 18);
  • línea 17: la dirección de correo electrónico es opcional ([required=False]); si se proporciona, debe ser válida.

Este modelo describe los datos esperados; no contiene instrucciones de validación. Esto se conoce como estilo declarativo. Un formulario se usa en tres pasos: se crea con los datos recibidos ([PersonModel(request.GET)]: un formulario “enlazado” a datos); se verifica su validez ([is_valid()]), lo que desencadena la conversión y la validación de cada campo; y luego se leen los valores convertidos ([cleaned_data], un diccionario) o los errores ([errors], un diccionario que asocia cada campo con error con la lista de sus mensajes). Cada campo se convierte y se valida de forma independiente de los demás: todos los errores se detectan a la vez.

3.2.2. El enlace: persons/binding.py

[Symfony] tenía un atributo, [#[MapQueryString]], que construía y validaba el modelo antes de llamar a la acción. [Django] no tiene nada parecido para las vistas basadas en funciones. Pero sabemos, por el ejemplo 02, que un decorador puede envolver una vista para actuar antes que ella: escribamos un decorador que construya el modelo a partir de los parámetros de la URL, lo valide y se lo pase a la vista.

# persons/binding.py: el ENLACE (binding) de los parámetros de la URL a un modelo y su validación

from functools import wraps


# la excepción que se lanza cuando los parámetros no respetan las restricciones del modelo;
# lleva el formulario y, por lo tanto, sus errores
class InvalidModel(Exception):
    def __init__(self, form):
        super().__init__("invalid model")
        self.form = form


# un DECORADOR parametrizado: @from_url(PersonModel) reemplaza la vista por una
# función envoltorio, que construye y valida el modelo ANTES de llamar a la vista.
# Un modelo inválido lanza InvalidModel, y la vista nunca se llama
def from_url(model_class):
    def decorator(view):
        # @wraps: el envoltorio conserva el nombre y la documentación de la vista
        @wraps(view)
        def wrapper(request, *args, **kwargs):
            form = model_class(request.GET)
            if not form.is_valid():
                raise InvalidModel(form)
            # cleaned_data: los valores convertidos y validados, en un diccionario
            return view(request, form.cleaned_data, *args, **kwargs)
        return wrapper
    return decorator
  • Líneas 8–11: una excepción “personalizada”: una clase que hereda de la clase [Exception] de [Python]. Su constructor llama al constructor de la clase padre ([super().__init__(...)], con el mensaje de la excepción) y luego almacena el formulario en un atributo: quien capture la excepción encontrará allí los errores;
  • Líneas 17–28: un decorador parametrizado. [@from_url(PersonModel)] se ejecuta en dos pasos: [from_url(PersonModel)] devuelve la función [decorator], que se aplica a la vista y, a su vez, devuelve la función [wrapper], que reemplaza a la vista. Las funciones definidas dentro de otra función conservan sus variables ([model_class], [view]) incluso después de que esta haya terminado su trabajo: esto se denomina clausura (closure);
  • Línea 20: [@wraps(view)], del módulo [functools], proporciona al wrapper el nombre y la documentación de la vista: los mensajes de error y las herramientas de [Django] seguirán refiriéndose a [action01], y no a [wrapper];
  • Línea 21: el wrapper recibe lo que [Django] pasa a la vista: la solicitud, seguida de los parámetros de la ruta, que no conoce de antemano. [*args] recibe los parámetros pasados por posición (en una tupla), mientras que [**kwargs] recibe los pasados por nombre (en un diccionario); al llamar en la línea 26, [*args] y [**kwargs] los transmiten tal cual;
  • Líneas 22–24: el formulario se enlaza con los parámetros de la URL y se valida; si no es válido, el wrapper lanza una excepción y la vista nunca se llama, de modo que no tiene que preocuparse por datos no válidos;
  • línea 26: de lo contrario, se llama a la vista, con un parámetro adicional: los valores convertidos y validados.

3.2.3. La vista: persons/views.py

# persons/views.py: una vista cuyo modelo es una clase

from django.http import JsonResponse
from django.views.decorators.http import require_GET

from .binding import from_url
from .viewmodels import PersonModel


# /persons/action01?name=martin&age=42&title=Mr
# @from_url construye un PersonModel a partir de los parámetros de la URL, lo VALIDA
# y pasa sus valores a la vista (parámetro person). Un modelo inválido lanza
# una excepción (véase config/middleware.py), y la vista nunca se llama
@require_GET
@from_url(PersonModel)
def action01(request, person):
    return JsonResponse({
        "received": request.GET.dict(),
        "person": person,
        "ageType": type(person["age"]).__name__,
    })
  • Líneas 14–15: se apilan dos decoradores; el más cercano a la función se aplica primero. [require_GET] envuelve, por lo tanto, el wrapper de [from_url]: el método HTTP se verifica antes que los parámetros;
  • línea 16: la vista recibe el modelo validado, en forma de diccionario;
  • líneas 17–21: la vista devuelve los parámetros recibidos tal cual, seguidos del modelo y del tipo de la edad, para ilustrar la diferencia.

3.2.4. Manejo de errores: config/middleware.py

¿Quién maneja la excepción [InvalidModel]? Sin ninguna otra acción, [Django] la maneja por sí mismo con una respuesta 500: para él, es una excepción más. Queremos una respuesta de error JSON, con código de estado 400, en nuestro propio formato. Ese es el papel de un middleware:

# config/middleware.py: los middlewares del ejemplo 08

import json

from django.http import JsonResponse

from persons.binding import InvalidModel


# un JSON legible por un humano (véase el ejemplo 03)
class ReadableJson:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        response = self.get_response(request)
        if isinstance(response, JsonResponse):
            data = json.loads(response.content)
            response.content = json.dumps(data, ensure_ascii=False, indent=4)
        return response


# un modelo inválido produce, para TODA la aplicación, una respuesta 400 que detalla
# los errores
class ValidationErrors:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        return self.get_response(request)

    # process_exception: Django llama a este método cuando una excepción sale de la
    # vista. Devuelve una respuesta, que reemplaza la página de error de Django, o None
    # para que Django maneje la excepción como de costumbre
    def process_exception(self, request, exception):
        if not isinstance(exception, InvalidModel):
            return None
        # errors: un diccionario {campo: lista de mensajes de error del campo}
        errors = [{"field": field, "message": message}
                  for field, messages in exception.form.errors.items()
                  for message in messages]
        return JsonResponse({"status": 400, "errors": errors}, status=400)
  • líneas 11–20: el middleware [ReadableJson] del ejemplo 03;
  • líneas 25–30: un segundo middleware, cuyo método [__call__] simplemente pasa la solicitud al siguiente componente de la cadena;
  • líneas 35–42: el método [process_exception]. Además de [__call__], un módulo de middleware puede tener métodos que [Django] llama en puntos específicos del procesamiento (el capítulo sobre el ciclo de vida los tratará todos). [process_exception] se llama cuando se lanza una excepción desde la vista. Devuelve una respuesta, que reemplaza la página de error generada por [Django], o devuelve [None], lo que permite que [Django] maneje la excepción de la forma habitual. Declarado en la configuración [MIDDLEWARE], el middleware se aplica a todas las vistas de la aplicación: toda vista que valide un modelo se beneficia de él, sin tener que escribir una sola línea de código de manejo de errores;
  • línea 36: si no es un error de validación, el middleware no hace nada;
  • líneas 39–41: la lista de errores, en forma de diccionarios, se calcula mediante una comprensión de listas con dos bucles: [for] para cada campo con un error, para cada mensaje asociado a ese campo. [items()] recorre un diccionario en pares (clave, valor);
  • línea 42: una respuesta JSON, con código de estado 400. Luego sube por la cadena de middleware y pasa por [ReadableJson] (líneas 18–20 del archivo [config/settings.py]).

3.2.5. Ejecución

Un modelo válido:

curl -i "http://localhost:8000/persons/action01?name=martin&age=42&title=Mr"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "received": {
        "name": "martin",
        "age": "42",
        "title": "Mr"
    },
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mr",
        "email": ""
    },
    "ageType": "int"
}

Los parámetros recibidos son cadenas; el modelo contiene la edad como un entero (sin comillas en JSON), y la dirección ausente es la cadena vacía (el valor “vacío” de un [CharField] o de un [EmailField]; el de un [IntegerField] opcional sería [None]). Un nombre rodeado de espacios ([%20]) y una dirección presente:

curl "http://localhost:8000/persons/action01?name=%20%20martin%20&age=42&title=Mme&email=jean.martin@example.com"
{
    "received": {
        "name": "  martin ",
        "age": "42",
        "title": "Mme",
        "email": "jean.martin@example.com"
    },
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mme",
        "email": "jean.martin@example.com"
    },
    "ageType": "int"
}

El campo eliminó los espacios que rodeaban al nombre: la vista recibe el valor depurado ([cleaned_data]). Por lo tanto, un nombre formado solo por espacios quedaría vacío y se rechazaría por ausente. Ahora sin parámetros: faltan los tres campos obligatorios.

curl -i http://localhost:8000/persons/action01
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "This field is required."
        },
        {
            "field": "age",
            "message": "This field is required."
        },
        {
            "field": "title",
            "message": "This field is required."
        }
    ]
}

Los mensajes están en inglés. Los mensajes de los formularios están escritos en inglés en el código de [Django], pero pasan por su mecanismo de traducción, y [Django] incluye sus traducciones en un centenar de idiomas: con la configuración [LANGUAGE_CODE = "fr"], estarían en francés. Todos nuestros ejemplos usan la configuración [LANGUAGE_CODE = "en"], desde el ejemplo 01. Cuatro campos no válidos a la vez:

curl "http://localhost:8000/persons/action01?name=m&age=200&title=Mlle&email=xx"
{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "Ensure this value has at least 2 characters (it has 1)."
        },
        {
            "field": "age",
            "message": "Ensure this value is less than or equal to 150."
        },
        {
            "field": "title",
            "message": "Select a valid choice. Mlle is not one of the available choices."
        },
        {
            "field": "email",
            "message": "Enter a valid email address."
        }
    ]
}

Todos los errores se informan a la vez, lo que permite al usuario corregir todo de una sola vez. Por último, una edad que no es un número:

curl "http://localhost:8000/persons/action01?name=m&age=abc&title=Mlle&email=xx"
{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "Ensure this value has at least 2 characters (it has 1)."
        },
        {
            "field": "age",
            "message": "Enter a whole number."
        },
        {
            "field": "title",
            "message": "Select a valid choice. Mlle is not one of the available choices."
        },
        {
            "field": "email",
            "message": "Enter a valid email address."
        }
    ]
}

Una vez más, se informan los cuatro errores: la conversión fallida de la edad es un error del campo [age], igual que los demás. Esto difiere de [Symfony], donde el curso demostró que una conversión fallida impedía por completo la validación, porque impedía construir el objeto: un formulario de [Django], en cambio, convierte y valida cada campo por separado.

3.3. Ejemplo 09: validación realizada por la vista

En el ejemplo 08, un modelo no válido interrumpe la vista y responde el middleware de la aplicación. Esto es conveniente para una API, cuyos clientes son programas que esperan una respuesta de error estandarizada. Pero una página web suele preferir volver a mostrar el formulario con mensajes de error: en ese caso, la vista debe decidir qué hacer con un modelo no válido. Usa el formulario directamente, sin un decorador. El ejemplo ya no tiene middleware:

1
2
3
4
5
6
7
8
9
09-action-validation/
├── config/
│   └── ...
├── persons/
│   ├── __init__.py
│   ├── urls.py
│   ├── viewmodels.py
│   └── views.py
└── manage.py

3.3.1. El modelo: persons/viewmodels.py

# persons/viewmodels.py: la ENTRADA de una persona y las restricciones que debe
# respetar, con nuestros propios mensajes de error

from django import forms

# error_messages: los mensajes de este formulario, que reemplazan los de Django. La clave
# es el CÓDIGO de error: required (campo faltante), invalid_choice (valor que no está en la
# lista), invalid (valor imposible de convertir)...
REQUIRED = {"required": "the field is required"}


class PersonInput(forms.Form):
    name = forms.CharField(min_length=2, max_length=20, error_messages=REQUIRED)
    # | fusiona dos diccionarios: un mensaje más para este campo
    age = forms.IntegerField(min_value=0, max_value=150,
                             error_messages=REQUIRED | {"invalid": "an integer is expected"})
    title = forms.ChoiceField(choices=[("Mr", "Mr"), ("Mme", "Mme"), ("Melle", "Melle")],
                              error_messages=REQUIRED | {"invalid_choice": "unknown value"})
    email = forms.EmailField(required=False)

El modelo tiene los campos del ejemplo 08, pero esta vez con nuestros propios mensajes de error:

  • línea 9: un diccionario, definido de una vez por todas y compartido por los tres campos obligatorios. Por convención, una variable de módulo escrita en mayúsculas es una constante;
  • líneas 13–18: el parámetro [error_messages] de un campo reemplaza sus mensajes por los nuestros. Cada tipo de error tiene un código: [required] (campo ausente o vacío), [invalid] (el valor no se puede convertir: una edad [abc]), [invalid_choice] (valor que no está en la lista), [min_length], [max_length], [min_value], [max_value]... El diccionario asocia un mensaje a cada código. Los mensajes que no figuran en el diccionario son los de [Django];
  • línea 16: el operador [|] fusiona dos diccionarios: el resultado contiene las claves de ambos (si hay una clave común, prevalece la de la derecha). Así, “age” tiene dos mensajes propios.

Los mensajes de [Django] no siempre son apropiados; acabamos de ver cómo reemplazarlos, campo por campo. Para reemplazarlos en toda la aplicación, se proporcionan traducciones (véase el capítulo sobre internacionalización): son estas traducciones, y no [error_messages], las que deben usarse en una aplicación multilingüe.

3.3.2. La vista: persons/views.py

# persons/views.py: es la vista la que decide qué hace con una entrada inválida

from django.http import HttpResponse
from django.utils.html import format_html, format_html_join
from django.views.decorators.http import require_GET

from .viewmodels import PersonInput


# /persons/action01?name=martin&age=42&title=Mr
@require_GET
def action01(request):
    # la entrada: los parámetros de la URL, entregados al formulario
    person_input = PersonInput(request.GET)
    # is_valid verifica las restricciones y almacena los errores en person_input.errors
    if not person_input.is_valid():
        # format_html_join: un trozo de HTML por cada error; los valores insertados están
        # ESCAPADOS (< se convierte en &lt;...): una entrada no puede inyectar HTML
        items = format_html_join("", "<li>{}: {}</li>",
                                 ((field, message) for field, messages in person_input.errors.items()
                                  for message in messages))
        return HttpResponse(format_html("<p>The form contains errors:</p><ul>{}</ul>", items))
    data = person_input.cleaned_data
    return HttpResponse(format_html("<p>Welcome {} {} ({} years old)</p>",
                                    data["title"], data["name"], data["age"]))
  • Línea 14: la vista crea el formulario, enlazado a los parámetros de la URL;
  • línea 16: [is_valid()] convierte y valida cada campo, y almacena los errores, si los hay, en [person_input.errors]. No lanza ninguna excepción: la vista decide por sí misma qué hacer a continuación;
  • Líneas 19–22: cada uno de los errores, campo por campo, se coloca dentro de una etiqueta [<li>]. [format_html_join] genera un segmento de HTML para cada elemento de una secuencia de valores (aquí, pares (campo, mensaje) producidos por una expresión generadora), a partir de una plantilla de texto, [<li>{}: {}</li>]: cada [{}] recibe un valor del par. [format_html] hace lo mismo para un único segmento. Estas dos funciones, del módulo [django.utils.html], tienen una propiedad esencial: los valores insertados se escapan;
  • líneas 23–25: si tiene éxito, se muestra un mensaje de bienvenida, junto con los valores convertidos.

Escapar un valor significa reemplazar los caracteres que tienen significado en HTML ([<], [>], [&], ["], [']) por sus entidades ([&lt;], [&gt;]...): se mostrarán tal cual en lugar de ser interpretados. Sin esta precaución, un usuario podría introducir un “nombre” que contenga HTML, o incluso [JavaScript], que se ejecutaría en el navegador de cualquiera que viera la página. Esta es la vulnerabilidad de seguridad más común en la web: la inyección de scripts (XSS, cross-site scripting). Una f-string, en cambio, no escapa nada: [HttpResponse(f"Welcome {name}")] sería vulnerable. [format_html] devuelve texto marcado como “seguro” (un objeto [SafeString]): las partes ya escapadas no se escapan por segunda vez al insertarse en otra ([items], línea 22). En la próxima sección, las plantillas de [Django] realizarán este escape automáticamente para cualquier valor insertado en una página.

Una entrada válida, seguida de una entrada con cuatro errores:

Image

Image

Los mensajes están en inglés: los de [Django] (el nombre, la dirección) y los nuestros (la edad, el título). La respuesta sin procesar a la segunda solicitud (la de un nombre que contiene HTML) y la respuesta a una solicitud sin nombre, con una edad demasiado alta:

1
2
3
curl "http://localhost:8000/persons/action01?name=m&age=abc&title=Mx&email=xx"
curl "http://localhost:8000/persons/action01?name=%3Cb%3Emartin%3C/b%3E&age=42&title=Mr"
curl "http://localhost:8000/persons/action01?age=200&title=Mr"
1
2
3
<p>The form contains errors:</p><ul><li>name: Ensure this value has at least 2 characters (it has 1).</li><li>age: an integer is expected</li><li>title: unknown value</li><li>email: Enter a valid email address.</li></ul>
<p>Welcome Mr &lt;b&gt;martin&lt;/b&gt; (42 years old)</p>
<p>The form contains errors:</p><ul><li>name: the field is required</li><li>age: Ensure this value is less than or equal to 150.</li></ul>

El nombre [<b>martin</b>] (codificado como [%3Cb%3E...] en la URL) se muestra tal cual, sin negrita: sus etiquetas han sido neutralizadas. Observe que la respuesta, esta vez, tiene código de estado 200: la vista decidió generar una página normal que contiene los errores.

3.4. Ejemplo 10: parámetros múltiples

Un mismo parámetro puede aparecer varias veces en una URL: [?color=red&color=green]. Esto es lo que envía un navegador para un grupo de casillas de verificación con el mismo nombre, o para una lista de selección múltiple (véase el próximo capítulo). Las vistas de la aplicación [arrays]:

# arrays/views.py: un parámetro que aparece varias veces en la URL

from django import forms
from django.http import JsonResponse
from django.views.decorators.http import require_GET


# /arrays/action01?color=red&color=green: get devuelve el ÚLTIMO valor del
# parámetro; request.GET los ha conservado todos, sin embargo
@require_GET
def action01(request):
    return JsonResponse({"color": request.GET.get("color"),
                         "raw": request.META["QUERY_STRING"]})


# /arrays/action02?color=red&color=green: getlist devuelve TODOS los valores del
# parámetro, en una lista (vacía si está ausente)
@require_GET
def action02(request):
    colors = request.GET.getlist("color")
    return JsonResponse({"color": colors, "count": len(colors)})


# el modelo de action03: un campo con VALORES MÚLTIPLES, cada uno de los cuales debe
# pertenecer a la lista; obligatorio (el valor predeterminado): al menos un valor
class ColorsModel(forms.Form):
    color = forms.MultipleChoiceField(
        choices=[("red", "red"), ("green", "green"), ("blue", "blue")],
        error_messages={"invalid_choice": "%(value)s: unknown value"})


# /arrays/action03?color=red&color=black: una lista, validada elemento por elemento
@require_GET
def action03(request):
    model = ColorsModel(request.GET)
    valid = model.is_valid()
    return JsonResponse({"colors": request.GET.getlist("color"), "valid": valid,
                         "errors": model.errors.get("color", [])})
  • líneas 11–13: [get] devuelve el último valor del parámetro. La vista también devuelve, a modo de comparación, la cadena de parámetros sin procesar tal como la envió el navegador;
  • líneas 19–21: [getlist] devuelve todos los valores del parámetro en una lista; la lista está vacía si el parámetro está ausente. Este es el propósito de la clase [QueryDict]: un diccionario que asocia una lista de valores a cada clave, y cuyo método [get] devuelve solo el último valor, para el caso más común;
  • líneas 26–29: el modelo de vista 03, un formulario de un solo campo. Un [MultipleChoiceField] recibe una lista de valores y verifica que cada uno pertenezca a la lista de opciones; como es obligatorio, exige al menos un valor. Su mensaje [invalid_choice] contiene el marcador [%(value)s], que [Django] reemplazará por el valor incorrecto (esta es la sintaxis de las cadenas de formato de [Python] que usan el operador [%]). Una clase puede definirse en el archivo de vistas; no necesita su propio módulo;
  • líneas 34–38: el formulario se enlaza con los parámetros de la URL: lee por sí mismo todos los valores del parámetro [color], porque su campo es un campo de múltiples valores. La vista devuelve los colores recibidos, el resultado de la validación y los errores del campo, si los hay ([errors.get("color", [])]: la lista de mensajes, o una lista vacía si el campo no tiene errores).

Los resultados:

curl "http://localhost:8000/arrays/action01?color=red&color=green"
curl "http://localhost:8000/arrays/action02?color=red&color=green"
{
    "color": "green",
    "raw": "color=red&color=green"
}
{
    "color": [
        "red",
        "green"
    ],
    "count": 2
}

Para HTML, basta con dar el mismo nombre a las casillas de verificación de un grupo (los formularios de [Django] lo harán por nosotros; véase el ejemplo 18). Esta es una diferencia con [PHP], que los lectores del curso de [Symfony] conocieron: [PHP] conserva solo el último valor de un parámetro repetido, a menos que su nombre termine con corchetes ([color[]]). [Django], como [Flask], [Spring MVC] o [ASP.NET Core], conserva todos los valores, sin corchetes. De hecho, para el sistema, los corchetes son solo dos caracteres del nombre: [?color[]=red] define un parámetro llamado [color[]], que [getlist("color")] no puede ver.

Validación: exitosa al principio, luego fallida por un color desconocido y, por último, por una lista vacía:

1
2
3
curl "http://localhost:8000/arrays/action03?color=red&color=blue"
curl "http://localhost:8000/arrays/action03?color=red&color=black"
curl "http://localhost:8000/arrays/action03"
{
    "colors": [
        "red",
        "blue"
    ],
    "valid": true,
    "errors": []
}
{
    "colors": [
        "red",
        "black"
    ],
    "valid": false,
    "errors": [
        "black: unknown value"
    ]
}
{
    "colors": [],
    "valid": false,
    "errors": [
        "This field is required."
    ]
}

El mensaje de error identifica el valor incorrecto, [black].

3.5. Ejemplo 11: parámetros de una solicitud POST

Los ejemplos anteriores usaban solicitudes GET, cuyos parámetros están contenidos en la URL. Una solicitud POST lleva sus datos en el cuerpo, en dos formas principales:

  • los campos de un formulario HTML: el cuerpo tiene la misma sintaxis que una cadena de consulta ([name=martin&age=42]), y su tipo (encabezado [Content-Type]) es [application/x-www-form-urlencoded] (o [multipart/form-data], para un formulario que envía archivos);
  • un documento JSON, enviado por un programa ([JavaScript] en una página, cliente de una API...): el tipo es [application/json].

Las vistas de la aplicación [post]:

# post/views.py: los parámetros de una solicitud POST

import json

from django.core.exceptions import BadRequest
from django.http import HttpResponse, JsonResponse
from django.views.decorators.http import require_POST

from .binding import body_data, from_body
from .viewmodels import PersonModel


# los campos de un formulario HTML (cuerpo application/x-www-form-urlencoded):
# request.POST contiene los parámetros del CUERPO de la solicitud
@require_POST
def action01(request):
    return JsonResponse({
        "receivedType": request.headers.get("Content-Type"),
        "fields": request.POST.dict(),
        # un campo repetido: todos sus valores (véase el ejemplo 10)
        "hobbies": request.POST.getlist("hobby"),
    })


# un cuerpo JSON: Django no lo decodifica; request.body contiene el cuerpo sin procesar (unos
# bytes), que json.loads deserializa
@require_POST
def action02(request):
    # content_type: el tipo del cuerpo, leído en el encabezado Content-Type
    if request.content_type != "application/json":
        return JsonResponse({"message": "the request body must be JSON"}, status=415)
    try:
        body = json.loads(request.body)
    except json.JSONDecodeError as e:
        raise BadRequest(f"malformed JSON: {e}")
    return JsonResponse({"receivedType": request.headers.get("Content-Type"), "body": body,
                         "name": body.get("name")})


# un solo campo, ya sea que el cuerpo sea un formulario o un documento JSON
@require_POST
def action03(request):
    name = body_data(request).get("name")
    return HttpResponse(f"name = [{name}]")


# el cuerpo, formulario o JSON, enlazado a un PersonModel y validado (véase el ejemplo 08)
@require_POST
@from_body(PersonModel)
def action04(request, person):
    return JsonResponse({"person": person, "valid": True})
  • líneas 15, 27, 41, 48: todas las vistas aceptan únicamente el método POST (decorador [require_POST]);
  • línea 18: el encabezado [Content-Type] de la solicitud;
  • líneas 19–21: el atributo [POST] de la solicitud contiene los campos del cuerpo de un formulario, dentro de un [QueryDict], igual que [GET] (ejemplos 07 y 10): [get], [getlist], [dict]... Está vacío para cualquier otro tipo de cuerpo, en particular un cuerpo JSON;
  • Línea 30: [content_type] es el tipo del cuerpo, leído del encabezado [Content-Type] (sin el juego de caracteres que pueda seguirlo). Un cuerpo que no es de tipo JSON se rechaza con el error 415 (Unsupported Media Type);
  • líneas 32–35: [Django] no decodifica un cuerpo JSON: el atributo [body] contiene el cuerpo sin procesar, en forma de bytes, que la función [json.loads] deserializa: el texto JSON se convierte en un diccionario (o una lista, un número...). Un JSON mal formado lanza la excepción [json.JSONDecodeError], que captura el bloque [try] / [except] ; [as e] asigna un nombre a la excepción para incluir su mensaje en el nuestro, en una respuesta 400;
  • líneas 41–44: un solo campo, leído de los datos del cuerpo, ya sea un formulario o un documento (JSON): este es el trabajo de la función [body_data], que se describe más adelante;
  • líneas 48–51: el decorador [from_body] es el equivalente, para el cuerpo de la solicitud, del decorador [from_url] del ejemplo 08: construye un [PersonModel] (el formulario del ejemplo 08) a partir de los campos del formulario o del documento JSON, y lo valida. Un modelo no válido lanza la excepción [InvalidModel], que el middleware [ValidationErrors] del ejemplo 08 convierte en una respuesta 400.

El archivo [post/binding.py]:

# post/binding.py: los datos del CUERPO de una solicitud y su enlace (binding) a un modelo

import json
from functools import wraps

from django.core.exceptions import BadRequest


# la excepción que se lanza cuando los datos no respetan las restricciones del modelo
class InvalidModel(Exception):
    def __init__(self, form):
        super().__init__("invalid model")
        self.form = form


# los datos del cuerpo de la solicitud, en un diccionario, ya sea que el cuerpo sea un
# documento JSON o los campos de un formulario HTML
def body_data(request):
    if request.content_type == "application/json":
        try:
            data = json.loads(request.body)
        except json.JSONDecodeError as e:
            raise BadRequest(f"malformed JSON: {e}")
        if not isinstance(data, dict):
            raise BadRequest("a JSON object is expected")
        return data
    return request.POST


# @from_body(PersonModel): la contraparte, para el cuerpo de la solicitud, del decorador
# @from_url del ejemplo 08
def from_body(model_class):
    def decorator(view):
        @wraps(view)
        def wrapper(request, *args, **kwargs):
            form = model_class(body_data(request))
            if not form.is_valid():
                raise InvalidModel(form)
            return view(request, form.cleaned_data, *args, **kwargs)
        return wrapper
    return decorator
  • Líneas 18–27: datos del cuerpo, en un diccionario: el documento JSON decodificado o los campos del formulario ([request.POST]). Un documento JSON que no es un objeto (una lista, un número) no puede llenar un formulario: esto produce un error 400;
  • Líneas 32–41: el decorador, idéntico al del ejemplo 08, salvo por la fuente de datos (línea 36). Un formulario de [Django] acepta cualquier diccionario, no solo un [QueryDict]: esto es lo que le permite validar también un documento JSON.

Para una solicitud POST, vale la pena destacar un punto: [Django] no requiere nada más para aceptarla, porque nuestros ejemplos todavía no incluyen el middleware de protección anti-CSRF (ejemplo 18). Con [curl], la opción [-d] (data) envía un cuerpo; la solicitud pasa entonces a ser una solicitud POST, de tipo [application/x-www-form-urlencoded], a menos que la opción [-H] (header) especifique un tipo diferente. La opción [-X POST] establece el método de forma explícita (aquí es opcional). Los campos de un formulario, incluido un campo repetido:

curl -i -X POST -d "name=martin&age=42&hobby=tennis&hobby=piano" http://localhost:8000/post/action01
HTTP/1.1 200 OK
Content-Type: application/json

{
    "receivedType": "application/x-www-form-urlencoded",
    "fields": {
        "name": "martin",
        "age": "42",
        "hobby": "piano"
    },
    "hobbies": [
        "tennis",
        "piano"
    ]
}

Un cuerpo JSON, que contiene un entero y un arreglo:

curl -i -H "Content-Type: application/json" -d "{\"name\": \"martin\", \"age\": 42, \"hobbies\": [\"tennis\", \"piano\"]}" http://localhost:8000/post/action02
HTTP/1.1 200 OK
Content-Type: application/json

{
    "receivedType": "application/json",
    "body": {
        "name": "martin",
        "age": 42,
        "hobbies": [
            "tennis",
            "piano"
        ]
    },
    "name": "martin"
}

Las comillas del JSON van precedidas de un [\] para evitar que termine la cadena del comando; en [Linux] y [macOS], también se puede encerrar el JSON entre apóstrofos: [-d '{"name": "martin"}']. A diferencia de los campos de un formulario, el JSON transporta tipos de datos: la edad ya es un entero. Un cuerpo que no es JSON, seguido de un JSON mal formado:

curl -i -d "name=martin" http://localhost:8000/post/action02
curl -i -H "Content-Type: application/json" -d "{name: martin}" http://localhost:8000/post/action02
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json

{
    "message": "the request body must be JSON"
}
HTTP/1.1 400 Bad Request
Content-Type: text/html

<!DOCTYPE html>
...

La segunda respuesta es la página de error de [Django], que muestra nuestro mensaje: [malformed JSON: Expecting property name enclosed in double quotes: line 1 column 2 (char 1)] (en JSON, los nombres de las propiedades deben ir entre comillas). Un solo campo, primero en el formulario, luego en JSON, seguido de la misma URL solicitada con GET:

1
2
3
curl -d "name=jean%20dupont" http://localhost:8000/post/action03
curl -H "Content-Type: application/json" -d "{\"name\": \"martin\"}" http://localhost:8000/post/action03
curl -i http://localhost:8000/post/action03
1
2
3
4
5
name = [jean dupont]
name = [martin]
HTTP/1.1 405 Method Not Allowed
Content-Type: text/html; charset=utf-8
Allow: POST

La URL existe, pero no para el método GET: [Django] devuelve una respuesta 405 (Method Not Allowed), y su encabezado [Allow] enumera los métodos aceptados (ejemplo 02). Por último, el modelo enlazado al cuerpo de la solicitud, primero mediante un formulario válido, luego uno no válido y, finalmente, mediante un documento JSON:

1
2
3
curl -d "name=martin&age=42&title=Mr" http://localhost:8000/post/action04
curl -d "name=m&age=abc&title=Mx" http://localhost:8000/post/action04
curl -H "Content-Type: application/json" -d "{\"name\": \"martin\", \"age\": \"42\", \"title\": \"Mr\"}" http://localhost:8000/post/action04
{
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mr",
        "email": ""
    },
    "valid": true
}
{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "Ensure this value has at least 2 characters (it has 1)."
        },
        {
            "field": "age",
            "message": "Enter a whole number."
        },
        {
            "field": "title",
            "message": "Select a valid choice. Mx is not one of the available choices."
        }
    ]
}
{
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mr",
        "email": ""
    },
    "valid": true
}

La última solicitud envía la edad como una cadena (["42"], entre comillas), mientras que el modelo espera un entero: el formulario la convierte, igual que convierte los campos de un formulario HTML. Un formulario de [Django] está pensado para datos de texto; también acepta un valor ya convertido (el entero 42 de JSON). Una API con requisitos de tipo más estrictos usaría, en cambio, la extensión [Django REST framework], cuyos serializadores distinguen la cadena ["42"] del entero 42.

3.6. Ejemplo 12: enlace y validación personalizados

Los conversores y campos estándar no siempre son suficientes. Este ejemplo muestra tres maneras de ampliar el enlace y la validación:

  • un conversor de ruta “personalizado”: una fecha en formato francés, [23-09-2026], en la ruta de la URL, entregada a la vista como un objeto;
  • un middleware que proporciona a la vista información que no proviene de la URL, sino de un encabezado HTTP;
  • un validador “personalizado” (sin espacios) y la conversión de una fecha [dd/mm/yyyy] mediante un método del formulario.
12-custom-binding/
├── bindings/
│   ├── __init__.py
│   ├── binding.py
│   ├── converters.py
│   ├── urls.py
│   ├── validators.py
│   ├── viewmodels.py
│   └── views.py
├── config/
│   ├── middleware.py
│   ├── settings.py
│   ├── urls.py
│   └── ...
└── manage.py

3.6.1. Un objeto enlazado a un parámetro de ruta: bindings/converters.py

En el ejemplo 02, vimos los conversores de [Django]: [int], [str], [slug], [uuid], [path]. La aplicación puede escribir los suyos. Escribiremos uno para una fecha en formato francés, representada por la clase [DayFr]:

# bindings/converters.py: una fecha francesa "23-09-2026" en la ruta de la URL

from dataclasses import dataclass
from datetime import date, datetime


@dataclass(frozen=True)
class DayFr:
    date: date

    # texto de la ruta -> objeto DayFr; None: el texto no designa una fecha.
    # @classmethod: un método de la CLASE, llamado DayFr.from_url(...)
    @classmethod
    def from_url(cls, text):
        try:
            # strptime lee una fecha según un formato; una fecha que no existe
            # ("31-02-2026") lanza ValueError
            return cls(datetime.strptime(text, "%d-%m-%Y").date())
        except ValueError:
            return None

    # objeto DayFr -> texto de la ruta (se usa al construir la URL de una ruta)
    def __str__(self):
        return self.date.strftime("%d-%m-%Y")


# un CONVERSOR de ruta: Django lo usa en ambos sentidos
class DayFrConverter:
    # la expresión regular que este segmento de la ruta debe cumplir
    regex = r"[0-9]{2}-[0-9]{2}-[0-9]{4}"

    # texto -> valor pasado a la vista; ValueError: la ruta no coincide (404)
    def to_python(self, value):
        day = DayFr.from_url(value)
        if day is None:
            raise ValueError(f"[{value}] is not a date")
        return day

    # valor -> texto, cuando reverse construye la URL de una ruta
    def to_url(self, value):
        return str(value)
  • líneas 7–9: una clase de datos inmutable, cuyo único atributo es una fecha, un objeto [date] del módulo [datetime] de la biblioteca estándar;
  • Líneas 13–20: un método de clase, marcado con [@classmethod]: se llama sobre la clase, [DayFr.from_url("23-09-2026")], y recibe la propia clase como primer parámetro, llamado [cls] por convención. Crea un objeto [DayFr] a partir del texto de la ruta, o devuelve [None] si el texto no es válido. [datetime.strptime] analiza una cadena según un formato específico: [%d] para el día, [%m] para el mes y [%Y] para el año de cuatro dígitos; devuelve un objeto [datetime] (una fecha y hora), del cual [.date()] conserva solo la fecha. Lanza una excepción [ValueError] si el texto no sigue el formato o si la fecha no existe: el 31 de febrero se rechaza. [cls(...)] crea un objeto de la clase;
  • líneas 23–24: la operación inversa. El método [__str__] especifica cómo convertir el objeto en una cadena ([str(day)], o una f-string); [strftime] escribe una fecha en un formato específico;
  • líneas 28–41: el conversor, una clase con un atributo y dos métodos, que [Django] reconoce por sus nombres (no se requiere ninguna clase padre: [Python] solo exige que un objeto tenga los atributos correctos; esto se conoce como “duck typing”);
  • línea 30: [regex] es la expresión regular con la que debe coincidir el segmento de la ruta: [[0-9]] denota un dígito, [{2}] denota la repetición del patrón anterior: dos dígitos, un guion, dos dígitos, un guion, cuatro dígitos. Un segmento con un formato diferente no coincide con la ruta. El prefijo [r] de la cadena sin procesar (raw string) indica a [Python] que no interprete las barras invertidas, que son comunes en las expresiones regulares;
  • líneas 33–37: [to_python] convierte el texto del segmento en un valor que se pasa a la vista. Si lanza [ValueError], [Django] considera que la ruta no coincide y prueba con las siguientes rutas; al final, se produce un error 404;
  • líneas 40–41: [to_url] hace lo contrario, mientras que [reverse] genera la URL de una ruta (ejemplo 04) a partir de un objeto [DayFr].

El conversor debe registrarse con un nombre antes de usarse por primera vez en una ruta. Esto es lo que hace el archivo [config/urls.py]:

# config/urls.py: la tabla de enrutamiento principal

from django.urls import include, path, register_converter

from bindings.converters import DayFrConverter

# un conversor "casero", registrado con el nombre dayfr: las rutas pueden
# ahora escribir <dayfr:day>, como <int:id>
register_converter(DayFrConverter, "dayfr")

urlpatterns = [
    path("examples/", include("bindings.urls")),
]
  • Línea 9: [register_converter] registra el conversor con el nombre [dayfr]: ahora las rutas pueden escribir [<dayfr:day>], igual que [<int:id>].

3.6.2. Un parámetro proporcionado por un middleware: config/middleware.py

Para dar a una vista información calculada a partir de la solicitud, también se puede hacer que la calcule un middleware (ejemplo 03), que la inserta en la solicitud antes de que llegue a la vista:

# config/middleware.py: los middlewares del ejemplo 12

from django.http import HttpResponse
from django.utils.translation import get_language_from_request

from bindings.binding import InvalidModel


# un middleware que CALCULA una información para las vistas
class DetectLanguage:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        # el encabezado "Accept-Language: fr-FR,fr;q=0.9,en;q=0.8" -> "fr": el idioma
        # preferido del navegador entre los del ajuste LANGUAGES (el de
        # LANGUAGE_CODE de forma predeterminada)
        request.language = get_language_from_request(request)
        # un objeto de Python acepta nuevos atributos: request.language queda ahora
        # disponible para los middlewares siguientes y para la vista
        return self.get_response(request)


# un modelo inválido produce una respuesta 400, que contiene, como texto plano, el mensaje
# del primer error
class TextError:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        return self.get_response(request)

    def process_exception(self, request, exception):
        if isinstance(exception, InvalidModel):
            # la primera lista de mensajes y su primer mensaje
            first = next(iter(exception.form.errors.values()))[0]
            return HttpResponse(first, status=400, content_type="text/plain; charset=utf-8")
        return None
  • línea 4: una función del [Django] módulo de traducción;
  • líneas 14–21: el middleware se ejecuta antes que la vista, ya que su código precede a la llamada a [self.get_response];
  • Línea 18: el encabezado de solicitud [Accept-Language] especifica los idiomas del usuario, en orden de preferencia: [fr-FR,fr;q=0.9,en;q=0.8] (el coeficiente [q] mide la preferencia, en una escala de 0 a 1). [get_language_from_request] selecciona, entre los idiomas admitidos por la aplicación (el ajuste [LANGUAGES], líneas 24–27 del archivo [config/settings.py]), el que prefiere el usuario; si no hay encabezado, o si ninguno es adecuado, usa por defecto el idioma especificado en el ajuste [LANGUAGE_CODE]. El middleware guarda el idioma en un nuevo atributo de la solicitud, [language]: a un objeto [Python] se le pueden agregar atributos en cualquier momento. Así es como [Django] mismo proporciona información a las vistas: [request.user] (el usuario autenticado), [request.session] (la sesión), [request.LANGUAGE_CODE] (el idioma)... son agregados por middleware;
  • líneas 26–38: la respuesta ante una validación fallida. Queremos que sea distinta de la del ejemplo 08: el mensaje del primer error, en texto sin formato, con código de estado 400. [errors.values()] recorre las listas de mensajes; [iter] devuelve un iterador sobre esas listas, del cual [next] obtiene la primera; [[0]] se refiere al primer mensaje de esta lista.

El middleware se ejecuta para todas las solicitudes. Un middleware que debe actuar solo para ciertas vistas verifica por sí mismo la ruta de la solicitud ([request.path]) o, en su método [process_view] (véase el capítulo sobre el ciclo de vida), la vista que está a punto de llamarse. Para una sola vista, es más apropiado un decorador, como [from_url]. En cuanto a la vista, encontrará la información en la solicitud (véase Vistas).

3.6.3. Un validador «personalizado» y una conversión: validators.py y viewmodels.py

Un validador es una función que recibe el valor de un campo (ya convertido) y lanza la excepción [ValidationError] si no es válido:

# bindings/validators.py: una restricción de validación "casera"

from django.core.exceptions import ValidationError


# un VALIDADOR: una función que recibe el valor de un campo y lanza
# ValidationError si no es adecuado
def no_space(value):
    if " " in value:
        raise ValidationError("the field must not contain any space", code="space")
  • Líneas 8–10: el operador [in] verifica la presencia de texto en una cadena. [ValidationError] es la excepción que lanzan los campos de [Django] mismo; su parámetro [code] ([space]) permitiría que un formulario reemplace el mensaje con [error_messages], de forma similar a los códigos de [Django] (ejemplo 09). El validador se llama solo si el valor está presente: la ausencia de un valor la gestiona el parámetro [required] del campo.

El validador lo usa la plantilla de búsqueda:

# bindings/viewmodels.py: el modelo de la búsqueda

from datetime import datetime

from django import forms
from django.core.exceptions import ValidationError

from .validators import no_space


class SearchModel(forms.Form):
    # una restricción "casera": validators, la lista de validadores del campo
    keyword = forms.CharField(required=False, validators=[no_space])
    # una fecha en formato dd/mm/aaaa, recibida como cadena...
    since = forms.CharField(required=False)

    # ... y CONVERTIDA por el método clean_since, que Django llama después de las
    # verificaciones del campo: lo que devuelve se convierte en el valor de cleaned_data["since"]
    def clean_since(self):
        text = self.cleaned_data["since"]
        if not text:
            return None
        try:
            return datetime.strptime(text, "%d/%m/%Y").date()
        except ValueError:
            raise ValidationError(f"{text} is not a valid dd/mm/yyyy date")
  • línea 13: el parámetro [validators] de un campo es la lista de sus validadores «personalizados», que se llaman después de las verificaciones propias del campo. [Django] proporciona validadores predefinidos en el módulo [django.core.validators]: [RegexValidator], [MinValueValidator], [URLValidator]...;
  • línea 15: la fecha se recibe como una cadena. Un [DateField] podría haberla convertido por sí mismo (con [input_formats=["%d/%m/%Y"]]); la convertimos manualmente para mostrar otra forma de hacerlo;
  • líneas 19–26: un método llamado [clean_] seguido del nombre de un campo es llamado por [is_valid()] después de las verificaciones del campo. Obtiene el valor del campo de [self.cleaned_data]; su valor de retorno reemplaza ese valor, y un [ValidationError] que lance se convierte en un error del campo. Aquí convierte la cadena en una fecha: la vista recibirá una fecha válida. Esta es la forma más común de agregar una regla o una conversión personalizada a un campo; para una regla que se aplica a varios campos, se redefine el método [clean] del formulario (ejemplo 19).

3.6.4. Vistas: bindings/views.py

# bindings/views.py: enlace y validación personalizados

from django.http import HttpResponse
from django.urls import reverse
from django.views.decorators.http import require_GET

from .binding import from_url
from .viewmodels import SearchModel


# /examples/schedule/23-09-2026: el parámetro day es un objeto DayFr, construido por
# el conversor de la ruta
@require_GET
def schedule(request, day):
    # reverse construye la URL de una ruta; el objeto DayFr se convierte en el texto de la ruta
    # mediante el método to_url del conversor: "23-09-2026"
    url = reverse("bindings:schedule", kwargs={"day": day})
    return HttpResponse(f"schedule for the day [{day.date.isoformat()}], of type "
                        f"{type(day.date).__name__}, URL: {url}")


# /examples/hello: una información que no proviene de la URL, sino de un encabezado,
# calculada por el middleware DetectLanguage y almacenada en la solicitud
@require_GET
def hello(request):
    return HttpResponse("Hello!" if request.language == "en" else "Bonjour !")


# /examples/search?keyword=django&since=01/09/2026
@require_GET
@from_url(SearchModel)
def search(request, search):
    since = search["since"].isoformat() if search["since"] else None
    return HttpResponse(f"search for [{search['keyword']}] since [{since}]")
  • Líneas 14–19: la vista recibe el objeto [DayFr] generado por el convertidor. Muestra la fecha en formato internacional ([isoformat()]: [2026-09-23]) y la URL de la ruta, generada por [reverse] (ejemplo 04), con el objeto [DayFr] como parámetro: [Django] lo convierte en texto mediante el método [to_url] del convertidor. La URL se refiere al sitio ([/examples/...]); [request.build_absolute_uri(url)] la haría absoluta. Dos f-strings escritas una junto a otra, entre paréntesis, son concatenadas por [Python] en una sola cadena;
  • líneas 25–26: la vista lee la información calculada por el middleware [DetectLanguage]. [a if condition else b] es la expresión condicional de [Python];
  • líneas 30–34: el modelo de la consulta, vinculado a los parámetros de la URL y validado por el decorador del ejemplo 08 (archivo [bindings/binding.py]). La vista recibe solo modelos válidos; la fecha ya es un objeto [date] o [None] .

3.6.5. Ejecución

El objeto asociado al parámetro de la ruta:

1
2
3
curl "http://localhost:8000/examples/schedule/23-09-2026"
curl -i "http://localhost:8000/examples/schedule/31-02-2026"
curl -i "http://localhost:8000/examples/schedule/2026-09-23"
1
2
3
4
5
6
7
schedule for the day [2026-09-23], of type date, URL: /examples/schedule/23-09-2026
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
...
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
...

La fecha se muestra en formato internacional, pero el objeto URL construido por [reverse] volvió al formato francés. El 31 de febrero no existe: 404, porque nuestro convertidor rechazó el segmento. Una fecha en formato internacional, [2026-09-23], no coincide con el patrón descrito por la expresión regular: también 404, sin que se llame siquiera a [to_python]. En ambos casos, la página de error de [Django] enumera las rutas, entre ellas [examples/ schedule/<dayfr:day>].

El middleware. La opción [-H] de [curl] establece el encabezado [Accept-Language]:

1
2
3
curl -H "Accept-Language: fr-FR,fr;q=0.9,en;q=0.8" http://localhost:8000/examples/hello
curl -H "Accept-Language: de-DE,de;q=0.9" http://localhost:8000/examples/hello
curl http://localhost:8000/examples/hello
1
2
3
Bonjour !
Hello!
Hello!

[fr-FR] no está en la lista de idiomas de la aplicación, pero [Django] puede recurrir al idioma genérico, [fr]. El alemán no está incluido en absoluto, y [curl] no envía un encabezado [Accept-Language]: en ambos casos, el idioma utilizado es el especificado en los ajustes ([LANGUAGE_CODE]). El capítulo sobre internacionalización abordará este tema, con la selección del idioma por parte del usuario.

El validador «interno» y la conversión de fechas:

1
2
3
4
curl "http://localhost:8000/examples/search?keyword=django&since=01/09/2026"
curl -i "http://localhost:8000/examples/search?keyword=key%20word&since=31/02/2026"
curl "http://localhost:8000/examples/search?since=31/02/2026"
curl "http://localhost:8000/examples/search"
1
2
3
4
5
6
7
search for [django] since [2026-09-01]
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8

the field must not contain any space
31/02/2026 is not a valid dd/mm/yyyy date
search for [] since [None]

La segunda solicitud contiene dos errores; el middleware devuelve solo el primero, el relacionado con la palabra clave. Sin ningún parámetro, el modelo es válido: ambos campos son opcionales.

3.6.6. Conclusión

Resumamos los métodos de que dispone una vista para obtener su modelo:

Origen
Métodos
Parámetros de la ruta
los parámetros de la vista, que tienen los mismos nombres; convertidos por un convertidor ([<int:id>]); un convertidor «personalizado» ([regex], [to_python], [to_url], [register_converter]) los vincula a un objeto
Parámetros de la URL
[request.GET.get(...)], [getlist], [dict]; un parámetro repetido conserva todos sus valores
Campos de un formulario POST
[request.POST.get(...)], [getlist], [dict]
JSON del cuerpo
[json.loads(request.body)], después de validar [request.content_type]
Modelo descrito por una clase
un formulario [Django] ([forms.Form]): conversión y validación de cada campo ([is_valid], [cleaned_data], [errors]); un decorador para hacerlo antes de la vista
Encabezados
[request.headers.get(...)], y funciones que los analizan, como [get_language_from_request]
Validación
parámetros de los campos ([required], [min_length], [min_value]...); validadores «personalizados» ([validators], [ValidationError]); los métodos [clean_<field>] y [clean]
Mensajes
el idioma [LANGUAGE_CODE], traducciones de [Django]; [error_messages] para un campo
Errores comunes
un middleware y su método [process_exception]
Información calculada
un componente de middleware, que la agrega a la solicitud ([request.language])

Los formularios HTML, en cambio, requieren más que una simple validación: deben mostrarse, volver a mostrarse con lo ingresado por el usuario y los posibles errores, y estar protegidos contra solicitudes falsificadas. Los formularios de [Django] pueden hacer todo esto con la ayuda de plantillas. Este es el tema del siguiente capítulo.