dataclasses

dataclasses (stdlib desde 3.7) genera el código repetitivo de métodos comunes para clases que principalmente contienen datos. Son la opción predeterminada para registros internos antes de recurrir a modelos ORM completos.

Receta

from dataclasses import dataclass, field
 
@dataclass
class User:
    id: int
    name: str
    tags: list[str] = field(default_factory=list)

Cuándo usar esto:

• Eventos de dominio y DTOs dentro de las capas de aplicación
• Objetos de configuración/valor inmutables (frozen=True)
• Estructuras anidadas con __repr__ legible para depuración
• Reemplazar tuplas donde los nombres de campo ayudan a la legibilidad

Ejemplo de Trabajo

from dataclasses import dataclass, field
 
@dataclass(frozen=True)
class Money:
    amount: int
    currency: str
 
    def __post_init__(self) -> None:
        if self.amount < 0:
            raise ValueError("amount must be non-negative")
 
@dataclass
class Order:
    id: int
    lines: list[Money] = field(default_factory=list)
 
    def total(self) -> Money:
        if not self.lines:
            return Money(0, "USD")
        currency = self.lines[0].currency
        amount = sum(line.amount for line in self.lines)
        return Money(amount, currency)
 
if __name__ == "__main__":
    order = Order(1, [Money(100, "USD"), Money(50, "USD")])
    print(order)
    print(order.total())

Lo que esto demuestra:

• frozen=True evita la reasignación de atributos después de la creación
• __post_init__ valida invariantes después de __init__
• default_factory=list crea una lista nueva por instancia
• Los métodos coexisten con los métodos generados por dataclass

Análisis Profundo

Cómo Funciona

• El decorador transforma la clase - Añade métodos basados en campos y banderas en el momento de la creación de la clase.
• Orden de los campos - Los campos sin valores predeterminados deben preceder a los campos con valores predeterminados.
• KW_ONLY - field(kw_only=True) fuerza el paso por palabra clave para campos tardíos (3.10+).
• slots - @dataclass(slots=True) combina dataclass con __slots__ (3.10+).
• replace - dataclasses.replace(obj, amount=200) actualizaciones funcionales en instancias congeladas.

Banderas Útiles

Notas de Python

from dataclasses import asdict, astuple
 
payload = asdict(order)  # diccionario superficial - los dataclasses anidados se recursan
coords = astuple(point)

Errores Comunes

• Lista predeterminada mutable - tags: list = [] sigue siendo un error sin field. Solución: field(default_factory=list).
• Orden de campos en herencia - Los valores predeterminados de las subclases son complicados a través del MRO. Solución: Mantener jerarquías poco profundas o usar composición.
• asdict con mutables profundos - Copia la estructura pero los mutables anidados aún se aliastan si no son dataclasses. Solución: Conocer las necesidades superficiales vs. profundas.
• frozen con campos mutables - frozen evita la reasignación de lines pero la lista interna sigue siendo mutable. Solución: Campos de tupla o tipos inmutables.
• Comparación con dict - La instancia de dataclass no es igual a dict aunque los campos coincidan. Solución: Convertir explícitamente para APIs JSON.

Alternativas

Preguntas Frecuentes

Relacionado

• Dunder / Magic Methods - métodos generados
• Properties & Descriptors - campos calculados
• TypedDict & NamedTuple - alternativas de tipado
• Immutability & Hashability - objetos congelados

Versiones de Stack: Esta página fue escrita 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+.