Saltar a contenido

Los DTOs

Por cada tabla se generan varios modelos Pydantic 2. Son objetos normales, sin sesión detrás: se pueden serializar, devolver desde una API y guardar sin miedo a un DetachedInstanceError.

DTO Para qué
<Modelo>Read Lo que devuelven las lecturas. Incluye las relaciones cargadas
<Modelo>Create Datos de alta. Admite relaciones anidadas
<Modelo>Filter Filtros; cuáles, según el tipo de cada columna
<Modelo>UpdateValues Los valores a escribir en un update
<Modelo>Update filter + values, para update_many. No admite escrituras anidadas
<Modelo>UpdateNested Un hijo que se actualiza dentro del update de su padre: su clave + values
<Padre><Relación>NestedUpdate create, update y delete de los hijos de una relación en un update (UsuarioPostsNestedUpdate). Se importa por su nombre
<Modelo>DataFrameValidator Valida un DataFrame contra el esquema de la tabla

Read

usuario = public_sync_api.usuario.find(id=1, includes=['posts'])

usuario.nombre               # los campos, tipados
usuario.posts                # List[PostRead], si se pidió en includes
usuario.model_dump()         # dict
usuario.model_dump_json()    # str
usuario.to_dict()            # dict, como model_dump()

Incluye las columnas calculadas y las columnas de auditoría, si el schema las declara. Las columnas cifradas vienen descifradas y las vectoriales solo si se pidieron.

Create

UsuarioCreate(nombre='Ana', email='ana@x.com')

PostCreate(
    titulo='Hola',
    contenido='...',
    autor=UsuarioCreate(nombre='Ana', email='ana@x.com'),   # relación anidada
)

Las columnas con default, las opcionales y las autoincrementales no hacen falta. Los campos que no existen en la tabla se rechazan (extra='forbid'): un typo en el nombre de un campo es un error de validación, no un valor que se pierde en silencio.

Un hijo que va anidado en la lista de su padre —UsuarioCreate(posts=[PostCreate(...)])— no puede traer a su vez la relación con ese padre (PostCreate(autor=...)): es un ValidationError. La columna FK sí puede venir, y la pone el padre. Ver escritura.

Las columnas bytes en JSON

En Python una columna bytes (o largebinary) es bytes; en JSON viaja en base64. Los DTOs la declaran como JsonBytes, que solo cambia esa frontera:

FichaCreate.model_validate_json('{"imagen": "iVBORw0KGgo..."}').imagen   # b'\x89PNG\r\n...'
ficha.model_dump_json()                                                # '{"imagen":"iVBORw0KGgo...",...}'
  • Al leer un JSON —el cuerpo de una petición, model_validate_json— acepta base64 estándar o URL-safe, con o sin relleno. Lo demás, también con espacios o con el prefijo data:…;base64,, es un error de validación bytes_invalid_encoding. Un str pasado desde Python se trata igual; unos bytes, no se tocan.
  • Al escribir un JSON —model_dump_json, model_dump(mode='json'), la respuesta de un endpoint— sale en base64 estándar con relleno, que es lo que entienden atob() y una URL data:. El JSON Schema lo dice: {"type": "string", "contentEncoding": "base64"}.

Hasta la 0.7.21 se leían y escribían en UTF-8: el base64 que mandaba un frontend se guardaba como texto dentro de la columna, y un binario de verdad no se podía devolver en JSON. Esas filas no hay que migrarlas: unos bytes guardados que ya son base64 canónico se devuelven tal cual, como antes. Un fichero real nunca lo es —su cabecera tiene bytes fuera del alfabeto—, pero un contenido que sea él mismo texto base64 canónico (un hash en hexadecimal, una palabra de longitud múltiplo de cuatro) sale sin recodificar. Si una columna guarda esa clase de contenido, que sea str o text.

Filter y Update

from database.public import UsuarioFilter, UsuarioUpdateValues, UsuarioUpdate

public_sync_api.usuario.update_many(UsuarioUpdate(
    filter=UsuarioFilter(activo=False, min_creado_en=datetime(2026, 1, 1)),
    values=UsuarioUpdateValues(activo=True),
))

UpdateValues solo lleva lo que quieras escribir: lo que no declares no se toca.

Enumerados

Los campos de tipo enumerado se validan contra sus valores:

PostCreate(titulo='Hola', contenido='...', estado='publicado')   # ✅
PostCreate(titulo='Hola', contenido='...', estado='inventado')   # ValidationError

Y los valores posibles se consultan en la fachada:

public_sync_api.estado.find_many()   # ['borrador', 'publicado', 'archivado']

Usarlos con FastAPI

Son modelos Pydantic estándar, así que encajan directamente:

from fastapi import FastAPI
from database.public import public_sync_api, UsuarioRead, UsuarioCreate

app = FastAPI()

@app.get('/usuarios', response_model=list[UsuarioRead])
def listar(limit: int = 50):
    return public_sync_api.usuario.find_many(limit=limit)

@app.post('/usuarios', response_model=UsuarioRead)
def crear(usuario: UsuarioCreate):
    return public_sync_api.usuario.create(usuario)