Image for post Validación de Datos Robusta en Python con Pydantic: Más Allá de los Diccionarios

Validación de Datos Robusta en Python con Pydantic: Más Allá de los Diccionarios

Escrito por Sergio Márquez

Contexto del Problema

Como desarrollador Python, seguramente te has enfrentado a la tarea de procesar datos externos: una respuesta de una API, un formulario enviado por un usuario, un archivo de configuración JSON o YAML. El primer paso, y uno de los más críticos, es validar que esos datos tienen la estructura y los tipos que tu aplicación espera.

El enfoque tradicional implica un anidamiento de sentencias if, comprobaciones de claves en diccionarios con .get() y bloques try-except para capturar errores de tipo. Este código, conocido como "código de fontanería" (boilerplate), es tedioso de escribir, difícil de mantener y muy propenso a errores. ¿Qué pasa si una clave esperada no existe? ¿O si esperabas un entero y recibes un string? Estos problemas pueden causar bugs sutiles que se manifiestan mucho más tarde en la ejecución de tu programa.

Aquí es donde Pydantic entra en juego. Es una librería que utiliza los "type hints" (pistas de tipo) de Python para validar, parsear y serializar datos de una forma declarativa, robusta y muy pitónica. En lugar de escribir lógica de validación imperativa, defines la "forma" de tus datos y Pydantic se encarga del resto.

Conceptos Clave

Antes de escribir código, entendamos los tres pilares de Pydantic.

  • BaseModel: Es la clase fundamental de la que heredarás para crear tus propios modelos de datos. Al definir una clase que hereda de BaseModel, la transformas en un potente sistema de validación y gestión de datos.
  • Type Hints (Pistas de Tipo): Pydantic se apoya completamente en las anotaciones de tipo de Python (PEP 484). Defines los campos de tu modelo y sus tipos esperados (str, int, bool, List, etc.), y Pydantic los usará como la única fuente de verdad para la validación.
  • Validación y Coerción de Tipos: Cuando instancias un modelo con datos, Pydantic no solo comprueba que los tipos son correctos, sino que también intenta "coercer" o convertir los datos al tipo esperado si es posible. Por ejemplo, si un campo es de tipo int y recibe el string "123", Pydantic lo convertirá automáticamente al entero 123. Si la conversión no es posible, lanzará un error claro y detallado.
  • ValidationError: Cuando los datos no cumplen con la estructura o los tipos definidos, Pydantic lanza una única excepción: ValidationError. Esta excepción contiene una lista estructurada de todos los errores encontrados, indicando qué campo falló y por qué.

Implementación Paso a Paso

Vamos a construir un modelo simple para ver Pydantic en acción.

1. Instalación

Primero, asegúrate de tener Pydantic instalado en tu entorno virtual. Es una dependencia estándar y no requiere nada más para empezar.

pip install pydantic

2. Creando nuestro primer modelo

Imagina que estamos construyendo un sistema que gestiona perfiles de usuario. Un perfil de usuario básico podría tener un ID, un nombre de usuario, un email y un estado de actividad.

from pydantic import BaseModel

class UserProfile(BaseModel):
    user_id: int
    username: str
    email: str
    is_active: bool = True # Un campo con valor por defecto

¡Eso es todo! Hemos definido un "esquema" para nuestros datos. user_id, username y email son campos requeridos. is_active es opcional y tomará el valor True si no se proporciona.

3. Validando datos correctos

Ahora, vamos a crear una instancia de nuestro modelo con un diccionario de datos que simula una entrada válida.

# Datos de entrada (por ejemplo, de un JSON)
data = {
    "user_id": 101,
    "username": "alex_dev",
    "email": "alex@example.com"
}

# Creamos una instancia del modelo
try:
    user = UserProfile(**data)
    print("Validación exitosa!")
    print(user)
    # Podemos acceder a los atributos como en un objeto normal
    print(f"Email del usuario: {user.email}")
except Exception as e:
    print(f"Ocurrió un error inesperado: {e}")

La salida será:

Validación exitosa!
user_id=101 username='alex_dev' email='alex@example.com' is_active=True
Email del usuario: alex@example.com

Nota cómo Pydantic usó el valor por defecto para is_active y cómo podemos acceder a los campos usando la notación de punto.

4. Manejando datos incorrectos

¿Qué sucede si los datos son incorrectos? Pydantic nos protege. Vamos a intentarlo con datos que tienen errores: falta un campo requerido (username) y otro tiene un tipo incorrecto (user_id).

from pydantic import BaseModel, ValidationError

class UserProfile(BaseModel):
    user_id: int
    username: str
    email: str
    is_active: bool = True

invalid_data = {
    "user_id": "not-an-integer", # Tipo incorrecto
    # Falta el campo 'username'
    "email": "alex@example.com"
}

try:
    user = UserProfile(**invalid_data)
except ValidationError as e:
    print("¡Errores de validación detectados!")
    print(e.json())

La salida será un JSON que detalla cada error, lo cual es extremadamente útil para depurar o para enviar respuestas de error en una API.

¡Errores de validación detectados!
[
  {
    "type": "int_parsing",
    "loc": [
      "user_id"
    ],
    "msg": "Input should be a valid integer, unable to parse string as an integer",
    "input": "not-an-integer"
  },
  {
    "type": "missing",
    "loc": [
      "username"
    ],
    "msg": "Field required",
    "input": {
      "user_id": "not-an-integer",
      "email": "alex@example.com"
    }
  }
]

El error nos dice exactamente que user_id no pudo ser parseado como un entero y que el campo username es requerido y no fue proporcionado.

Mini Proyecto / Aplicación Sencilla

Vamos a aplicar lo aprendido en un script que lee una lista de usuarios desde un archivo JSON, valida cada uno y separa los usuarios válidos de los inválidos.

1. Crea el archivo users.json:

Copia y pega este contenido en un archivo llamado users.json en el mismo directorio que tu script de Python.

[
    {
        "user_id": 201,
        "username": "sara_ml",
        "email": "sara@example.com",
        "is_active": true
    },
    {
        "user_id": "202",
        "username": "mike_ops",
        "email": "mike@example.com"
    },
    {
        "user_id": 203,
        "username": "invalid_user",
        "email": "not-an-email"
    },
    {
        "user_id": 204,
        "email": "jane@example.com"
    }
]

2. Crea el script de validación validator.py:

Para validar emails de forma más estricta, Pydantic ofrece tipos especiales. Necesitarás instalar una dependencia extra para ello.

pip install pydantic[email]

Ahora, el script:

import json
from typing import List, Optional
from pydantic import BaseModel, ValidationError, EmailStr

# Modelo para un Post, que puede ser parte de un usuario
class Post(BaseModel):
    post_id: int
    title: str
    content: Optional[str] = None

# Modelo de Usuario actualizado con un tipo de email estricto y un campo anidado
class User(BaseModel):
    user_id: int
    username: str
    email: EmailStr  # Validación de email incorporada
    is_active: bool = True
    posts: List[Post] = [] # Modelo anidado

def process_user_data(file_path: str):
    """Lee datos de un JSON, los valida y separa los válidos de los inválidos."""
    valid_users = []
    invalid_entries = []

    try:
        with open(file_path, 'r') as f:
            data = json.load(f)
    except (FileNotFoundError, json.JSONDecodeError) as e:
        print(f"Error al leer el archivo: {e}")
        return

    for i, entry in enumerate(data):
        try:
            # Intentamos crear una instancia del modelo User
            user = User(**entry)
            valid_users.append(user)
        except ValidationError as e:
            invalid_entries.append({"entry_number": i + 1, "data": entry, "errors": e.errors()})

    print("--- Usuarios Válidos ---")
    for user in valid_users:
        print(user.model_dump_json(indent=2))

    print("\n--- Entradas Inválidas ---")
    for entry in invalid_entries:
        print(f"Entrada #{entry['entry_number']}: {entry['data']}")
        print(f"Errores: {entry['errors']}\n")

# Ejecución del script
if __name__ == "__main__":
    process_user_data("users.json")

3. Ejecuta el script:

python validator.py

Verás una salida clara que muestra qué usuarios pasaron la validación (incluyendo el usuario con user_id: "202", que fue exitosamente convertido a entero) y cuáles no, junto con los errores específicos para cada caso.

Errores Comunes y Depuración

  • Olvidar Optional: Si un campo puede ser None o no estar presente, debes declararlo como Optional[Tipo] del módulo typing. De lo contrario, Pydantic lo tratará como un campo requerido.
  • Coerción de tipos inesperada: A veces, la coerción automática de Pydantic puede ser sorprendente. Por ejemplo, bool aceptará valores como 'true', 'false', 1, 0. Si necesitas un comportamiento estricto, puedes configurar el modelo o usar tipos específicos como StrictBool.
  • Depurar ValidationError: El método .errors() te da una lista de diccionarios, mientras que .json() te da un string JSON. Ambos son increíblemente útiles. No te limites a imprimir la excepción (print(e)), ya que la representación JSON es mucho más rica para la depuración programática.
  • Modelos Anidados: Cuando un modelo contiene otro (como en nuestro ejemplo con List[Post]), Pydantic valida la estructura completa de forma recursiva. Un error común es pasar un diccionario en lugar de una instancia del modelo anidado, pero Pydantic maneja esto automáticamente al parsear los datos.

Aprendizaje Futuro / Próximos Pasos

Dominar BaseModel es solo el comienzo. Aquí tienes algunas áreas para explorar:

  • Validadores personalizados: Puedes usar el decorador @validator (en Pydantic v1) o @field_validator (en v2) para añadir lógica de validación personalizada que va más allá de las comprobaciones de tipo. Por ejemplo, para asegurar que una contraseña tenga una longitud mínima o contenga ciertos caracteres.
  • Gestión de Configuración con pydantic-settings: Pydantic tiene un paquete complementario, pydantic-settings, que te permite definir la configuración de tu aplicación en un modelo. Puede leer automáticamente variables de entorno y archivos .env, validando que toda tu configuración sea correcta al iniciar la aplicación.
  • Integración con FastAPI: Si trabajas con APIs, FastAPI utiliza Pydantic de forma nativa para definir los cuerpos de las solicitudes (request bodies) y las respuestas. Todo lo que has aprendido aquí se aplica directamente, permitiéndote construir APIs robustas y auto-documentadas con muy poco esfuerzo.
  • Serialización avanzada: Explora cómo exportar tus modelos a JSON o diccionarios con opciones avanzadas, como el uso de alias para los campos (Field(alias='...')) o la exclusión de ciertos valores al exportar.

Pydantic es una herramienta fundamental en el ecosistema moderno de Python. Te ahorra tiempo, previene errores y hace tu código más limpio y declarativo. Invertir tiempo en dominarlo es una de las mejores decisiones que puedes tomar como desarrollador junior-mid.

Volver al blog