Saltearse al contenido

Hashabilidad

Un diccionario encuentra una clave en tiempo constante porque no la busca: calcula su hash, va a la cubeta correspondiente y compara. Ese truco exige dos promesas del objeto: que su valor no cambie y que dos objetos iguales produzcan el mismo hash. Un objeto que cumple las dos es hashable, y sólo los hashables pueden ser claves.

Hashable es la promesa de que el valor no cambia y de que dos iguales producen el mismo hash.

class Punto:
def __init__(self, x, y):
self.x, self.y = x, y
def __eq__(self, otro):
return (self.x, self.y) == (otro.x, otro.y)
def __hash__(self):
return hash((self.x, self.y))
  • __eq__ define qué significa ser igual.
  • __hash__ devuelve un entero estable mientras el objeto viva.

Las dos tienen que ser coherentes: si a == b, entonces hash(a) == hash(b) obligatoriamente. Lo contrario no: dos objetos distintos pueden compartir hash (una colisión), y el diccionario la resuelve comparando con ==.

Ese es el detalle que explica el caso más raro del lenguaje:

Tres claves que son la misma
Comprobación Resultado
hash(1) == hash(1.0) True
hash(1) == hash(True) True
len({1: "a", True: "b", 1.0: "c"}) 1
El diccionario resultante {1: "c"}

verificado en CPython 3.13

No es un bug: 1 == 1.0 == True, así que el contrato exige el mismo hash, y el diccionario considera que es la misma clave. La última asignación gana y la clave conserva el primer objeto insertado.

Tres nombres, una cubeta
clave 1 una sola entrada: {1: 'c'} 1 True 1.0

Son iguales entre sí y comparten hash, así que ocupan la misma entrada. El diccionario no distingue tipos en las claves: distingue igualdad.

El precio de O(1)
Operación Coste
Construir un set de 100 000 enteros 3.6 ms
Una consulta x in set 30 ns

python mediciones/01-06-09-argumentos-numeros-texto-hash.py

Treinta nanosegundos frente a los 30 microsegundos de un recorrido lineal del capítulo 11: mil veces. Ese es todo el argumento de dict y set, y también su factura de memoria: 32–37 bytes por entrada.

Hashable No hashable
int, float, bool, complex list
str, bytes dict
tuple (si todo su contenido lo es) set
frozenset bytearray
dataclass(frozen=True) dataclass normal
Instancias con __hash__ y __eq__ coherentes Objetos con __eq__ y sin __hash__

La regla es la de siempre: mutable no puede ser clave, porque si cambia, su hash cambia y la entrada queda en la cubeta equivocada, inencontrable para siempre.

Dos claves distintas pueden acabar en la misma cubeta: el hash tiene 64 bits y las cubetas son muchas menos, así que las colisiones son normales, no excepcionales. El diccionario las resuelve comparando con == dentro de la cubeta.

Eso tiene dos consecuencias que casi nadie conecta:

  • Un __eq__ lento hace lento el diccionario, aunque el hash sea perfecto. Comparar objetos con listas grandes dentro es una mala idea para una clave.
  • El hash de str se calcula una vez y se guarda en el objeto. Comparar cadenas por igualdad también es barato, porque primero compara longitudes y luego memoria.

Y una tercera: como el hash de str está aleatorizado por proceso (para evitar ataques de colisiones), el orden de iteración de un set de cadenas cambia entre ejecuciones. Si un test compara list(mi_set) contra una lista fija, fallará de forma intermitente. Ordena antes de comparar.

  • En objetos mutables de negocio. Un pedido cuyo total cambia no debe ser clave: usa su identificador.
  • Cuando el objeto ya es único por identidad. Si dos instancias nunca deben considerarse iguales, el __hash__ de object es correcto y no hay que tocarlo.
  • Para acelerar comparaciones. El hash acelera la búsqueda en tablas, no la comparación directa; añadirlo a un objeto que nunca va a un dict o set es código muerto que puede volverse incorrecto.

Tienes Punto(x, y) como @dataclass normal. Quieres usarlo como clave de un diccionario. Explica qué falla y compara las dos soluciones posibles.

Solución

Falla porque @dataclass genera __eq__, y eso deja __hash__ en None: la instancia es unhashable.

Solución 1 — frozen=True:

from dataclasses import dataclass
@dataclass(frozen=True)
class Punto:
x: int
y: int

Genera __hash__ a partir de los campos congelados. Es la opción correcta si el punto no debe cambiar: sirve como clave y además documenta que es un valor.

Solución 2 — eq=False:

@dataclass(eq=False)
class Punto:
x: int
y: int

Conserva la igualdad por identidad y el hash heredado de object: dos puntos con las mismas coordenadas son objetos distintos y claves distintas. Es lo correcto si cada punto representa una entidad única aunque sus coordenadas coincidan.

Lo que no funciona es añadir __hash__ a mano sobre una dataclass mutable: el hash cambiaría al mutar un campo y la clave se perdería dentro del diccionario.

Comprobación con datos de ejemplo:

@dataclass
class PuntoMutable:
x: int
y: int
try:
{PuntoMutable(1, 2): "a"}
except TypeError as error:
print("dataclass normal:", error)
@dataclass(frozen=True)
class PuntoFijo:
x: int
y: int
print("frozen, claves iguales:", {PuntoFijo(1, 2): "a"}[PuntoFijo(1, 2)])
print("eq=False, mismas coordenadas:", Punto(1, 2) == Punto(1, 2))
print("eq=False, claves en dict:", len({Punto(1, 2): "a", Punto(1, 2): "b"}))
  • Ramalho, L. Fluent Python, 2ª ed. Capítulo 3: Dictionaries and Sets.
  • CPython 3.13: Objects/dictobject.c (tabla combinada y sondeo), Objects/object.c (PyObject_Hash).
  • Mediciones: mediciones/01-06-09-argumentos-numeros-texto-hash.py.
  • 04 · Mutabilidad: la razón por la que un objeto mutable no puede ser clave.
  • 07 · Números: por qué 1, 1.0 y True colisionan.
  • 11 · Elección por coste: el precio en memoria de esa búsqueda en 30 nanosegundos.