Python's Built-in Exceptions: A Walkthrough With Examples

Handling Exceptions

If you have a piece of code that raises an exception, and you don’t provide a handler code for that exception, then your program will stop running. After that, an exception traceback will appear on the standard output, your screen.

In Python, you can handle exceptions using the try … except statement, which allows you to catch the exception and provide recuperative actions.

Consider the following example. A common exception that you’ll see when you start using Python’s lists and tuples is IndexError. This exception happens when you try to access an index that’s out of range:

>>> numbers = [1, 2, 3]
>>> numbers[5]
Traceback (most recent call last):
    ...
IndexError: list index out of range

In this example, the list of numbers only has three values. So, when you try to access index 5 in an indexing operation, you get an IndexError that breaks the code. You can wrap up this code in a try … except block to prevent the breakdown:

>>> try:
...     numbers[5]
... except IndexError:
...     print("Your list doesn't have that index 😔")
...
Your list doesn't have that index 😔

Now, the code doesn’t break with an exception. Instead, it prints a message to the screen. Note that the call to print() is just a placeholder action for the sake of the example. In real-world code, you may do other things here.

The above example illustrates the most basic construct to handle exceptions in Python. You can check out the tutorial suggested above to dive deeper into exception handling. Now, it’s time to learn about the other side of the coin. You can also raise exceptions in Python.

Raising Exceptions

Python has the raise statement as part of its syntax. You can use this statement to raise exceptions in your code as a response to exceptional situations.

As an example of how to use the raise statement, say that you need to write a function for calculating the average grade of students. You come up with the following function:

>>> def average_grade(grades):
...     return sum(grades) / len(grades)
...

>>> average_grade([5, 4, 5, 3])
4.25

>>> average_grade([])
Traceback (most recent call last):
    ...
ZeroDivisionError: division by zero

This function works okay. However, when the list of grades is empty, you get a zero division error because len(grades) will be 0. When the user of the code sees the error message, they may get confused. A zero division error? What’s causing this?

A better approach would probably be to make sure that the input list isn’t empty and raise a more appropriate exception if that’s the case:

>>> def average_grade(grades):
...     if not grades:
...         raise ValueError("empty grades not allowed")
...     return sum(grades) / len(grades)
...

>>> average_grade([5, 4, 5, 3])
4.25

>>> average_grade([])
Traceback (most recent call last):
    ...
ValueError: empty grades not allowed

In this updated version of average_grade(), you add a conditional statement that checks whether the input data is empty. If it is, you raise a ValueError with an explicit error message that clearly communicates what’s wrong with the code.

The IndexError and ValueError exceptions are examples of commonly used built-in exceptions in Python. In the following sections, you’ll learn more about these and several other built-in exceptions.

This knowledge will help you in several ways. First, you’ll be able to quickly figure out the type of error you may have in your code, which improves your debugging skills. Second, you’ll be armed with a wide arsenal of already available exceptions to raise in your own code, freeing yourself from creating custom exceptions.

Glancing at the Exceptions Hierarchy

As you already know, you’ll find many built-in exceptions in Python. You can explore them by inspecting the builtins namespace from a REPL session:

>>> import builtins

>>> dir(builtins)
[
    'ArithmeticError',
    'AssertionError',
    'AttributeError',
    'BaseException',
    ...
]

In this example, you first import the builtins namespace. Then, you use the built-in dir() function to list the names that this module defines. Note that you’ll get the complete list of built-in names. Between them, you’ll find the built-in exceptions.

Python’s built-in exceptions are coded as classes and organized in a class hierarchy that includes the following levels:

• Base classes: They provide the base classes for other exceptions. You should only use them as parent classes. However, you might find some of these exceptions, such as the Exception class, in some codebases.
• Concrete exceptions: They’re exceptions that Python will raise as a response to different exceptional situations. They also provide a great base of concrete exceptions that you can raise in your own code when appropriate.
• OS exceptions: They provide exceptions that the operating system generates. Python passes them along to your application. In most cases, you’ll be catching these exceptions but not raising them in your code.
• Warnings: They provide warnings about unexpected events or actions that could result in errors later. These particular types of exceptions don’t represent errors. Ignoring them can cause you issues later, but you can ignore them.

A diagram of the exception hierarchy is below:

BaseException
 ├── BaseExceptionGroup
 ├── GeneratorExit
 ├── KeyboardInterrupt
 ├── SystemExit
 └── Exception
      ├── ArithmeticError
      │    ├── FloatingPointError
      │    ├── OverflowError
      │    └── ZeroDivisionError
      ├── AssertionError
      ├── AttributeError
      ├── BufferError
      ├── EOFError
      ├── ExceptionGroup [BaseExceptionGroup]
      ├── ImportError
      │    └── ModuleNotFoundError
      ├── LookupError
      │    ├── IndexError
      │    └── KeyError
      ├── MemoryError
      ├── NameError
      │    └── UnboundLocalError
      ├── OSError
      │    ├── BlockingIOError
      │    ├── ChildProcessError
      │    ├── ConnectionError
      │    │    ├── BrokenPipeError
      │    │    ├── ConnectionAbortedError
      │    │    ├── ConnectionRefusedError
      │    │    └── ConnectionResetError
      │    ├── FileExistsError
      │    ├── FileNotFoundError
      │    ├── InterruptedError
      │    ├── IsADirectoryError
      │    ├── NotADirectoryError
      │    ├── PermissionError
      │    ├── ProcessLookupError
      │    └── TimeoutError
      ├── ReferenceError
      ├── RuntimeError
      │    ├── NotImplementedError
      │    └── RecursionError
      ├── StopAsyncIteration
      ├── StopIteration
      ├── SyntaxError
      │    └── IndentationError
      │         └── TabError
      ├── SystemError
      ├── TypeError
      ├── ValueError
      │    └── UnicodeError
      │         ├── UnicodeDecodeError
      │         ├── UnicodeEncodeError
      │         └── UnicodeTranslateError
      └── Warning
           ├── BytesWarning
           ├── DeprecationWarning
           ├── EncodingWarning
           ├── FutureWarning
           ├── ImportWarning
           ├── PendingDeprecationWarning
           ├── ResourceWarning
           ├── RuntimeWarning
           ├── SyntaxWarning
           ├── UnicodeWarning
           └── UserWarning

Note that most classes in the hierarchy inherit from Exception. This is also the base class that you should use in those situations when you need to create a custom exception.

Knowing the Base Exceptions

In the built-in exception hierarchy, you’ll find a few classes that are designed to be base classes. The BaseException class is on the top. Then you have five subclasses:

As you can see, all of these base exceptions have their specific use case. It’s important to note that you should use Exception and not BaseException when you create custom exceptions. That’s because BaseException should be used for exceptions that should never be caught in real code.

In practice, when catching and raising exceptions, you should use the most specific exception for the problem at hand.

For example, if you have a piece of code that can potentially raise a ValueError, then you should explicitly handle this exception. If you use Exception instead of ValueError, then your code will catch Exception and all its subclasses, including ValueError. If your code ends up raising something different from ValueError, then that error will be mishandled.

Getting to Know Warnings

At the bottom of the exception hierarchy, you’ll find warnings. These are particular types of exceptions that denote something that can cause problems in the near future. Warnings are exceptions that pertain to the warning categories.

Probably the most common warning that you’ll see while executing Python code is DeprecationWarning. This warning appears when you use deprecated features of the language. For example, Python 3.12 has deprecated the calendar.January and calendar.February constants:

>>> # Python 3.12.2
>>> calendar.January
<stdin>:1: DeprecationWarning: The 'January' attribute is deprecated,
    use 'JANUARY' instead
1

Even though the code works because the constants haven’t been removed yet, Python lets you know that the feature is deprecated to prevent you from having issues in the future. As the warning message says, now you should use calendar.JANUARY.

SyntaxError

When Python detects an invalid syntax in a piece of code, it raises a SyntaxError exception. The exception prints a traceback with helpful information that you can use to debug the error and fix your code.

There are many situations where you can end up with a syntax error in your code. You can forget a comma or a closing bracket, misuse an operator or a keyword, and more.

Here are a few examples:

>>> numbers = [1, 2, 3 4]
  File "<stdin>", line 1
    numbers = [1, 2, 3 4]
                     ^^^
SyntaxError: invalid syntax. Perhaps you forgot a comma?

>>> 7 = 7
  File "<stdin>", line 1
    7 = 7
    ^
SyntaxError: cannot assign to literal here.
    Maybe you meant '==' instead of '='?

>>> class = "Economy"
  File "<stdin>", line 1
    class = "Economy"
          ^
SyntaxError: invalid syntax

These are common syntax errors that you can fall into at times. The good news is that with the improved error messages that Python provides these days, you can quickly track down the error and fix it.

IndentationError

Unlike other programming languages, indentation is part of Python syntax. To delimit a code block in Python, you use indentation. Therefore, you may get an error if the indentation isn’t correct. Python uses the IndentationError exception to denote this problem.

You may encounter this exception when you’re starting to learn Python. It can also appear when you copy and paste code from intricate places. Fortunately, the error isn’t common nowadays because modern code editors can automatically fix code indentation.

To see the exception in action, consider the following example of a function whose code block uses non-uniform indentation:

>>> def greet(name):
...     print(f"Hello, {name}!")
...   print("Welcome to Real Python!")
  File "<stdin>", line 3
    print("Welcome to Real Python!")
                                   ^
IndentationError: unindent does not match any outer indentation level

In this example, the highlighted lines have different indentations. The first line is indented at four spaces, while the second line is indented at two spaces. This indentation mismatch triggers an IndentationError. Again, because this is a syntax error, Python reports it immediately. You can quickly fix the issue by correcting the indentation.

TabError

Another possible issue for those who come from other programming languages is to mix tab and space characters while indenting Python code. The exception for this issue is TabError, which is a subclass of IndentationError. So, it’s another syntax error exception.

Here’s an example where Python raises a TabError exception:

def greet(name):
    print(f"Hello, {name}!")
        print("Welcome to Real Python!")

In this example, the first line in greet() is indented using a tab character, while the second line is indented using eight spaces, which is the common number of spaces that replaces a tab character.

To try out the example, go ahead and run the file from the command line:

$ python greeting.py
  File ".../greeting.py", line 3
    print("Welcome to Real Python!")
TabError: inconsistent use of tabs and spaces in indentation

Because the code indentation mixes tabs and spaces, you get a TabError indentation error. Again, TabError exceptions aren’t common nowadays because modern code editors can fix them automatically. So, if you have your editor well-set for Python development, then you probably won’t see this exception in action.

ModuleNotFoundError

As you’ve already learned, the ModuleNotFoundError exception is a subclass of ImportError with a more specific goal. Python raises this exception when it can’t find the module from which you want to import something:

>>> import non_existing
Traceback (most recent call last):
    ...
ModuleNotFoundError: No module named 'non_existing'

When Python doesn’t find the target module in its import search path, it raises a ModuleNotFoundError exception. To fix this problem, you must ensure your module is listed in sys.path.

Because ModuleNotFoundError is a subclass of ImportError, when you explicitly use the latter in a try … except block, you’ll be catching both exceptions. So, if your intention is to catch those situations where the target module isn’t present, then you should be specific and use ModuleNotFoundError.

ImportError

Python raises the ImportError exception for all the import-related issues that aren’t covered by ModuleNotFoundError. This can happen for two main reasons:

1. An import module statement fails to load a module for a reason not covered by ModuleNotFoundError.
2. A from module import name statement fails to find name in the target module.

Now go ahead and run the following import statement to see the ImportError exception in action:

>>> from sys import non_existing
Traceback (most recent call last):
    ...
ImportError: cannot import name 'non_existing' from 'sys' (unknown location)

In this example, you try to import the non_existing name from the sys module. Because the name doesn’t exist in this module, you get an ImportError. You can quickly fix the problem by providing the correct target name.

In real-world code, you can take advantage of ImportError or ModuleNotFoundError to optionally load different modules or libraries that provide a given functionality depending on the library availability.

For example, say you need to parse a TOML file and read its content. In this case, you can use the standard-library module tomllib if you’re using Python 3.11 or later. Otherwise, you should use the third-party library tomli, which is compatible with tomllib.

Here’s how you can do this:

try:
    import tomllib  # Python >= 3.11
except ModuleNotFoundError:
    import tomli as tomllib  # Python < 3.11

The import in the try clause targets the standard-library module tomllib. If this import raises an exception because you’re using a Python version lower than 3.11, then the except clause imports the third-party library tomli, which you need to install as an external dependency of your project.

IndexError

The IndexError exception happens when you try to retrieve a value from a sequence using an out-of-range index:

>>> colors = [
...     "red",
...     "orange",
...     "yellow",
...     "green",
...     "blue",
...     "indigo",
...     "violet",
... ]

>>> colors[10]
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    colors[10]
    ~~~~~~^^^^
IndexError: list index out of range

In this example, you use 10 as the index to get a value from your colors list. Because the list only has seven items, the valid indices go from 0 to 6. Your target index is out of range, and Python gives you an IndexError exception.

IndexError can be a frequent exception in Python, especially when you’re using dynamically generated indices. To fix the problem, you need to figure out which index your code is using to retrieve a value from the target sequence and then adjust the index range to correct the issue.

If you can’t control the range of indices, then you can catch the exception in a try … except block and take the appropriate recovery action.

You can also raise the IndexError exception in your own code. This exception can be appropriate when you’re creating custom sequence-like data structures. For example, say that you need to create a sequence-like stack:

class Stack:
    def __init__(self, items=None):
        self.items = list(items) if items is not None else []

    def push(self, item):
        self.items.append(item)

    def pop(self):
        return self.items.pop()

    def __len__(self):
        return len(self.items)

    def __getitem__(self, index):
        try:
            return self.items[index]
        except IndexError:
            raise IndexError(
                f"your stack only has {len(self)} items!"
            ) from None

In this example, you define Stack and provide the .push() and .pop() methods. The former method appends a new item to the top of the stack, while the latter removes and returns the item at the top of the stack.

Then, you have the .__len__() special method to support the built-in len() function, which gives you the number of items in the stack.

Finally, you have the .__getitem__() method. This special method takes an index as an argument and returns the item at the input index. The try … except block catches the IndexError exception and reraises it with a more specific error message. You don’t rely on the original message, which makes your code more focused.

KeyError

Similarly, when you try to get a non-existing key from a dictionary, then you get a KeyError exception. This issue is also common in Python:

>>> fruits = {"apple": 0.40, "orange": 0.35, "banana": 0.25}

>>> fruits["grape"]
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    fruits["grape"]
    ~~~~~~^^^^^^^^^
KeyError: 'grape'

In this example, you try to get the grape key from the fruits dictionary and get a KeyError exception. In this case, the error message is pretty short. It only displays the name of the missing key.

Again, using dynamically generated keys can be the source of the problem. So, to correct the issue, you’ll need to check the generated and existing keys in your code. Alternatively, you can use the .get() method with an appropriate default value if that’s a suitable solution for your use case.

Finally, you can also raise a KeyError in your code. This could be helpful when you need to create a dictionary-like class and provide a more descriptive error message for your users.

TypeError

Python raises a TypeError exception when you apply an operation or function to an object that doesn’t support that operation. For example, consider calling the built-in len() function with a number as an argument:

>>> len(42)
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    len(42)
TypeError: object of type 'int' has no len()

In this example, the argument to len() is an integer number, which doesn’t support the function. Therefore, you get an error with an appropriate message.

In practice, you can catch the TypeError exception in your own code when you need to prevent a type-related issue. You can also raise the exception in your code to denote a type-related problem. For example, say that you want to write a function that takes an iterable of numbers and returns a list of squared values. You want to make sure that the function only accepts iterable objects.

In this situation, you can have a function like the following:

>>> def squared(numbers):
...     try:
...         iter(numbers)
...     except TypeError:
...         raise TypeError(
...             f"expected an iterable, got '{type(numbers).__name__}'"
...         ) from None
...     return [number**2 for number in numbers]
...

>>> squared([1, 2, 3, 4, 5])
[1, 4, 9, 16, 25]

>>> squared(42)
Traceback (most recent call last):
    ...
TypeError: expected an iterable, got 'int'

In this example, your function uses the built-in iter() function to check the input data. This function raises a TypeError exception if the provided input isn’t iterable. You catch this exception and reraise it but with a custom error message that adheres to your code’s purpose. Then, you build the list of squared values using a list comprehension.

ValueError

Similarly, Python raises the ValueError exception when an operation or function gets an argument that has the right type but an inappropriate value:

>>> float("1")
1.0

>>> float("one")
Traceback (most recent call last):
    ...
ValueError: could not convert string to float: 'one'

In this example, you first use the built-in float() function to convert a string to a floating-point number. The input string contains a numeric value, so the operation succeeds.

In the second example, you call the same function using a string that doesn’t represent a valid number and get a ValueError exception. Note that the input argument is a string, which is the correct type of argument. However, the input string isn’t a valid numeric value, so you have the right type but the wrong value.

You can also use ValueError in your Python code. This exception can be appropriate in different situations. For example, say that you need to write a class to represent rainbow colors. This class has seven allowed color names, which you can represent with strings:

COLORS = {
    "Red": {"Hex": "#FF0000", "RGB": (255, 0, 0)},
    "Orange": {"Hex": "#FF7F00", "RGB": (255, 127, 0)},
    "Yellow": {"Hex": "#FFFF00", "RGB": (255, 255, 0)},
    "Green": {"Hex": "#00FF00", "RGB": (0, 255, 0)},
    "Blue": {"Hex": "#0000FF", "RGB": (0, 0, 255)},
    "Indigo": {"Hex": "#4B0082", "RGB": (75, 0, 130)},
    "Violet": {"Hex": "#8B00FF", "RGB": (139, 0, 255)},
}

class RainbowColor:
    def __init__(self, name="Red"):
        name = name.title()
        if name not in COLORS:
            raise ValueError(f"{name} is not a valid rainbow color")
        self.name = name

    def as_hex(self):
        return COLORS[self.name]["Hex"]

    def as_rgb(self):
        return COLORS[self.name]["RGB"]

In this example, you first define a COLORS constant that holds the rainbow colors and their corresponding Hex and RGB representation.

Then, you define the RainbowColor class. In the class initializer, you use a conditional to make sure that the input color name is one of the rainbow colors. If that’s not the case, then you raise a ValueError because the color name is of the correct type but has the wrong value. It’s a string but not a valid color name.

Here’s how the class works in practice:

>>> from rainbow import RainbowColor

>>> color = RainbowColor("Gray")
Traceback (most recent call last):
    ...
ValueError: Gray is not a valid rainbow color

>>> color = RainbowColor("Blue")
>>> color.name
'Blue'
>>> color.as_rgb()
(0, 0, 255)

In this code snippet, when you try to pass a color name that’s not allowed, then you get a ValueError. If the color name is valid, then the class works fine.

AttributeError

Another common exception that you’ll see when you work with Python classes is AttributeError. This exception occurs when the specified object doesn’t define the attribute or method that you’re trying to access.

Take, for example, your RainbowClass from the previous section. This class has one attribute and two methods, .name, .as_hex(), and .as_rgb(). If you access them, then you’ll have a result according to what they do. However, say that you try to access a method called .as_hsl(). What would happen?

Here’s the answer:

>>> from rainbow import RainbowColor

>>> color = RainbowColor("Blue")

>>> color.as_hsl()
Traceback (most recent call last):
    ...
AttributeError: 'RainbowColor' object has no attribute 'as_hsl'

Because RainbowColor doesn’t define the .as_hsl() method, you get an AttributeError that tells you the class doesn’t have an attribute that matches that name.

This error can be common in complex class hierarchies that define similar classes with slightly different interfaces. In this situation, you may think that a given class defines a given method or attribute, but that may not be the case. To fix the issue, you can take a look at the class definition or documentation to make sure that you only use the attributes and methods that the class defines.

You can skip the AttributeError exception by using the built-in hasattr() function:

>>> if hasattr(color, "as_hsl"):
...     color.as_hsl()
... else:
...     print("Hmm, you can't call that.")
...
Hmm, you can't call that.

In this example, you use hasattr() to explicitly check if the color object has an attribute called "as_hsl".

You can also catch and raise the AttributeError exception in your custom classes. In practice, this exception can be pretty useful because Python encourages you to use a coding style based on handling exceptions called EAFP (easier to ask forgiveness than permission).

In short, using this style means that you decide to handle errors and exceptions when they happen. In contrast, with the LBYL (look before you leap) style, you try to prevent errors and exceptions before they happen. That’s what you did in the example above.

So, instead of relying on hasattr(), you should write the above example as follows:

>>> try:
...     color.as_hsl()
... except AttributeError:
...     print("Hmm, you can't call that.")
...
Hmm, you can't call that.

This coding style is more direct. You go and call the desired method. If that fails with an AttributeError, then you perform alternative actions.

Finally, you’ll also get an AttributeError exception when you try to access an object that’s not defined in an already imported module:

>>> import sys

>>> sys.non_existing
Traceback (most recent call last):
    ...
AttributeError: module 'sys' has no attribute 'non_existing'

Note that you don’t get an import error in this example. Instead, you get an AttributeError exception. That’s because the objects defined in a module become attributes of that module.

ZeroDivisionError

Python raises the ZeroDivisionError exception when a division’s divisor or right operand is zero. As a quick example, say that you need to write a function to compute the average grade of a group of students. In this case, you can come up with the following function:

>>> def average_grade(grades):
...     return sum(grades) / len(grades)
...

>>> average_grade([4, 3, 3, 4, 5])
3.8

This function works okay when you use appropriate input data. But what would happen if you called the function with an empty list object? Here’s the answer:

>>> average_grade([])
Traceback (most recent call last):
    ...
ZeroDivisionError: division by zero

Because the input list is empty, the len() function returns 0. This return value produces a ZeroDivisionError exception when the actual division occurs.

To fix the issue, you can catch the exception and present the user with a descriptive error message:

>>> def average_grade(grades):
...     try:
...         return sum(grades) / len(grades)
...     except ZeroDivisionError:
...         raise ValueError(
...             "you should pass at least one grade to average_grade()"
...         ) from None
...

>>> average_grade([])
Traceback (most recent call last):
    ...
ValueError: you should pass at least one grade to average_grade()

In this updated version of average_grade(), you catch the ZeroDivisionError that an empty input list generates and raise a ValueError with a user-friendly error message.

Finally, the ZeroDivisionError exception also occurs when the right-hand operand on a modulo operation is zero:

>>> 42 % 0
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    42 % 0
    ~~~^~~
ZeroDivisionError: integer modulo by zero

The modulo operator returns the remainder of dividing two numbers. Because the division of the numbers is the first step to computing the remainder, you can get a ZeroDivisionError if the right-hand operand is 0.

OverflowError

The OverflowError isn’t that common. Python raises this exception when the result of an arithmetic operation is too large, and there’s no way to represent it:

>>> 10.0**1000
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    10.0**1000
    ~~~~^^~~~~
OverflowError: (34, 'Result too large')

In this example, the number that results from the power operation is too high, and Python can’t represent it correctly. So, you get an OverflowError exception.

RecursionError

A function that calls itself is known as a recursive function. These types of functions are the base of an iteration technique called recursion.

Consider the following toy function as an example of a recursive function:

>>> def recurse():
...     recurse()
...

This function doesn’t follow the rules of recursion because it doesn’t have a base case that stops the repetition. It only has a recursive case. So, if you call the function, then you get a RecursionError exception:

>>> recurse()
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    recurse()
  File "<input>", line 2, in recurse
    recurse()
  File "<input>", line 2, in recurse
    recurse()
  File "<input>", line 2, in recurse
    recurse()
  [Previous line repeated 981 more times]
RecursionError: maximum recursion depth exceeded

Python will raise a RecursionError exception when the interpreter detects that the maximum recursion depth is exceeded. This may happen when your base case doesn’t work properly or when the required number of recursions for performing the computation exceeds the recursion limit.

You can use the sys.getrecursionlimit() function to check your current recursion depth:

>>> import sys

>>> sys.getrecursionlimit()
1000

The result of calling this function is a number representing how many times a recursive function can call itself in Python. If appropriate for your use case, you can also set a different recursion limit using the sys.setrecursionlimit() function.

StopIteration

Python raises a StopIteration exception when you call the built-in next() function on an exhausted iterator. Its purpose is to signal that there are no more items in the iterator. So, Python uses this exception internally to control iteration.

Consider the following toy example:

>>> numbers_iterator = iter([1, 2, 3])

>>> next(numbers_iterator)
1
>>> next(numbers_iterator)
2
>>> next(numbers_iterator)
3
>>> next(numbers_iterator)
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    next(numbers_iterator)
StopIteration

In this example, you use the built-in iter() function to create an iterator from a short list of numbers. Then, you call next() repeatedly to consume the iterator. The fourth call to this function raises a StopIteration exception to signal that the iterator has no more items to retrieve.

Internally, Python uses this exception to terminate for loops. In other words, when a for loop is iterating over an iterator, the loop stops when it gets the StopIteration exception. Because of this, it’s not common to see this exception in action. Note that Python’s for loop calls next() under the hood to perform the iteration.

In practice, you can use the StopIteration exception in your code as part of an implementation of the iterator protocol. This protocol consists of two special methods:

1. .__iter__() is called to initialize the iterator. It must return an iterator object.
2. .__next__() is called to iterate over the iterator. It must return the next value in the data stream.

When you provide these methods in a custom class, then your class supports iteration. To signal when the iteration must stop, you must raise the StopIteration exception in the .__next__() method.

To illustrate how to use StopIteration, say that you need to create a custom class that takes a list of values and creates an iterator over their squares:

class SquareIterator:
    def __init__(self, values):
        self.values = values
        self.index = 0

    def __iter__(self):
        return self

    def __next__(self):
        if self.index >= len(self.values):
            raise StopIteration
        square = self.values[self.index] ** 2
        self.index += 1
        return square

In this class, the initializer takes a list of values as an argument. It also defines a reference index, which starts at 0. The .__iter__() method returns self, which is common practice when you’re using the iterator protocol like in this example.

In the .__next__() method, you check if the current index is greater than or equal to the number of values in the input list. If that’s the case, then you raise a StopIteration to signal that the iterator is exhausted. Next, you compute the square of the current value and return it as the method’s result.

Now you can use instances of this class in a for loop:

>>> from squares import SquareIterator

>>> for value in SquareIterator([1, 2, 3]):
...     print(value)
...
1
4
9

Your iterator works fine. It generates square values and supports iteration. Note that you don’t see the StopIteration exception happening. However, Python uses the exception internally to terminate the loop when the iterator is done.

FileExistsError

When you try to create a file or directory that already exists, Python raises the built-in FileExistsError exception.

To see this exception in action, say that you need to create a file in your working directory and write some text to it. However, you want to avoid replacing the file if it already exists. In this case, you can take advantage of the FileExistsError and write the following code:

try:
    with open("hello.txt", mode="x") as file:
        file.write("Hello, World!")
except FileExistsError:
    print("The file already exists")

In this example, you use the built-in open() function to open a file called hello.txt. The "x" mode means that you want to open the file for exclusive creation, failing if the file already exists.

Now go ahead and run this hello.py file from your command line:

$ python hello.py

This command won’t issue any output. However, if you look at your working directory, then you’ll see a new file called hello.txt with the text "Hello, World!" in it.

If you run the command again, then the result will be different:

$ python hello.py
The file already exists

This time, because the hello.txt file already exists, the file-creation code raises a FileExistsError exception, and the except clause prints an error message on the screen.

FileNotFoundError

Python raises the FileNotFoundError exception when a file or directory is requested but doesn’t exist in the target location. For example, say that you’ve accidentally removed the hello.txt file that you created in the previous section. When you try to read the file’s content, you get an error:

>>> with open("hello.txt", mode="r") as file:
...     print(file.read())
...
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    with open("hello.txt", mode="r") as file:
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^
FileNotFoundError: [Errno 2] No such file or directory: 'hello.txt'

In this code snippet, you try to open the hello.txt file to read its content. Because you removed the file prior to this operation, your code fails with the FileNotFoundError exception.

To handle this issue, you can rewrite your code as in the following example:

>>> try:
...     with open("hello.txt", mode="r") as file:
...         print(file.read())
... except FileNotFoundError:
...     print("The file doesn't exist")
...
The file doesn't exist

Now, you use a try … except block to handle the FileNotFoundError exception and prevent your code from breaking out.

PermissionError

Another common issue when processing files is when you try to access a file or directory without adequate access permissions. In this case, Python raises the PermissionError exception to let you know that you don’t have the required permissions.

For example, say you’re working on a Unix-like system, such as Linux or macOS. You want to update the content of the /etc/hosts file. In Unix-like systems, only the root user can modify this file. So, if you try to do your task using a different user, then you’ll get an error:

>>> with open("/etc/hosts", mode="a") as file:
...     print(file.write("##"))
...
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    with open("/etc/hosts", mode="a") as file:
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^
PermissionError: [Errno 13] Permission denied: '/etc/host'

This error occurs because the file /etc/hosts is a system file. You need root permissions to modify this file. Your code tries to open the file for appending content without having the necessary permissions, which leads to a PermissionError exception.

SystemExit

Python raises the SystemExit exception when you call the sys.exit() function in your code. When you don’t handle the exception, the Python interpreter exits without printing an exception traceback:

>>> import sys
>>> sys.exit(0)
$

In this example, you call the sys.exit() to terminate the Python interpreter. This call takes you back to your terminal session.

In practice, you can use SystemExit directly when you need to terminate an app. For example, say that you want to create a minimal CLI (command-line interface) app that mimics the basic functionality of the Unix ls command, which lists the content of a given directory.

In this situation, you can write a script like the following:

import sys
from pathlib import Path

if (args_count := len(sys.argv)) > 2:
    print(f"One argument expected, got {args_count - 1}")
    raise SystemExit(2)
elif args_count < 2:
    print("You must specify the target directory")
    raise SystemExit(2)

target_dir = Path(sys.argv[1])

if not target_dir.is_dir():
    print("The target directory doesn't exist")
    raise SystemExit(1)

for entry in target_dir.iterdir():
    print(entry.name)

This program processes the arguments provided at the command line, which are automatically stored in the sys.argv variable. The first item in sys.argv is the program’s name. The second item should be the target directory.

The app should only accept one target directory, so the args_count variable must be 2 at most. If the app gets more than one target directory, then you print an error message and raise a SystemExit exception with an exit status of 2. This indicates that the app exited after a failure.

The elif branch checks whether the user has provided a target directory. If that’s not the case, then you print an error message to the user and exit the app, raising a SystemExit exception.

After checking the content of sys.argv, you create a pathlib.Path object to store the path to your target directory. If this directory doesn’t exist, then you inform the user and exit the app using the SystemExit exception again. This time, the exit status is 1 to signal that the app faced an error during its execution. Finally, the for loop lists the directory content, one entry per line.

On a Unix-like system, such as Linux and macOS, you can run the following command to check how the script works:

$ python ls.py
You must specify the target directory
$ echo $?
2

$ python ls.py /home /etc
One argument expected, got 2
$ echo $?
2

$ python ls.py .
hello.py
birds.py
grades.py
greeting.py
fizzbuzz.py
ls.py
mean.py
stack.py
square.py
rainbow.py
$ echo $?
0

When you run the script with no argument, then you get a message telling you that you need to provide a target directory. When you use the echo command to check the exit code, represented by $?, you’ll see that it’s 2. In the second example, you provide two target directories. Again, the app fails with an error message. The echo command also returns 2.

Finally, you run the script with the current working directory as an argument. In this case, you get the list of files that live in that directory. When you run echo, you get an exit status of 0, which signals that the app’s execution was successful.

KeyboardInterrupt

The KeyboardInterupt exception is somewhat different from other exceptions. Python raises this exception when the user intentionally presses the Ctrl+C key combination during the execution of a program. This action interrupts a running program.

For example, say that you’re working on a piece of code that involves a loop. By error, the code falls into an infinite loop. In this situation, you need a quick way to terminate the code’s execution. That’s when the Ctrl+C key combination comes in handy.

Consider the following toy loop:

>>> while True:
...     print("Hello")
...
Hello
Hello
Hello
Hello
Hello
Hello
Hello
Hello
Traceback (most recent call last):
    ...
KeyboardInterrupt

This loop is intentionally written to be infinite. In practice, you can have real loops that run into infinite iteration because of a logical error. When you encounter this issue, you can press the Ctrl+C keys to terminate the code’s execution. As a result, Python will raise a KeyboardInterrupt exception.

Finally, it’s important to note that you shouldn’t catch this exception in your code because this may prevent the interpreter from exiting.