Pydantic: validación de datos

Teoría22 min20 XP

Nunca confíes en los datos que llegan de afuera: un cliente puede enviar campos faltantes, tipos equivocados, valores absurdos. PYDANTIC es la pieza que valida y estructura esos datos en FastAPI: defines un MODELO con los campos y sus tipos, y Pydantic verifica que todo cumpla —o rechaza con un error detallado—. Si viste Zod en TypeScript (SC-03), esto te va a sonar íntimo: es la misma idea, en Python. Hoy dominas Pydantic, el corazón de la validación de FastAPI.

El inspector en la puerta

Modelos con BaseModel

Un modelo de Pydantic es una clase que hereda de BaseModel, con los campos declarados por tipo (como una dataclass, pero con validación):

modelos.py

from pydantic import BaseModel, Field, EmailStr

# un MODELO define la forma y las reglas de los datos
class Gasto(BaseModel):
  nombre: str
  valor: int = Field(gt=0)                    # gt=0 -> mayor que 0
  categoria: str = "otros"                    # opcional, con valor por defecto

# Pydantic VALIDA al crear la instancia:
gasto = Gasto(nombre="Café", valor=4000)
print(gasto)                                    # nombre='Café' valor=4000 categoria='otros'
print(gasto.model_dump())                       # {'nombre': 'Café', 'valor': 4000, ...}

# si los datos no cumplen, Pydantic LANZA un error detallado:
try:
  Gasto(nombre="Bus", valor=-100)             # valor negativo -> falla
except Exception as e:
  print(e)                                    # explica: valor should be greater than 0

# convierte tipos cuando puede: "4000" (texto) -> 4000 (int)
g2 = Gasto(nombre="Cine", valor="18000")
print(g2.valor, type(g2.valor))                 # 18000 <class 'int'>

Un modelo Pydantic (class Gasto(BaseModel)) declara los campos con sus tipos, y VALIDA automáticamente al crear una instancia: si valor es negativo (con la regla Field(gt=0)), o falta nombre, o un tipo no cuadra, lanza un error detallado. También CONVIERTE tipos cuando tiene sentido (el string "18000" a int 18000). model_dump() lo convierte de vuelta a un diccionario. Es exactamente el patrón de Zod: un esquema que garantiza que los datos tienen la forma correcta antes de usarlos.

Reglas de validación y FastAPI

Validaciones ricas y la integración mágica

Pydantic ofrece validaciones potentes con Field y tipos especiales:

validaciones.py

from pydantic import BaseModel, Field, EmailStr, field_validator

class Usuario(BaseModel):
  nombre: str = Field(min_length=2, max_length=50)      # largo del texto
  edad: int = Field(ge=18, le=120)                       # entre 18 y 120
  email: EmailStr                                        # valida formato de email
  saldo: float = Field(default=0, ge=0)                  # no negativo

  # validador personalizado (regla propia)
  @field_validator("nombre")
  @classmethod
  def nombre_sin_numeros(cls, v: str) -> str:
      if any(c.isdigit() for c in v):
          raise ValueError("el nombre no puede tener números")
      return v.strip().title()                           # y lo normaliza

Field permite reglas como gt/ge/lt/le (mayor/menor que), min_length/max_length, y tipos como EmailStr validan formatos. Con @field_validator escribes reglas propias. Y aquí está la magia con FastAPI: cuando un endpoint recibe un parámetro de tipo modelo (gasto: Gasto), FastAPI usa Pydantic para validar el cuerpo de la petición AUTOMÁTICAMENTE —si los datos no cumplen, responde un error 422 con el detalle exacto, sin que escribas validación—. Y al devolver un modelo, lo serializa a JSON solo. Pydantic + FastAPI = datos validados a la entrada y serializados a la salida, gratis. Por eso FastAPI es tan seguro y productivo: la validación, que en otros frameworks es código tedioso, aquí sale de declarar tus modelos —el mismo z.infer y esquemas de Zod que ya conocías, en el ecosistema Python—.

¿Qué hace un modelo de Pydantic y cómo se integra con FastAPI?

Mini-reto

Diseña modelos Pydantic para Mi Bolsillo (en tu Python instalado): 1) un modelo Gasto con nombre: str (mínimo 2 caracteres), valor: int (mayor que 0) y categoria: str (con default); 2) prueba crear uno válido e imprime su model_dump(); 3) intenta crear uno inválido (valor negativo, nombre vacío) y captura el error para ver el detalle; 4) bonus: agrega un @field_validator que rechace nombres con números. Compara con los esquemas de Zod del SC-03.

Qué sigue

Ya validas los datos que entran. Pero una API real los GUARDA: en una base de datos. La próxima lección trae la persistencia con SQL —verás sqlite3 corriendo en vivo aquí mismo— y SQLModel, la forma moderna de conectar tu API FastAPI con una base de datos usando los mismos modelos que ya conoces.