Dictionaries in Python

What is a dictionary in Python?

A dictionary stores key-value pairs, so you look values up by a name instead of a position. You write the pairs inside curly braces, with a colon between each key and its value, and the dict type keeps them in the order you added them. A dictionary is the natural type for a record with named fields, a lookup table, or a count of how often things occur.

ages = {"Ada": 36, "Bob": 28}
print(ages)
print(type(ages))
print(len(ages))
print(ages["Ada"])

{'Ada': 36, 'Bob': 28}
<class 'dict'>
2
36

ages["Ada"] asks for the value stored under the key "Ada", the way fruits[0] asks a list for the item at position 0. Keys are unique, so a dictionary holds one value per key, and len() counts the pairs. Python programmers say dict as often as dictionary, and the two words mean the same thing.

How do I create a dictionary in Python?

Write key: value pairs inside curly braces, separated by commas. Empty braces make an empty dictionary, and dict(name="Ada", age=36) builds one from name=value arguments. Keys must be values that can't change, such as strings, numbers or tuples, and values can be anything, including lists and other dictionaries.

empty = {}
print(empty)
person = dict(name="Ada", age=36)
print(person)
mixed = {1: "one", "two": 2, (3, 4): "point"}
print(mixed)
student = {"name": "Ada", "grades": [90, 85]}
print(student["grades"][0])

{}
{'name': 'Ada', 'age': 36}
{1: 'one', 'two': 2, (3, 4): 'point'}
90

The keys in mixed are a number, a string and a tuple, and each one works because none of them can change. A tuple works as a key only while everything inside it can't change either. The last line reads a value that is a list and then indexes into it, one pair of brackets per step.

A list can't be a key, because its contents could change after the dictionary has filed it. Python calls a value hashable when it can turn it into a fixed number, which it can do for any value that can't change, and unhashable is the word in the error message when a list is tried as a key.

How do I get a value from a dictionary?

Put the key in square brackets, or call get(). Square brackets raise KeyError when the key is missing, and get() returns None instead, or a default value you pass as its second argument. The in operator tests whether a key exists.

ages = {"Ada": 36, "Bob": 28}
print(ages["Bob"])
print(ages.get("Bob"))
print(ages.get("Cy"))
print(ages.get("Cy", 0))
print("Ada" in ages)
print("Cy" in ages)

28
28
None
0
True
False

Use the brackets when the key must exist and a missing one is a bug worth stopping for. Use get() when a missing key is normal, such as counting words you haven't seen before. in looks at keys only, so 36 in ages is False even though 36 is a value.

A lookup with a default also replaces an if and elif chain that maps each case to one value, which is the dictionary lookup the match statement lesson mentioned.

messages = {200: "OK", 404: "Not found"}
print(messages.get(404, "Unknown status"))
print(messages.get(418, "Unknown status"))

Not found
Unknown status

How do I add a key or change its value in a dictionary?

Assign a value to the key in square brackets. When the key is new, the assignment adds the pair at the end. When the key exists, the assignment replaces its value, and the pair keeps its place. update() does the same for several pairs at once.

ages = {"Ada": 36, "Bob": 28}
ages["Cy"] = 41
print(ages)
ages["Bob"] = 29
print(ages)
ages.update({"Dee": 25, "Ada": 37})
print(ages)
print(len(ages))

{'Ada': 36, 'Bob': 28, 'Cy': 41}
{'Ada': 36, 'Bob': 29, 'Cy': 41}
{'Ada': 37, 'Bob': 29, 'Cy': 41, 'Dee': 25}
4

There is no append() on a dictionary, because a pair is added by assigning to its key, not by pushing it onto the end. The update() call added "Dee" and changed "Ada" in one step, and the length rose by one, since "Ada" was already there.

How do I remove a key from a dictionary?

Use del with the key in brackets, or call pop() with the key. pop() returns the value it removed, and a second argument makes it return that default instead of raising KeyError for a missing key.

ages = {"Ada": 36, "Bob": 28, "Cy": 41}
del ages["Bob"]
print(ages)
removed = ages.pop("Cy")
print(removed)
print(ages)
print(ages.pop("Zed", "nobody"))

{'Ada': 36, 'Cy': 41}
41
{'Ada': 36}
nobody

clear() empties the whole dictionary, and popitem() removes and returns the pair that was added last.

How do I loop through a dictionary in Python?

A for loop over a dictionary gives you its keys, one per pass. Call values() to loop over the values instead, and items() to get each key and value together as a pair you can unpack into two names.

ages = {"Ada": 36, "Bob": 28}
for name in ages:
    print(name)
for age in ages.values():
    print(age)
for name, age in ages.items():
    print(name, "is", age)
print(ages.keys())

Ada
Bob
36
28
Ada is 36
Bob is 28
dict_keys(['Ada', 'Bob'])

The items() loop is the one you will use most, because a key on its own usually needs its value. The last line shows what keys() returns, a view printed as dict_keys([...]). A view is a live window onto the dictionary's keys rather than a copy, and list(ages.keys()) turns it into a list.

Every loop over a dictionary runs in the order the keys were added, which Python has guaranteed since version 3.7.

Counting is the classic dictionary loop, and get() with a default of 0 handles the first time a word shows up.

words = ["red", "blue", "red", "green", "red"]
counts = {}
for word in words:
    counts[word] = counts.get(word, 0) + 1
print(counts)

{'red': 3, 'blue': 1, 'green': 1}

Which dictionary methods does Python have?

Python dictionaries have eleven methods, and the table lists all of them. len() counts the pairs, and sorted(ages) returns the keys in order, because a dictionary hands out its keys to anything that loops over it, and sorted() loops.

A dictionary comprehension, {n: n * n for n in range(4)}, builds a dictionary the way a list comprehension builds a list, with a key and a value in the expression.

What is the difference between a list and a dictionary?

A list stores items by position, and a dictionary stores values by key. Use a list when the order is the point or the items have no natural name, and a dictionary when each value has a name you will look it up by.

Finding a key in a dictionary takes about the same time however many pairs it holds, while finding a value in a list means checking the items one by one. That is why a dictionary is the tool for lookups, and a set, which the next lesson covers, gives the same fast test without the values.

What is a nested dictionary in Python?

A nested dictionary is a dictionary whose values are dictionaries. One pair of brackets picks the inner dictionary and a second pair picks a value inside it, so people["ada"]["city"] reads the city of the record filed under "ada".

people = {
    "ada": {"age": 36, "city": "London"},
    "bob": {"age": 28, "city": "Paris"},
}
print(people["ada"]["city"])
people["bob"]["age"] = 29
print(people["bob"])
for key, info in people.items():
    print(key, info["age"])

London
{'age': 29, 'city': 'Paris'}
ada 36
bob 29

Data from the web arrives in this shape, because JSON, the text format most websites use to send data, maps its objects onto dictionaries and its arrays onto lists. The JSON to Python converter shows the Python code for any JSON you paste in, and a later lesson covers reading JSON in code.

Common mistakes with dictionaries in Python

Each of these four mistakes with dictionaries usually stops the program with a message that names the problem.

• KeyError: 'Bob'. The key isn't in the dictionary. Check with in, or read with get() and a default.
• TypeError: cannot use 'list' as a dict key (unhashable type: 'list'). A list was used as a key, and a list can change, so it isn't hashable. Use a tuple or a string.
• ValueError: too many values to unpack (expected 2). The loop was written as for name, age in ages: without items(), so each pass received only a key and tried to split it in two. A key that happens to be two characters long even splits silently into its letters. Add .items().
• AttributeError: 'dict' object has no attribute 'append'. A dictionary has no append(). Assign to a new key instead.

Run the three broken programs to see the messages, then fix them in the editor.

ages = {"Ada": 36}
print(ages["Bob"])

Traceback (most recent call last):
  File "main.py", line 2, in <module>
    print(ages["Bob"])
          ~~~~^^^^^^^
KeyError: 'Bob'

prices = {[1, 2]: "pair"}

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    prices = {[1, 2]: "pair"}
             ^^^^^^^^^^^^^^^^
TypeError: cannot use 'list' as a dict key (unhashable type: 'list')

ages = {"Ada": 36, "Bob": 28}
for name, age in ages:
    print(name, age)

Traceback (most recent call last):
  File "main.py", line 2, in <module>
    for name, age in ages:
        ^^^^^^^^^
ValueError: too many values to unpack (expected 2)