Understanding Exceptions and Syntax Errors

Syntax errors occur when the parser detects an incorrect statement. Observe the following example:

>>> print(0 / 0))  File"<stdin>", line1print(0/0))^SyntaxError:unmatched ')'

The arrow indicates where the parser ran into thesyntax error. Additionally, the error message gives you a hint about what went wrong. In this example, there was one bracket too many. Remove it and run your code again:

>>>print(0/0)Traceback (most recent call last):  File"<stdin>", line1, in<module>ZeroDivisionError:division by zero

This time, you ran into anexception error. This type of error occurs whenever syntactically correct Python code results in an error. The last line of the message indicates what type of exception error you ran into.

Instead of just writingexception error, Python details whattype of exception error it encountered. In this case, it was aZeroDivisionError. Python comes withvarious built-in exceptions as well as the possibility to create user-defined exceptions.

Raising an Exception in Python

There are scenarios where you might want to stop your program by raising an exception if a condition occurs. You can do this with theraise keyword:

You can even complement the statement with a custom message. Assume that you’re writing a tiny toy program that expects only numbers up to5. You can raise an error when an unwanted condition occurs:

number=10ifnumber>5:raiseException(f"The number should not exceed 5. ({number=})")print(number)

In this example, you raised anException object and passed it an informative custom message. You built the message using anf-string and aself-documenting expression.

When you runlow.py, you’ll get the following output:

Traceback (most recent call last):  File"./low.py", line3, in<module>raiseException(f"The number should not exceed 5. ({number=})")Exception:The number should not exceed 5. (number=10)

The program comes to a halt and displays the exception to yourterminal orREPL, offering you helpful clues about what went wrong. Note that the final call toprint() never executed, because Python raised the exception before it got to that line of code.

With theraise keyword, you can raise any exception object in Python and stop your program when an unwanted condition occurs.

Debugging During Development Withassert

Before moving on to the most common way of working with exceptions in Python usingthetry …except block, you’ll take a quick look at an exception that’s a bit different than the others.

Python offers a specific exception type that you should only use when debugging your program during development. This exception is theAssertionError. TheAssertionError is special because you shouldn’t ever raise it yourself usingraise.

Instead, you usetheassert keyword to check whether a condition is met and let Python raise theAssertionError if the condition isn’t met.

The idea of an assertion is that your program should only attempt to run if certain conditions are in place. If Python checks your assertion and finds that the condition isTrue, then that is excellent! The program can continue. If the condition turns out to beFalse, then your program raises anAssertionError exception and stops right away:

Revisit your tiny script,low.py, fromthe previous section. Currently, you’re explicitly raising an exception when a certain condition isn’t met:

number=1ifnumber>5:raiseException(f"The number should not exceed 5. ({number=})")print(number)

Assuming that you’ll handle this constraint safely for your production system, you could replace thisconditional statement with an assertion for a quick way to retain this sanity check during development:

number=1assert(number<5),f"The number should not exceed 5. ({number=})"print(number)

If thenumber in your program is below5, then the assertion passes and your script continues with the next line of code. However, if you setnumber to a value higher than5—for example,10—then the outcome of the assertion will beFalse:

number=10assert(number<5),f"The number should not exceed 5. ({number=})"print(number)

In that case, Python raises anAssertionError that includes the message you passed, and ends the program execution:

$pythonlow.pyTraceback (most recent call last):  File "./low.py", line 2, in <module>    assert (number < 5), f"The number should not exceed 5. ({number=})"            ^^^^^^^^^^AssertionError: The number should not exceed 5. (number=10)

In this example, raising anAssertionError exception is the last thing that the program will do. The program will then come to halt and won’t continue. The call toprint() that follows the assertion won’t execute.

Using assertions in this way can be helpful when you’re debugging your program during development because it can be quite a fast and straightforward to add assertions into your code.

However, you shouldn’t rely on assertions for catching crucial run conditions of your program in production. That’s because Python globally disables assertions when you run it in optimized mode using the-O and-OO command line options:

$python-Olow.py10

In this run of your program, you used the-O command line option, which removes allassert statements. Therefore, your script ran all the way to the end and displayed a number that isdreadfully high!

In production, your Python code may run using this optimized mode, which means that assertions aren’t a reliable way to handle runtime errors in production code. They can be quick and useful helpers when your debugging your code, but you should never use assertions to set crucial constraints for your program.

Iflow.py should reliably fail whennumber is above5, then it’s best to stick withraising an exception. However, sometimes you might not want your program to fail when it encounters an exception, so how should you handle those situations?

Handling Exceptions With thetry andexcept Block

In Python, you use thetry andexcept block to catch and handle exceptions. Python executes code following thetry statement as a normal part of the program. The code that follows theexcept statement is the program’s response to any exceptions in the precedingtry clause:

As you saw earlier, when syntactically correct code runs into an error, Python will raise an exception error. This exception error will crash the program if you don’t handle it. In theexcept clause, you can determine how your program should respond to exceptions.

The following function can help you understand thetry andexcept block:

deflinux_interaction():importsysif"linux"notinsys.platform:raiseRuntimeError("Function can only run on Linux systems.")print("Doing Linux things.")

Thelinux_interaction() can only run on a Linux system. Python will raise aRuntimeError exception if you call it on an operating system other then Linux.

You can give the function atry by adding the following code:

# ...try:linux_interaction()except:pass

The way you handled the error here is by handing out apass. If you run this code on a macOS or Windows machine, then you get the following output:

$pythonlinux_interaction.py

You got nothing in response. The good thing here is that your program didn’t crash. But letting an exception that occurred pass silently is bad practice. You should always at least know about andlog if some type of exception occurred when you ran your code.

To this end, you can changepass into something that generates an informative message:

# ...try:linux_interaction()except:print("Linux function wasn't executed.")

When you now execute this code on a macOS or Windows machine, you’ll see the message from yourexcept block printed to the console:

$pythonlinux_interaction.pyLinux function wasn't executed.

When an exception occurs in a program that runs this function, then the program will continue as well as inform you about the fact that the function call wasn’t successful.

What you didn’t get to see was the type of error that Python raised as a result of the function call. In order to see exactly what went wrong, you’d need to catch the error that the function raised.

The following code is an example where you capture theRuntimeError and output that message to your screen:

# ...try:linux_interaction()exceptRuntimeErroraserror:print(error)print("The linux_interaction() function wasn't executed.")

In theexcept clause, you assign theRuntimeError to the temporary variableerror—often also callederr—so that you can access the exception object in the indented block. In this case, you’re printing the object’s string representation, which corresponds to the error message attached to the object.

Running this function on a macOS or Windows machine outputs the following:

$pythonlinux_interaction.pyFunction can only run on Linux systems.The linux_interaction() function wasn't executed.

The first message is theRuntimeError, informing you that Python can only execute the function on a Linux machine. The second message tells you which function wasn’t executed.

In the example above, you called a function that you wrote yourself. When you executed the function, you caught theRuntimeError exception and printed it to your screen.

Here’s another example where you open a file and use a built-in exception:

try:withopen("file.log")asfile:read_data=file.read()except:print("Couldn't open file.log")

Iffile.log doesn’t exist, then this block of code will output the following:

$pythonopen_file.pyCouldn't open file.log

This is an informative message, and your program will still continue to run. However, yourexcept block will currently catchany exception, whether that’s related to not being able to open the file or not. You could lead yourself onto a confusing path if you see this message even when Python raises a completely unrelated exception.

Therefore, it’s always best to bespecific when you’re handling an exception.

In thePython docs, you can see that there are a couple of built-in exceptions that you could raise in such a situation, for example:

exceptionFileNotFoundError

Raised when a file or directory is requested but doesn’t exist. Corresponds to errno ENOENT. (Source)

You want to handle the situation when Python can’t find the requested file. To catch this type of exception and print it to screen, you could use the following code:

try:withopen("file.log")asfile:read_data=file.read()exceptFileNotFoundErrorasfnf_error:print(fnf_error)

In this case, iffile.log doesn’t exist, then the output will be the following:

$pythonopen_file.py[Errno 2] No such file or directory: 'file.log'

You can have more than one function call in yourtry clause and anticipate catching various exceptions. Something to note here is that the code in thetry clause will stop as soon as it encounters any one exception.

Look at the following code. Here, you first calllinux_interaction() and then try to open a file:

# ...try:linux_interaction()withopen("file.log")asfile:read_data=file.read()exceptFileNotFoundErrorasfnf_error:print(fnf_error)exceptRuntimeErroraserror:print(error)print("Linux linux_interaction() function wasn't executed.")

If you run this code on a macOS or Windows machine, then you’ll see the following:

$pythonlinux_interaction.pyFunction can only run on Linux systems.Linux linux_interaction() function wasn't executed

Inside thetry clause, you ran into an exception immediately and didn’t get to the part where you attempt to openfile.log. Now look at what happens when you run the code on a Linux machine if the file doesn’t exist:

$pythonlinux_interaction.py[Errno 2] No such file or directory: 'file.log'

Note that if you’re handling specific exceptions as you did above, then the order of theexcept clauses doesn’t matter too much. It’s all about which of the exceptions Python raises first. As soon as Python raises an exception, it checks the except clauses from top to bottom and executes the first matching one that it finds.

Here are the key takeaways about using Python’stry …except statements:

• Python executes atry clause up until the point where it encounters the first exception.
• Inside theexcept clause—the exception handler—you determine how the program responds to the exception.
• You can anticipatemultiple exceptions and differentiate how the program should respond to them.
• Avoid using bareexcept clauses, because they can hide unexpected exceptions.

While usingtry together withexcept is probably the most common error handling that you’ll encounter, there’s more that you can do to fine-tune your program’s response to exceptions.

Proceeding After a Successful Try Withelse

You can use Python’selse statement to instruct a program to execute a certain block of code only in the absence of exceptions:

Look at the following example:

# ...try:linux_interaction()exceptRuntimeErroraserror:print(error)else:print("Doing even more Linux things.")

If you were to run this code on a Linux system, then the output would be the following:

$pythonlinux_interaction.pyDoing Linux things.Doing even more Linux things.

Because the program didn’t run intoany exceptions, Python executed the code in theelse clause. However, if you run this code on a macOS or Windows system, then you get a different output:

$pythonlinux_interaction.pyFunction can only run on Linux systems.

Thelinux_interaction() function raised aRuntimeError. You’ve handled the exception, so your program doesn’t crash, and instead prints the exception message to the console. The code nested under theelse clause, however, doesn’t execute, because Python encountered an exception during execution.

Note that structuring your code like this is different from just adding the call toprint() outside of the context of thetry …except block:

# ...try:linux_interaction()exceptRuntimeErroraserror:print(error)print("Doing even more Linux things.")

If you don’t nest theprint() call under theelse clause, then it’ll execute even if Python encounters theRuntimeError that you handle in theexcept block above. On a Linux system, the output would be the same, but on macOS or Windows, you’d get the following output:

$pythonlinux_interaction.pyFunction can only run on Linux systems.Doing even more Linux things.

Nesting code under theelse clause assures that it’ll only run when Python doesn’t encounter any exception when executing thetry …except block.

You can also create a nestedtry …except block inside theelse clause and catch possible exceptions there as well:

# ...try:linux_interaction()exceptRuntimeErroraserror:print(error)else:try:withopen("file.log")asfile:read_data=file.read()exceptFileNotFoundErrorasfnf_error:print(fnf_error)

If you were to execute this code on a Linux machine, then you’d get the following result:

$pythonlinux_interaction.pyDoing Linux things.[Errno 2] No such file or directory: 'file.log'

From the output, you can see thatlinux_interaction() ran. Because Python encountered no exceptions, it attempted to openfile.log. That file didn’t exist, but instead of letting the program crash, you caught theFileNotFoundError exception and printed a message to the console.

Cleaning Up After Execution Withfinally

Imagine that you always had to implement some sort of action to clean up after executing your code. Python enables you to do so using thefinally clause:

Have a look at the following example:

# ...try:linux_interaction()exceptRuntimeErroraserror:print(error)else:try:withopen("file.log")asfile:read_data=file.read()exceptFileNotFoundErrorasfnf_error:print(fnf_error)finally:print("Cleaning up, irrespective of any exceptions.")

In this code, Python will execute everything in thefinally clause. It doesn’t matter if you encounter an exception somewhere in any of thetry …except blocks. Running the code on a macOS or Windows machine will output the following:

$pythonlinux_interaction.pyFunction can only run on Linux systems.Cleaning up, irrespective of any exceptions.

Note that the code inside thefinally block will execute regardless of whether or not you’re handling the exceptions:

# ...try:linux_interaction()finally:print("Cleaning up, irrespective of any exceptions.")

You simplified the example code from above, butlinux_interaction() still raises an exception on a macOS or Windows system. If you now run this code on an operating system other than Linux, then you’ll get the following output:

$pythonlinux_interaction.pyCleaning up, irrespective of any exceptions.Traceback (most recent call last):  ...RuntimeError: Function can only run on Linux systems.

Despite the fact that Python raised theRuntimeError, the code in thefinally clause still executed and printed the message to your console.

This can be helpful because even code outside of atry…except block won’t necessarily execute if your script encounters an unhandled exception. In that case, your program will terminate and the codeafter thetry …except block will never run. However, Python will still execute the code inside of thefinally clause. This helps you make sure that resources likefile handles anddatabase connections are cleaned up properly.

Creating Custom Exceptions in Python

With the large number of built-in exceptions that Python offers, you’ll likely find a fitting type when deciding which exception to raise. However, sometimes your code won’t fit the mold.

Python makes it straightforward to create custom exception types by inheriting from a built-in exception. Think back to yourlinux_interaction() function:

deflinux_interaction():importsysif"linux"notinsys.platform:raiseRuntimeError("Function can only run on Linux systems.")print("Doing Linux things.")# ...

Using aRuntimeError isn’t a bad choice in this situation, but it would be nice if your exception name was a bit more specific. For this, you can create a custom exception:

classPlatformException(Exception):"""Incompatible platform."""# ...

You generally create a custom exception in Python by inheriting fromException, which is the base class for most built-in Python exceptions as well. You could also inherit from a different exception, but choosingException is usually the best choice.

That’s really all that you need to do. In the code snippet above, you also added adocstring that describes the exception type and serves as the class body.

While you can customize your exception object, you don’t need to do that. It’s often enough to give your custom Python exceptions a descriptive name, so you’ll know what happened when Python raises this exception in your code.

Now that you’ve defined the custom exception, you can raise it like any other Python exception:

classPlatformException(Exception):"""Incompatible platform."""deflinux_interaction():importsysif"linux"notinsys.platform:raisePlatformException("Function can only run on Linux systems.")print("Doing Linux things.")# ...

If you now calllinux_interaction() on macOS or Windows, then you’ll see that Python raises your custom exception:

$pythonlinux_interaction.pyTraceback (most recent call last):  ...PlatformException: Function can only run on Linux systems.

You could even use your customPlatformException as a parent class for other custom exceptions that you could descriptively name for each of the platforms that users may run your code on.

Conclusion

At this point, you’re familiar with the basics of using Python exceptions. After seeing the difference between syntax errors and exceptions, you learned about various ways to raise, catch, and handle exceptions in Python. You also learned how you can create your own custom exceptions.

In this article, you gained experience working with the following exception-related keywords:

• raise allows you to raise an exception at any time.
• assert enables you to verify if a certain condition is met and raises an exception if it isn’t.
• In thetry clause, all statements are executed until an exception is encountered.
• except allows you to catch and handle the exception or exceptions that Python encountered in thetry clause.
• else lets you code sections that should run only when Python encounters no exceptions in thetry clause.
• finally enables you to execute sections of code that should always run, whether or not Python encountered any exceptions.

You now understand the basic tools that Python offers for dealing with exceptions. If you’re curious about the topic and want to dive deeper, then take a look at the following tutorials:

• Python’s Built-in Exceptions: A Walkthrough With Examples
• Exception Groups andexcept*
• Pythonraise: Effectively Raising Exceptions in Your Code
• How to Catch Multiple Exception in Python
• Understanding the Python Traceback
• LBYL vs EAFP: Preventing or Handling Errors in Python

What’s your favorite aspect of exception handling in Python? Share your thoughts in the comments below.

Frequently Asked Questions

Now that you have some experience with Python exceptions, you can use the questions and answers below to check your understanding and recap what you’ve learned.

These FAQs are related to the most important concepts you’ve covered in this tutorial. Click theShow/Hide toggle beside each question to reveal the answer.

Take the Quiz: Test your knowledge with our interactive “Python Exceptions: An Introduction” quiz. You’ll receive a score upon completion to help you track your learning progress:

---

Interactive Quiz

Python Exceptions: An Introduction

In this quiz, you'll test your understanding of Python exceptions. You'll cover the difference between syntax errors and exceptions and learn how to raise exceptions, make assertions, and use the try and except block.