Si una lista es una fila de cuadros numerados, un diccionario de Python es un conjunto de cuadros etiquetados. Usted solicita lo que desea por nombre en lugar de por posición, razón por la cual los diccionarios se encuentran detrás de los datos JSON, la configuración, los cachés y gran parte del propio Python.

Este tutorial comienza con lo básico y continúa con los patrones que los desarrolladores experimentados utilizan todos los días. Ejecutamos todos los ejemplos en Python 3.13 y el resultado que se muestra proviene de esa ejecución.

¿Qué es un diccionario?

Un diccionario, o dict, asigna claves a valores. Cada clave aparece sólo una vez y los valores pueden ser cualquier cosa, incluidas listas u otros diccionarios.

Desde Python 3.7, los diccionarios mantienen oficialmente el orden de inserción. Muchos tutoriales antiguos todavía los llaman desordenados, lo cual ya no es cierto. Para obtener una comparación más amplia de los otros tipos, consulte Lista de Python, tupla y conjunto.

Las búsquedas son rápidas porque los diccionarios utilizan una tabla hash. Verificar una clave lleva aproximadamente el mismo tiempo ya sea que el diccionario contenga diez elementos o un millón, mientras que la búsqueda en una lista se vuelve más lenta a medida que crece.

Crear un diccionario

user = {"name": "Asha", "age": 31, "city": "Pune"}

empty = {}
from_keywords = dict(name="Asha", age=31)
from_pairs = dict([("a", 1), ("b", 2)])

Las llaves son la forma más común. Una trampa: {} crea un diccionario vacío, no un conjunto vacío. Para un conjunto vacío, necesita set().

Leer valores de forma segura

Hay dos formas de leer un valor y la diferencia es importante cuando es posible que una clave no exista:

user["name"]                  # 'Asha'
user["email"]                 # KeyError: 'email'

user.get("email")             # None
user.get("email", "not set")  # 'not set'

Utilice corchetes cuando la clave deba existir, de modo que una clave faltante falle ruidosamente. Utilice get() cuando la ausencia sea normal, como un campo opcional en una respuesta API. Para verificar una clave, use el operador in, que busca claves en lugar de valores:

"city" in user    # True
"Pune" in user    # False

Agregar, actualizar y eliminar

La asignación de una clave la actualiza si existe o la agrega si no existe:

user["age"] = 32
user["email"] = "asha@example.com"
print(user)

# {'name': 'Asha', 'age': 32, 'city': 'Pune', 'email': 'asha@example.com'}

Python ofrece varias formas de eliminar elementos:

user.pop("city")          # returns 'Pune' and removes it
user.pop("phone", None)   # no error if it is missing
del user["email"]         # removes it, and raises KeyError if missing
user.clear()              # empties the dictionary

Utilice pop() cuando desee recuperar el valor. Pasar un valor predeterminado como segundo argumento evita un error cuando la clave no está allí. popitem() elimina y devuelve el par agregado más recientemente.

Recorrer un diccionario

Hacer un bucle directamente te da las claves. Para obtener claves y valores, utilice items():

user = {"name": "Asha", "age": 32}

for key, value in user.items():
    print(key, "=", value)

# name = Asha
# age = 32

keys(), values() y items() devuelven vistas en vivo en lugar de copias, por lo que reflejan cambios posteriores. No agregue ni elimine claves mientras recorre un diccionario, porque Python genera un RuntimeError. Pase por list(user) si necesita hacerlo.

Hoja de referencia de métodos de diccionario

Fusionar diccionarios

Una necesidad común es aplicar la configuración del usuario además de la predeterminada. Cuando las teclas chocan, gana el lado derecho:

defaults = {"theme": "light", "lang": "en"}
saved = {"theme": "dark"}

defaults | saved
{**defaults, **saved}

# Both give: {'theme': 'dark', 'lang': 'en'}

El operador | necesita Python 3.9 o posterior, mientras que la versión ** también funciona en versiones anteriores. Ambos crean un nuevo diccionario. Por el contrario, defaults.update(saved) y defaults |= saved cambian defaults en su lugar.

Comprensiones y clasificación

Las comprensiones de diccionario crean un nuevo diccionario en una sola línea legible, tal como lo hacen las comprensiones de listas con las listas:

prices = {"pen": 10, "book": 250, "bag": 900}

{k: v for k, v in prices.items() if v > 100}
# {'book': 250, 'bag': 900}

Para ordenar por valor, pase una función key a sorted(). Para encontrar la clave con el valor más grande, use max():

sorted(prices.items(), key=lambda item: item[1], reverse=True)
# [('bag', 900), ('book', 250), ('pen', 10)]

max(prices, key=prices.get)
# 'bag'

Un diccionario no tiene método sort() y sorted() devuelve una lista de pares. Envuelva el resultado en dict() si desea un diccionario en ese orden.

Patrones de conteo y agrupación.

Constantemente surgen dos tareas. El primero es contar, lo cual puedes hacer usando get() con un valor predeterminado de cero:

words = "to be or not to be".split()

counts = {}
for word in words:
    counts[word] = counts.get(word, 0) + 1

print(counts)
# {'to': 2, 'be': 2, 'or': 1, 'not': 1}

La biblioteca estándar hace esto aún más corto con Counter:

from collections import Counter

Counter(words).most_common(2)
# [('to', 2), ('be', 2)]

El segundo es agrupar, y defaultdict es ideal aquí porque crea el valor faltante:

from collections import defaultdict

orders = [("Asha", 1200), ("Ben", 300), ("Asha", 800)]

by_customer = defaultdict(list)
for name, total in orders:
    by_customer[name].append(total)

print(dict(by_customer))
# {'Asha': [1200, 800], 'Ben': [300]}

Sin él, deberá verificar si cada clave existe antes de agregarla. Estos mismos patrones funcionan bien para agregar datos de API o líneas de registro. Cuando un diccionario está vacío o falta una clave, nuestra guía para el manejo de excepciones de Python muestra cómo lidiar con el resultado KeyError.

Datos anidados y la trampa de copia

JSON se asigna directamente a listas y diccionarios anidados, por lo que a menudo encadenarás claves. Encadenar get() mantiene esto seguro cuando puede faltar un nivel:

response = {"user": {"profile": {"city": "Pune"}}}

response["user"]["profile"]["city"]               # 'Pune'
response.get("user", {}).get("settings", {}).get("theme")   # None

Tenga cuidado al copiar datos anidados. copy() duplica solo el nivel superior, por lo que los diccionarios internos permanecen compartidos con el original:

settings = {"db": {"host": "localhost"}}

shallow = settings.copy()
shallow["db"]["host"] = "prod"

print(settings["db"]["host"])
# prod

Cambiar la copia cambió el original, lo que puede ser un error desagradable. Utilice copy.deepcopy(settings) para obtener una copia totalmente independiente.

¿Qué puede ser una clave de diccionario?

Las claves deben ser hashable, lo que generalmente significa inmutable. Cadenas, números y tuplas de valores inmutables funcionan. Las listas y diccionarios no:

{["a"]: 1}

# TypeError: unhashable type: 'list'

La razón es que el hash de una clave decide dónde se almacena su valor. Si una clave pudiera cambiar, Python ya no podría encontrarla. Si necesita una clave compuesta, utilice una tupla, como {("Pune", 2026): 120}.

Errores comunes

• Uso de corchetes en claves opcionales. Busque get() cuando pueda faltar una clave.
• Suponiendo que get() significa que la clave existe. None podría significar que falta o está almacenada None. Utilice in cuando la diferencia sea importante.
• Usando un valor predeterminado mutable. dict.fromkeys(names, []) le da a cada clave la misma lista. Utilice una comprensión en su lugar.
• Cambio de tamaño durante la iteración. Recorre una copia de las claves.
• Usar un dict para campos fijos y conocidos. Un dataclass puede ser más claro y detecta errores tipográficos en los nombres de los campos.

Conclusión

Los diccionarios recompensan un poco de práctica. Recuerde get() para claves opcionales, items() para bucles y Counter y defaultdict para los dos trabajos más comunes. Para practicar, tome un pequeño archivo JSON y escriba código para contar y agrupar sus registros. Si eres nuevo en el idioma, comienza con nuestro tutorial de Python para principiantes.

Preguntas frecuentes

sigue aprendiendo