Métodos Dunder / Mágicos

Los métodos de doble guion bajo permiten que tus clases participen en la sintaxis de Python: operadores, gestores de contexto, iteración y formato de cadenas. Implementa estos métodos deliberadamente; los valores predeterminados no siempre son correctos para los objetos de valor.

Receta

class Vector:
    def __init__(self, x: float, y: float) -> None:
        self.x = x
        self.y = y
 
    def __repr__(self) -> str:
        return f"Vector({self.x}, {self.y})"
 
    def __add__(self, other: "Vector") -> "Vector":
        return Vector(self.x + other.x, self.y + other.y)
 
    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Vector):
            return NotImplemented
        return (self.x, self.y) == (other.x, other.y)

Cuándo usar esto:

• Tipos de valor con +, == o ordenamiento natural.
• Contenedores personalizados que implementan len, getitem.
• Tipos de recursos que necesitan limpieza con with.
• __repr__ útil para depuración en objetos de dominio.

Ejemplo de Trabajo

class Shelf:
    def __init__(self, items: list[str]) -> None:
        self._items = list(items)
 
    def __len__(self) -> int:
        return len(self._items)
 
    def __getitem__(self, index: int) -> str:
        return self._items[index]
 
    def __contains__(self, item: object) -> bool:
        return item in self._items
 
    def __repr__(self) -> str:
        return f"Shelf({self._items!r})"
 
class Money:
    __slots__ = ("amount", "currency")
 
    def __init__(self, amount: int, currency: str) -> None:
        self.amount = amount
        self.currency = currency
 
    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Money):
            return NotImplemented
        return self.amount == other.amount and self.currency == other.currency
 
    def __hash__(self) -> int:
        return hash((self.amount, self.currency))
 
if __name__ == "__main__":
    s = Shelf(["a", "b"])
    print(len(s), "a" in s, s[0])
    cache = {Money(100, "USD"): "ok"}
    print(cache[Money(100, "USD")])

Lo que esto demuestra:

• Protocolo de contenedor a través de __len__, __getitem__, __contains__.
• Igualdad de valor con __eq__ devolviendo NotImplemented para tipos desconocidos.
• La coincidencia de __hash__ permite su uso como clave de diccionario.
• __repr__ muestra una pista de reconstrucción orientada al desarrollador.

Análisis Profundo

Cómo Funciona

• Modelo de datos: Python llama a los métodos dunder para operadores y funciones integradas.
• __init__ vs __new__: __new__ crea la instancia; __init__ la inicializa. Raramente se anula __new__.
• Comparaciones enriquecidas: __lt__ etc. habilitan sorted y @total_ordering.
• Contrato de hash: Objetos iguales deben tener hashes iguales; el hash no debe cambiar mientras está en un diccionario/conjunto.
• Protocolo de iterador: __iter__ + __next__ o métodos generadores.

Dunders Comunes

Notas de Python

from functools import total_ordering
 
@total_ordering
class Version:
    def __init__(self, major: int, minor: int) -> None:
        self.major = major
        self.minor = minor
 
    def __eq__(self, other: object) -> bool:
        ...
 
    def __lt__(self, other: "Version") -> bool:
        return (self.major, self.minor) < (other.major, other.minor)

Errores Comunes

• __eq__ sin __hash__: Hace que las instancias no sean "hasheables". Solución: Añadir un __hash__ consistente o usar una dataclass frozen.
• Objetos mutables como claves con __hash__: El hash no debe cambiar después de la inserción. Solución: Solo objetos de valor inmutables.
• __repr__ devolviendo secretos de usuario: Fugas de tokens en los registros. Solución: Redactar campos sensibles.
• Devolver NotImplemented: Un tipo incorrecto debe devolver NotImplemented, no False, para ==.
• Sobrecargar todo: Comportamiento de operador sorprendente. Solución: Implementar solo operaciones naturales.

Alternativas

Preguntas Frecuentes

Relacionado

• dataclasses - dunders generados
• Propiedades y Descriptores - acceso a atributos
• Inmutabilidad y Hashabilidad - reglas de hash
• Gestores de Contexto - enter/exit

Versiones de pila: 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+.