Conceptos básicos de Pydantic

9 ejemplos para modelos Pydantic 2: 6 básicos y 3 intermedios.

Prerrequisitos

uv pip install "pydantic>=2" pydantic-settings

• Pydantic 2 utiliza pydantic-core para una validación rápida en Python 3.14.

Ejemplos básicos

1. Definir un modelo

Contenedor de datos tipados con validación.

from pydantic import BaseModel
 
class User(BaseModel):
    id: int
    name: str

• Las subclases de BaseModel definen campos.
• La validación se ejecuta al instanciar.
• Los campos extra están prohibidos por defecto en los modos estrictos de la v2.

Relacionado: Tipos de campo y restricciones - Field()

2. Errores de validación

Captura de entradas incorrectas.

from pydantic import BaseModel, ValidationError
 
class Age(BaseModel):
    years: int
 
try:
    Age(years="x")
except ValidationError as e:
    print(e.error_count())

• ValidationError contiene las ubicaciones.
• Úsalo en respuestas 422 de API.
• error_count resume los fallos.

3. Valores por defecto y opcionales

Campos opcionales y fábricas.

from pydantic import BaseModel, Field
 
class Item(BaseModel):
    name: str
    tags: list[str] = Field(default_factory=list)

• Usa default_factory para valores por defecto mutables.
• Optional significa T | None.
• La diferencia entre "no establecido" y "nulo explícito" en las exportaciones.

4. model_dump

Serializa a datos compatibles con dict/JSON.

user = User(id=1, name="Ada")
user.model_dump()
user.model_dump(mode="json")

• mode='json' convierte datetimes.
• exclude_unset omite los campos faltantes.
• Prefiere model_dump sobre dict().

Relacionado: Serialización - exportaciones avanzadas

5. Modelos anidados

Compón estructuras.

class Address(BaseModel):
    city: str
 
class Profile(BaseModel):
    address: Address

• Los modelos anidados se validan recursivamente.
• Usa list[Model] para colecciones.
• Aplana con model_dump anidado.

Relacionado: Modelos anidados y recursivos - árboles

6. ConfigDict

Comportamiento a nivel de modelo.

from pydantic import BaseModel, ConfigDict
 
class Strict(BaseModel):
    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)

• extra='forbid' rechaza claves desconocidas.
• str_strip_whitespace limpia la entrada.
• from_attributes habilita el modo ORM.

Ejemplos intermedios

7. field_validator

Comprobaciones personalizadas a nivel de campo.

from pydantic import BaseModel, field_validator
 
class EmailUser(BaseModel):
    email: str
 
    @field_validator("email")
    @classmethod
    def must_have_at(cls, v: str) -> str:
        if "@" not in v:
            raise ValueError("invalid email")
        return v.lower()

• Los validadores se ejecutan después de la coerción de tipos.
• classmethod es requerido en v2.
• Lanza ValueError para fallos.

Relacionado: Validadores - validadores de modelo

8. model_validator

Reglas entre campos.

from pydantic import BaseModel, model_validator
 
class Range(BaseModel):
    low: int
    high: int
 
    @model_validator(mode="after")
    def check_order(self):
        if self.high < self.low:
            raise ValueError("high < low")
        return self

• mode='after' ve el modelo analizado.
• Úsalo para pares de confirmación de contraseña.
• Devuelve self en validadores after.

9. Esquema JSON

Genera el esquema para la documentación.

User.model_json_schema()

• Alimenta los componentes de OpenAPI.
• Mantén los modelos como única fuente de verdad.
• Exporta para la generación de código del cliente.

Relacionado: Serialización - exportación de esquemas

Versiones de la pila: Esta página se escribió para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.