2.9. Dicionários¶

Um dicionário é um mapeamento de chaves para valores. Cada chave é consultada diretamente; o dicionário lembra qual valor foi associado por último a essa chave.

2.9.1. Criando dicionários¶

Use chaves com pares key: value ou o construtor dict:

empty   = {}
person  = {"name": "OpenMV", "id": 42}
counts  = dict(a=1, b=2, c=3)            # keyword form
pairs   = dict([("x", 1), ("y", 2)])     # from a list of pairs

Os valores podem ser de qualquer tipo – strings, números, listas e até outros dicts:

config = {
    "name":  "OpenMV",
    "id":    42,
    "width": 320,
    "tags":  ["red", "round"],
}

Um dicionário exibido em duas colunas: as chaves à esquerda, os valores à direita, com setas ligando cada par. — Cada chave em um dicionário mapeia para exatamente um valor.¶

2.9.2. Acesso e pertinência¶

A indexação com [] recupera o valor de uma chave. Uma chave inexistente gera KeyError:

>>> person = {"name": "OpenMV", "id": 42}
>>> person["name"]
'OpenMV'
>>> person["missing"]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError: 'missing'

Para uma consulta tolerante, use dict.get(). Ela retorna None para uma chave inexistente, ou um valor que você passe como segundo argumento:

>>> person.get("name")
'OpenMV'
>>> person.get("missing")            # returns None
>>> person.get("missing", "n/a")
'n/a'

A palavra-chave in testa a pertinência de chave – não de valor:

>>> "name" in person
True
>>> "OpenMV" in person
False

2.9.3. Adicionando, atualizando e removendo¶

Atribuir a d[key] adiciona a entrada se a chave for nova e a sobrescreve se ela já existir:

>>> person["seen"] = 1
>>> person["seen"] = 2               # overwrites
>>> person
{'name': 'OpenMV', 'id': 42, 'seen': 2}

A remoção tem algumas formas:

del d[key] – remove uma entrada; gera KeyError se a chave não existir.
dict.pop() – remove e retorna o valor; um padrão opcional permite evitar a exceção.
dict.clear() – remove todas as entradas.

dict.update() mescla outro dicionário (ou uma lista de pares (key, value)) no receptor, sobrescrevendo quaisquer chaves coincidentes:

>>> person.update({"id": 100, "owner": "alice"})
>>> person
{'name': 'OpenMV', 'id': 100, 'seen': 2, 'owner': 'alice'}

2.9.4. Iterando¶

Iterar um dicionário diretamente produz suas chaves, na ordem de inserção:

for k in person:
    print(k)

Três visões dão acesso explícito:

dict.keys() – as chaves (o mesmo que iterar o dict).
dict.values() – os valores.
dict.items() – tuplas (key, value), perfeitas para desempacotar em um laço.

for key, value in person.items():
    print(key, "=", value)

2.9.5. O que pode ser uma chave¶

As chaves de um dicionário devem ser hashable – seu valor não pode mudar durante seu tempo de vida. Os tipos hashable comuns são:

int, float, bool
str, bytes
tuple (quando todos os elementos internos são, por sua vez, hashable)
None

Tipos mutáveis como list, dict e bytearray não podem ser chaves; usar um deles gera TypeError. Tuplas de valores imutáveis são a maneira padrão de indexar um dicionário por um identificador composto, como uma coordenada de grade 2-D:

>>> grid = {}
>>> grid[(0, 0)] = "start"
>>> grid[(5, 7)] = "end"

2.9.6. Comprimento¶

len() retorna o número de entradas:

>>> len(person)
4