Recommended Video Course
Using Python's assert to Debug and Test Your Code
Table of Contents
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’sassert
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, it indicates a bug by raising anAssertionError
.
Assertions are a convenient tool fordocumenting,debugging, andtesting 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. You disable assertions by running Python in optimized mode with the-O
or-OO
options, or by setting thePYTHONOPTIMIZE
environment variable.
By the end of this tutorial, you’ll understand that:
assert
in Python is astatement for setting sanity checks in your code.assert()
checks a condition andraises anAssertionError
if false.raise
andassert
are different becauseraise
manually triggers an exception, whileassert
checks a condition and raises an exception automatically if the condition fails.To get the most out of this tutorial, you should have previous knowledge ofexpressions and operators,functions,conditional statements, andexceptions. Having a basic understanding ofdocumenting,debugging, andtesting Python code is also a plus.
Delve into the tutorial to learn how to effectively use assertions for documenting, debugging, and testing your Python code, along with understanding their limitations and best practices for production environments.
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.
Python implements a feature calledassertions that’s pretty useful during the development of your applications and projects. You’ll find this feature in several other languages too, such asC andJava, and it comes in handy fordocumenting,debugging, andtesting 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.
In Python, assertions arestatementsthat you can use to setsanity 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 thatinvariants within your code stay invariant. By doing so, you can check assumptions likepreconditions andpostconditions. For example, you can test conditions along the lines ofThis argument is notNone
orThis return value is astring. These kinds of checks can help you catch errors as soon as possible when you’re developing a program.
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 meanMake 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, ascomments anddocstrings are.
Finally, assertions are also ideal for writingtest 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 youshouldn’t use assertions.
In general, you shouldn’t use assertions fordata processing ordata 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 inUnderstanding Common Pitfalls ofassert
later in this tutorial.
Additionally, assertions aren’t anerror-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 regulartry
…except
statement.
assert
StatementsNow 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 theassert
keyword rather than as afunction. 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 theassert
statement to introduce assertions in your code. You’ll study the syntax of theassert
statement. Most importantly, you’ll understand how this statement works in Python. Finally, you’ll also learn the basics of theAssertionError
exception.
assert
StatementAnassert
statement consists of theassert
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, thenassert
halts the program by raising anAssertionError
.
In Python,assert
is asimple statement with the following syntax:
assertexpression[,assertion_message]
Here,expression
can be any valid Pythonexpression or object, which is then tested fortruthiness. Ifexpression
is false, then the statement throws anAssertionError
. Theassertion_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:
>>>number=42>>>assertnumber>0>>>number=-42>>>assertnumber>0Traceback (most recent call last):...AssertionError
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 anAssertionError
and breaking the program’s execution.
To make yourassert
statements clear to other developers, you should add a descriptive assertion message:
>>>number=42>>>assertnumber>0,f"number greater than 0 expected, got:{number}">>>number=-42>>>assertnumber>0,f"number greater than 0 expected, got:{number}"Traceback (most recent call last):...AssertionError:number greater than 0 expected, got: -42
The message in this assertion clearly states which condition should be true and what is making that condition fail. Note that theassertion_message
argument toassert
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 useassert
, it’s a good idea to use a descriptive assertion message for thetraceback of theAssertionError
exception.
An important point regarding theassert
syntax is that this statementdoesn’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 aSyntaxWarning
:
>>>number=42>>>assert(number>0,f"number greater than 0 expected, got:{number}")<stdin>:1: SyntaxWarning: assertion is always true, perhaps remove parentheses?
This warning has to do with non-emptytuples 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 aSyntaxWarning
to alert you of this misleading syntax. However, in older versions of the language, anassert
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:
number=42assert(number>0andisinstance(number,int),f"number greater than 0 expected, got:{number}")
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 anassert
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 (\
) forexplicit line joining:
number=42assertnumber>0andisinstance(number,int), \f"number greater than 0 expected, got:{number}"
The backslash at the end of first line of this assertion joins the assertion’s twophysical lines into a singlelogical line. This way, you can have appropriateline 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, thenassert
will work just fine:
>>>number=42>>>assert(number>0)>>>number=-42>>>assert(number>0)Traceback (most recent call last):...AssertionError
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, andassert
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.
AssertionError
ExceptionIf the condition of anassert
statement evaluates to false, thenassert
raises anAssertionError
. If you provide the optional assertion message, then this message is internally used as an argument to theAssertionError
class. Either way, the raised exception breaks your program’s execution.
Most of the time, you won’t raiseAssertionError
exceptions explicitly in your code. Theassert
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 theAssertionError
exception, as you’ll learn later in this tutorial.
Finally,AssertionError
is a built-in exception that inherits from theException
class and is considered aconcrete exception that should be raised instead of subclassed.
That’s it! Now you know the basics of theassert
statement. You’ve learned the statement’s syntax, howassert
works in practice, and also what the main characteristics of theAssertionError
exception are. It’s time to move forward and explore some effective and common ways to write assertions in Python.
When it comes to writing theassert
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>>>assert3>2>>>assert3==2Traceback (most recent call last):...AssertionError>>>assert3>2and5<10>>>assert3==2or5>10Traceback (most recent call last):...AssertionError
Comparison assertions are intended to test conditions that compare two or more objects usingcomparison operators. These assertions can also include compound expressions based onBoolean operators.
Another common assertion format is related tomembership tests:
>>># Membership assertions>>>numbers=[1,2,3,4,5]>>>assert4innumbers>>>assert10innumbersTraceback (most recent call last):...AssertionError
Membership assertions allow you to check if a given item is present in a specific collection, such as alist, tuple,set,dictionary, or the like. These assertions use the membership operators,in
andnot in
, to perform the required check.
The assertion format in the example below is related to an object’sidentity:
>>># Identity assertions>>>x=1>>>y=x>>>null=None>>>assertxisy>>>assertxisnotyTraceback (most recent call last):...AssertionError>>>assertnullisNone>>>assertnullisnotNoneTraceback (most recent call last):...AssertionError
Identity assertions provide a way to test for an object’s identity. In this case, the assertion expression uses the identity operators,is
andis not
.
Finally, you’ll learn how to check the data type of your objects in the context of an assertion:
>>># Type check assertions>>>number=42>>>assertisinstance(number,int)>>>number=42.0>>>assertisinstance(number,int)Traceback (most recent call last):...AssertionError
Type check assertions commonly involve using the built-inisinstance()
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-inall()
andany()
functions to write assertions that check for the truth value of items in an iterable:
>>>assertall([True,True,True])>>>assertall([True,False,True])Traceback (most recent call last):...AssertionError>>>assertany([False,True,False])>>>assertany([False,False,False])Traceback (most recent call last):...AssertionError
Theall()
assertions check if all the items in an input iterable are truthy, while theany()
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 orBoolean-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.
Theassert
statement is an effective way to document code. For example, if you want to state that a specificcondition
should always be true in your code, thenassert 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:
defget_response(server,ports=(443,80)):# The ports argument expects a non-empty tupleforportinports:ifserver.connect(port):returnserver.get()returnNone
If someone accidentally callsget_response()
with an empty tuple, then thefor
loop will never run, and the function will returnNone
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 anassert
statement can be more effective:
defget_response(server,ports=(443,80)):assertlen(ports)>0,f"ports expected a non-empty tuple, got{ports}"forportinports:ifserver.connect(port):returnserver.get()returnNone
The advantage of anassert
statement over a comment is that when the condition isn’t true,assert
immediately raises anAssertionError
. 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.
At its core, theassert
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 theassert
statement to assist you while debugging your code at development time.
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 followingCircle
class:
circle.py
importmathclassCircle:def__init__(self,radius):ifradius<0:raiseValueError("positive radius expected")self.radius=radiusdefarea(self):assertself.radius>=0,"positive radius expected"returnmath.pi*self.radius**2
The class’s initializer,.__init__()
, takesradius
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 anassert
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 toCircle
:
classCircle:# ...defcorrect_radius(self,correction_coefficient):self.radius*=correction_coefficient
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:
>>>fromcircleimportCircle>>>tire=Circle(42)>>>tire.area()5541.769440932395>>>tire.correct_radius(-1.02)>>>tire.radius-42.84>>>tire.area()Traceback (most recent call last):...AssertionError:positive radius expected
The first call to.area()
works correctly because the initial radius is positive. But the second call to.area()
breaks your code with anAssertionError
. 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, yourassert
statement works as a watchdog for situations in which the radius could take invalid values. TheAssertionError
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.
Developers often useassert
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’sreturn value is valid, right before returning the value to the caller.
In general, the conditions that you check with anassert
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 anAssertionError
, 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 usetry
…except
blocks that catch and handleAssertionError
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 atry
…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 aFileNotFoundError
, 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.
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:
-O
or-OO
options.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.
__debug__
Built-in ConstantPython has a built-in constant called__debug__
. This constant is closely related to theassert
statement. Python’s__debug__
is a Boolean constant, which defaults toTrue
. It’s a constant because you can’t change its value once your Python interpreter is running:
>>>importbuiltins>>>"__debug__"indir(builtins)True>>>__debug__True>>>__debug__=False File"<stdin>", line1SyntaxError:cannot assign to __debug__
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, theassert
statement is equivalent to the following conditional:
if__debug__:ifnotexpression:raiseAssertionError(assertion_message)# Equivalent toassertexpression,assertion_message
If__debug__
is true, then the code under the outerif
statement runs. The innerif
statement checksexpression
for truthiness and raises anAssertionError
only if the expression isnot true. This is the default or normal Python mode, in which all your assertions are enabled because__debug__
isTrue
.
On the other hand, if__debug__
isFalse
, then the code under the outerif
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 variablePYTHONOPTIMIZE
to an appropriate value. You’ll learn how to do both operations in the following sections.
-O
or-OO
OptionsYou can disable all yourassert
statements by having the__debug__
constant set toFalse
. 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__
toFalse
. This change removes theassert
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 compiledbytecode smaller. Additionally, if you have several assertions orif __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 thecircle.py
file and run an interactive session with thepython -O
command. Once there, run the following code:
>>># Running Python in optimized mode>>>__debug__False>>>fromcircleimportCircle>>># Normal use of Circle>>>ring=Circle(42)>>>ring.correct_radius(1.02)>>>ring.radius42.84>>>ring.area()5765.656926346065>>># Invalid use of Circle>>>ring=Circle(42)>>>ring.correct_radius(-1.02)>>>ring.radius-42.84>>>ring.area()5765.656926346065
Because the-O
option disables your assertions by setting__debug__
toFalse
, yourCircle
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 useassert
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 theCircle
class would be to turn the.radius
attribute into amanaged attribute using the@property
decorator. This way, you perform the.radius
validation every time the attribute changes:
circle.py
importmathclassCircle:def__init__(self,radius):self.radius=radius@propertydefradius(self):returnself._radius@radius.setterdefradius(self,value):ifvalue<0:raiseValueError("positive radius expected")self._radius=valuedefarea(self):returnmath.pi*self.radius**2defcorrect_radius(self,correction_coefficient):self.radius*=correction_coefficient
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 updatedCircle
works as expected if you run the code in optimized mode:
>>># Running Python in optimized mode>>>__debug__False>>>fromcircleimportCircle>>># Normal use of Circle>>>ring=Circle(42)>>>ring.correct_radius(1.02)>>>ring.radius42.84>>>ring.area()5765.656926346065>>># Invalid use of Circle>>>ring=Circle(42)>>>ring.correct_radius(-1.02)Traceback (most recent call last):...ValueError:positive radius expected
Circle
always validates the value of.radius
before assignment, and your class works correctly, raising aValueError
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 explicitif __debug__:
condition is also disabled. Consider the following script:
demo.py
print(f"{__debug__= }")if__debug__:print("Running in Normal mode!")else:print("Running in Optimized mode!")
This script explicitly checks the value of__debug__
in anif
…else
statement. The code in theif
code block will run only if__debug__
isTrue
. In contrast, if__debug__
isFalse
, then the code in theelse
block will run.
Now tryrunning the script in normal and optimized mode to check its behavior in each mode:
$pythondemo.py__debug__ = TrueRunning in Normal mode!$python-Odemo.py__debug__ = FalseRunning in Optimized mode!
When you execute the script in normal mode, the code under theif __debug__:
condition runs because__debug__
isTrue
in this mode. On the other hand, when you execute the script in optimized mode with the-O
option,__debug__
changes toFalse
, and the code under theelse
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__
toFalse
, any code under an explicitif __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 thePYTHONOPTIMIZE
environment variable.
PYTHONOPTIMIZE
Environment VariableYou can also run Python in optimized mode with disabled assertions by setting thePYTHONOPTIMIZE
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 tryPYTHONOPTIMIZE
out, fire up your command line and run the following command:
C:\>setPYTHONOPTIMIZE="1"
$exportPYTHONOPTIMIZE="1"
Once you’ve setPYTHONOPTIMIZE
to a non-empty string, you can launch your Python interpreter with the bare-bonespython
command. This command will automatically run Python in optimized mode.
Now go ahead and run the following code from the directory containing yourcircle.py
file:
>>>fromcircleimportCircle>>># Normal use of Circle>>>ring=Circle(42)>>>ring.correct_radius(1.02)>>>ring.radius42.84>>># Invalid use of Circle>>>ring=Circle(42)>>>ring.correct_radius(-1.02)>>>ring.radius-42.84
Again, your assertions are off, and theCircle
class accepts negative radius values. You’re running Python in optimized mode again.
Another possibility is to setPYTHONOPTIMIZE
to an integer value,n
, which is equivalent to running Python using the-O
optionn
times. In other words, you’re usingn
levels of optimization:
C:\>setPYTHONOPTIMIZE=1 # Equivalent to python -OC:\>setPYTHONOPTIMIZE=2 # Equivalent to python -OO
$exportPYTHONOPTIMIZE=1# Equivalent to python -O$exportPYTHONOPTIMIZE=2# Equivalent to python -OO
You can use any integer number to setPYTHONOPTIMIZE
. However, Python only implements two levels of optimization. Using a number greater than2
has no real effect on your compiled bytecode. Additionally, settingPYTHONOPTIMIZE
to0
will cause the interpreter to run in normal 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 fromcircle.py
, thePython 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 thePYTHONOPTIMIZE
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__
toFalse
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 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.
Thepytest
third-party library is a popular testing framework in Python. At its core, you’ll find theassert
statement, which you can use to write most of your test cases inpytest
.
Here are a few examples of writing test cases usingassert
statements. The examples below take advantage of some built-in functions, which provide the testing material:
test_samples.py
deftest_sum():assertsum([1,2,3])==6deftest_len():assertlen([1,2,3])>0deftest_reversed():assertlist(reversed([1,2,3]))==[3,2,1]deftest_membership():assert3in[1,2,3]deftest_isinstance():assertisinstance([1,2,3],list)deftest_all():assertall([True,True,True])deftest_any():assertany([False,True,False])deftest_always_fail():assertpow(10,2)==42
All these test cases use theassert
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 withpytest
.
Now, why doespytest
favor plainassert
statements in test cases over a customAPI, which is what other testing frameworks prefer? There are a couple of remarkable advantages behind this choice:
assert
statement allowspytest
to lower the entry barrier and somewhat flatten the learning curve because its users can take advantage of Python syntax that they already know.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 withpytest
a pleasant experience for beginners and people coming from other testing frameworks with custom APIs.
For example, the standard-libraryunittest
module provides an API consisting of a list of.assert*()
methods that work pretty much likeassert
statements. This kind of API can be difficult to learn and memorize for developers starting with the framework.
You can usepytest
to run all the test case examples above. First, you need to install the library by issuing thepython -m pip install pytest
command. Then you can executepytest test_samples.py
from the command-line. This latter command will display an output similar to the following:
========================== test session starts =========================platform linux -- Python 3.10.0, pytest-6.2.5, py-1.10.0, pluggy-1.0.0rootdir: /home/user/python-assertcollected 8 itemstest_samples.py.......F[100%]========================== FAILURES =====================================__________________________ test_always_fail _____________________________ def test_always_fail():> assert pow(10, 2) == 42E assert 100 == 42E + where 100 = pow(10, 2)test_samples.py:25: AssertionError========================== short test summary info ======================FAILED test_samples.py::test_always_fail - assert 100 == 42==========================1 failed,7 passed in 0.21s ==================
The first highlighted line in this output tells you thatpytest
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 anF
.
Note: To avoid issues withpytest
, 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 yourPYTHOPTIMIZE
environment variable by running the following command:
C:\>echo%PYTHONOPTIMIZE%
$echo$PYTHONOPTIMIZE
IfPYTHONOPTIMIZE
is set, then this command’s output will display its current value.
A remarkable feature to note is thatpytest
integrates nicely with theassert
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 theE
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)
returns100
instead of42
, which is intentionally wrong. You can usepytest.raises()
to handle code that isexpected to fail.
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:
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.
assert
for Data Processing and ValidationYou shouldn’t useassert
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:
store.py
# Code under developmentdefprice_with_discount(product,discount):assert0<discount<1,"discount expects a value between 0 and 1"new_price=int(product["price"]*(1-discount))returnnew_price
Notice theassert
statement in the first line ofprice_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:
>>>fromstoreimportprice_with_discount>>>shoes={"name":"Fancy Shoes","price":14900}>>># 25% off -> $111.75>>>price_with_discount(shoes,0.25)11175
All right,price_with_discount()
works nicely! It takes the product as adictionary, applies the intended discount to the current price, and returns the new price. Now, try to apply some invalid discounts:
>>># 200% off>>>price_with_discount(shoes,2.0)Traceback (most recent call last):...AssertionError:discount expects a value between 0 and 1>>># 100% off>>>price_with_discount(shoes,1)Traceback (most recent call last):...AssertionError:discount expects a value between 0 and 1
Applying an invalid discount raises anAssertionError
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 thetraceback.
The real problem with the example above comes if the end user can make direct calls toprice_with_discount()
in production code with disabled assertions. In this situation, the function won’t check the input value fordiscount
, possibly accepting wrong values and breaking the correctness of your discount functionality.
In general, you can writeassert
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 anif
statement or atry
…except
block.
Here’s a new version ofprice_with_discount()
that uses a conditional instead of an assertion:
store.py
# Code in productiondefprice_with_discount(product,discount):if0<discount<1:new_price=int(product["price"]*(1-discount))returnnew_priceraiseValueError("discount expects a value between 0 and 1")
In this new implementation ofprice_with_discount()
, you replace theassert
statement with an explicit conditional statement. The function now applies the discount only if the input value is between0
and1
. Otherwise, it raises aValueError
, signaling the problem.
Now you can wrap up any calls to this function in atry
…except
block that catches theValueError
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 theassert
statement for data processing or data validation, because this statement is typically turned off in production code.
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:
# Bad practicedefsquare(x):assertx>=0,"only positive numbers are allowed"returnx**2try:square(-2)exceptAssertionErroraserror:print(error)
If you execute this code in production with disabled assertions, thensquare()
will never run theassert
statement and raise anAssertionError
. In this situation, thetry
…except
block is superfluous and nonfunctional.
What can you do to fix this example? Try updatingsquare()
to use anif
statement and aValueError
:
# Best practicedefsquare(x):ifx<0:raiseValueError("only positive numbers are allowed")returnx**2try:square(-2)exceptValueErroraserror:print(error)
Nowsquare()
deals with the condition by using an explicitif
statement that can’t be disabled in production code. Yourtry
…except
block now handles aValueError
, which is a more appropriate exception in this example.
Don’t ever catchAssertionError
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.
assert
on Expressions With Side EffectsAnother subtle pitfall with theassert
statement appears when you use this statement to check operations, functions, or expressions that have some kind ofside effect. In other words, these operations modify thestate of objects outside the operation’sscope.
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 aglobal variable as a side effect:
>>>sample=[42,27,40,38]>>>defpopped(sample,index=-1):...item=sample.pop(index)...returnitem...>>>assertsample[-1]==popped(sample)>>>assertsample[1]==popped(sample,1)>>>sample[42, 40]
In this example,popped()
returnsitem
at a givenindex
in the inputsample
of data, with the side effect of also removing saiditem
.
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 ofsample
.
To prevent unexpected behaviors like the one in the above example, use assertion expressions that don’t cause side effects. For example, you can usepure functions that just take input arguments and return the corresponding output without modifying the state of objects from other scopes andnamespaces.
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, andclasses implying a costly instantiation process.
Assertions can impact your code’s performance in two main ways. They will:
Anassert
statement that checks for aNone
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 thePYTHONOPTIMIZE
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.
assert
Statements Enabled by DefaultIn Python, assertions are enabled by default. When the interpreter runs in normal mode, the__debug__
variable isTrue
, 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 thePYTHONOPTIMIZE
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.
Now you know how to use Python’sassert
statement to setsanity 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.
Theassert
statement is pretty handy when you need todocument,debug, andtest 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:
assert
statement worksassert
is handy fordocumenting,debugging, andtesting codeassert
statementsWith this knowledge on theassert
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.
Now that you have some experience with usingassert
in Python, 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.
In Python,assert
is a statement you can use to set sanity checks in your code, allowing you to test conditions that should remain true during development.
Theassert
statement checks if a given condition is true. If it’s false, the statement raises anAssertionError
and halts program execution.
Yes, you should useassert
statements for debugging, testing, and documenting code during development, but avoid using them for data validation or error handling in production.
In Python, you useraise
to trigger exceptions explicitly, while you useassert
to check for conditions. If anassert
condition is false, Python will automatically raise anAssertionError
.
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 Tricks 💌
Get a short & sweetPython Trick delivered to your inbox every couple of days. No spam ever. Unsubscribe any time. Curated by the Real Python team.
AboutLeodanis 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.
» More about LeodanisMasterReal-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:
MasterReal-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 andget answers to common questions in our support portal.
Keep Learning
Related Topics:intermediatebest-practicespython
Recommended Video Course:Using Python's assert to Debug and Test Your Code
Related Tutorials:
Already have an account?Sign-In
Almost there! Complete this form and click the button below to gain instant access:
"Python Tricks: The Book" – Free Sample Chapter (PDF)