Dictionaries allow you to connect pieces of related information.

Understanding dictionaries allows you to model a variety of real­ world objects more accurately. You’ll be able to create a dictionary representing a person and then store as much information as you want about that person. You can store their name, age, location, profession, and any other aspect of a person you can describe. You’ll be able to store any two kinds of information that can be matched up, such as a list of words and their meanings, a list of people’s names and their favorite numbers, a list of mountains and their elevations, and so forth.

A Simple Dictionary

Consider a game featuring aliens that can have different colors and point values. This simple dictionary stores information about a particular alien.

alien_0 = {'color' : 'green', 'points' : 5}

print(alien_0['color'])
print(alien_0['points'])

green
5

The dictionary alien_0 stores the alien’s color and point value.

Working with Dictionaries

A dictionary in Python is a collection of key-value pairs.

Each key is connected to a value, and you can use a key to access the value associated with that key. A key’s value can be a number, a string, a list, or even another dictionary. In fact, you can use any object that you can create in Python as a value in a dictionary.

In Python, a dictionary is wrapped in braces, {}, with a series of key-value pairs inside the braces.

A key-value pair is a set of values associated with each other. When you provide a key, Python returns the value associated with that key. Every key is connected to its value by a colon, and individual key-­value pairs are separated by commas. You can store as many key-­value pairs as you want in a dictionary.

The simplest dictionary has exactly one key-­value pair.

alien_0 = {'color': 'green'}

This dictionary stores one piece of information about alien_0, namely the alien’s color. The string 'color' is a key in this dictionary, and its associated value is 'green'.

Accessing Values in a Dictionary

To get the value associated with a key, give the name of the dictionary and then place the key inside a set of square brackets.

alien_0 = {'color': 'green'}

print(alien_0['color'])

This returns the value associated with the key 'color' from the dictionary alien_0.

green

You can have an unlimited number of key-­value pairs in a dictionary. For example, here’s the alien_0 dictionary with two key-­value pairs.

alien_0 = {'color': 'green', 'points': 5}

Now you can access either the color or the point value of alien_0. If a player shoots down this alien, you can look up how many points they should earn using code like this

alien_0 = {'color': 'green', 'points': 5}

new_points = alien_0['points']
print(f"You just earned {new_points} points!")

You just earned 5 points!

If you run this code every time an alien is shot down, the alien’s point value will be retrieved.

Adding New Key-Value Pairs

Dictionaries are dynamic structures, and you can add new key­-value pairs to a dictionary at any time. For example, to add a new key-­value pair, you would give the name of the dictionary followed by the new key in square brackets along with the new value.

Let’s add two new pieces of information to the alien_0 dictionary: the alien’s x­ and y­coordinates, which will help us display the alien in a particular position on the screen. Let’s place the alien on the left edge of the screen, 25 pixels down from the top. Because screen coordinates usually start at the upper­left corner of the screen, we’ll place the alien on the left edge of the screen by setting the x­coordinate to 0 and 25 pixels from the top by setting its y­coordinate to positive 25:

alien_0 = {'color' : 'green', 'points' : 5}
print(alien_0)

alien_0['x_position'] = 0
alien_0['y_position'] = 25
print(alien_0)

{'color': 'green', 'points': 5}
{'color': 'green', 'points': 5, 'x_position': 0, 'y_position': 25}

The final version of the dictionary contains four key-­value pairs. The original two specify color and point value, and two more specify the alien’s position.

Starting with an Empty Dictionary

It’s sometimes convenient, or even necessary, to start with an empty dictionary and then add each new item to it. To start filling an empty dictionary, define a dictionary with an empty set of braces and then add each key­-value pair on its own line. For example, here’s how to build the alien_0 dictionary using this approach:

alien_0 = {}

alien_0['color'] = 'green'
alien_0['points'] = 5

print(alien_0)

{'color': 'green', 'points': 5}

Typically, you’ll use empty dictionaries when storing user-­supplied data in a dictionary or when you write code that generates a large number of key­-value pairs automatically.

Modifying Values in a Dictionary

To modify a value in a dictionary, give the name of the dictionary with the key in square brackets and then the new value you want associated with that key. For example, consider an alien that changes from green to yellow as a game progresses:

alien_0 = {'color': 'green'}
print(f"The alien is {alien_0['color']}.")

alien_0['color'] = 'yellow'
print(f"The alien is now {alien_0['color']}.")

The alien is green.
The alien is now yellow.

For a more interesting example, let’s track the position of an alien that can move at different speeds. We’ll store a value representing the alien’s current speed and then use it to determine how far to the right the alien should move:

alien_0 = {'x_position': 0, 'y_position': 25, 'speed': 'medium'}
print(f"Original position: {alien_0['x_position']}")

# Move the alien to the right.
# Determine how far to move the alien based on its current speed.
if alien_0['speed'] == 'slow':
    x_increment = 1
elif alien_0['speed'] == 'medium':
    x_increment = 2
else:
    # This must be a fast alien.
    x_increment = 3

# The new position is the old position plus the increment.
alien_0['x_position'] = alien_0['x_position'] + x_increment

print(f"New position: {alien_0['x_position']}")

Because this is a medium­speed alien, its position shifts two units to the right:

Original x-position: 0
New x-position: 2

This technique is pretty cool: by changing one value in the alien’s dictionary, you can change the overall behavior of the alien. For example, to turn this medium­speed alien into a fast alien, you would add the line:

alien_0['speed'] = 'fast'

The if-­elif-­else block would then assign a larger value to x_increment the next time the code runs.

Removing Key-Value Pairs

When you no longer need a piece of information that’s stored in a dictionary, you can use the del statement to completely remove a key-­value pair. All del needs is the name of the dictionary and the key that you want to remove.

alien_0 = {'color': 'green', 'points': 5}
print(alien_0)

del alien_0['points']
print(alien_0)

{'color': 'green', 'points': 5}
{'color': 'green'}

Be aware that the deleted key-value pair is removed permanently.

A Dictionary of Similar Objects

The previous example involved storing different kinds of information about one object, an alien in a game. You can also use a dictionary to store one kind of information about many objects. For example, say you want to poll a number of people and ask them what their favorite programming language is. A dictionary is useful for storing the results of a simple poll, like this:

favorite_language = {
    'Ahmed' : 'Python',
    'Mohammed' : 'C',
    'Ali' : 'Rust',
    'Omar' : 'Go',
    }

As you can see, we’ve broken a larger dictionary into several lines. Each key is the name of a person who responded to the poll, and each value is their language choice.

It’s good practice to include a comma after the last key­-value pair as well, so you’re ready to add a new key-­value pair on the next line.

To use this dictionary, given the name of a person who took the poll, you can easily look up their favorite language:

favorite_language = {
    'Ahmed' : 'Python',
    'Mohammed' : 'C',
    'Ali' : 'Rust',
    'Omar' : 'Go',
    }

print(f"Ali favorite language is {favorite_language['Ali']}.")

Ali favorite language is Rust.

Using get() to Access Values

Using keys in square brackets to retrieve the value you’re interested in from a dictionary might cause one potential problem: if the key you ask for doesn’t exist, you’ll get an error.

alien_0 = {'color': 'green', 'speed': 'slow'}
print(alien_0['points'])

KeyError: 'points'

For dictionaries, specifically, you can use the get() method to set a default value that will be returned if the requested key doesn’t exist. The get() method requires a key as a first argument. As a second optional argument, you can pass the value to be returned if the key doesn’t exist:

alien_0 = {'color': 'green', 'speed': 'slow'}

point_value = alien_0.get('points', 'No point value assigned.')
print(point_value)

If the key 'points' exists in the dictionary, you’ll get the corresponding value. If it doesn’t, you get the default value.

No point value assigned.

If there’s a chance the key you’re asking for might not exist, consider using the get() method instead of the square bracket notation.

If you leave out the second argument in the call to get() and the key doesn’t exist, Python will return the value None. The special value None means “no value exists.” This is not an error: it’s a special value meant to indicate the absence of a value.

Looping Through a Dictionary

A single Python dictionary can contain just a few key­-value pairs or millions of pairs. Because a dictionary can contain large amounts of data, Python lets you loop through a dictionary. Dictionaries can be used to store information in a variety of ways; therefore, several different ways exist to loop through them. You can loop through all of a dictionary’s key­-value pairs, through its keys, or through its values.

Looping Through All Key-Value Pairs

Before we explore the different approaches to looping, let’s consider a new dictionary designed to store information about a user on a website.

user_0 = {
    'user_name' : 'ahmedgouda',
    'first_name' : 'ahmed'
    'last_name' : 'gouda',
    }

You can access any single piece of information about user_0 based on what we’ve already learned. But what if you wanted to see everything stored in this user’s dictionary? To do so, you could loop through the dictionary using a for loop:

user_0 = {
    'user_name' : 'ahmedgouda',
    'first_name' : 'ahmed',
    'last_name' : 'gouda',
    }

for key, value in user_0.items():
    print(f"Key : {key}")
    print(f"Value : {value}\n")

To write a for loop for a dictionary, you create names for the two variables that will hold the key and value in each key­-value pair. You can choose any names you want for these two variables.

The second half of the for statement includes the name of the dictionary followed by the method items(), which returns a list of key­-value pairs. The for loop then assigns each of these pairs to the two variables provided.

Looping through all key-­value pairs works particularly well for dictionaries like the favorite_languages example, which stores the same kind of information for many different keys. If you loop through the favorite_languages dictionary, you get the name of each person in the dictionary and their favorite programming language.

favorite_language = {
    'ahmed' : 'python',
    'mohammed' : 'c',
    'ali' : 'rust',
    'omar' : 'go',
    }

for name, language in favorite_language.items():
    print(f"{name.title()}'s favorite programming language is {language.title()}.")

Ahmed's favorite programming language is Python.
Mohammed's favorite programming language is C.
Ali's favorite programming language is Rust.
Omar's favorite programming language is Go.

The code tells Python to loop through each key-­value pair in the dictionary. As it works through each pair the key is assigned to the variable name, and the value is assigned to the variable language.

This type of looping would work just as well if our dictionary stored the results from polling a thousand or even a million people.

Looping Through All the Keys in a Dictionary

The keys() method is useful when you don’t need to work with all of the values in a dictionary. Let’s loop through the favorite_languages dictionary and print the names of everyone who took the poll:

favorite_language = {
    'ahmed' : 'python',
    'mohammed' : 'c',
    'ali' : 'rust',
    'omar' : 'go',
    }

for name in favorite_language.keys():
    print(name.title())

The code tells Python to pull all the keys from the dictionary favorite_languages and assign them one at a time to the variable name.

Looping through the keys is actually the default behavior when looping through a dictionary, so this code would have exactly the same output if you wrote:

for name in favorite_language:

rather than

for name in favorite_language.keys():

You can choose to use the keys() method explicitly if it makes your code easier to read, or you can omit it if you wish.

You can access the value associated with any key you care about inside the loop by using the current key. Let’s print a message to a couple of friends about the languages they chose.

favorite_language = {
    'ahmed' : 'python',
    'mohammed' : 'c',
    'ali' : 'rust',
    'omar' : 'go',
    }

friends = ['ali', 'hassan', 'ahmed']

for name in favorite_language.keys():
    print(f"Hi {name.title()}")

    if name in friends:
        language = favorite_language[name].title()
        print(f"\t{name.title()}, I see you love {language}.")

Hi Ahmed
        Ahmed, I see you love Python.
Hi Mohammed
Hi Ali
        Ali, I see you love Rust.
Hi Omar

You can also use the keys() method to find out if a particular person was polled. This time, let’s find out if Hassan took the poll:

favorite_language = {
    'ahmed' : 'python',
    'mohammed' : 'c',
    'ali' : 'rust',
    'omar' : 'go',
    }

if 'hassan' not in favorite_language.keys():
    print("Hassan, please take our poll!")

The keys() method isn’t just for looping: it actually returns a list of all the keys, and the code simply checks if 'hassan' is in this list. Because he’s not, a message is printed inviting her to take the poll:

Hassan, please take our poll!

Looping Through a Dictionary’s Keys in a Particular Order

Starting in Python 3.7, looping through a dictionary returns the items in the same order they were inserted. Sometimes, though, you’ll want to loop through a dictionary in a different order. One way to do this is to sort the keys as they’re returned in the for loop. You can use the sorted() function to get a copy of the keys in order:

favorite_language = {
    'ahmed' : 'python',
    'mohammed' : 'c',
    'ali' : 'rust',
    'omar' : 'go',
    }

for name in sorted(favorite_language.keys()):
    print(f"Thanks {name.title()} for taking the poll.")

Thanks Ahmed for taking the poll.
Thanks Ali for taking the poll.
Thanks Mohammed for taking the poll.
Thanks Omar for taking the poll.

This for statement is like other for statements except that we’ve wrapped the sorted() function around the dictionary.keys() method. This tells Python to list all keys in the dictionary and sort that list before looping through it.

Looping Through All Values in a Dictionary

If you are primarily interested in the values that a dictionary contains, you can use the values() method to return a list of values without any keys. For example, say we simply want a list of all languages chosen in our programming language poll without the name of the person who chose each language:

favorite_language = {
    'ahmed' : 'python',
    'mohammed' : 'c',
    'ali' : 'rust',
    'omar' : 'go',
    }

print("The following languages have been mentioned:")
for language in favorite_language.values():
    print(language.title())

The following languages have been mentioned:
Python
C
Rust
Go

The for statement here pulls each value from the dictionary and assigns it to the variable language.

This approach pulls all the values from the dictionary without checking for repeats. That might work fine with a small number of values, but in a poll with a large number of respondents, this would result in a very repetitive list. To see each language chosen without repetition, we can use a set.

A set is a collection in which each item must be unique:

favorite_language = {
    'ahmed' : 'python',
    'mohammed' : 'c',
    'ali' : 'rust',
    'omar' : 'go',
    'Hassan' : 'python',
    }

print("The following languages have been mentioned:")
for language in set(favorite_language.values()):
    print(language.title())

C
Go
Rust
Python

When you wrap set() around a list that contains duplicate items, Python identifies the unique items in the list and builds a set from those items.

As you continue learning about Python, you’ll often find a built­in feature of the language that helps you do exactly what you want with your data. You can build a set directly using braces and separating the elements with commas:

>>> languages = {'python', 'ruby', 'python', 'c'}
>>> languages
{'ruby', 'python', 'c'}

It’s easy to mistake sets for dictionaries because they’re both wrapped in braces. When you see braces but no key-value pairs, you’re probably looking at a set. Unlike lists and dictionaries, sets do not retain items in any specific order.

Nesting

Sometimes you’ll want to store multiple dictionaries in a list, or a list of items as a value in a dictionary. This is called nesting. You can nest dictionaries inside a list, a list of items inside a dictionary, or even a dictionary inside another dictionary. Nesting is a powerful feature.

A List of Dictionaries

The alien_0 dictionary contains a variety of information about one alien, but it has no room to store information about a second alien, much less a screen full of aliens. How can you manage a fleet of aliens? One way is to make a list of aliens in which each alien is a dictionary of information about that alien. For example, the following code builds a list of three aliens:

alien_0 = {'color': 'green', 'points': 5}
alien_1 = {'color': 'yellow', 'points': 10}
alien_2 = {'color': 'red', 'points': 15}

aliens = [alien_0, alien_1, alien_2]

for alien in aliens:
print(alien)

{'color': 'green', 'points': 5}
{'color': 'yellow', 'points': 10}
{'color': 'red', 'points': 15}

We first create three dictionaries, each representing a different alien. We store each of these dictionaries in a list called aliens. Finally, we loop through the list and print out each alien.

A more realistic example would involve more than three aliens with code that automatically generates each alien. In the following example we use range() to create a fleet of 30 aliens:

# Make an empty list for storing aliens.
aliens = []

# Make 30 green aliens.
for alien_number in range(30):
    new_alien = {'color': 'green', 'points': 5, 'speed': 'slow'}
    aliens.append(new_alien)

# Show the first 5 aliens.
for alien in aliens[:5]:
    print(alien)
print("...")

# Show how many aliens have been created.
print(f"Total number of aliens: {len(aliens)}")

{'speed': 'slow', 'color': 'green', 'points': 5}
{'speed': 'slow', 'color': 'green', 'points': 5}
{'speed': 'slow', 'color': 'green', 'points': 5}
{'speed': 'slow', 'color': 'green', 'points': 5}
{'speed': 'slow', 'color': 'green', 'points': 5}
...
Total number of aliens: 30

range() returns a series of numbers, which just tells Python how many times we want the loop to repeat.

These aliens all have the same characteristics, but Python considers each one a separate object, which allows us to modify each alien individually.

How might you work with a group of aliens like this? Imagine that one aspect of a game has some aliens changing color and moving faster as the game progresses. When it’s time to change colors, we can use a for loop and an if statement to change the color of aliens. For example, to change the first three aliens to yellow, medium­speed aliens worth 10 points each, we could do this:

# Make an empty list for storing aliens.
aliens = []

# Make 30 green aliens.
for alien_number in range (30):
    new_alien = {'color': 'green', 'points': 5, 'speed': 'slow'}
    aliens.append(new_alien)

for alien in aliens[:3]:
    if alien['color'] == 'green':
        alien['color'] = 'yellow'
        alien['speed'] = 'medium'
        alien['points'] = 10

# Show the first 5 aliens.
for alien in aliens[:5]:
    print(alien)
print("...")

{'color': 'yellow', 'points': 10, 'speed': 'medium'}
{'color': 'yellow', 'points': 10, 'speed': 'medium'}
{'color': 'yellow', 'points': 10, 'speed': 'medium'}
{'color': 'green', 'points': 5, 'speed': 'slow'}
{'color': 'green', 'points': 5, 'speed': 'slow'}
...

Because we want to modify the first three aliens, we loop through a slice that includes only the first three aliens. All of the aliens are green now but that won’t always be the case, so we write an if statement to make sure we’re only modifying green aliens.

You could expand this loop by adding an elif block that turns yellow aliens into red, fast-­moving ones worth 15 points each.

for alien in aliens[0:3]:
    if alien['color'] == 'green':
        alien['color'] = 'yellow'
        alien['speed'] = 'medium'
        alien['points'] = 10
    elif alien['color'] == 'yellow':
        alien['color'] = 'red'
        alien['speed'] = 'fast'
        alien['points'] = 15

It’s common to store a number of dictionaries in a list when each dictionary contains many kinds of information about one object. For example, you might create a dictionary for each user on a website, and store the individual dictionaries in a list called users. All of the dictionaries in the list should have an identical structure so you can loop through the list and work with each dictionary object in the same way.

A List in a Dictionary

Rather than putting a dictionary inside a list, it’s sometimes useful to put a list inside a dictionary. For example, consider how you might describe a pizza that someone is ordering. If you were to use only a list, all you could really store is a list of the pizza’s toppings. With a dictionary, a list of toppings can be just one aspect of the pizza you’re describing.

In the following example, two kinds of information are stored for each pizza: a type of crust and a list of toppings. The list of toppings is a value associated with the key 'toppings'. To use the items in the list, we give the name of the dictionary and the key 'toppings', as we would any value in the dictionary. Instead of returning a single value, we get a list of toppings:

# Store information about a pizza being ordered.
pizza = {
    'crust': 'thick',
    'toppings': ['mushrooms', 'extra cheese'],
    }

# Summarize the order.
print(f"You ordered a {pizza['crust']}-crust pizza "
    "with the following toppings:")

for topping in pizza['toppings']:
    print("\t" + topping)

You ordered a thick-crust pizza with the following toppings:
    mushrooms
    extra cheese

When you need to break up a long line in a print() call, choose an appropriate point at which to break the line being printed, and end the line with a quotation mark. Indent the next line, add an opening quotation mark, and continue the string. Python will automatically combine all of the strings it finds inside the parentheses.

You can nest a list inside a dictionary any time you want more than one value to be associated with a single key in a dictionary. In the earlier example of favorite programming languages, if we were to store each person’s responses in a list, people could choose more than one favorite language. When we loop through the dictionary, the value associated with each person would be a list of languages rather than a single language.

favorite_languages = {
    'ahmed' : ['python', 'c', 'rust'],
    'mohammed' : ['c', 'c++'],
    'ali' : ['rust', 'c'],
    'omar' : ['go'],
    }

for name, languages in favorite_languages.items():
    print(f"\n{name.title()}'s favorite languages:")

    for language in languages:
        print(language.title())

Ahmed's favorite languages:
Python
C
Rust

Mohammed's favorite languages:
C
C++

Ali's favorite languages:
Rust
C

Omar's favorite languages:
Go

To refine this program even further, you could include an if statement at the beginning of the dictionary’s for loop to see whether each person has more than one favorite language by examining the value of len(languages).

favorite_languages = {
    'ahmed' : ['c', 'python', 'rust'],
    'mohammed' : ['c'],
    'ali' : ['rust', 'go'],
    'omar' : ['go'],
    }

for name, languages in favorite_languages.items():
    if len(languages) == 1:
        print(f"\n{name.title()}'s favorite language is: {languages[0].title()}")
    else:
        print(f"\n{name.title()}'s favorite languages are:")
        for language in languages:
            print(language.title())

Ahmed's favorite languages are:
C
Python
Rust

Mohammed's favorite language is: C

Ali's favorite languages are:
Rust
Go

Omar's favorite language is: Go

A Dictionary in a Dictionary

You can nest a dictionary inside another dictionary, but your code can get complicated quickly when you do. For example, if you have several users for a website, each with a unique username, you can use the usernames as the keys in a dictionary. You can then store information about each user by using a dictionary as the value associated with their username. In the following listing, we store three pieces of information about each user: their first name, last name, and location. We’ll access this information by looping through the usernames and the dictionary of information associated with each username:

users = {
    'ahmedgouda' : {
        'first_name' : 'ahmed',
        'last_name' : 'gouda',
        'location' : 'egypt',
    },

    'mohammedali' : {
        'first_name' : 'mohammed',
        'last_name' : 'ali',
        'location' : 'america',
    },
}

for username, user_info in users.items():
    print(f"\nUsername: {username}")
    full_name = f"{user_info['first_name']} {user_info['last_name']}"
    location = user_info['location']

    print(f"Full Name: {full_name.title()}")
    print(f"Location : {location.title()}")

Username: ahmedgouda
Full Name: Ahmed Gouda
Location : Egypt

Username: mohammedali
Full Name: Mohammed Ali
Location : America

Notice that the structure of each user’s dictionary is identical. Although not required by Python, this structure makes nested dictionaries easier to work with. If each user’s dictionary had different keys, the code inside the for loop would be more complicated.