Adicionar Itens a um Dicionário Python

Os dicionários Python são coleções mutáveis e ordenadas (desde o Python 3.7) de pares chave-valor. Por serem mutáveis, é possível adicionar novas entradas a qualquer momento após a criação. Este capítulo aborda todas as técnicas padrão para adicionar itens a um dicionário, incluindo os operadores de mesclagem do Python 3.9+, com notas práticas sobre quando cada abordagem é mais indicada.

O Que É um Dicionário Python?

Um dicionário armazena dados como pares chave-valor dentro de chaves {}. As chaves devem ser únicas e imutáveis (strings, números ou tuplas); os valores podem ser qualquer objeto Python.

# A simple dictionary
person = {'name': 'Alice', 'age': 30, 'city': 'New York'}

As chaves são únicas — se você atribuir um valor a uma chave que já existe, o valor antigo será sobrescrito, não duplicado. Tenha esse comportamento em mente ao estudar os métodos a seguir.

Formas de Adicionar Itens a um Dicionário

Usando Notação de Colchetes

A forma mais simples de adicionar um novo par chave-valor é a atribuição direta com colchetes:

Saída:

{'name': 'John', 'age': 25, 'city': 'New York', 'gender': 'Male'}

Se a chave já existir, o valor é substituído em vez de adicionado:

my_dict = {'name': 'John', 'age': 25}

my_dict['age'] = 30  # overwrites 25

print(my_dict)
# {'name': 'John', 'age': 30}

Use a atribuição por colchetes quando estiver adicionando ou atualizando uma única chave cujo nome você conhece no momento da escrita.

Usando o Método update()

dict.update() mescla um ou mais pares chave-valor ao dicionário em uma única chamada. É possível passar outro dicionário, um iterável de pares (key, value) ou argumentos de palavra-chave.

Mesclar um segundo dicionário:

Saída:

{'name': 'John', 'age': 25, 'city': 'New York', 'gender': 'Male', 'occupation': 'Software Engineer'}

Usar argumentos de palavra-chave para adicionar várias chaves de uma vez:

my_dict = {'name': 'John', 'age': 25}

my_dict.update(city='New York', gender='Male')

print(my_dict)
# {'name': 'John', 'age': 25, 'city': 'New York', 'gender': 'Male'}

Assim como a atribuição por colchetes, update() sobrescreve chaves existentes. Use-o quando precisar adicionar ou atualizar várias entradas de uma vez.

Usando o Método setdefault()

dict.setdefault(key, default) adiciona uma chave somente se ela ainda não estiver presente. Se a chave existir, retorna o valor atual sem alterar nada.

Saída:

{'name': 'John', 'age': 25, 'city': 'New York', 'gender': 'Male'}

Quando a chave já existe, setdefault() a deixa intacta e retorna o valor atual:

my_dict = {'name': 'John', 'age': 25}

result = my_dict.setdefault('name', 'Alice')

print(result)   # John  — not overwritten
print(my_dict)  # {'name': 'John', 'age': 25}

setdefault() é a ferramenta certa quando você deseja inicializar uma chave com um valor padrão sem sobrescrever acidentalmente dados que já existem. Um padrão comum é inicializar uma chave ausente com uma lista vazia antes de adicionar elementos a ela:

groups = {}

for item in ['apple', 'banana', 'avocado']:
    letter = item[0]
    groups.setdefault(letter, []).append(item)

print(groups)
# {'a': ['apple', 'avocado'], 'b': ['banana']}

Usando os Operadores de Mesclagem (Python 3.9+)

O Python 3.9 adicionou dois operadores que oferecem uma sintaxe concisa para combinar dicionários.

| — cria um novo dicionário mesclado (não destrutivo):

d1 = {'a': 1, 'b': 2}
d2 = {'c': 3, 'd': 4}

d3 = d1 | d2  # d1 and d2 are unchanged

print(d3)
# {'a': 1, 'b': 2, 'c': 3, 'd': 4}

|= — atualiza no lugar (equivalente a update(), porém mais curto):

d1 = {'a': 1, 'b': 2}
d2 = {'c': 3, 'd': 4}

d1 |= d2  # d1 is modified

print(d1)
# {'a': 1, 'b': 2, 'c': 3, 'd': 4}

Quando as chaves se sobrepõem, o operando do lado direito prevalece — mesma precedência de update(). Esses operadores exigem Python 3.9 ou posterior; use update() para maior compatibilidade.

Usando dict.fromkeys() para Pré-popular um Dicionário

dict.fromkeys(keys, default) é um método de classe que cria um dicionário completamente novo a partir de um iterável de chaves e um valor padrão opcional. Ele não adiciona itens a um dicionário existente.

# Create a dictionary with a shared default value
template = dict.fromkeys(['name', 'age', 'city'], 'Unknown')

print(template)
# {'name': 'Unknown', 'age': 'Unknown', 'city': 'Unknown'}

# You can then populate it with real values
template['name'] = 'Alice'
template['age'] = 28

print(template)
# {'name': 'Alice', 'age': 28, 'city': 'Unknown'}

fromkeys() é útil para estruturar um dicionário quando você conhece as chaves antecipadamente, mas preencherá os valores mais tarde.

Escolhendo o Método Certo

Capítulos Relacionados

• Dicionários Python — visão geral sobre criação e sintaxe de dicionários
• Acessar Itens — lendo valores por chave, get() e iteração
• Alterar Itens — atualizando valores existentes com segurança
• Remover Itens — pop(), popitem(), del e clear()
• Métodos de Dicionário — referência completa de todos os métodos embutidos de dict
• Iterar Dicionários — iterando sobre chaves, valores e itens

Prática