Python Assert Statement: Learn It in 7 Steps
The Python assert statement is one of the tools that as a Python developer is available to you to make your programs more robust.
What is the Python assert statement?
The assert statement allows to verify that the state of a Python program is the one expected by a developer. Expressions verified by assert should always be true unless there is an unexpected bug…
Written by Claudio Sabato
I’m a Software Engineer and Programming Coach. I want to help you in your journey to become a Super Developer!
Python's assert: Debug and Test Your Code Like a Pro
Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: Using Python's assert to Debug and Test Your Code
Python’s assert statement allows you to write sanity checks in your code. These checks are known as assertions, and you can use them to test if certain assumptions remain true while you’re developing your code. If any of your assertions turn false, then you have a bug in your code.
Assertions are a convenient tool for documenting, debugging, and testing code during development. Once you’ve debugged and tested your code with the help of assertions, then you can turn them off to optimize the code for production. Assertions will help you make your code more efficient, robust, and reliable.
In this tutorial, you’ll learn:
- What assertions are and when to use them
- How Python’s assert statement works
- How assert can help you document, debug, and test your code
- How assertions can be disabled to improve performance in production
- What common pitfalls you might face when using assert statements
To get the most out of this tutorial, you should have previous knowledge of expressions and operators, functions, conditional statements, and exceptions. Having a basic understanding of documenting, debugging, and testing Python code is also a plus.
Free Download: Get a sample chapter from Python Tricks: The Book that shows you Python’s best practices with simple examples you can apply instantly to write more beautiful + Pythonic code.
Getting to Know Assertions in Python
Python implements a feature called assertions that’s pretty useful during the development of your applications and projects. You’ll find this feature in several other languages too, such as C and Java, and it comes in handy for documenting, debugging, and testing your code.
If you’re looking for a tool to strengthen your debugging and testing process, then assertions are for you. In this section, you’ll learn the basics of assertions, including what they are, what they’re good for, and when you shouldn’t use them in your code.
What Are Assertions?
In Python, assertions are statements that you can use to set sanity checks during the development process. Assertions allow you to test the correctness of your code by checking if some specific conditions remain true, which can come in handy while you’re debugging code.
The assertion condition should always be true unless you have a bug in your program. If the condition turns out to be false, then the assertion raises an exception and terminates the execution of your program.
With assertions, you can set checks to make sure that invariants within your code stay invariant. By doing so, you can check assumptions like preconditions and postconditions. For example, you can test conditions along the lines of This argument is not None or This return value is a string. These kinds of checks can help you catch errors as soon as possible when you’re developing a program.
What Are Assertions Good For?
Assertions are mainly for debugging. They’ll help you ensure that you don’t introduce new bugs while adding features and fixing other bugs in your code. However, they can have other interesting use cases within your development process. These use cases include documenting and testing your code.
The primary role of assertions is to trigger the alarms when a bug appears in a program. In this context, assertions mean Make sure that this condition remains true. Otherwise, throw an error.
In practice, you can use assertions to check preconditions and postconditions in your programs at development time. For example, programmers often place assertions at the beginning of functions to check if the input is valid (preconditions). Programmers also place assertions before functions’ return values to check if the output is valid (postconditions).
Assertions make it clear that you want to check if a given condition is and remains true. In Python, they can also include an optional message to unambiguously describe the error or problem at hand. That’s why they’re also an efficient tool for documenting code. In this context, their main advantage is their ability to take concrete action instead of being passive, as comments and docstrings are.
Finally, assertions are also ideal for writing test cases in your code. You can write concise and to-the-point test cases because assertions provide a quick way to check if a given condition is met or not, which defines if the test passes or not.
You’ll learn more about these common use cases of assertions later in this tutorial. Now you’ll learn the basics of when you shouldn’t use assertions.
When Not to Use Assertions?
In general, you shouldn’t use assertions for data processing or data validation, because you can disable assertions in your production code, which ends up removing all your assertion-based processing and validation code. Using assertions for data processing and validation is a common pitfall, as you’ll learn in Understanding Common Pitfalls of assert later in this tutorial.
Additionally, assertions aren’t an error-handling tool. The ultimate purpose of assertions isn’t to handle errors in production but to notify you during development so that you can fix them. In this regard, you shouldn’t write code that catches assertion errors using a regular try … except statement.
Understanding Python’s assert Statements
Now you know what assertions are, what they’re good for, and when you shouldn’t use them in your code. It’s time to learn the basics of writing your own assertions. First, note that Python implements assertions as a statement with the assert keyword rather than as a function. This behavior can be a common source of confusion and issues, as you’ll learn later in this tutorial.
In this section, you’ll learn the basics of using the assert statement to introduce assertions in your code. You’ll study the syntax of the assert statement. Most importantly, you’ll understand how this statement works in Python. Finally, you’ll also learn the basics of the AssertionError exception.
The Syntax of the assert Statement
An assert statement consists of the assert keyword, the expression or condition to test, and an optional message. The condition is supposed to always be true. If the assertion condition is true, then nothing happens, and your program continues its normal execution. On the other hand, if the condition becomes false, then assert halts the program by raising an AssertionError .
In Python, assert is a simple statement with the following syntax:
Here, expression can be any valid Python expression or object, which is then tested for truthiness. If expression is false, then the statement throws an AssertionError . The assertion_message parameter is optional but encouraged. It can hold a string describing the issue that the statement is supposed to catch.
Here’s how this statement works in practice:
With a truthy expression, the assertion succeeds, and nothing happens. In that case, your program continues its normal execution. In contrast, a falsy expression makes the assertion fail, raising an AssertionError and breaking the program’s execution.
To make your assert statements clear to other developers, you should add a descriptive assertion message:
The message in this assertion clearly states which condition should be true and what is making that condition fail. Note that the assertion_message argument to assert is optional. However, it can help you better understand the condition under test and figure out the problem that you’re facing.
So, whenever you use assert , it’s a good idea to use a descriptive assertion message for the traceback of the AssertionError exception.
An important point regarding the assert syntax is that this statement doesn’t require a pair of parentheses to group the expression and the optional message. In Python, assert is a statement instead of a function. Using a pair of parentheses can lead to unexpected behaviors.
For example, an assertion like the following will raise a SyntaxWarning :
This warning has to do with non-empty tuples always being truthy in Python. In this example, the parentheses turn the assertion expression and message into a two-item tuple, which always evaluates to true.
Fortunately, recent versions of Python throw a SyntaxWarning to alert you of this misleading syntax. However, in older versions of the language, an assert statement like the one above will always succeed.
This issue often appears when you’re using long expressions or messages that take more than a single line. In these cases, the parentheses are the natural way to format the code, and you may end up with something like the following:
Using a pair of parentheses to split a long line into multiple lines is a common formatting practice in Python code. However, in the context of an assert statement, the parentheses turn the assertion expression and message into a two-item tuple.
In practice, if you want to split a long assertion into several lines, then you can use the backslash character ( \ ) for explicit line joining:
The backslash at the end of first line of this assertion joins the assertion’s two physical lines into a single logical line. This way, you can have appropriate line length without the risk of a warning or a logical error in your code.
Note: PEP 679 was created on January 7, 2022, and is proposing to allow parentheses around the assertion expression and message. If the PEP gets approved and implemented, then the issue of accidental tuples won’t affect Python code in the future.
There’s an edge case of this parentheses-related issue. If you provide only the assertion expression in parentheses, then assert will work just fine:
Why is this happening? To create a single-item tuple, you need to place a comma after the item itself. In the code above, the parentheses by themselves don’t create a tuple. That’s why the interpreter ignores the parentheses, and assert works as expected.
Even though the parentheses seem to work in the scenario described in the above example, it’s not a recommended practice. You can end up shooting yourself in the foot.
The AssertionError Exception
If the condition of an assert statement evaluates to false, then assert raises an AssertionError . If you provide the optional assertion message, then this message is internally used as an argument to the AssertionError class. Either way, the raised exception breaks your program’s execution.
Most of the time, you won’t raise AssertionError exceptions explicitly in your code. The assert statement takes care of raising this exception when the assertion condition fails. Additionally, you shouldn’t attempt to handle errors by writing code that catches the AssertionError exception, as you’ll learn later in this tutorial.
Finally, AssertionError is a built-in exception that inherits from the Exception class and is considered a concrete exception that should be raised instead of subclassed.
That’s it! Now you know the basics of the assert statement. You’ve learned the statement’s syntax, how assert works in practice, and also what the main characteristics of the AssertionError exception are. It’s time to move forward and explore some effective and common ways to write assertions in Python.
Exploring Common Assertion Formats
When it comes to writing the assert statement, you’ll find several assertion formats that are common in Python code. Being aware of these formats will allow you to write better assertions.
The following examples showcase a few of these common assertion formats, starting with assertions that compare objects:
Comparison assertions are intended to test conditions that compare two or more objects using comparison operators. These assertions can also include compound expressions based on Boolean operators.
Another common assertion format is related to membership tests:
Membership assertions allow you to check if a given item is present in a specific collection, such as a list, tuple, set, dictionary, or the like. These assertions use the membership operators, in and not in , to perform the required check.
The assertion format in the example below is related to an object’s identity:
Identity assertions provide a way to test for an object’s identity. In this case, the assertion expression uses the identity operators, is and is not .
Finally, you’ll learn how to check the data type of your objects in the context of an assertion:
Type check assertions commonly involve using the built-in isinstance() function to make sure that a given object is an instance of a certain class or classes.
Even though these are some of the most common assertion formats that you’ll find in Python code, there are many other possibilities. For example, you can use the built-in all() and any() functions to write assertions that check for the truth value of items in an iterable:
The all() assertions check if all the items in an input iterable are truthy, while the any() examples check if any item in the input iterable is truthy.
Your imagination is the only limit for writing useful assertions. You can write assertions using predicate or Boolean-valued functions, regular Python objects, comparison expressions, Boolean expressions, or general Python expressions. Your assertion will depend on what specific condition you need to check at a given moment.
Now you know some of the most common assertion formats that you can use in your code. It’s time to learn about specific use cases of assertions. In the following section, you’ll learn how to use assertions to document, debug, and test your code.
Documenting Your Code With Assertions
The assert statement is an effective way to document code. For example, if you want to state that a specific condition should always be true in your code, then assert condition can be better and more effective than a comment or a docstring, as you’ll learn in a moment.
To understand why assertions can be a handy documenting tool, say that you have a function that takes a server name and a tuple of port numbers. The function will iterate over the port numbers trying to connect to the target server. For your function to work correctly, the tuple of ports shouldn’t be empty:
If someone accidentally calls get_response() with an empty tuple, then the for loop will never run, and the function will return None even if the server is available. To alert programmers to this buggy call, you can use a comment, like you did in the example above. However, using an assert statement can be more effective:
The advantage of an assert statement over a comment is that when the condition isn’t true, assert immediately raises an AssertionError . After that, your code stops running, so it avoids abnormal behaviors and points you directly to the specific problem.
So, using assertions in situations like the one described above is an effective and powerful way to document your intentions and avoid hard-to-find bugs due to accidental errors or malicious actors.
Debugging Your Code With Assertions
At its core, the assert statement is a debugging aid for testing conditions that should remain true during your code’s normal execution. For assertions to work as a debugging tool, you should write them so that a failure indicates a bug in your code.
In this section, you’ll learn how to use the assert statement to assist you while debugging your code at development time.
An Example of Debugging With Assertions
You’ll typically use assertions to debug your code during development. The idea is to make sure that specific conditions are and remain true. If an asserted condition becomes false, then you immediately know that you have a bug.
As an example, say that you have the following Circle class:
The class’s initializer, .__init__() , takes radius as an argument and makes sure that the input value is a positive number. This check prevents circles with a negative radius.
The .area() method computes the circle’s area. However, before doing that, the method uses an assert statement to guarantee that .radius remains a positive number. Why would you add this check? Well, suppose that you’re working on a team, and one of your coworkers needs to add the following method to Circle :
This method takes a correction coefficient and applies it to the current value of .radius . However, the method doesn’t validate the coefficient, introducing a subtle bug. Can you spot it? Say that the user provides a negative correction coefficient by accident:
The first call to .area() works correctly because the initial radius is positive. But the second call to .area() breaks your code with an AssertionError . Why? This happens because the call to .correct_radius() turns the radius into a negative number, which uncovers a bug: the function doesn’t properly check for valid input.
In this example, your assert statement works as a watchdog for situations in which the radius could take invalid values. The AssertionError immediately points you to the specific problem: .radius has unexpectedly changed to a negative number. You have to figure out how this unexpected change happened and then fix your code before it goes into production.
A Few Considerations on Debugging With Assertions
Developers often use assert statements to state preconditions, just like you did in the above example, where .area() checks for a valid .radius right before doing any computation. Developers also use assertions to state postconditions. For example, you can check if a function’s return value is valid, right before returning the value to the caller.
In general, the conditions that you check with an assert statement should be true, unless you or another developer in your team introduces a bug in the code. In other words, these conditions should never be false. Their purpose is to quickly flag if someone introduces a bug. In this regard, assertions are early alerts in your code. These alerts are meant to be useful during development.
If one of these conditions fails, then the program will crash with an AssertionError , telling you exactly which condition isn’t succeeding. This behavior will help you track down and fix bugs more quickly.
To properly use assertions as a debugging tool, you shouldn’t use try … except blocks that catch and handle AssertionError exceptions. If an assertion fails, then your program should crash because a condition that was supposed to be true became false. You shouldn’t change this intended behavior by catching the exception with a try … except block.
A proper use of assertions is to inform developers about unrecoverable errors in a program. Assertions shouldn’t signal an expected error, like a FileNotFoundError , where a user can take a corrective action and try again.
The goal of assertion should be to uncover programmers’ errors rather than users’ errors. Assertions are useful during the development process, not during production. By the time you release your code, it should be (mostly) free of bugs and shouldn’t require the assertions to work correctly.
Finally, once your code is ready for production, you don’t have to explicitly remove assertions. You can just disable them, as you’ll learn in the following section.
Disabling Assertions in Production for Performance
Now say that you’ve come to the end of your development cycle. Your code has been extensively reviewed and tested. All your assertions pass, and your code is ready for a new release. At this point, you can optimize the code for production by disabling the assertions that you added during development. Why should you optimize your code this way?
Assertions are great during development, but in production, they can affect the code’s performance. For example, a codebase with many assertions running all the time can be slower than the same code without assertions. Assertions take time to run, and they consume memory, so it’s advisable to disable them in production.
Now, how can you actually disable your assertions? Well, you have two options:
- Run Python with the -O or -OO options.
- Set the PYTHONOPTIMIZE environment variable to an appropriate value.
In this section, you’ll learn how to disable your assertions by using these two techniques. Before doing this, you’ll get to know the built-in __debug__ constant, which is the internal mechanism that Python uses to disable assertions.
Understanding the __debug__ Built-in Constant
Python has a built-in constant called __debug__ . This constant is closely related to the assert statement. Python’s __debug__ is a Boolean constant, which defaults to True . It’s a constant because you can’t change its value once your Python interpreter is running:
In this code snippet, you first confirm that __debug__ is a Python built-in that’s always available for you. True is the default value of __debug__ , and there’s no way to change this value once your Python interpreter is running.
The value of __debug__ depends on which mode Python runs in, normal or optimized:
| Mode | Value of __debug__ |
|---|---|
| Normal (or debug) | True |
| Optimized | False |
Normal mode is typically the mode that you use during development, while optimized mode is what you should use in production. Now, what does __debug__ have to do with assertions? In Python, the assert statement is equivalent to the following conditional:
If __debug__ is true, then the code under the outer if statement runs. The inner if statement checks expression for truthiness and raises an AssertionError only if the expression is not true. This is the default or normal Python mode, in which all your assertions are enabled because __debug__ is True .
On the other hand, if __debug__ is False , then the code under the outer if statement doesn’t run, meaning that your assertions will be disabled. In this case, Python is running in optimized mode.
Normal or debug mode allows you to have assertions in place as you develop and test the code. Once your current development cycle is complete, then you can switch to optimized mode and disable the assertions to get your code ready for production.
To activate optimized mode and disable your assertions, you can either start up the Python interpreter with the –O or -OO option, or set the system variable PYTHONOPTIMIZE to an appropriate value. You’ll learn how to do both operations in the following sections.
Running Python With the -O or -OO Options
You can disable all your assert statements by having the __debug__ constant set to False . To accomplish this task, you can use Python’s -O or -OO command-line options to run the interpreter in optimized mode.
The -O option internally sets __debug__ to False . This change removes the assert statements and any code that you’ve explicitly introduced under a conditional targeting __debug__ . The -OO option does the same as -O and also discards docstrings.
Running Python with the -O or -OO command-line option makes your compiled bytecode smaller. Additionally, if you have several assertions or if __debug__: conditionals, then these command-line options can also make your code faster.
Now, what effect does this optimization have on your assertions? It disables them. For an example, open your command line or terminal within the directory containing the circle.py file and run an interactive session with the python -O command. Once there, run the following code:
Because the -O option disables your assertions by setting __debug__ to False , your Circle class now accepts a negative radius, as the final example showcases. This behavior is completely wrong because you can’t have a circle with a negative radius. Additionaly, the circle’s area is computed using the wrong radius as an input.
The potential to disable assertions in optimized mode is the main reason why you must not use assert statements to validate input data but as an aid to your debugging and testing process.
Note: Assertions are typically turned off in production code to avoid any overhead or side effect that they may cause.
A Pythonic solution for the Circle class would be to turn the .radius attribute into a managed attribute using the @property decorator. This way, you perform the .radius validation every time the attribute changes:
Now .radius is a managed attribute that provides setter and getter methods using the @property decorator. You’ve moved the validation code from .__init__() to the setter method, which is called whenever the class changes the value of .radius .
Now, the updated Circle works as expected if you run the code in optimized mode:
Circle always validates the value of .radius before assignment, and your class works correctly, raising a ValueError for negative values of .radius . That’s it! You’ve fixed the bug with an elegant solution.
An interesting side effect of running Python in optimized mode is that code under an explicit if __debug__: condition is also disabled. Consider the following script:
This script explicitly checks the value of __debug__ in an if … else statement. The code in the if code block will run only if __debug__ is True . In contrast, if __debug__ is False , then the code in the else block will run.
Now try running the script in normal and optimized mode to check its behavior in each mode:
When you execute the script in normal mode, the code under the if __debug__: condition runs because __debug__ is True in this mode. On the other hand, when you execute the script in optimized mode with the -O option, __debug__ changes to False , and the code under the else block runs.
Python’s -O command-line option removes assertions from the resulting compiled bytecode. Python’s -OO option performs the same kind of optimization as -O , with the addition of removing docstrings from your bytecode.
Because both options set __debug__ to False , any code under an explicit if __debug__: conditional also stops working. This behavior provides a powerful mechanism to introduce debugging-only code in your Python projects during their development stages.
Now you know the basics of using Python’s -O and -OO options to disable your assertions in production code. However, running Python with either of these options every time you need to run your production code seems repetitive and may be error-prone. To automate the process, you can use the PYTHONOPTIMIZE environment variable.
Setting the PYTHONOPTIMIZE Environment Variable
You can also run Python in optimized mode with disabled assertions by setting the PYTHONOPTIMIZE environment variable to an appropriate value. For example, setting this variable to a non-empty string is equivalent to running Python with the -O option.
To try PYTHONOPTIMIZE out, fire up your command line and run the following command:
- Windows
- Linux + macOS
Once you’ve set PYTHONOPTIMIZE to a non-empty string, you can launch your Python interpreter with the bare-bones python command. This command will automatically run Python in optimized mode.
Now go ahead and run the following code from the directory containing your circle.py file:
Again, your assertions are off, and the Circle class accepts negative radius values. You’re running Python in optimized mode again.
Another possibility is to set PYTHONOPTIMIZE to an integer value, n , which is equivalent to running Python using the -O option n times. In other words, you’re using n levels of optimization:
- Windows
- Linux + macOS
You can use any integer number to set PYTHONOPTIMIZE . However, Python only implements two levels of optimization. Using a number greater than 2 has no real effect on your compiled bytecode. Additionally, setting PYTHONOPTIMIZE to 0 will cause the interpreter to run in normal mode.
Running Python in Optimized Mode
When you run Python, the interpreter compiles any imported module to bytecode on the fly. The compiled bytecode will live in a directory called __pycache__/ , which is placed in the directory containing the module that provided the imported code.
Inside __pycache__/ , you’ll find a .pyc file named after your original module plus the interpreter’s name and version. The name of the .pyc file will also include the optimization level used to compile the code.
For example, when you import code from circle.py , the Python 3.10 interpreter generates the following files, depending on the optimization level:
| File Name | Command | PYTHONOPTIMIZE |
|---|---|---|
| circle.cpython-310.pyc | python circle.py | 0 |
| circle.cpython-310.opt-1.pyc | python -O circle.py | 1 |
| circle.cpython-310.opt-2.pyc | python -OO circle.py | 2 |
The name of each file in this table includes the original module’s name ( circle ), the interpreter that generated the code ( cpython-310 ), and the optimization level ( opt-x ). The table also summarizes the corresponding commands and values for the PYTHONOPTIMIZE variable. PEP 488 provides more context on this naming format for .pyc files.
The main results of running Python in the first level of optimization is that the interpreter sets __debug__ to False and removes the assertions from the resulting compiled bytecode. These optimizations make the code smaller and potentially faster than the same code running in normal mode.
The second level of optimization does the same as the first level. It also removes all the docstrings from the compiled code, which results in an even smaller compiled bytecode.
Testing Your Code With Assertions
Testing is another field in the development process where assertions are useful. Testing boils down to comparing an observed value with an expected one to check if they’re equal or not. This kind of check perfectly fits into assertions.
Assertions must check for conditions that should typically be true, unless you have a bug in your code. This idea is another important concept behind testing.
The pytest third-party library is a popular testing framework in Python. At its core, you’ll find the assert statement, which you can use to write most of your test cases in pytest .
Here are a few examples of writing test cases using assert statements. The examples below take advantage of some built-in functions, which provide the testing material:
All these test cases use the assert statement. Most of them are written using the assertion formats that you learned before. They all showcase how you’d write real-world test cases to check different pieces of your code with pytest .
Now, why does pytest favor plain assert statements in test cases over a custom API, which is what other testing frameworks prefer? There are a couple of remarkable advantages behind this choice:
- The assert statement allows pytest to lower the entry barrier and somewhat flatten the learning curve because its users can take advantage of Python syntax that they already know.
- The users of pytest don’t need to import anything from the library to start writing test cases. They only need to start importing things if their test cases get complicated, demanding more advanced features.
These advantages make working with pytest a pleasant experience for beginners and people coming from other testing frameworks with custom APIs.
For example, the standard-library unittest module provides an API consisting of a list of .assert*() methods that work pretty much like assert statements. This kind of API can be difficult to learn and memorize for developers starting with the framework.
You can use pytest to run all the test case examples above. First, you need to install the library by issuing the python -m pip install pytest command. Then you can execute pytest test_samples.py from the command-line. This latter command will display an output similar to the following:
The first highlighted line in this output tells you that pytest discovered and ran eight test cases. The second highlighted line shows that seven out of eight tests passed successfully. That’s why you get seven green dots and an F .
Note: To avoid issues with pytest , you must run your Python interpreter in normal mode. Remember that optimized mode disables assertions. So, make sure that you’re not running Python in optimized mode.
You can check the current value of your PYTHOPTIMIZE environment variable by running the following command:
- Windows
- Linux + macOS
If PYTHONOPTIMIZE is set, then this command’s output will display its current value.
A remarkable feature to note is that pytest integrates nicely with the assert statement. The library can display error reports with detailed information about the failing assertions and why they’re failing. As an example, check out the the lines starting with the E letter in the above output. They display error messages.
Those lines clearly uncover the root cause of the failure. In this example, pow(10, 2) returns 100 instead of 42 , which is intentionally wrong. You can use pytest.raises() to handle code that is expected to fail.
Understanding Common Pitfalls of assert
Even though assertions are such a great and useful tool, they have some downsides. Like any other tool, assertions can be misused. You’ve learned that you should use assertions mainly for debugging and testing code during development. In contrast, you shouldn’t rely on assertions to provide functionality in production code, which is one of the main drivers of pitfalls with assertions.
In particular, you may run into pitfalls if you use assertions for:
- Processing and validating data
- Handling errors
- Running operations with side effects
Another common source of issues with assertions is that keeping them enabled in production can negatively impact your code’s performance.
Finally, Python has assertions enabled by default, which can confuse developers coming from other languages. In the following sections, you’ll learn about all these possible pitfalls of assertions. You’ll also learn how to avoid them in your own Python code.
Using assert for Data Processing and Validation
You shouldn’t use assert statements to verify the user’s input or any other input data from external sources. That’s because production code typically disables assertions, which will remove all the verification.
For example, suppose you’re building an online store with Python, and you need to add functionality to accept discount coupons. You end up writing the following function:
Notice the assert statement in the first line of price_with_discount() ? It’s there to guarantee that the discounted price won’t be equal to or lower than zero dollars. The assertion also ensures that the new price won’t be higher than the product’s original price.
Now consider the example of a pair of shoes at twenty-five percent off:
All right, price_with_discount() works nicely! It takes the product as a dictionary, applies the intended discount to the current price, and returns the new price. Now, try to apply some invalid discounts:
Applying an invalid discount raises an AssertionError that points out the violated condition. If you ever encounter this error while developing and testing your online store, then it shouldn’t be hard to figure out what happened by looking at the traceback.
The real problem with the example above comes if the end user can make direct calls to price_with_discount() in production code with disabled assertions. In this situation, the function won’t check the input value for discount , possibly accepting wrong values and breaking the correctness of your discount functionality.
In general, you can write assert statements to process, validate, or verify data during development. However, if those operations remain valid in production code, then make sure to replace them with an if statement or a try … except block.
Here’s a new version of price_with_discount() that uses a conditional instead of an assertion:
In this new implementation of price_with_discount() , you replace the assert statement with an explicit conditional statement. The function now applies the discount only if the input value is between 0 and 1 . Otherwise, it raises a ValueError , signaling the problem.
Now you can wrap up any calls to this function in a try … except block that catches the ValueError and sends an informative message to the users so that they can take action accordingly.
The moral of this example is that you shouldn’t rely on the assert statement for data processing or data validation, because this statement is typically turned off in production code.
Handling Errors With assert
Another important pitfall with assertions is that sometimes developers use them as a quick form of error handling. As a result, if the production code removes assertions, then important error checks are also removed from the code. So, keep in mind that assertions aren’t a replacement for good error handling.
Here’s an example of using assertions for error handling:
If you execute this code in production with disabled assertions, then square() will never run the assert statement and raise an AssertionError . In this situation, the try … except block is superfluous and nonfunctional.
What can you do to fix this example? Try updating square() to use an if statement and a ValueError :
Now square() deals with the condition by using an explicit if statement that can’t be disabled in production code. Your try … except block now handles a ValueError , which is a more appropriate exception in this example.
Don’t ever catch AssertionError exceptions in your code, because that would silence failing assertions, which is a clear sign of misused assertions. Instead, catch concrete exceptions that are clearly related to the errors that you’re handling and let your assertions fail.
Use assertions only to check errors that shouldn’t happen during the normal execution of your programs unless you have a bug. Remember that assertions can be disabled.
Running assert on Expressions With Side Effects
Another subtle pitfall with the assert statement appears when you use this statement to check operations, functions, or expressions that have some kind of side effect. In other words, these operations modify the state of objects outside the operation’s scope.
In those situations, the side effect takes place every time your code runs the assertion, which might silently change your program’s global state and behavior.
Consider the following toy example, in which a function modifies the value of a global variable as a side effect:
In this example, popped() returns item at a given index in the input sample of data, with the side effect of also removing said item .
Using assertions to make sure that your function is returning the correct item can seem appropriate. However, this will cause the function’s internal side effect to run in every assertion, modifying the original content of sample .
To prevent unexpected behaviors like the one in the above example, use assertion expressions that don’t cause side effects. For example, you can use pure functions that just take input arguments and return the corresponding output without modifying the state of objects from other scopes and namespaces.
Impacting Performance With assert
Too many assertions in production can impact your code’s performance. This issue becomes critical when the asserted conditions involve too much logic, such as long compound conditions, long-running predicate functions, and classes implying a costly instantiation process.
Assertions can impact your code’s performance in two main ways. They will:
- Take time to execute
- Use extra memory
An assert statement that checks for a None value can be relatively inexpensive. However, more complex assertions, especially those running heavy code, can measurably slow down your code. Assertions also consume memory to store their own code and any required data.
To avoid performance issues in production code, you should use Python’s -O or -OO command-line options or set the PYTHONOPTIMIZE environment variable according to your needs. Either strategy will optimize your code by generating an assertions-free compiled bytecode, which will run more quickly and take up less memory.
Additionally, to prevent performance issues during development, your assertions should be fairly slim and to the point.
Having assert Statements Enabled by Default
In Python, assertions are enabled by default. When the interpreter runs in normal mode, the __debug__ variable is True , and your assertions are enabled. This behavior makes sense because you typically develop, debug, and test your code in normal mode.
If you want to disable your assertions, then you need to do it explicitly. You can either run the Python interpreter with the -o or -OO options, or set the PYTHONOPTIMIZE environment variable to a proper value.
In contrast, other programming languages have assertions disabled by default. For example, if you’re coming into Python from Java, you may assume that your assertions won’t run unless you explicitly turn them on. This assumption can be a common source of confusion for Python beginners, so keep it in mind.
Conclusion
Now you know how to use Python’s assert statement to set sanity checks throughout your code and make sure that certain conditions are and remain true. When any of these conditions fail, you have a clear indication of what’s happening. This way, you can quickly debug and fix your code.
The assert statement is pretty handy when you need to document, debug, and test your code during the development stages. In this tutorial, you learned how to use assertions in your code and how they can make your debugging and testing process more efficient and straightforward.
In this tutorial, you learned:
- What assertions are and when to use them
- How Python’s assert statement works
- How assert is handy for documenting, debugging, and testing code
- How assertions can be disabled to improve performance in production
- What common pitfalls you can face when using assert statements
With this knowledge on the assert statement, you can now write robust, reliable, and less buggy code, which can take you to the next level as a developer.
Free Download: Get a sample chapter from Python Tricks: The Book that shows you Python’s best practices with simple examples you can apply instantly to write more beautiful + Pythonic code.
Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: Using Python's assert to Debug and Test Your Code
Get a short & sweet Python Trick delivered to your inbox every couple of days. No spam ever. Unsubscribe any time. Curated by the Real Python team.
About Leodanis Pozo Ramos
Leodanis is an industrial engineer who loves Python and software development. He's a self-taught Python developer with 6+ years of experience. He's an avid technical writer with a growing number of articles published on Real Python and other sites.
Each tutorial at Real Python is created by a team of developers so that it meets our high quality standards. The team members who worked on this tutorial are:
Master Real-World Python Skills With Unlimited Access to Real Python
Join us and get access to thousands of tutorials, hands-on video courses, and a community of expert Pythonistas:
Master Real-World Python Skills
With Unlimited Access to Real Python
Join us and get access to thousands of tutorials, hands-on video courses, and a community of expert Pythonistas:
What Do You Think?
What’s your #1 takeaway or favorite thing you learned? How are you going to put your newfound skills to use? Leave a comment below and let us know.
Commenting Tips: The most useful comments are those written with the goal of learning from or helping out other students. Get tips for asking good questions and get answers to common questions in our support portal. Looking for a real-time conversation? Visit the Real Python Community Chat or join the next “Office Hours” Live Q&A Session. Happy Pythoning!
Assertionerror Python
An Assertion is a programming concept that helps us to test an expression. If the expression returns true, the control of the program is moved to the next line. But if the expression returns false, an AssertionError is generated by Python. AssertionError Python can be avoided by using the -O flag , using the environment variable to set a flag, or by making sure that the flow of the program doesn't reach the assert statement. AssertionError Python is useful to check the output of a function, to check whether the input is valid or not, or to test a program.
What is Assertionerror in Python?
Before learning about AssertionError Python, let's have a brief of what is an assert statement. The assert statement is used when we want to debug the code. Consider a case where we want the expression 'x' to be always true. But can we check if 'x' is always true or not? Here comes the assert statement. An assert statement returns the AssertionError if the expression is false. Hence it halts the execution of the program.
Explanation
From the above image, we can see that if the assertion condition is false, the program is halted and AssertionError Python is returned.
Syntax
The assert statement in Python also provides us the option to add an error message in case the AssertionError Python is returned. Let's see the syntax for both cases.
Without Error Message
With Error Message
Examples
Let's have an example of the division of two numbers. When we divide a number x by another y, we know that y can not be equal to 0. Hence we have to make sure that y!=0 . Here our expression will be y!=0 if it returns true we must stop the execution of the program. Let's use the assert statement to implement the same.
Output:
Now let's set y as 0 and check the program's output.
Output:
See the assert statement returned the AssertionError Python as y was equal to 0.
Now let's add the error-message to the assert statement and then check the program's output.
Output:
Here we can see that the error-message is printed stating that we "Cannot divide by 0".
How does Assertionerror in Python Work?
The Python programming language has an assert statement that allows us to generate basic debug message outputs based on logical assertions. An AssertionError Python is returned when the assertion expression is false. In Python BaseException class is the base of all the exception classes. AssertionError's base class is the Exception class which inherits from the BaseException class. When an assert statement is used in the code, we have to make sure to add the exception handling code as well. If the error-message is provided in the code, the error-message is printed else the error is handled without the error-message.
Steps to Avoid Assertionerror in Python
- The -O flag can be used to disable all assert statements in the program. By disabling the assert statements in the program, we can avoid the AssertionError exception in Python.
Example: If we try to run python -c "assert False" in the terminal, the output states that there's an assertion error as the expression is false. But we can use the -O to disable the assert statement as, The output of the above code in the terminal will be empty. As the assert statement was disabled by the -O flag. - We can also use the environment variable to set a flag that disables the assert statements. But note, that all the processes that inherit or use this environment will be impacted if this is used.
Example: In the cmd we can use SET PYTHONOPTIMIZE=TRUE to disable the assert statement and this will affect all the processes that use or inherit the environment. Later we can enable asserts using SET PYTHONOPTIMIZE= . - Another way to avoid AssertionError Python is to make sure that the flow of the program doesn't reach the assert statement or after catching the AssertionError Python the normal flow of the program should resume. For example. using try-except block in Python.
Handling Python Assertionerror
Consider the example we used in the beginning of the article where we are dividing two numbers. We will add a try-except block to that code and let's see the output.
Output:
Can you guess why the output is empty?
This is because the except block is printing the error-message but we have not provided any error-message to the assert statement. Let's add the error-message and check the output.
Output:
Practical Applications of Python Assertion Error
- Checking values of parameters
We can check whether the provided parameters are valid or not. Just like the example we saw in the beginning of the article. - Checking valid input/type
We can also check whether the user has passed the correct data type or not. Consider the case where we are dividing two numbers and the user passes string instead of numbers. This can be caught using the assert statement. - We can also detect whether an interface is being misused by another programmer or not.
Assertionerror Python Example
Let's have an example to calculate average marks of a student,
Output:
You can see in the above program even after getting an AssertionError Python on line 10, the normal flow of the program resumes.
Built-in Exceptions¶
In Python, all exceptions must be instances of a class that derives from BaseException . In a try statement with an except clause that mentions a particular class, that clause also handles any exception classes derived from that class (but not exception classes from which it is derived). Two exception classes that are not related via subclassing are never equivalent, even if they have the same name.
The built-in exceptions listed below can be generated by the interpreter or built-in functions. Except where mentioned, they have an “associated value” indicating the detailed cause of the error. This may be a string or a tuple of several items of information (e.g., an error code and a string explaining the code). The associated value is usually passed as arguments to the exception class’s constructor.
User code can raise built-in exceptions. This can be used to test an exception handler or to report an error condition “just like” the situation in which the interpreter raises the same exception; but beware that there is nothing to prevent user code from raising an inappropriate error.
The built-in exception classes can be subclassed to define new exceptions; programmers are encouraged to derive new exceptions from the Exception class or one of its subclasses, and not from BaseException . More information on defining exceptions is available in the Python Tutorial under User-defined Exceptions .
Exception context¶
When raising a new exception while another exception is already being handled, the new exception’s __context__ attribute is automatically set to the handled exception. An exception may be handled when an except or finally clause, or a with statement, is used.
This implicit exception context can be supplemented with an explicit cause by using from with raise :
The expression following from must be an exception or None . It will be set as __cause__ on the raised exception. Setting __cause__ also implicitly sets the __suppress_context__ attribute to True , so that using raise new_exc from None effectively replaces the old exception with the new one for display purposes (e.g. converting KeyError to AttributeError ), while leaving the old exception available in __context__ for introspection when debugging.
The default traceback display code shows these chained exceptions in addition to the traceback for the exception itself. An explicitly chained exception in __cause__ is always shown when present. An implicitly chained exception in __context__ is shown only if __cause__ is None and __suppress_context__ is false.
In either case, the exception itself is always shown after any chained exceptions so that the final line of the traceback always shows the last exception that was raised.
Inheriting from built-in exceptions¶
User code can create subclasses that inherit from an exception type. It’s recommended to only subclass one exception type at a time to avoid any possible conflicts between how the bases handle the args attribute, as well as due to possible memory layout incompatibilities.
CPython implementation detail: Most built-in exceptions are implemented in C for efficiency, see: Objects/exceptions.c. Some have custom memory layouts which makes it impossible to create a subclass that inherits from multiple exception types. The memory layout of a type is an implementation detail and might change between Python versions, leading to new conflicts in the future. Therefore, it’s recommended to avoid subclassing multiple exception types altogether.
Base classes¶
The following exceptions are used mostly as base classes for other exceptions.
The base class for all built-in exceptions. It is not meant to be directly inherited by user-defined classes (for that, use Exception ). If str() is called on an instance of this class, the representation of the argument(s) to the instance are returned, or the empty string when there were no arguments.
The tuple of arguments given to the exception constructor. Some built-in exceptions (like OSError ) expect a certain number of arguments and assign a special meaning to the elements of this tuple, while others are usually called only with a single string giving an error message.
This method sets tb as the new traceback for the exception and returns the exception object. It was more commonly used before the exception chaining features of PEP 3134 became available. The following example shows how we can convert an instance of SomeException into an instance of OtherException while preserving the traceback. Once raised, the current frame is pushed onto the traceback of the OtherException , as would have happened to the traceback of the original SomeException had we allowed it to propagate to the caller.
Add the string note to the exception’s notes which appear in the standard traceback after the exception string. A TypeError is raised if note is not a string.
New in version 3.11.
A list of the notes of this exception, which were added with add_note() . This attribute is created when add_note() is called.
New in version 3.11.
All built-in, non-system-exiting exceptions are derived from this class. All user-defined exceptions should also be derived from this class.
The base class for those built-in exceptions that are raised for various arithmetic errors: OverflowError , ZeroDivisionError , FloatingPointError .
Raised when a buffer related operation cannot be performed.
The base class for the exceptions that are raised when a key or index used on a mapping or sequence is invalid: IndexError , KeyError . This can be raised directly by codecs.lookup() .
Concrete exceptions¶
The following exceptions are the exceptions that are usually raised.
Raised when an assert statement fails.
Raised when an attribute reference (see Attribute references ) or assignment fails. (When an object does not support attribute references or attribute assignments at all, TypeError is raised.)
The name and obj attributes can be set using keyword-only arguments to the constructor. When set they represent the name of the attribute that was attempted to be accessed and the object that was accessed for said attribute, respectively.
Changed in version 3.10: Added the name and obj attributes.
Raised when the input() function hits an end-of-file condition (EOF) without reading any data. (N.B.: the io.IOBase.read() and io.IOBase.readline() methods return an empty string when they hit EOF.)
Not currently used.
Raised when a generator or coroutine is closed; see generator.close() and coroutine.close() . It directly inherits from BaseException instead of Exception since it is technically not an error.
Raised when the import statement has troubles trying to load a module. Also raised when the “from list” in from . import has a name that cannot be found.
The name and path attributes can be set using keyword-only arguments to the constructor. When set they represent the name of the module that was attempted to be imported and the path to any file which triggered the exception, respectively.
Changed in version 3.3: Added the name and path attributes.
A subclass of ImportError which is raised by import when a module could not be located. It is also raised when None is found in sys.modules .
New in version 3.6.
Raised when a sequence subscript is out of range. (Slice indices are silently truncated to fall in the allowed range; if an index is not an integer, TypeError is raised.)
Raised when a mapping (dictionary) key is not found in the set of existing keys.
Raised when the user hits the interrupt key (normally Control — C or Delete ). During execution, a check for interrupts is made regularly. The exception inherits from BaseException so as to not be accidentally caught by code that catches Exception and thus prevent the interpreter from exiting.
Catching a KeyboardInterrupt requires special consideration. Because it can be raised at unpredictable points, it may, in some circumstances, leave the running program in an inconsistent state. It is generally best to allow KeyboardInterrupt to end the program as quickly as possible or avoid raising it entirely. (See Note on Signal Handlers and Exceptions .)
Raised when an operation runs out of memory but the situation may still be rescued (by deleting some objects). The associated value is a string indicating what kind of (internal) operation ran out of memory. Note that because of the underlying memory management architecture (C’s malloc() function), the interpreter may not always be able to completely recover from this situation; it nevertheless raises an exception so that a stack traceback can be printed, in case a run-away program was the cause.
Raised when a local or global name is not found. This applies only to unqualified names. The associated value is an error message that includes the name that could not be found.
The name attribute can be set using a keyword-only argument to the constructor. When set it represent the name of the variable that was attempted to be accessed.
Changed in version 3.10: Added the name attribute.
This exception is derived from RuntimeError . In user defined base classes, abstract methods should raise this exception when they require derived classes to override the method, or while the class is being developed to indicate that the real implementation still needs to be added.
It should not be used to indicate that an operator or method is not meant to be supported at all – in that case either leave the operator / method undefined or, if a subclass, set it to None .
NotImplementedError and NotImplemented are not interchangeable, even though they have similar names and purposes. See NotImplemented for details on when to use it.
This exception is raised when a system function returns a system-related error, including I/O failures such as “file not found” or “disk full” (not for illegal argument types or other incidental errors).
The second form of the constructor sets the corresponding attributes, described below. The attributes default to None if not specified. For backwards compatibility, if three arguments are passed, the args attribute contains only a 2-tuple of the first two constructor arguments.
The constructor often actually returns a subclass of OSError , as described in OS exceptions below. The particular subclass depends on the final errno value. This behaviour only occurs when constructing OSError directly or via an alias, and is not inherited when subclassing.
A numeric error code from the C variable errno .
Under Windows, this gives you the native Windows error code. The errno attribute is then an approximate translation, in POSIX terms, of that native error code.
Under Windows, if the winerror constructor argument is an integer, the errno attribute is determined from the Windows error code, and the errno argument is ignored. On other platforms, the winerror argument is ignored, and the winerror attribute does not exist.
The corresponding error message, as provided by the operating system. It is formatted by the C functions perror() under POSIX, and FormatMessage() under Windows.
For exceptions that involve a file system path (such as open() or os.unlink() ), filename is the file name passed to the function. For functions that involve two file system paths (such as os.rename() ), filename2 corresponds to the second file name passed to the function.
Changed in version 3.3: EnvironmentError , IOError , WindowsError , socket.error , select.error and mmap.error have been merged into OSError , and the constructor may return a subclass.
Changed in version 3.4: The filename attribute is now the original file name passed to the function, instead of the name encoded to or decoded from the filesystem encoding and error handler . Also, the filename2 constructor argument and attribute was added.
Raised when the result of an arithmetic operation is too large to be represented. This cannot occur for integers (which would rather raise MemoryError than give up). However, for historical reasons, OverflowError is sometimes raised for integers that are outside a required range. Because of the lack of standardization of floating point exception handling in C, most floating point operations are not checked.
This exception is derived from RuntimeError . It is raised when the interpreter detects that the maximum recursion depth (see sys.getrecursionlimit() ) is exceeded.
New in version 3.5: Previously, a plain RuntimeError was raised.
This exception is raised when a weak reference proxy, created by the weakref.proxy() function, is used to access an attribute of the referent after it has been garbage collected. For more information on weak references, see the weakref module.
Raised when an error is detected that doesn’t fall in any of the other categories. The associated value is a string indicating what precisely went wrong.
Raised by built-in function next() and an iterator ‘s __next__() method to signal that there are no further items produced by the iterator.
The exception object has a single attribute value , which is given as an argument when constructing the exception, and defaults to None .
When a generator or coroutine function returns, a new StopIteration instance is raised, and the value returned by the function is used as the value parameter to the constructor of the exception.
If a generator code directly or indirectly raises StopIteration , it is converted into a RuntimeError (retaining the StopIteration as the new exception’s cause).
Changed in version 3.3: Added value attribute and the ability for generator functions to use it to return a value.
Changed in version 3.5: Introduced the RuntimeError transformation via from __future__ import generator_stop , see PEP 479.
Changed in version 3.7: Enable PEP 479 for all code by default: a StopIteration error raised in a generator is transformed into a RuntimeError .
Must be raised by __anext__() method of an asynchronous iterator object to stop the iteration.
New in version 3.5.
Raised when the parser encounters a syntax error. This may occur in an import statement, in a call to the built-in functions compile() , exec() , or eval() , or when reading the initial script or standard input (also interactively).
The str() of the exception instance returns only the error message. Details is a tuple whose members are also available as separate attributes.
The name of the file the syntax error occurred in.
Which line number in the file the error occurred in. This is 1-indexed: the first line in the file has a lineno of 1.
The column in the line where the error occurred. This is 1-indexed: the first character in the line has an offset of 1.
The source code text involved in the error.
Which line number in the file the error occurred ends in. This is 1-indexed: the first line in the file has a lineno of 1.
The column in the end line where the error occurred finishes. This is 1-indexed: the first character in the line has an offset of 1.
For errors in f-string fields, the message is prefixed by “f-string: ” and the offsets are offsets in a text constructed from the replacement expression. For example, compiling f’Bad field’ results in this args attribute: (‘f-string: …’, (‘’, 1, 2, ‘(a b)n’, 1, 5)).
Changed in version 3.10: Added the end_lineno and end_offset attributes.
Base class for syntax errors related to incorrect indentation. This is a subclass of SyntaxError .
Raised when indentation contains an inconsistent use of tabs and spaces. This is a subclass of IndentationError .
Raised when the interpreter finds an internal error, but the situation does not look so serious to cause it to abandon all hope. The associated value is a string indicating what went wrong (in low-level terms).
You should report this to the author or maintainer of your Python interpreter. Be sure to report the version of the Python interpreter ( sys.version ; it is also printed at the start of an interactive Python session), the exact error message (the exception’s associated value) and if possible the source of the program that triggered the error.
This exception is raised by the sys.exit() function. It inherits from BaseException instead of Exception so that it is not accidentally caught by code that catches Exception . This allows the exception to properly propagate up and cause the interpreter to exit. When it is not handled, the Python interpreter exits; no stack traceback is printed. The constructor accepts the same optional argument passed to sys.exit() . If the value is an integer, it specifies the system exit status (passed to C’s exit() function); if it is None , the exit status is zero; if it has another type (such as a string), the object’s value is printed and the exit status is one.
A call to sys.exit() is translated into an exception so that clean-up handlers ( finally clauses of try statements) can be executed, and so that a debugger can execute a script without running the risk of losing control. The os._exit() function can be used if it is absolutely positively necessary to exit immediately (for example, in the child process after a call to os.fork() ).
The exit status or error message that is passed to the constructor. (Defaults to None .)
Raised when an operation or function is applied to an object of inappropriate type. The associated value is a string giving details about the type mismatch.
This exception may be raised by user code to indicate that an attempted operation on an object is not supported, and is not meant to be. If an object is meant to support a given operation but has not yet provided an implementation, NotImplementedError is the proper exception to raise.
Passing arguments of the wrong type (e.g. passing a list when an int is expected) should result in a TypeError , but passing arguments with the wrong value (e.g. a number outside expected boundaries) should result in a ValueError .
Raised when a reference is made to a local variable in a function or method, but no value has been bound to that variable. This is a subclass of NameError .
Raised when a Unicode-related encoding or decoding error occurs. It is a subclass of ValueError .
UnicodeError has attributes that describe the encoding or decoding error. For example, err.object[err.start:err.end] gives the particular invalid input that the codec failed on.
The name of the encoding that raised the error.
A string describing the specific codec error.
The object the codec was attempting to encode or decode.
The first index of invalid data in object .
The index after the last invalid data in object .
Raised when a Unicode-related error occurs during encoding. It is a subclass of UnicodeError .
Raised when a Unicode-related error occurs during decoding. It is a subclass of UnicodeError .
Raised when a Unicode-related error occurs during translating. It is a subclass of UnicodeError .
Raised when an operation or function receives an argument that has the right type but an inappropriate value, and the situation is not described by a more precise exception such as IndexError .
Raised when the second argument of a division or modulo operation is zero. The associated value is a string indicating the type of the operands and the operation.
The following exceptions are kept for compatibility with previous versions; starting from Python 3.3, they are aliases of OSError .
exception EnvironmentError ¶ exception IOError ¶ exception WindowsError ¶
Only available on Windows.
OS exceptions¶
The following exceptions are subclasses of OSError , they get raised depending on the system error code.
Raised when an operation would block on an object (e.g. socket) set for non-blocking operation. Corresponds to errno EAGAIN , EALREADY , EWOULDBLOCK and EINPROGRESS .
In addition to those of OSError , BlockingIOError can have one more attribute:
An integer containing the number of characters written to the stream before it blocked. This attribute is available when using the buffered I/O classes from the io module.
Raised when an operation on a child process failed. Corresponds to errno ECHILD .
A base class for connection-related issues.
A subclass of ConnectionError , raised when trying to write on a pipe while the other end has been closed, or trying to write on a socket which has been shutdown for writing. Corresponds to errno EPIPE and ESHUTDOWN .
A subclass of ConnectionError , raised when a connection attempt is aborted by the peer. Corresponds to errno ECONNABORTED .
A subclass of ConnectionError , raised when a connection attempt is refused by the peer. Corresponds to errno ECONNREFUSED .
A subclass of ConnectionError , raised when a connection is reset by the peer. Corresponds to errno ECONNRESET .
Raised when trying to create a file or directory which already exists. Corresponds to errno EEXIST .
Raised when a file or directory is requested but doesn’t exist. Corresponds to errno ENOENT .
Raised when a system call is interrupted by an incoming signal. Corresponds to errno EINTR .
Changed in version 3.5: Python now retries system calls when a syscall is interrupted by a signal, except if the signal handler raises an exception (see PEP 475 for the rationale), instead of raising InterruptedError .
Raised when a file operation (such as os.remove() ) is requested on a directory. Corresponds to errno EISDIR .
Raised when a directory operation (such as os.listdir() ) is requested on something which is not a directory. On most POSIX platforms, it may also be raised if an operation attempts to open or traverse a non-directory file as if it were a directory. Corresponds to errno ENOTDIR .
Raised when trying to run an operation without the adequate access rights — for example filesystem permissions. Corresponds to errno EACCES , EPERM , and ENOTCAPABLE .
Changed in version 3.11.1: WASI’s ENOTCAPABLE is now mapped to PermissionError .
Raised when a given process doesn’t exist. Corresponds to errno ESRCH .
Raised when a system function timed out at the system level. Corresponds to errno ETIMEDOUT .
New in version 3.3: All the above OSError subclasses were added.
PEP 3151 — Reworking the OS and IO exception hierarchy
Warnings¶
The following exceptions are used as warning categories; see the Warning Categories documentation for more details.
Base class for warning categories.
Base class for warnings generated by user code.
Base class for warnings about deprecated features when those warnings are intended for other Python developers.
Ignored by the default warning filters, except in the __main__ module ( PEP 565). Enabling the Python Development Mode shows this warning.
The deprecation policy is described in PEP 387.
Base class for warnings about features which are obsolete and expected to be deprecated in the future, but are not deprecated at the moment.
This class is rarely used as emitting a warning about a possible upcoming deprecation is unusual, and DeprecationWarning is preferred for already active deprecations.
Ignored by the default warning filters. Enabling the Python Development Mode shows this warning.
The deprecation policy is described in PEP 387.
Base class for warnings about dubious syntax.
Base class for warnings about dubious runtime behavior.
Base class for warnings about deprecated features when those warnings are intended for end users of applications that are written in Python.
Base class for warnings about probable mistakes in module imports.
Ignored by the default warning filters. Enabling the Python Development Mode shows this warning.
Base class for warnings related to Unicode.
Base class for warnings related to encodings.
New in version 3.10.
Base class for warnings related to bytes and bytearray .
Base class for warnings related to resource usage.
Ignored by the default warning filters. Enabling the Python Development Mode shows this warning.
New in version 3.2.
Exception groups¶
The following are used when it is necessary to raise multiple unrelated exceptions. They are part of the exception hierarchy so they can be handled with except like all other exceptions. In addition, they are recognised by except* , which matches their subgroups based on the types of the contained exceptions.
exception ExceptionGroup ( msg , excs ) ¶ exception BaseExceptionGroup ( msg , excs ) ¶
Both of these exception types wrap the exceptions in the sequence excs . The msg parameter must be a string. The difference between the two classes is that BaseExceptionGroup extends BaseException and it can wrap any exception, while ExceptionGroup extends Exception and it can only wrap subclasses of Exception . This design is so that except Exception catches an ExceptionGroup but not BaseExceptionGroup .
The BaseExceptionGroup constructor returns an ExceptionGroup rather than a BaseExceptionGroup if all contained exceptions are Exception instances, so it can be used to make the selection automatic. The ExceptionGroup constructor, on the other hand, raises a TypeError if any contained exception is not an Exception subclass.
The msg argument to the constructor. This is a read-only attribute.
A tuple of the exceptions in the excs sequence given to the constructor. This is a read-only attribute.
Returns an exception group that contains only the exceptions from the current group that match condition, or None if the result is empty.
The condition can be either a function that accepts an exception and returns true for those that should be in the subgroup, or it can be an exception type or a tuple of exception types, which is used to check for a match using the same check that is used in an except clause.
The nesting structure of the current exception is preserved in the result, as are the values of its message , __traceback__ , __cause__ , __context__ and __notes__ fields. Empty nested groups are omitted from the result.
The condition is checked for all exceptions in the nested exception group, including the top-level and any nested exception groups. If the condition is true for such an exception group, it is included in the result in full.
Like subgroup() , but returns the pair (match, rest) where match is subgroup(condition) and rest is the remaining non-matching part.
Returns an exception group with the same message , but which wraps the exceptions in excs .
This method is used by subgroup() and split() . A subclass needs to override it in order to make subgroup() and split() return instances of the subclass rather than ExceptionGroup .
subgroup() and split() copy the __traceback__ , __cause__ , __context__ and __notes__ fields from the original exception group to the one returned by derive() , so these fields do not need to be updated by derive() .
Note that BaseExceptionGroup defines __new__() , so subclasses that need a different constructor signature need to override that rather than __init__() . For example, the following defines an exception group subclass which accepts an exit_code and and constructs the group’s message from it.
Like ExceptionGroup , any subclass of BaseExceptionGroup which is also a subclass of Exception can only wrap instances of Exception .