Serialización en Pydantic con model_dump resuelve un problema frecuente en proyectos Python: Convierte modelos validados en diccionarios o JSON mediante un contrato explícito. Esta guía explica el mecanismo, presenta un ejemplo ejecutable y marca los límites que evitan una implementación frágil.
Concepto y caso de uso
model_dump devuelve un diccionario; mode json convierte valores a tipos serializables. model_dump_json genera texto JSON con las reglas del modelo.
Para repasar los fundamentos relacionados, consulta también la guía de Pydantic. La integración es más simple cuando cada función recibe dependencias y datos explícitamente en lugar de depender de estado global.
Ejemplo práctico
from datetime import datetime
from pydantic import BaseModel, Field, field_serializer
class UserOut(BaseModel):
id: int
display_name: str = Field(serialization_alias="name")
created_at: datetime
@field_serializer("created_at")
def serialize_date(self, value: datetime) -> str:
return value.isoformat()
payload = user.model_dump(mode="json", by_alias=True)Crea modelos de salida separados para fronteras públicas. Usa include y exclude como protección adicional, no como sustituto del contrato.
Decisiones importantes
La elección correcta depende del contrato público, del volumen y del comportamiento ante fallos.
Considera concurrencia, entradas vacías y fallos parciales. Documenta cada límite que afecte a consumidores y usa nombres que expresen intención.
Errores frecuentes
El ejemplo mínimo no sustituye límites, manejo de errores y observabilidad. Serializar un modelo interno puede exponer hashes o flags administrativas. Los aliases inconsistentes rompen consumidores silenciosamente.
Evita capturar excepciones sin contexto o devolver resultados parciales como si fueran completos. Un fallo explícito suele ser más seguro que datos silenciosamente incorrectos.
Cómo validar
Valida el comportamiento y no solo el camino feliz. Prueba el payload exacto, fechas, enums, aliases, opcionales y la ausencia deliberada de información sensible.