2.9. Dicionários¶

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

2.9.1. Criar dicionários¶

Use chavetas 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 – cadeias de caracteres, números, listas, ou mesmo outros dicionários:

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

A dictionary shown as two columns: keys on the left, values on the right, with arrows linking each pair. — Cada chave num dicionário mapeia para exatamente um valor.¶

2.9.2. Acesso e pertença¶

A indexação com [] obtém o valor de uma chave. Uma chave inexistente levanta 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 a falhas, use dict.get(). Devolve None para uma chave inexistente, ou um valor que 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 pertença da chave – não do valor:

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

2.9.3. Adicionar, atualizar e remover¶

Atribuir a d[key] adiciona a entrada se a chave for nova e substitui-a se 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; levanta KeyError se a chave não existir.
dict.pop() – remove e devolve o valor; um padrão opcional permite evitar a exceção.
dict.clear() – remove todas as entradas.

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

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

2.9.4. Iterar¶

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

for k in person:
    print(k)

Três vistas dão acesso explícito:

dict.keys() – as chaves (igual a iterar o dicionário).
dict.values() – os valores.
dict.items() – tuplos (key, value), perfeitos para desempacotar num ciclo.

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

2.9.5. O que pode ser uma chave¶

As chaves de um dicionário têm de ser hasháveis – o seu valor não pode mudar ao longo da sua vida. Os tipos hasháveis mais comuns são:

int, float, bool
str, bytes
tuple (quando todos os elementos internos são eles próprios hasháveis)
None

Os tipos mutáveis como list, dict e bytearray não podem ser chaves; usar um deles levanta TypeError. Tuplos de valores imutáveis são a forma padrão de indexar um dicionário por um identificador composto, como uma coordenada numa grelha 2D:

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

2.9.6. Comprimento¶

len() devolve o número de entradas:

>>> len(person)
4