Métodos de Dicionário em Python

Os dicionários em Python armazenam dados como pares chave-valor e disponibilizam um rico conjunto de métodos integrados para leitura, adição, atualização e remoção de entradas. Este capítulo aborda todos os métodos de dicionário disponíveis no Python 3, com exemplos corretos e notas práticas sobre quando — e quando não — utilizar cada um.

Para uma introdução geral sobre dicionários (criação, acesso a itens, aninhamento), consulte o capítulo Python Dictionaries.

O que é um Dicionário Python?

Um dicionário mapeia chaves únicas a valores. As chaves precisam ser hashable (strings, números e tuplas de hashables funcionam; listas não). Os valores podem ser qualquer objeto Python.

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

Os dicionários mantêm a ordem de inserção desde o Python 3.7 — iterar sobre eles sempre retorna as chaves na ordem em que foram adicionadas.

Métodos de Dicionário em Resumo

clear()

clear() remove todos os itens do dicionário no lugar, deixando um dict vazio. Use-o quando precisar reutilizar o mesmo objeto dict em vez de criar um novo.

Atenção: inventory = {} parece similar, mas cria um novo objeto dict. Se outra variável apontar para o mesmo dict, clear() o esvazia para ambas; a reatribuição não faz isso.

a = {"x": 1}
b = a
a.clear()
print(b)   # Output: {}  — b sees the change

a = {"x": 1}
b = a
a = {}
print(b)   # Output: {'x': 1}  — b is unaffected

copy()

copy() retorna uma cópia superficial — um novo dict com as mesmas chaves e referências aos mesmos valores.

Atenção: Se algum valor for um objeto mutável (lista, dict, set), tanto o original quanto a cópia compartilham esse objeto. Use copy.deepcopy() quando precisar de total independência.

Para mais detalhes sobre como copiar dicts com segurança, consulte Copy Dictionaries.

fromkeys()

fromkeys(iterable, value) é um método de classe que constrói um novo dict a partir de uma sequência de chaves, todas mapeadas para o mesmo valor (padrão None).

fields = ["name", "email", "phone"]
record = dict.fromkeys(fields, "")
print(record)
# Output: {'name': '', 'email': '', 'phone': ''}

Atenção: Se o valor padrão for mutável (ex.: uma lista), todas as chaves compartilham o mesmo objeto:

bad = dict.fromkeys(["a", "b"], [])
bad["a"].append(1)
print(bad)  # Output: {'a': [1], 'b': [1]}  — both share the list!

A solução é usar uma compreensão de dict:

good = {k: [] for k in ["a", "b"]}
good["a"].append(1)
print(good)  # Output: {'a': [1], 'b': []}

get()

get(key, default=None) retorna o valor de key se ele existir, ou default caso contrário. Nunca levanta KeyError.

Quando usar: prefira get() em vez de dict[key] sempre que a chave puder estar ausente. Use a forma com dois argumentos para fornecer um padrão significativo em vez de capturar KeyError com try/except.

items()

items() retorna uma dict_items view — um iterável de tuplas (key, value) que reflete o estado atual do dict.

O uso mais comum é desempacotando chave e valor em um laço for:

scores = {"math": 90, "english": 85, "science": 92}
for subject, grade in scores.items():
    print(f"{subject}: {grade}")
# Output:
# math: 90
# english: 85
# science: 92

As views são dinâmicas — elas refletem alterações no dict sem precisar ser regeradas.

Para mais padrões de laço, consulte Loop Dictionaries.

keys()

keys() retorna uma dict_keys view de todas as chaves na ordem de inserção.

Por ser uma view, você pode utilizá-la em operações de conjunto para comparar dois dicts:

a = {"x": 1, "y": 2}
b = {"y": 3, "z": 4}

print(a.keys() & b.keys())  # Output: {'y'}    — keys in both
print(a.keys() | b.keys())  # Output: {'x', 'y', 'z'}  — all keys
print(a.keys() - b.keys())  # Output: {'x'}    — keys only in a

values()

values() retorna uma dict_values view de todos os valores.

Casos de uso comuns:

prices = {"apple": 0.99, "banana": 0.59, "cherry": 2.49}

total = sum(prices.values())
print(f"Total: {total:.2f}")   # Output: Total: 4.07

most_expensive = max(prices.values())
print(most_expensive)          # Output: 2.49

Ao contrário de keys(), values() não suporta operações de conjunto porque os valores não têm garantia de unicidade.

pop()

pop(key, default) remove o item com a chave especificada e retorna seu valor. Se a chave estiver ausente e nenhum padrão for fornecido, levanta KeyError.

Quando usar: pop() é a ferramenta certa quando você precisa tanto remover um item quanto usar seu valor na mesma operação, como ao processar itens de um dict semelhante a uma fila.

popitem()

popitem() remove e retorna o par chave-valor inserido por último como uma tupla (key, value). Chamá-lo em um dict vazio levanta KeyError.

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

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

Um padrão prático é processar um dict de forma destrutiva até que fique vazio:

tasks = {"write tests": True, "review PR": False, "deploy": True}
while tasks:
    name, done = tasks.popitem()
    status = "done" if done else "pending"
    print(f"{name}: {status}")

setdefault()

setdefault(key, default=None) retorna o valor de key se ele existir. Se key estiver ausente, insere-o com default e retorna default.

options = {"color": "blue"}

# Key exists — returns existing value, does NOT overwrite
print(options.setdefault("color", "red"))   # Output: blue

# Key absent — inserts and returns default
print(options.setdefault("size", "medium")) # Output: medium

print(options)
# Output: {'color': 'blue', 'size': 'medium'}

Caso de uso principal: construir dicionários de listas (agrupamento):

words = ["apple", "avocado", "banana", "blueberry", "cherry"]
grouped = {}
for word in words:
    grouped.setdefault(word[0], []).append(word)

print(grouped)
# Output: {'a': ['apple', 'avocado'], 'b': ['banana', 'blueberry'], 'c': ['cherry']}

Isso é mais limpo do que uma verificação if key not in d: d[key] = [] a cada iteração.

update()

update(other) mescla other no dicionário, sobrescrevendo as chaves existentes. other pode ser outro dict, um iterável de pares (key, value) ou argumentos de palavra-chave.

Alternativa no Python 3.9+: o operador |= de mesclagem no lugar faz a mesma coisa de forma mais concisa:

profile = {"name": "Alice", "age": 28}
profile |= {"age": 29, "city": "Berlin"}
print(profile)
# Output: {'name': 'Alice', 'age': 29, 'city': 'Berlin'}

O operador | (sem =) retorna um novo dict em vez de modificar no lugar.

Acessando e Modificando Itens

Além dos métodos acima, Python oferece sintaxe direta para ler, adicionar e remover entradas de dicionário.

Ler um valor por chave:

Acessar uma chave que não existe levanta KeyError. Use get() para evitar isso.

Adicionar ou sobrescrever um valor:

person = {"name": "Alice", "age": 28}
person["occupation"] = "Engineer"  # new key
person["age"] = 29                 # overwrite existing key
print(person)
# Output: {'name': 'Alice', 'age': 29, 'occupation': 'Engineer'}

Percorrer chaves e valores com laço:

Escolhendo o Método Certo

Capítulos Relacionados

• Python Dictionaries — fundamentos: criação, acesso e verificação de pertencimento
• Nested Dictionaries — dicts de dicts para dados hierárquicos
• Loop Dictionaries — todos os padrões de laço com keys(), values() e items()
• Copy Dictionaries — cópia superficial vs. cópia profunda em detalhes
• List Methods — a referência equivalente para listas Python

Prática