Dicionários Python: Como Alterar Chave e Valor

Os dicionários Python permitem armazenar dados como pares de chave-valor e atualizá-los livremente após a criação. Este capítulo abrange todas as formas práticas de modificar itens existentes em um dicionário: alterar um único valor, renomear uma chave, fazer atualizações em massa com update() e trabalhar com dicionários aninhados — incluindo os casos especiais que você encontrará em código real.

Para entender como os dicionários funcionam, consulte o capítulo Acessar Itens de Dicionário. Para adicionar novas entradas, consulte Adicionar Itens ao Dicionário. Para excluir entradas, consulte Remover Itens do Dicionário.

Alterando um Valor

A modificação mais simples é reatribuir o valor armazenado em uma chave existente. Use a chave como índice no lado esquerdo de uma atribuição:

Se a chave já existir, o valor é sobrescrito no local. As outras entradas não são afetadas e o dicionário preserva sua ordem de inserção (Python 3.7+).

O que acontece quando a chave não existe?

Se você usar uma atribuição com uma chave que não está no dicionário, Python silenciosamente cria uma nova entrada em vez de gerar um erro:

prices = {'apple': 1.00, 'banana': 0.50}
prices['mango'] = 2.50   # 'mango' did not exist — a new entry is created
print(prices)
# {'apple': 1.00, 'banana': 0.50, 'mango': 2.50}

Quando você quiser atualizar apenas se a chave existir, verifique primeiro com in:

if 'banana' in prices:
    prices['banana'] = 0.75

Atualização em Massa com update()

dict.update() permite alterar vários valores de uma vez. Passe um dicionário (ou argumentos de palavra-chave) com os pares de chave-valor a serem aplicados:

inventory = {'apple': 10, 'banana': 5, 'orange': 8}
inventory.update({'banana': 12, 'orange': 3})
print(inventory)
# {'apple': 10, 'banana': 12, 'orange': 3}

As chaves presentes no argumento sobrescrevem os valores existentes; as chaves não mencionadas permanecem inalteradas. Você também pode passar argumentos de palavra-chave diretamente:

inventory.update(apple=20, banana=15)
print(inventory)
# {'apple': 20, 'banana': 15, 'orange': 3}

update() também adiciona quaisquer chaves do argumento que ainda não existam no dicionário de destino, sendo útil para mesclar dois dicionários.

Renomeando (Alterando) uma Chave

As chaves de um dicionário são referências imutáveis — não é possível renomear uma chave diretamente. O padrão padrão é adicionar uma nova chave com o valor antigo e excluir a chave antiga. O método pop() faz ambos em uma única expressão:

pop('banana') retorna 2 e remove a entrada 'banana'. Atribuir esse valor de retorno a my_dict['pear'] cria a entrada renomeada.

Observe que a chave renomeada aparece no final do dicionário, não na posição original de 'banana', porque é uma nova chave sendo inserida.

Renomeando uma chave quando você não tem certeza se ela existe

Se a chave puder estar ausente, pop() gera um KeyError. Passe um valor padrão como segundo argumento para evitar a exceção:

value = my_dict.pop('grape', None)  # returns None if 'grape' is missing
if value is not None:
    my_dict['kiwi'] = value

Alterando Chave e Valor ao Mesmo Tempo

Combine o padrão de renomeação com uma reatribuição de valor para alterar ambos de uma vez:

Ou reduza para uma única etapa atribuindo diretamente o valor desejado em vez do valor extraído com pop:

my_dict = {'apple': 1, 'banana': 2, 'orange': 3}
my_dict.pop('banana')          # remove old key (discard value)
my_dict['pear'] = 4            # insert new key with new value
print(my_dict)
# {'apple': 1, 'orange': 3, 'pear': 4}

Atualizando Itens em um Dicionário Aninhado

Quando um dicionário contém outros dicionários como valores, use indexação encadeada para acessar o valor interno:

catalog = {
    'apple':  {'price': 1.00, 'stock': 50},
    'banana': {'price': 0.50, 'stock': 30},
}

# Update only the price of 'banana'
catalog['banana']['price'] = 0.75
print(catalog['banana'])
# {'price': 0.75, 'stock': 30}

Você também pode chamar update() no dicionário interno:

catalog['apple'].update({'price': 1.20, 'stock': 45})
print(catalog['apple'])
# {'price': 1.20, 'stock': 45}

Erros Comuns

Reconstruindo para preservar a ordem das chaves

Se você precisar que a chave renomeada fique em sua posição original, reconstrua o dicionário com uma comprehension:

my_dict = {'apple': 1, 'banana': 2, 'orange': 3}
my_dict = {
    ('pear' if k == 'banana' else k): v
    for k, v in my_dict.items()
}
print(my_dict)
# {'apple': 1, 'pear': 2, 'orange': 3}

Isso itera sobre cada entrada existente e emite a chave renomeada apenas onde a condição é verdadeira, deixando todo o resto inalterado.

Prática