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 exceptiontraceback will appear on the standard output, your screen.

In Python, you can handle exceptions using thetry …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’slists andtuples isIndexError. 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 index5 in anindexing operation, you get anIndexError that breaks the code. You can wrap up this code in atry …except block to prevent the breakdown:

>>>try:...numbers[5]...exceptIndexError:...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 toprint() 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 theraise statement as part of itssyntax. You can use this statement to raise exceptions in your code as a response to exceptional situations.

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

>>>defaverage_grade(grades):...returnsum(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 becauselen(grades) will be0. 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:

>>>defaverage_grade(grades):...ifnotgrades:...raiseValueError("empty grades not allowed")...returnsum(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 ofaverage_grade(), you add aconditional statement that checks whether the input data is empty. If it is, you raise aValueError with an explicit error message that clearly communicates what’s wrong with the code.

TheIndexError andValueError 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 thebuiltins namespace from a REPL session:

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

In this example, you first import thebuiltinsnamespace. Then, you use the built-indir() 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 asclasses and organized in aclass 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 theException 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 fromException. 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. TheBaseException 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 useException and notBaseException when you create custom exceptions. That’s becauseBaseException 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 aValueError, then you should explicitly handle this exception. If you useException instead ofValueError, then your code will catchException and all its subclasses, includingValueError. If your code ends up raising something different fromValueError, 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 thewarning categories.

Probably the most common warning that you’ll see while executing Python code isDeprecationWarning. This warning appears when you use deprecated features of the language. For example, Python 3.12 hasdeprecated thecalendar.January andcalendar.February constants:

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

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 usecalendar.JANUARY.

SyntaxError

When Python detects an invalid syntax in a piece of code, it raises aSyntaxError exception. The exception prints atraceback with helpful information that you can use todebug 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,34]  File"<stdin>", line1numbers=[1,2,34]^^^SyntaxError:invalid syntax. Perhaps you forgot a comma?>>>7=7  File"<stdin>", line17=7^SyntaxError:cannot assign to literal here.    Maybe you meant '==' instead of '='?>>>class= "Economy"  File"<stdin>", line1class= "Economy"^SyntaxError:invalid syntax

These are common syntax errors that you can fall into at times. The good news is that with theimproved 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 theIndentationError 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:

>>>defgreet(name):...print(f"Hello,{name}!")...print("Welcome to Real Python!")  File"<stdin>", line3print("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 anIndentationError. 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 isTabError, which is a subclass ofIndentationError. So, it’s another syntax error exception.

Here’s an example where Python raises aTabError exception:

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

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

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

$pythongreeting.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 aTabError 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, theModuleNotFoundError exception is a subclass ofImportError with a more specific goal. Python raises this exception when it can’t find the module from which you want to import something:

>>>importnon_existingTraceback (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 aModuleNotFoundError exception. To fix this problem, you must ensure your module is listed insys.path.

BecauseModuleNotFoundError is a subclass ofImportError, when you explicitly use the latter in atry …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 useModuleNotFoundError.

ImportError

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

1. Animport module statement fails to load a module for a reason not covered byModuleNotFoundError.
2. Afrom module import name statement fails to findname in the target module.

Now go ahead and run the followingimport statement to see theImportError exception in action:

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

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

In real-world code, you can take advantage ofImportError orModuleNotFoundError to optionallyload different modules or libraries that provide a given functionality depending on the library availability.

For example, say you need to parse aTOML file and read its content. In this case, you can use the standard-library moduletomllib if you’re using Python3.11 or later. Otherwise, you should use the third-party librarytomli, which is compatible withtomllib.

Here’s how you can do this:

try:importtomllib# Python >= 3.11exceptModuleNotFoundError:importtomliastomllib# Python < 3.11

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

IndexError

TheIndexError 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>", line1, in<module>colors[10]~~~~~~^^^^IndexError:list index out of range

In this example, you use10 as the index to get a value from yourcolors list. Because the list only has seven items, the valid indices go from0 to6. Your target index is out of range, and Python gives you anIndexError 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 atry …except block and take the appropriate recovery action.

You can also raise theIndexError 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-likestack:

classStack:def__init__(self,items=None):self.items=list(items)ifitemsisnotNoneelse[]defpush(self,item):self.items.append(item)defpop(self):returnself.items.pop()def__len__(self):returnlen(self.items)def__getitem__(self,index):try:returnself.items[index]exceptIndexError:raiseIndexError(f"your stack only has{len(self)} items!")fromNone

In this example, you defineStack 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-inlen() 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. Thetry …except block catches theIndexError 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 adictionary, then you get aKeyError 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>", line1, in<module>fruits["grape"]~~~~~~^^^^^^^^^KeyError:'grape'

In this example, you try to get thegrape key from thefruits dictionary and get aKeyError 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 aKeyError in your code. This could be helpful when you need to create adictionary-like class and provide a more descriptive error message for your users.

TypeError

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

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

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

In practice, you can catch theTypeError 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:

>>>defsquared(numbers):...try:...iter(numbers)...exceptTypeError:...raiseTypeError(...f"expected an iterable, got '{type(numbers).__name__}'"...)fromNone...return[number**2fornumberinnumbers]...>>>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-initer() function to check the input data. This function raises aTypeError 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 alist comprehension.

ValueError

Similarly, Python raises theValueError 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-infloat() 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 aValueError 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 useValueError 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)},}classRainbowColor:def__init__(self,name="Red"):name=name.title()ifnamenotinCOLORS:raiseValueError(f"{name} is not a valid rainbow color")self.name=namedefas_hex(self):returnCOLORS[self.name]["Hex"]defas_rgb(self):returnCOLORS[self.name]["RGB"]

In this example, you first define aCOLORS constant that holds the rainbow colors and their correspondingHex andRGB representation.

Then, you define theRainbowColor class. In the classinitializer, 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 aValueError 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:

>>>fromrainbowimportRainbowColor>>>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 aValueError. 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 isAttributeError. This exception occurs when the specified object doesn’t define theattribute ormethod that you’re trying to access.

Take, for example, yourRainbowClass 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:

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

BecauseRainbowColor doesn’t define the.as_hsl() method, you get anAttributeError 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 theAttributeError exception by using the built-inhasattr() function:

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

In this example, you usehasattr() to explicitly check if thecolor object has an attribute called"as_hsl".

You can also catch and raise theAttributeError 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 calledEAFP (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 theLBYL (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 onhasattr(), you should write the above example as follows:

>>>try:...color.as_hsl()...exceptAttributeError:...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 anAttributeError, then you perform alternative actions.

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

>>>importsys>>>sys.non_existingTraceback (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 anAttributeError exception. That’s because the objects defined in a module become attributes of that module.

ZeroDivisionError

Python raises theZeroDivisionError 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:

>>>defaverage_grade(grades):...returnsum(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, thelen() function returns0. This return value produces aZeroDivisionError exception when the actual division occurs.

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

>>>defaverage_grade(grades):...try:...returnsum(grades)/len(grades)...exceptZeroDivisionError:...raiseValueError(..."you should pass at least one grade to average_grade()"...)fromNone...>>>average_grade([])Traceback (most recent call last):...ValueError:you should pass at least one grade to average_grade()

In this updated version ofaverage_grade(), you catch theZeroDivisionError that an empty input list generates and raise aValueError with a user-friendly error message.

Finally, theZeroDivisionError exception also occurs when the right-hand operand on amodulo operation is zero:

>>>42%0Traceback (most recent call last):  File"<input>", line1, 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 aZeroDivisionError if the right-hand operand is0.

OverflowError

TheOverflowError 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**1000Traceback (most recent call last):  File"<input>", line1, 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 anOverflowError exception.

RecursionError

A function that calls itself is known as arecursive function. These types of functions are the base of an iteration technique calledrecursion.

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

>>>defrecurse():...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 aRecursionError exception:

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

Python will raise aRecursionError 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 thesys.getrecursionlimit() function to check your current recursion depth:

>>>importsys>>>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 thesys.setrecursionlimit() function.

StopIteration

Python raises aStopIteration exception when you call the built-innext() function on an exhaustediterator. 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>", line1, in<module>next(numbers_iterator)StopIteration

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

Internally, Python uses this exception to terminatefor loops. In other words, when afor loop is iterating over an iterator, the loop stops when it gets theStopIteration exception. Because of this, it’s not common to see this exception in action. Note that Python’sfor loop callsnext() under the hood to perform the iteration.

In practice, you can use theStopIteration exception in your code as part of an implementation of theiterator 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 theStopIteration exception in the.__next__() method.

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

classSquareIterator:def__init__(self,values):self.values=valuesself.index=0def__iter__(self):returnselfdef__next__(self):ifself.index>=len(self.values):raiseStopIterationsquare=self.values[self.index]**2self.index+=1returnsquare

In this class, the initializer takes a list of values as an argument. It also defines a reference index, which starts at0. The.__iter__() method returnsself, 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 aStopIteration 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 afor loop:

>>>fromsquaresimportSquareIterator>>>forvalueinSquareIterator([1,2,3]):...print(value)...149

Your iterator works fine. It generates square values and supports iteration. Note that you don’t see theStopIteration 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-inFileExistsError 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 theFileExistsError and write the following code:

try:withopen("hello.txt",mode="x")asfile:file.write("Hello, World!")exceptFileExistsError:print("The file already exists")

In this example, you use the built-inopen() function to open a file calledhello.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 thishello.py file from your command line:

$pythonhello.py

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

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

$pythonhello.pyThe file already exists

This time, because thehello.txt file already exists, the file-creation code raises aFileExistsError exception, and theexcept clause prints an error message on the screen.

FileNotFoundError

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

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

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

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

>>>try:...withopen("hello.txt",mode="r")asfile:...print(file.read())...exceptFileNotFoundError:...print("The file doesn't exist")...The file doesn't exist

Now, you use atry …except block to handle theFileNotFoundError 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 thePermissionError exception to let you know that you don’t have the required permissions.

For example, say you’re working on aUnix-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:

>>>withopen("/etc/hosts",mode="a")asfile:...print(file.write("##"))...Traceback (most recent call last):  File"<input>", line1, in<module>withopen("/etc/hosts",mode="a")asfile:^^^^^^^^^^^^^^^^^^^^^^^^^^^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 aPermissionError exception.

SystemExit

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

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

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

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

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

importsysfrompathlibimportPathif(args_count:=len(sys.argv))>2:print(f"One argument expected, got{args_count-1}")raiseSystemExit(2)elifargs_count<2:print("You must specify the target directory")raiseSystemExit(2)target_dir=Path(sys.argv[1])ifnottarget_dir.is_dir():print("The target directory doesn't exist")raiseSystemExit(1)forentryintarget_dir.iterdir():print(entry.name)

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

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

Theelif 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 aSystemExit exception.

After checking the content ofsys.argv, you create apathlib.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 theSystemExit exception again. This time, the exit status is1 to signal that the app faced an error during its execution. Finally, thefor 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:

$pythonls.pyYou must specify the target directory$echo$?2$pythonls.py/home/etcOne argument expected, got 2$echo$?2$pythonls.py.hello.pybirds.pygrades.pygreeting.pyfizzbuzz.pyls.pymean.pystack.pysquare.pyrainbow.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 theecho command to check the exit code, represented by$?, you’ll see that it’s2. In the second example, you provide two target directories. Again, the app fails with an error message. Theecho command also returns2.

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 runecho, you get an exit status of0, which signals that the app’s execution was successful.

KeyboardInterrupt

TheKeyboardInterupt exception is somewhat different from other exceptions. Python raises this exception when the user intentionally presses theCtrl+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 aninfinite loop. In this situation, you need a quick way to terminate the code’s execution. That’s when theCtrl+C key combination comes in handy.

Consider the following toy loop:

>>>whileTrue:...print("Hello")...HelloHelloHelloHelloHelloHelloHelloHelloTraceback (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 theCtrl+C keys to terminate the code’s execution. As a result, Python will raise aKeyboardInterrupt 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.