Python KeyError – Tutorial with Examples

Python offers a rich library of data structures, and the dictionary is one of them. A dictionary maps a set of keys to a set of values, which can be of any type of objects. In Python, dictionary is implemented as a hash table where the keys are the hashable values. A hashable value is an object that is immutable and generates an integer unique hash value. The dictionary is a very useful data structure for representing a map, and hence it has many applications in data analysis, machine learning, web development, and scientific computing.

While working with dictionaries in Python, you may often encounter the KeyError exception. The KeyError is raised when you try to access a non-existent key in a dictionary. This article provides a comprehensive tutorial on the Python KeyError exception with examples. We will discuss the causes, consequences, and solutions to the KeyError. We will also explore some best practices for working with dictionaries.

1. Overview of the KeyError

The KeyError is a Python built-in exception that is raised when you try to access a key in a dictionary that does not exist. The KeyError is a subclass of the LookupError category of exceptions that are raised when a lookup operation fails to find the requested object.

The KeyError object has one argument, which is the name of the key that caused the error. You can use various techniques to handle the KeyError, such as the try-except block, the ‘in’ operator, the get() method, and the defaultdict() function. You can also use the KeyError object to raise another exception or to generate a custom error message.

2. Causes of the KeyError

The KeyError is raised when you request a non-existent key in a dictionary. Here are some common causes of the KeyError:

• You misspelled the key name or used a wrong key name.
• You forgot to add the key-value pair to the dictionary.
• You deleted the key-value pair from the dictionary.
• You are working with nested dictionaries or complex data structures.
• You are using external data sources that may contain incomplete or invalid data.

3. Examples of the KeyError

In this section, we will explore some examples of the KeyError in Python. We will define a simple dictionary, and then we will try to access some non-existent keys in the dictionary.

3.1 Example 1: Accessing a non-existent key

Let’s define a dictionary named stocks that maps the names of some popular stocks to their current prices:

stocks = {'AAPL': 148.48, 'GOOG': 2762.87, 'TSLA': 709.67, 'AMZN': 3459.39}

Now, let’s try to access the price of the stock ‘TWTR’, which is not present in the dictionary:

print("The price of TWTR is", stocks['TWTR'])

The above code will raise a KeyError with the message ‘TWTR’. This is because the key ‘TWTR’ is not present in the dictionary, and hence the lookup operation fails.

The output of the above code will be:

Traceback (most recent call last):
  File "test.py", line 5, in <module>
    print("The price of TWTR is", stocks['TWTR'])
KeyError: 'TWTR'

3.2 Example 2: Misspelling the key name

In this example, we will try to access the price of the stock ‘AMZN’ by misspelling its name as ‘AMZM’:

print("The price of AMZN is", stocks['AMZM'])

The above code will raise a KeyError with the message ‘AMZM’. This is because we misspelled the key name and hence the lookup operation fails.

The output of the above code will be:

Traceback (most recent call last):
  File "test.py", line 5, in <module>
    print("The price of AMZN is", stocks['AMZM'])
KeyError: 'AMZM'

3.3 Example 3: Nested dictionaries

In this example, we will define a nested dictionary that contains the prices of some popular stocks in different currencies. We will try to access the price of the stock ‘AAPL’ in the currency ‘JPY’:

stocks = {'AAPL': {'USD': 148.48, 'EUR': 124.50, 'JPY': 16477.57},
          'GOOG': {'USD': 2762.87, 'EUR': 2320.33, 'JPY': 308964.18},
          'TSLA': {'USD': 709.67, 'EUR': 594.67, 'JPY': 79104.22},
          'AMZN': {'USD': 3459.39, 'EUR': 2900.12, 'JPY': 386669.82}}

print("The price of AAPL in JPY is", stocks['AAPL']['JPY'])
print("The price of AMZN in JPY is", stocks['AMZN']['JPY'])
print("The price of TSLA in JPY is", stocks['TSLA']['JPY'])
print("The price of GOOG in JPY is", stocks['GOOG']['JPY'])
print("The price of TWTR in JPY is", stocks['TWTR']['JPY'])

The first four print statements will work correctly and print the prices of the respective stocks in JPY. However, the last print statement will raise a KeyError because the key ‘TWTR’ is not present in the dictionary:

The price of AAPL in JPY is 16477.57
The price of AMZN in JPY is 386669.82
The price of TSLA in JPY is 79104.22
The price of GOOG in JPY is 308964.18
Traceback (most recent call last):
  File "test.py", line 10, in <module>
    print("The price of TWTR in JPY is", stocks['TWTR']['JPY'])
KeyError: 'TWTR'

4. Handling the KeyError

Now that we have seen some examples of the KeyError in Python, let’s discuss how to handle it. There are several ways to handle the KeyError, and we will discuss them one by one.

4.1 Try-except block

The try-except block is a Python language construct that allows you to catch and handle exceptions. The try block contains the code that may raise an exception, and the except block contains the code that handles the exception.

You can use the try-except block to catch the KeyError and print a custom error message. The syntax of the try-except block is as follows:

try:
    # code that may raise a KeyError
except KeyError:
    # code that handles the KeyError

Here is an example that uses the try-except block to catch the KeyError:

stocks = {'AAPL': 148.48, 'GOOG': 2762.87, 'TSLA': 709.67, 'AMZN': 3459.39}

try:
    print("The price of TWTR is", stocks['TWTR'])
except KeyError:
    print("The stock TWTR is not present in the dictionary.")

The above code will catch the KeyError and print a custom error message ‘The stock TWTR is not present in the dictionary.’ The output of the above code will be:

The stock TWTR is not present in the dictionary.

4.2 ‘in’ operator

The ‘in’ operator is a Python built-in operator that allows you to test whether a key is present in a dictionary. The ‘in’ operator returns a Boolean value of True if the key is present in the dictionary, and False otherwise.

You can use the ‘in’ operator to test whether a key is present in a dictionary before trying to access it. If the key is present, you can then access its corresponding value. If the key is not present, you can print a custom error message.

The syntax of the ‘in’ operator is as follows:

if key in dictionary:
    # code that accesses the value of the key
else:
    # code that handles the non-existent key

Here is an example that uses the ‘in’ operator to test whether a key is present in a dictionary:

stocks = {'AAPL': 148.48, 'GOOG': 2762.87, 'TSLA': 709.67, 'AMZN': 3459.39}

if 'TWTR' in stocks:
    print("The price of TWTR is", stocks['TWTR'])
else:
    print("The stock TWTR is not present in the dictionary.")

The above code will check whether the key ‘TWTR’ is present in the dictionary ‘stocks’. Since the key is not present, the code will print a custom error message ‘The stock TWTR is not present in the dictionary.’ The output of the above code will be:

The stock TWTR is not present in the dictionary.

4.3 get() method

The get() method is a dictionary method that allows you to access the value of a key in a dictionary. The get() method returns the value of the key if the key is present in the dictionary, and None otherwise.

You can use the get() method to get the value of a key in a dictionary and print a custom error message if the key is not present.

The syntax of the get() method is as follows:

dictionary.get(key, default)

Here is an example that uses the get() method to get the value of a key in a dictionary:

stocks = {'AAPL': 148.48, 'GOOG': 2762.87, 'TSLA': 709.67, 'AMZN': 3459.39}

price = stocks.get('TWTR', None)
if price is None:
    print("The stock TWTR is not present in the dictionary.")
else:
    print("The price of TWTR is", price)

The above code will use the get() method to get the value of the key ‘TWTR’ in the dictionary ‘stocks’. Since the key is not present, the code will print a custom error message ‘The stock TWTR is not present in the dictionary.’ The output of the above code will be:

The stock TWTR is not present in the dictionary.

4.4 defaultdict() function

The defaultdict() function is a useful utility function from the collections module that allows you to create a dictionary with default values. The default values are specified by a function that you provide. If you try to access a non-existent key in a defaultdict(), the function is called to generate the default value for the key.

You can use the defaultdict() function to handle the KeyError in a graceful way. When you access a non-existent key in a defaultdict(), the function generates a default value instead of raising a KeyError.

The syntax of the defaultdict() function is as follows:

defaultdict(default_factory)

Here is an example that uses the defaultdict() function to handle the KeyError:

from collections import defaultdict

stocks = {'AAPL': 148.48, 'GOOG': 2762.87, 'TSLA': 709.67, 'AMZN': 3459.39}

prices = defaultdict(lambda : 'not listed')
print("The price of TWTR is", prices['TWTR'])

The above code will use the defaultdict() function to create a dictionary named ‘prices’ with default value ‘not listed’. When we access the non-existent key ‘TWTR’ in the dictionary ‘prices’, the function generates the default value ‘not listed’ instead of raising a KeyError. The output of the above code will be:

The price of TWTR is not listed

5. Best practices for working with dictionaries

Here are some best practices for working with dictionaries in Python:

• Always use meaningful and unique key names. Avoid using reserved keywords or built-in function names as keys.
• Avoid modifying the dictionary while iterating over its keys or values.
• Handle the KeyError in a graceful way, such as using the try-except block, the ‘in’ operator, the get() method, or the defaultdict() function.
• If you are working with nested dictionaries or complex data structures, use the pprint() function from the pprint module to format the output for better readability.
• If you are working with external data sources, such as CSV files or JSON files, validate the data before using it and handle any invalid or incomplete data.

6. Conclusion

The KeyError is a common exception that is raised when you try to access a non-existent key in a dictionary in Python. The KeyError can cause your program to terminate abruptly if it is not handled properly. In this article, we have discussed the causes, consequences, and solutions to the KeyError. We have also explored some best practices for working with dictionaries in Python. By following these best practices, you can avoid the KeyError and make your code more robust and reliable.