Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #59701 > unrolled thread

When to use assert

Back to article view | Back to comp.lang.python

Contents

  When to use assert Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2013-11-17 07:35 +0000
    Re: When to use assert Tim Chase <python.list@tim.thechases.com> - 2013-11-17 06:50 -0600
      Re: When to use assert Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2013-11-18 00:52 +0000
    Re: When to use assert Roy Smith <roy@panix.com> - 2013-11-17 08:33 -0500
      Re: When to use assert Robert Day <robertkday@gmail.com> - 2013-11-18 08:20 +0000
      Re: When to use assert Oscar Benjamin <oscar.j.benjamin@gmail.com> - 2013-11-18 09:50 +0000
      Re: When to use assert Mark Lawrence <breamoreboy@yahoo.co.uk> - 2013-11-18 10:02 +0000
      Re: When to use assert Tim Chase <python.list@tim.thechases.com> - 2013-11-18 05:44 -0600

#59701 — When to use assert

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

[toc] | [next] | [standalone]

#59718

On 2013-11-17 07:35, Steven D'Aprano wrote:
> py> x = 23
> py> assert x > 0, "x is not zero or negative"

This is the worst way to use an assertion:  with a misleading
message ;-)

-tkc

[toc] | [prev] | [next] | [standalone]

#59820

On Sun, 17 Nov 2013 06:50:56 -0600, Tim Chase wrote:

> On 2013-11-17 07:35, Steven D'Aprano wrote:
>> py> x = 23
>> py> assert x > 0, "x is not zero or negative"
> 
> This is the worst way to use an assertion:  with a misleading message
> ;-)


D'oh!


Sorry about that.



-- 
Steven

[toc] | [prev] | [next] | [standalone]

#59727

In article <528871d5$0$29975$c3e8da3$5496439d@news.astraweb.com>,
 Steven D'Aprano <steve+comp.lang.python@pearwood.info> wrote:

> * 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.

Which leads to another reason for using asserts...

Every once in a while, I'll get into a situation where something is 
happening that I just can't understand.  If a given pice of code is 
being called, there's NO WAY the program should be exhibiting the 
behavior it's exhibiting.  But, there's also NO WAY that piece of code 
can't be getting called.

So, I stick "assert 0" in the code an re-run the program to see if I get 
an AssertionError.  If I do, then I know the code is being run.  If I 
don't then I know it's not.  Either way, I know more about what's going 
on than I did before.  Once I know what's going on, I remove the assert.

[toc] | [prev] | [next] | [standalone]

#59838

On 17/11/13 13:33, Roy Smith wrote:
> Every once in a while, I'll get into a situation where something is 
> happening that I just can't understand. If a given pice of code is 
> being called, there's NO WAY the program should be exhibiting the 
> behavior it's exhibiting. But, there's also NO WAY that piece of code 
> can't be getting called. So, I stick "assert 0" in the code an re-run 
> the program to see if I get an AssertionError. If I do, then I know 
> the code is being run. If I don't then I know it's not. Either way, I 
> know more about what's going on than I did before. Once I know what's 
> going on, I remove the assert. 

Are assertions the right thing in that case? I'm becoming more and more 
inclined to the idea that if you want to know whether code is getting 
run, you should put a debug log in, and leave it in. That way it's 
easier to track down the next bug (I don't know about others, but when I 
write buggy code I go all-out and put lots of bugs in rather than just one).

Rob

[toc] | [prev] | [next] | [standalone]

#59844

On 17 November 2013 13:33, Roy Smith <roy@panix.com> wrote:
>
> So, I stick "assert 0" in the code an re-run the program to see if I get
> an AssertionError.  If I do, then I know the code is being run.  If I
> don't then I know it's not.  Either way, I know more about what's going
> on than I did before.  Once I know what's going on, I remove the assert.

If the program is invoked from a terminal I would probably go with
'import pdb; pdb.set_trace()' rather than 'assert 0'. Then you can
check much more than whether or not the code is being executed. It's a
bit more to type but I type it so often that I can now type it *really
fast*.


Oscar

[toc] | [prev] | [next] | [standalone]

#59846

On 18/11/2013 09:50, Oscar Benjamin wrote:
> On 17 November 2013 13:33, Roy Smith <roy@panix.com> wrote:
>>
>> So, I stick "assert 0" in the code an re-run the program to see if I get
>> an AssertionError.  If I do, then I know the code is being run.  If I
>> don't then I know it's not.  Either way, I know more about what's going
>> on than I did before.  Once I know what's going on, I remove the assert.
>
> If the program is invoked from a terminal I would probably go with
> 'import pdb; pdb.set_trace()' rather than 'assert 0'. Then you can
> check much more than whether or not the code is being executed. It's a
> bit more to type but I type it so often that I can now type it *really
> fast*.
>
>
> Oscar
>

If I used something that often I'd either cut and paste it or have a key 
combination set up to insert it automatically.  Or get my man to type it 
up for me :)

-- 
Python is the second best programming language in the world.
But the best has yet to be invented.  Christian Tismer

Mark Lawrence

[toc] | [prev] | [next] | [standalone]

#59851

On 2013-11-18 09:50, Oscar Benjamin wrote:
> If the program is invoked from a terminal I would probably go with
> 'import pdb; pdb.set_trace()' rather than 'assert 0'. Then you can
> check much more than whether or not the code is being executed.
> It's a bit more to type but I type it so often that I can now type
> it *really fast*.

I do this so much that on my main development machines, I have a line
in my vimrc file

  nnoremap <leader>p oimport pdb; pdb.set_trace()<esc>
  nnoremap <leader>P Oimport pdb; pdb.set_trace()<esc>

which maps the the leader key (defaults to "\") followed by p/P to
insert the pdb line below/above the current line.  Saves bunches of
time & hassle.  I'm sure it's equally easy in other quality editors.

-tkc

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web