Diccionarios en Python

Un diccionario de Python es una colección mutable y ordenada de pares clave-valor. A diferencia de las listas o las tuplas (que usan posiciones enteras), un diccionario te permite etiquetar cada valor con una clave significativa, lo que hace que las búsquedas sean rápidas y el código más legible. Los diccionarios son uno de los tipos integrados más utilizados de Python y son la base del manejo de JSON, la gestión de configuraciones, el conteo de palabras y mucho más.

Este capítulo cubre todo lo que necesitas saber para usar diccionarios con confianza: creación, acceso, modificación, eliminación, iteración, comprensiones y errores comunes.

Capítulos relacionados: Métodos de Diccionario | Diccionarios Anidados | Recorrer Diccionarios | Copiar Diccionarios | Comprensiones en Python

¿Qué es un Diccionario?

Un diccionario mapea claves únicas y hasheables a valores de cualquier tipo. La regla principal: las claves deben ser inmutables — strings, números y tuplas de elementos inmutables califican; las listas y otros diccionarios no.

# string keys → integer values
inventory = {'apple': 10, 'banana': 5, 'orange': 8}

# mixed value types are fine
person = {'name': 'Alice', 'age': 30, 'active': True}

# tuple keys work because tuples are immutable
grid = {(0, 0): 'origin', (1, 0): 'east', (0, 1): 'north'}

Desde Python 3.7, los diccionarios mantienen el orden de inserción — iterar un diccionario siempre devuelve las claves en el orden en que fueron añadidas.

Crear un Diccionario

Literal con llaves

La forma más común: separa los pares clave-valor con comas, usa dos puntos entre cada clave y su valor, y envuelve todo entre {}.

config = {'host': 'localhost', 'port': 5432, 'debug': True}
print(config)
# {'host': 'localhost', 'port': 5432, 'debug': True}

Un diccionario vacío es simplemente {}.

empty = {}
print(type(empty))  # <class 'dict'>

Constructor dict()

Pasa argumentos de palabra clave a dict() cuando tus claves sean identificadores válidos de Python:

config = dict(host='localhost', port=5432, debug=True)
print(config)
# {'host': 'localhost', 'port': 5432, 'debug': True}

También puedes pasar un iterable de secuencias de dos elementos:

pairs = [('x', 10), ('y', 20)]
point = dict(pairs)
print(point)  # {'x': 10, 'y': 20}

dict.fromkeys()

Crea un diccionario a partir de una lista de claves, todas con el mismo valor inicial:

defaults = dict.fromkeys(['timeout', 'retries', 'verbose'], 0)
print(defaults)
# {'timeout': 0, 'retries': 0, 'verbose': 0}

Precaución: si el valor por defecto es un objeto mutable (como una lista), todas las claves compartirán el mismo objeto. Usa una comprensión de diccionario en su lugar (se muestra más abajo).

Comprensión de diccionario

Una forma concisa de construir un diccionario a partir de cualquier iterable:

squares = {x: x ** 2 for x in range(1, 6)}
print(squares)
# {1: 1, 2: 4, 3: 9, 4: 16, 5: 25}

Consulta Comprensiones en Python para ver la sintaxis completa.

Acceder a los Valores

Acceso por corchetes

inventory = {'apple': 10, 'banana': 5, 'orange': 8}
print(inventory['apple'])   # 10

Si la clave no existe, Python lanza un KeyError:

try:
    print(inventory['grape'])
except KeyError as e:
    print(f'KeyError: {e}')   # KeyError: 'grape'

get() — búsqueda segura con valor por defecto

dict.get(key, default) devuelve el valor si la clave existe, o default (que es None si se omite) en caso contrario — sin lanzar excepción.

print(inventory.get('grape'))       # None
print(inventory.get('grape', 0))    # 0
print(inventory.get('apple', 0))    # 10

Usa .get() siempre que no estés seguro de si una clave existe. Usa el acceso por corchetes cuando la clave deba estar presente — una clave faltante es entonces un error real que debe aflorar.

Comprobar si existe una clave

print('apple' in inventory)    # True
print('grape' in inventory)    # False
print('grape' not in inventory) # True

in prueba claves, no valores. Se ejecuta en tiempo O(1) promedio — constante, sin importar el tamaño del diccionario.

Agregar y Actualizar Elementos

Añadir un nuevo par clave-valor

Asigna a una clave que aún no exista:

inventory['grape'] = 12
print(inventory)
# {'apple': 10, 'banana': 5, 'orange': 8, 'grape': 12}

Actualizar un valor existente

Asigna a una clave que ya exista — el valor anterior se reemplaza:

inventory['apple'] = 15
print(inventory['apple'])  # 15

update() — agregar o sobreescribir en bloque

Pasa otro diccionario o un iterable de pares clave-valor:

inventory.update({'banana': 7, 'mango': 3})
print(inventory)
# {'apple': 15, 'banana': 7, 'orange': 8, 'grape': 12, 'mango': 3}

Fusionar con | (Python 3.9+)

El operador | crea un nuevo diccionario fusionado. Si una clave aparece en ambos, el lado derecho tiene prioridad:

a = {'x': 1, 'y': 2}
b = {'y': 99, 'z': 3}
merged = a | b
print(merged)   # {'x': 1, 'y': 99, 'z': 3}

Usa |= para fusionar b en a en el lugar — igual que a.update(b) pero más legible.

setdefault() — insertar solo si no existe

dict.setdefault(key, default) inserta la clave con el valor por defecto si está ausente, y siempre devuelve el valor de esa clave. Esto es más eficiente que el patrón if key not in d: d[key] = default.

scores = {'Alice': 95}
scores.setdefault('Bob', 0)     # Bob absent → inserts 0, returns 0
scores.setdefault('Alice', 0)   # Alice present → does nothing, returns 95
print(scores)   # {'Alice': 95, 'Bob': 0}

Un caso de uso clásico es agrupar elementos:

words = ['cat', 'car', 'bus', 'can', 'bat']
groups = {}
for word in words:
    groups.setdefault(word[0], []).append(word)
print(groups)
# {'c': ['cat', 'car', 'can'], 'b': ['bus', 'bat']}

Eliminar Elementos

del — eliminar por clave

inventory = {'apple': 15, 'banana': 7, 'orange': 8, 'grape': 12}
del inventory['orange']
print(inventory)
# {'apple': 15, 'banana': 7, 'grape': 12}

del lanza KeyError si la clave no existe. Para evitarlo, comprueba primero con in, o usa pop() con un valor por defecto.

pop() — eliminar y devolver el valor

removed = inventory.pop('grape')
print(removed)      # 12
print(inventory)    # {'apple': 15, 'banana': 7}

Proporciona un segundo argumento para evitar KeyError cuando la clave podría estar ausente:

val = inventory.pop('pear', 'not found')
print(val)   # not found

popitem() — eliminar el último elemento insertado (Python 3.7+)

d = {'a': 1, 'b': 2, 'c': 3}
last = d.popitem()
print(last)   # ('c', 3)
print(d)      # {'a': 1, 'b': 2}

clear() — eliminar todo

d = {'a': 1, 'b': 2}
d.clear()
print(d)   # {}

Iterar sobre un Diccionario

Tres vistas te permiten iterar sobre distintas partes de un diccionario. Las tres son vistas en vivo — reflejan los cambios en el diccionario sin necesidad de ser recreadas.

Claves (iteración por defecto)

Iterar directamente sobre un diccionario devuelve sus claves:

person = {'name': 'Alice', 'age': 30, 'city': 'Paris'}

for key in person:
    print(key)
# name
# age
# city

person.keys() devuelve las mismas claves como un objeto de vista dict_keys explícito.

Valores

for val in person.values():
    print(val)
# Alice
# 30
# Paris

Pares clave-valor

for key, val in person.items():
    print(f'{key}: {val}')
# name: Alice
# age: 30
# city: Paris

.items() es la opción más común cuando necesitas tanto la clave como el valor dentro del bucle. Consulta Recorrer Diccionarios para ver patrones avanzados.

Las vistas son en vivo

d = {'a': 1}
keys_view = d.keys()
d['b'] = 2
print(keys_view)   # dict_keys(['a', 'b'])  ← reflects the new key

Comprensiones de Diccionario

Las comprensiones de diccionario te permiten construir o transformar diccionarios en una sola expresión legible.

Filtrar por valor

inventory = {'apple': 15, 'banana': 7, 'orange': 8, 'grape': 12, 'mango': 3}
popular = {k: v for k, v in inventory.items() if v >= 8}
print(popular)
# {'apple': 15, 'orange': 8, 'grape': 12}

Invertir un diccionario (intercambiar claves y valores)

original = {'a': 1, 'b': 2, 'c': 3}
swapped = {v: k for k, v in original.items()}
print(swapped)   # {1: 'a', 2: 'b', 3: 'c'}

Esto solo funciona de forma segura cuando todos los valores son únicos.

Contador de frecuencia de palabras

sentence = 'the quick brown fox jumps over the lazy dog'
freq = {}
for word in sentence.split():
    freq[word] = freq.get(word, 0) + 1
print(freq)
# {'the': 2, 'quick': 1, 'brown': 1, 'fox': 1, ...}

Funciones Integradas Útiles

Para una referencia completa de todos los métodos de diccionario (copy, fromkeys, update, setdefault, popitem y más), consulta Métodos de Diccionario de Python.

Errores Comunes

1. KeyError con clave inexistente — usa siempre .get() o in cuando una clave podría no existir.

2. Tipos de clave no hasheables — las listas no pueden ser claves de diccionario porque son mutables. Usa una tupla en su lugar:

# This raises TypeError: unhashable type: 'list'
# bad = {[1, 2]: 'value'}

# Use a tuple:
coords = {(1, 2): 'A', (3, 4): 'B'}
print(coords[(1, 2)])  # A

3. Mutar mientras se itera — añadir o eliminar claves mientras se recorre un diccionario lanza RuntimeError. Toma una instantánea primero:

d = {'a': 1, 'b': 2, 'c': 3}
for key in list(d):          # list() copies the keys
    if d[key] < 2:
        del d[key]
print(d)   # {'b': 2, 'c': 3}

4. Copia superficial vs. copia profunda — dict.copy() y {**d} hacen ambos una copia superficial. Los valores mutables anidados (listas, dicts) siguen siendo compartidos. Usa copy.deepcopy() cuando necesites copias totalmente independientes. Consulta Copiar Diccionarios.

Diccionarios vs. Otros Tipos de Colecciones

Cuando necesitas buscar algo por una etiqueta significativa en lugar de una posición, un diccionario es casi siempre la opción correcta. Para valores únicos ordenados, considera un conjunto. Para una secuencia ordenada simple, usa una lista.

Práctica