Iterar Dicionários

Os dicionários Python armazenam dados como pares chave-valor, e frequentemente você precisará percorrê-los — para imprimir cada entrada, filtrar dados, transformar valores ou construir novas estruturas. Este capítulo cobre todas as técnicas padrão para iterar sobre um dicionário, explica qual método usar em cada situação e destaca o erro mais comum: modificar um dicionário enquanto você o percorre.

Se você é novo em dicionários, leia primeiro Python Dictionaries. Para a sintaxe geral de loops, veja Python For Loops.

Iterando Sobre Chaves

Quando você usa um loop for simples em um dicionário, Python itera sobre suas chaves por padrão.

Iterar sobre as chaves do dicionário

person = {"name": "Alice", "age": 30, "city": "Berlin"}

for key in person:
    print(key)

Saída:

name
age
city

Chamar .keys() é equivalente e torna a intenção mais explícita:

Com a chave em mãos, você pode buscar seu valor dentro do loop:

person = {"name": "Alice", "age": 30, "city": "Berlin"}

for key in person:
    print(key, "->", person[key])

Saída:

name -> Alice
age -> 30
city -> Berlin

Quando usar .keys()

Use a forma simples for key in d quando precisar apenas das chaves. Use d.keys() explicitamente quando quiser testar pertencimento ("name" in d.keys()) ou passar a visão para outra função. Para um teste de pertencimento simples, porém, if "name" in d é mais rápido.

Iterando Sobre Valores

Use .values() quando precisar apenas dos valores e não se importar com as chaves.

Iterar sobre os valores do dicionário

scores = {"math": 92, "science": 87, "english": 95}

for score in scores.values():
    print(score)

Saída:

92
87
95

Um caso de uso comum é calcular um resumo sobre todos os valores:

scores = {"math": 92, "science": 87, "english": 95}

total = sum(scores.values())
average = total / len(scores)
print(f"Average score: {average:.1f}")

Saída:

Average score: 91.3

Iterando Sobre Pares Chave-Valor com .items()

.items() retorna cada entrada como uma tupla (key, value). Você pode desempacotar a tupla diretamente em duas variáveis. Este é o método de iteração mais versátil e o que você usará com mais frequência.

Iterar sobre pares chave-valor

person = {"name": "Alice", "age": 30, "city": "Berlin"}

for key, value in person.items():
    print(f"{key}: {value}")

Saída:

name: Alice
age: 30
city: Berlin

Filtrando Durante a Iteração

Combine um loop for com uma condição if para processar apenas as entradas que lhe interessam.

Imprimir apenas itens em estoque

inventory = {"apples": 5, "bananas": 0, "oranges": 3, "grapes": 0}

print("In stock:")
for item, qty in inventory.items():
    if qty > 0:
        print(f"  {item}: {qty}")

Saída:

In stock:
  apples: 5
  oranges: 3

Ordenando Entradas do Dicionário

Python 3.7+ garante que os dicionários mantêm a ordem de inserção. Se você precisar de uma ordem diferente, ordene as chaves ou os itens antes de iterar — o dicionário em si não é afetado.

Ordenar por chave (alfabético)

book = {"banana": 7, "apple": 3, "cherry": 12}

for fruit in sorted(book):
    print(f"{fruit}: {book[fruit]}")

Saída:

apple: 3
banana: 7
cherry: 12

Ordenar por valor

Passe uma função key para sorted() para controlar o critério de ordenação.

book = {"banana": 7, "apple": 3, "cherry": 12}

for fruit, count in sorted(book.items(), key=lambda item: item[1], reverse=True):
    print(f"{fruit}: {count}")

Saída:

cherry: 12
banana: 7
apple: 3

Usando enumerate() Durante a Iteração

Envolva .items() com enumerate() para obter um índice sequencial junto com cada par chave-valor.

colors = {"red": "#FF0000", "green": "#00FF00", "blue": "#0000FF"}

for index, (name, hex_code) in enumerate(colors.items()):
    print(f"{index}: {name} -> {hex_code}")

Saída:

0: red -> #FF0000
1: green -> #00FF00
2: blue -> #0000FF

Dictionary Comprehensions

Uma dictionary comprehension constrói um novo dicionário a partir de um existente em uma única expressão. A sintaxe espelha as list comprehensions, mas usa chaves e dois-pontos entre a chave e o valor.

Aplicar 10% de desconto em cada preço

prices = {"apple": 1.20, "banana": 0.50, "orange": 0.80}

discounted = {item: round(price * 0.9, 2) for item, price in prices.items()}
print(discounted)

Saída:

{'apple': 1.08, 'banana': 0.45, 'orange': 0.72}

Você pode adicionar uma condição de filtro ao final:

Manter apenas alunos com pontuação 90 ou acima

students = {
    "Alice": {"grade": "A", "score": 95},
    "Bob":   {"grade": "B", "score": 82},
    "Carol": {"grade": "A", "score": 91},
}

top_students = {name: info for name, info in students.items() if info["score"] >= 90}
print(top_students)

Saída:

{'Alice': {'grade': 'A', 'score': 95}, 'Carol': {'grade': 'A', 'score': 91}}

Iterando Sobre Dicionários Aninhados

Quando os valores são eles próprios dicionários (veja Nested Dictionaries), acesse as entradas internas com um segundo subscrito ou um segundo loop.

Imprimir todos os campos de cada aluno

students = {
    "Alice": {"grade": "A", "score": 95},
    "Bob":   {"grade": "B", "score": 82},
    "Carol": {"grade": "A", "score": 91},
}

for name, info in students.items():
    print(f"{name}: grade={info['grade']}, score={info['score']}")

Saída:

Alice: grade=A, score=95
Bob: grade=B, score=82
Carol: grade=A, score=91

Modificar um Dicionário Durante a Iteração — a Armadilha Principal

Você não pode adicionar ou remover chaves de um dicionário enquanto itera sobre ele. Python lança um RuntimeError imediatamente:

d = {"a": 1, "b": 2, "c": 3}

# This raises RuntimeError: dictionary changed size during iteration
for key in d:
    if d[key] == 2:
        del d[key]

O padrão seguro é coletar as chaves que você deseja remover primeiro e depois excluí-las após o loop:

Exclusão segura após a iteração

config = {"debug": True, "verbose": True, "timeout": 30}

keys_to_remove = [k for k, v in config.items() if v is True]
for k in keys_to_remove:
    del config[k]

print(config)

Saída:

{'timeout': 30}

O mesmo princípio se aplica à adição de chaves: colete os novos pares e depois atualize o dicionário com update() ou atribuição direta após o loop.

Escolhendo o Método Adequado

Para o conjunto completo de operações de dicionário, veja Python Dictionary Methods e Copy Dictionaries.

Prática