The Python assert statement is a concise, built-in tool for placing checks directly in your code. When a condition you assert turns out to be False, Python raises an AssertionError — effectively signalling a bug in the program logic rather than an expected runtime error.
Despite its simplicity, assert is widely misunderstood. Many
developers either overuse it (putting it in production logic that genuinely
needs error handling) or underuse it (avoiding it when it would improve code
clarity in tests and development). This guide covers everything: the exact
syntax, how AssertionError works, the hidden pitfalls, the -O flag, pytest
integration, and clear guidance on when to use it and when not to.
|
Key Takeaways |
|
1. assert evaluates a condition and raises AssertionError if 2. assert statements can be completely disabled at runtime 3. The parentheses trap: assert (x > 0, ‘msg’) always 4. assert is the correct tool for internal invariant checks 5. For validating user input, external data, or any |
Python assert Syntax
The Python assert statement has two forms:
Form 1: Simple Assert
assert
expression
If expression evaluates to False (or any falsy value), Python
raises AssertionError with no message.
Form 2: Assert with Message
assert
expression, message
If expression is False, Python raises AssertionError with
message as the error message. The message can be any expression — typically a
string, but f-strings and function calls are also valid.
Basic Example
x = 10
assert x >
0 # passes silently
assert x >
0, ‘x must be positive’ # passes silently
y = -5
assert y >
0 # raises AssertionError
assert y >
0, f’Expected positive, got {y}’ # raises AssertionError: Expected positive,
got -5
How Python Processes assert Internally
According to the Python language reference, the statement:
assert
expression, message
is roughly equivalent to:
if __debug__:
if not
expression:
raise
AssertionError(message)
The __debug__ built-in constant is True under normal execution
and False when Python runs with the -O (optimize) flag. This is what allows
assert to be stripped out entirely at compile time during optimised runs.
Note: __debug__ is a compile-time constant, not a runtime
variable. You cannot change its value in code — assigning to __debug__ raises a
SyntaxError.
Understanding AssertionError
AssertionError is a built-in exception that inherits from
Exception. It behaves like any other Python exception — it can be caught,
re-raised, and inspected.
AssertionError in the Exception Hierarchy
BaseException
Exception
AssertionError
Catching an AssertionError
try:
assert 1
== 2, ‘Math is broken’
except
AssertionError as e:
print(f’Caught: {e}’) # Caught: Math is broken
Note: While you can catch AssertionError, it is generally
considered a sign of a bug in the calling code — not a condition you should
routinely handle. If a check needs to be caught and handled, use raise with a
specific exception type instead.
AssertionError with an f-string Message
def divide(a,
b):
assert b
!= 0, f’Divisor must not be zero, got b={b}’
return a /
b
divide(10, 0)
#
AssertionError: Divisor must not be zero, got b=0
Practical Assert Examples
1. Checking Function Arguments (Development Only)
def
get_user(user_id):
assert
isinstance(user_id, int), f’user_id must be int, got {type(user_id)}’
assert
user_id > 0, f’user_id must be positive, got {user_id}’
# …
database lookup
Tip: These checks are appropriate during development to
catch programming mistakes. In production, if user_id comes from external
input, use if/raise with ValueError or TypeError instead.
2. Verifying Internal State
def
process_items(items):
assert
len(items) > 0, ‘items list must not be empty’
result =
[]
for item
in items:
result.append(item * 2)
assert
len(result) == len(items), ‘Internal error: result length mismatch’
return
result
3. Using assert in pytest Tests
# test_math.py
def add(a, b):
return a +
b
def
test_add_positive():
assert
add(2, 3) == 5
def
test_add_negative():
assert
add(-1, -1) == -2
def
test_add_zero():
assert
add(0, 0) == 0
pytest automatically rewrites python assert statements to provide
detailed output on failure, showing the actual vs expected values without any
extra code.
4. Documenting Invariants
def
binary_search(arr, target):
assert arr
== sorted(arr), ‘binary_search requires a sorted array’
low, high
= 0, len(arr) – 1
while low
<= high:
mid =
(low + high) // 2
if
arr[mid] == target:
return mid
elif
arr[mid] < target:
low = mid + 1
else:
high = mid – 1
return -1
The -O Flag: How assert Can Be Disabled
One of the most important things to understand about Python assert is
that it can be completely disabled at the interpreter level. Running Python
with the -O (optimize) flag instructs the compiler to strip out all assert
statements — they produce no bytecode at all.
Running Python with -O
# Normal run —
assert is active
python
script.py
# Optimised
run — all assert statements are removed
python -O
script.py
# You can
verify __debug__ interactively
$ python
>>>
__debug__
True
$ python -O
>>>
__debug__
False
Warning: Because -O removes all python assert statements, any
logic that depends on assert for correctness will silently stop working in an
optimised environment. This is why assert must never be used to validate input,
enforce security constraints, or perform actions that have side effects.
The -OO Flag
Python also supports -OO, which does everything -O does plus
removes docstrings. Both flags set __debug__ to False.
The Parentheses Trap — A Critical Pitfall
One of the most common and silent bugs when using assert is
wrapping the entire expression in parentheses. This is especially easy to make
when adding a message to an existing assert statement.
The Problem
# WRONG — this
ALWAYS passes!
assert (x >
0, ‘x must be positive’)
# Why? Because
this asserts a non-empty tuple (x > 0, ‘x must be positive’)
# A non-empty
tuple is always truthy in Python
# Python will
issue a SyntaxWarning in Python 3.6+ for this pattern
The Correct Form
# CORRECT — no
outer parentheses
assert x >
0, ‘x must be positive’
# If you need
to break a long condition across lines, use backslash continuation
assert (
some_very_long_condition_here
), ‘The
condition failed’ # <– note: comma is OUTSIDE the parentheses
Warning: assert (expression, message) is a silent bug — it
will never raise AssertionError regardless of what expression evaluates to.
Python 3.6+ issues a SyntaxWarning for this pattern. Always use assert
expression, message without outer parentheses.
assert vs raise vs if: Which Should You Use?
The table below compares assert, raise, and conditional checks
to help you choose the right tool:
|
Feature |
assert |
raise |
if / |
|
Purpose |
Debugging / |
Explicit error |
General control |
|
Can be disabled |
Yes (-O flag) |
No |
No |
|
Exception |
AssertionError |
Any exception |
None (unless |
|
Use in |
No (bad |
Yes |
Yes |
|
Use in tests |
Yes (expected) |
Rarely (use |
No |
|
Optimised away |
Yes (with -O) |
No |
No |
|
Custom message |
Yes (second |
Yes (exception |
N/A |
When to Use raise Instead of assert
Use raise with a specific exception when:
•
The condition could legitimately fail at runtime due to external
factors.
•
You need to control the exception type precisely (ValueError, TypeError,
etc.).
•
The check must remain active even in production (assert can be
disabled).
•
You are validating user input, API data, or file contents.
# Use raise
for input validation — not assert
def
set_age(age):
if not
isinstance(age, int):
raise
TypeError(f’age must be int, got {type(age).__name__}’)
if age
< 0 or age > 150:
raise
ValueError(f’age must be 0-150, got {age}’)
Using assert in pytest
pytest is the most widely used Python testing framework, and
assert is the standard way to write test assertions within it. pytest rewrites
python assert statements automatically to provide detailed introspection on failure.
pytest Assertion Rewriting
#
test_example.py
def
test_string_contains():
result =
‘hello world’
assert
‘hello’ in result
def
test_list_equality():
expected =
[1, 2, 3]
actual =
[1, 2, 4]
assert
actual == expected
# On
failure, pytest shows:
#
AssertionError: assert [1, 2, 4] == [1, 2, 3]
# At
index 2 diff: 4 != 3
Testing for Expected Exceptions with pytest.raises
When you expect a function to raise an exception, use
pytest.raises as a context manager rather than asserting on the exception
directly:
import pytest
def divide(a,
b):
if b == 0:
raise
ZeroDivisionError(‘Cannot divide by zero’)
return a /
b
def
test_divide_by_zero():
with
pytest.raises(ZeroDivisionError, match=’Cannot divide by zero’):
divide(10,
0)
Tip: pytest.raises is the preferred way to test that
exceptions are raised. Avoid wrapping divide() in a try/except inside a test
function — it obscures the intent and requires more boilerplate.
When to Use assert — and When Not To
|
Use assert |
Do NOT use |
|
Checking |
Validating user |
|
Verifying |
Enforcing |
|
Writing |
Security-critical |
|
Documenting |
Replacing |
|
Catching |
Checking for |
The Google Python Style Guide on assert
The Google Python Style Guide provides clear guidance: assert
statements must not be critical to application logic. A useful litmus test is
whether the code would still be correct if all python assert statements were removed.
If removing an assert would break the program, it should be replaced with an
if/raise check.
Common Mistakes and How to Avoid Them
Mistake 1: The Parentheses Trap (Already Covered — Repeat of #1 Pitfall)
# Wrong
assert (x >
0, ‘must be positive’) # always True — silent bug!
# Correct
assert x >
0, ‘must be positive’
Mistake 2: Using assert for Input Validation
# Wrong —
assert can be disabled
def
process(data):
assert
data is not None, ‘data is required’
# Correct —
use raise for runtime validation
def
process(data):
if data is
None:
raise
ValueError(‘data is required’)
Mistake 3: assert with Side Effects
# Wrong — if
-O is used, the side effect never happens
assert
my_list.pop() == expected_value
# Correct —
separate the side effect from the assertion
result =
my_list.pop()
assert result
== expected_value
Mistake 4: Catching AssertionError as Normal Flow
# Wrong — do
not use assert/except AssertionError for control flow
try:
assert
some_condition
except
AssertionError:
handle_failure()
# Correct —
use if/raise/except with specific exceptions
if not
some_condition:
handle_failure()
Frequently Asked Questions
|
Question |
Answer |
|
What does |
It evaluates an |
|
What is |
AssertionError |
|
Can assert be |
Yes. Running |
|
What is the |
assert (x == 1, |
|
Should I use |
Generally no. |
|
Is assert OK in |
Yes. pytest |
Conclusion
The Python assert statement is a powerful tool when used in
the right context. To summarise:
•
Use assert to document and verify internal invariants and assumptions
during development.
•
Use assert freely in pytest and unittest test cases — it is the expected
pattern.
•
Never use assert for validating external input, enforcing security
checks, or any logic that must remain active in production, since assert can be
disabled with -O.
•
Always use assert expression, message syntax — never assert (expression,
message) which creates a tuple that is always truthy.
•
When a check genuinely needs to hold in production, use if/raise with an
appropriate exception type instead.
Understanding when to use assert versus raise is one of the
clearer signs of Python maturity. Both serve important roles — the key is
choosing the right tool for the right context.
