Dicionários Python

Um dicionário Python é uma coleção mutável e ordenada de pares chave-valor. Ao contrário de listas ou tuplas (que usam posições inteiras), um dicionário permite rotular cada valor com uma chave significativa — tornando as buscas rápidas e o código mais legível. Os dicionários são um dos tipos embutidos mais usados do Python e formam a base do tratamento de JSON, gerenciamento de configurações, contagem de palavras e muito mais.

Este capítulo abrange tudo o que você precisa saber para usar dicionários com confiança: criação, acesso, modificação, exclusão, iteração, comprehensions e armadilhas comuns.

Capítulos relacionados: Métodos de Dicionário | Dicionários Aninhados | Loop em Dicionários | Copiar Dicionários | Python Comprehensions

O que é um Dicionário?

Um dicionário mapeia chaves únicas e hasheáveis para valores de qualquer tipo. A regra principal: as chaves devem ser imutáveis — strings, números e tuplas de imutáveis são aceitos; listas e outros dicionários não são.

# 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 o Python 3.7, os dicionários mantêm a ordem de inserção — iterar um dicionário sempre retorna as chaves na ordem em que foram adicionadas.

Criando um Dicionário

Literal com chaves

A forma mais comum: separe os pares chave-valor com vírgulas, use dois-pontos entre cada chave e seu valor, e envolva tudo em {}.

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

Um dicionário vazio é simplesmente {}.

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

Construtor dict()

Passe argumentos de palavra-chave para dict() quando suas chaves forem identificadores Python válidos:

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

Você também pode passar um iterável de sequências de dois elementos:

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

dict.fromkeys()

Crie um dicionário a partir de uma lista de chaves, todas compartilhando o mesmo valor inicial:

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

Armadilha: se o valor padrão for um objeto mutável (como uma lista), todas as chaves compartilharão o mesmo objeto. Use uma comprehension de dicionário nesse caso (mostrado abaixo).

Comprehension de dicionário

Uma forma concisa de construir um dicionário a partir de qualquer iterável:

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

Consulte Python Comprehensions para a sintaxe completa.

Acessando Valores

Acesso por colchetes

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

Se a chave não existir, Python lança um KeyError:

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

get() — busca segura com valor padrão

dict.get(key, default) retorna o valor se a chave existir, ou default (que é None se omitido) caso contrário — sem lançar exceção.

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

Use .get() sempre que não tiver certeza se uma chave existe. Use o acesso por colchetes quando a chave deve estar presente — uma chave ausente é um erro genuíno que deve aparecer como exceção.

Verificando se uma chave existe

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

in testa as chaves, não os valores. É executado em tempo O(1) médio — constante, independentemente do tamanho do dicionário.

Adicionando e Atualizando Itens

Adicionar um novo par chave-valor

Atribua a uma chave que ainda não existe:

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

Atualizar um valor existente

Atribua a uma chave que já existe — o valor antigo é substituído:

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

update() — adicionar ou sobrescrever em massa

Passe outro dicionário ou um iterável de pares chave-valor:

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

Mesclar com | (Python 3.9+)

O operador | cria um novo dicionário mesclado. Se uma chave aparecer em ambos, o lado direito prevalece:

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

Use |= para mesclar b em a no lugar — equivalente a a.update(b), mas mais legível.

setdefault() — inserir somente quando ausente

dict.setdefault(key, default) insere a chave com o valor padrão se ela estiver ausente e sempre retorna o valor dessa chave. É mais eficiente do que o padrão 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}

Um caso de uso clássico é agrupar itens:

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']}

Removendo Itens

del — remover por chave

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

del lança KeyError se a chave estiver ausente. Para evitar isso, verifique com in primeiro ou use pop() com um valor padrão.

pop() — remover e retornar o valor

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

Forneça um segundo argumento para evitar KeyError quando a chave pode estar ausente:

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

popitem() — remover o último item inserido (Python 3.7+)

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

clear() — remover tudo

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

Iterando Sobre um Dicionário

Três visões permitem iterar sobre diferentes partes de um dicionário. Todas as três são visões ao vivo — refletem as alterações no dicionário sem precisar ser recriadas.

Chaves (iteração padrão)

Iterar diretamente sobre um dicionário retorna suas chaves:

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

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

person.keys() retorna as mesmas chaves como um objeto de visão dict_keys explícito.

Valores

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

Pares chave-valor

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

.items() é a escolha mais comum quando você precisa tanto da chave quanto do valor dentro do loop. Consulte Loop em Dicionários para padrões avançados.

As visões são ao vivo

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

Comprehensions de Dicionário

As comprehensions de dicionário permitem construir ou transformar dicionários em uma única expressão legível.

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}

Inverter um dicionário (trocar chaves e 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'}

Isso só funciona com segurança quando todos os valores são únicos.

Contador de frequência de palavras

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, ...}

Funções Embutidas Úteis

Para uma referência completa de todos os métodos de dicionário (copy, fromkeys, update, setdefault, popitem e outros), consulte Métodos de Dicionário Python.

Armadilhas Comuns

1. KeyError em chave ausente — use sempre .get() ou in quando uma chave pode não existir.

2. Tipos de chave não hasheáveis — listas não podem ser chaves de dicionário porque são mutáveis. Use uma tupla em vez disso:

# 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 durante a iteração — adicionar ou remover chaves enquanto percorre um dicionário lança RuntimeError. Tire um instantâneo primeiro:

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. Cópia rasa vs. cópia profunda — dict.copy() e {**d} fazem uma cópia rasa. Valores mutáveis aninhados (listas, dicts) ainda são compartilhados. Use copy.deepcopy() quando precisar de cópias totalmente independentes. Consulte Copiar Dicionários.

Dicionários vs. Outros Tipos de Coleção

Quando você precisa buscar algo por um rótulo significativo em vez de uma posição, um dicionário é quase sempre a escolha certa. Para valores únicos ordenados, considere um set. Para uma sequência ordenada simples, use uma list.

Prática