The question of when to use the assert statement comes up occasionally,
usually in response to somebody misusing it, so I thought I'd write a
post describing when and why to use assertions, and when not to.
For those who aren't aware of it, Python's "assert" checks a condition,
if it is true it does nothing, and if it is false it raises an
AssertionError with an optional error message. For example:
py> x = 23
py> assert x > 0, "x is not zero or negative"
py> assert x%2 == 0, "x is not an even number"
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AssertionError: x is not an even number
Many people use asserts as a quick and easy way to raise an exception if
an argument is given the wrong value. But this is wrong, dangerously
wrong, for two reasons. The first is that AssertionError is usually the
wrong error to give when testing function arguments. You wouldn't write
code like this:
if not isinstance(x, int):
raise AssertionError("not an int")
you'd raise TypeError instead. "assert" raises the wrong sort of
exception.
But, and more dangerously, there's a twist with assert: it can be
compiled away and never executed, if you run Python with the -O or -OO
optimization flags, and consequently there is no guarantee that assert
statements will actually be run. When using assert properly, this is a
feature, but when assert is used inappropriately, it leads to code that
is completely broken when running with the -O flag.
When should use assert? In no particular order, assertions should be used
for:
* defensive programming;
* runtime checks on program logic;
* checking contracts (e.g. pre-conditions and post-conditions);
* program invariants; and
* checked documentation.
(It's also acceptable to use assert when testing code, as a sort of quick-
and-dirty poor man's unit testing, so long as you accept that the tests
simply won't do anything if you run with the -O flag. And I sometimes use
"assert False" in code to mark code branches that haven't been written
yet, and I want them to fail. Although "raise NotImplementedError" is
probably better for that, if a little more verbose.)
Opinions on assertions vary, because they can be a statement of
confidence about the correctness of the code. If you're certain that the
code is correct, then assertions are pointless, since they will never
fail and you can safely remove them. If you're certain the checks can
fail (e.g. when testing input data provided by the user), then you dare
not use assert since it may be compiled away and then your checks will be
skipped.
It's the situations in between those two that are interesting, times when
you're certain the code is correct but not *quite* absolutely certain.
Perhaps you've missed some odd corner case (we're all only human). In
this case an extra runtime check helps reassure you that any errors will
be caught as early as possible rather than in distant parts of the code.
(This is why assert can be divisive. Since we vary in our confidence
about the correctness of code, one person's useful assert is another
person's useless runtime test.)
Another good use for asserts is checking program invariants. An invariant
is some condition which you can rely on to be true unless a bug causes it
to become false. If there's a bug, better to find out as early as
possible, so we make a test for it, but we don't want to slow the code
down with such tests. Hence assert, which can be turned on in development
and off in production.
An example of an invariant might be, if your function expects a database
connection to be open when it starts, and promises that it will still be
open when it returns, that's an invariant of the function:
def some_function(arg):
assert not DB.closed()
... # code goes here
assert not DB.closed()
return result
Assertions also make good checked comments. Instead of writing a comment:
# when we reach here, we know that n > 2
you can ensure it is checked at runtime by turning it into an assert:
assert n > 2
Assertions are also a form of defensive programming. You're not
protecting against errors in the code as it is now, but protecting
against changes which introduce errors later. Ideally, unit tests will
pick those up, but let's face it, even when tests exist at all, they're
often incomplete. Build-bots can be down and nobody notices for weeks, or
people forget to run tests before committing code. Having an internal
check is another line of defence against errors sneaking in, especially
those which don't noisily fail but cause the code to malfunction and
return incorrect results.
Suppose you have a series of if...elif blocks, where you know ahead of
time what values some variable is expected to have:
# target is expected to be one of x, y, or z, and nothing else.
if target == x:
run_x_code()
elif target == y:
run_y_code()
else:
run_z_code()
Assume that this code is completely correct now. But will it stay
correct? Requirements change. Code changes. What happens if the
requirements change to allow target = w, with associated action
run_w_code? If we change the code that sets target, but neglect to change
this block of code, it will wrongly call run_z_code() and Bad Things will
occur. It would be good to write this block of code defensively, so that
it will either be correct, or fail immediately, even in the face of
future changes.
The comment at the start of the block is a good first step, but people
are notorious for failing to read and update comments. Chances are it
will soon be obsolete. But with an assertion, we can both document the
assumptions of this block, and cause a clean, immediate failure if they
are violated:
assert target in (x, y, z)
if target == x:
run_x_code()
elif target == y:
run_y_code()
else:
assert target == z
run_z_code()
Here, the assertions are both defensive programming and checked
documentation. I consider this to be a far superior solution than this:
if target == x:
run_x_code()
elif target == y:
run_y_code()
elif target == z:
run_z_code()
else:
# This can never happen. But just in case it does...
raise RuntimeError("an unexpected error occurred")
This tempts some helpful developer to "clean it up" by removing the
"unnecessary" test for value==c and removing the "dead code" of the
RuntimeError. Besides, "unexpected error" messages are embarrassing when
they occur, and they will.
Design by contract is another good use of assertions. In design by
contract, we consider that functions make "contracts" with their callers.
E.g. something like this:
"If you pass me an non-empty string, I guarantee to return the first
character of that string converted to uppercase."
If the contract is broken by either the function or the code calling it,
the code is buggy. We say that functions have pre-conditions (the
constraints that arguments are expected to have) and post-conditions (the
constraints on the return result). So this function might be coded as:
def first_upper(astring):
assert isinstance(astring, str) and len(astring) > 0
result = astring[0].upper()
assert isinstance(result, str) and len(result) == 1
assert result == result.upper()
return result
The aim of Design By Contract is that in a correct program, the pre-
conditions and post-conditions will always hold. Assertions are typically
used, since (so the idea goes) by the time we release the bug-free
program and put it into production, the program will be correct and we
can safely remove the checks.
Here's my advice when *not* to use assertions:
* Never use them for testing user-supplied data, or for anything
where the check must take place under all circumstances.
* Don't use assert for checking anything that you expect might fail
in the ordinary use of your program. Assertions are for extraordinary
failure conditions. Your users should never see an AssertionError;
if they do, it's a bug to be fixed.
* In particular, don't use assert just because it's shorter than an
explicit test followed by a raise. Assert is not a shortcut for
lazy coders.
* Don't use them for checking input arguments to public library
functions (private ones are okay) since you don't control the
caller and can't guarantee that it will never break the
function's contract.
* Don't use assert for any error which you expect to recover from.
In other words, you've got no reason to catch an AssertionError
exception in production code.
* Don't use so many assertions that they obscure the code.
--
Steven
--
https://mail.python.org/mailman/listinfo/python-list
