Code Kills

The evils of `except:`

2011-09-29T19:34:24Z

I had some discussion recently about the evils of using a naked except:. Here is a more complete description of the dangers, and of the correct solutions.

In short, except: is bad because hides the source source of the exception and frustrates debugging. For example, consider this code:

try:
    parsed = parse(file_name)
except:
    raise ParseError("can't parse file")

It will likely produce an error something like this:

$ ./my_program.py
Traceback (most recent call last):
    ...
ParseError: can't parse file

This kind of error makes me want to high-five someone. In the face. With a chair.

Notice that it does not contain any information about:

The file which caused the error
The line which caused the error
The nature of the error (is it an expected error? A bug? Who knows!)

And tracking down the source of this error would likely involve some binary searching on the input file or dropping into a debugger.

These are some other, equally unhelpful, bits of code that I have seen:

# There isn't much worse than completely hiding the error
except:
    pass

# Almost as bad is not giving any hit at what it was
except:
    print "there was an error!"

# And even showing the original error can be unhelpful if the error is
# something like an IndexError which could come from anywhere
except Exception, e:
    raise MyException("there was an error: %r" %(e, ))

Now, there is a situations where using a naked except: can be used safely. Exactly one.

1. The `except:` block is terminated with a `raise`

For example, when some cleanup needs to be done before leaving the function:

cxn = open_connection()
try:
    use_connection(cxn)
except:
    close_connection(cxn)
    raise

(note that, usually, the finally: block should be used for this kind of cleanup, but there are some situations where the code above makes more sense)

Every other situation should use except Exception, e::

2. A new exception is raised but the original stack trace is used

For example:

try:
    parsed = parse(file_name)
except Exception, e:
    raise ParseError("error parsing %r: %r" %(file_name, e)), None, sys.exc_info()[2]

A few things to note: first, the three expression version of raise is used, the third of which being the current stack trace. This means that the stack trace will point to the original source of the error:

File "my_program.py", line 9, in <module>
  parse(file_name)
File "parser.py", line 2, in parse
  for lineno, line in enumerate(open(file_name), "rb"):
ParseError: error parsing 'input.bin': TypeError("'str' object cannot be interpreted as an index",)

Instead of the (less helpful) line which re-raised the error:

File "my_program.py", line 11, in <module>
  raise ParseError("error parsing %r: %r" %(file_name, e))
ParseError: error parsing 'input.bin': TypeError("'str' object cannot be interpreted as an index",)

Second, the error includes the file name and original exception, which will make debugging significantly easier. When I'm writing particularly fragile code I'll often wrap the entire block in a try/except which will include as much state as is sensible in the error. For example, the main loop of the parse function might be:

def parse(file_name):
    lineno = -1
    current_foo = None
    try:
        f = open(file_name)
        for lineno, line in enumerate(f):
            current_foo = line.split()[0]
            ...
    except Exception, e:
        raise ParseError("error while parsing %r (line %r; current_foo: %r): %r"
                         %(file_name, lineno, current_foo, e)), None, sys.exc_info()[2]

3. The exception and stack trace are logged

For example, the main runloop of an application might be:

while 1:
    try:
        do_stuff()
    except Exception, e:
        log.exception("error in mainloop")
        time.sleep(1)

A few things to note: first, a naked except: should not be used here, as it will also catch KeyboardInterrupt and SystemExit exceptions, which is almost certainly a bad thing.

Second, log.exception is used, which includes a complete stack trace in the log (care should also be taken to make sure that these logs will be checked - for example by sending an email on exception logs).

Third, the time.sleep(1) ensures that the system won't get clobbered if the do_stuff() function immediately raises an exception.

Checking types in Python

2011-09-26T17:53:08Z

A friend asked me recently when it's acceptable to check types in Python. Here is my reply:

It is almost never a good idea to check that function arguments are exactly the type you expect. For example, these two functions are very, very bad:

def add(a, b):
    if not isinstance(a, int):
        raise ValueError("a is not an int")
    if not isinstance(b, int):
        raise ValueError("b is not an int")
    return a + b

def sum(xs):
    if not isinstance(xs, list):
        raise ValueError("xs is not a list")
    base = 0
    for x in xs:
        base += x
    return base

There's no reason to impose those restrictions, and it makes life difficult if, for example, you want to add floats or sum an iterator:

>>> add(1.2, 3)
...
ValueError("a is not an int")
>>> sum(person.age for person in people)
...
ValueError("xs is not a list")

Type checking to correctly handle different kinds of input is occasionally acceptable, but should be used carefully (ex, to do optimizations, or situations where method overloading would be used in other languages). For example, these functions could be ok:

def contains_all(haystack, needles):
    if not isinstance(haystack, (set, dict)):
        haystack = set(haystack)
    return all(needle in haystack for needle in needles)

def ping_ip(addr):
    if isinstance(addr, numbers.Number):
        addr = numeric_ip_to_string(addr)
    # ping 'addr' which should be a string in "1.2.3.4" form
    ...

But it's almost always better to check for capabilities instead of checking for types. For example, if you want to make sure that add throws an error on invalid input, this would be a better way:

def add(a, b):
    if not (hasattr(a, "__add__") or hasattr(b, "__radd__")):
        raise ValueError("can't add a to b"))
    return a + b

This would be equivalent to excepting an interface instead of an implementation in a statically typed language:

// This is equivilent to ``isinstance(xs, list)`` -- usually bad
public static int sum(ArrayList xs) {
    ...
}

// This is equivilent to ``hasattr(xs, "__iter__")`` -- almost always better
public static int sum(Collection xs) {
    ...
}

Or better yet, Just Do It and wrap any exceptions which pop up:

def add(a, b):
    try:
        return a + b
    except Exception, e:
        raise ValueError("cannot add %r and %r: %r" %(a, b, e)), None, sys.exc_info()[2]

In general, though, code should assume that function arguments will behave correctly, then let the caller use your documentation and Python's helpful stack traces and debugging facilities to figure out what they did wrong.

Python 2.X's str.format is unsafe

2011-09-22T23:33:00Z

I posted a tweet today when I learned that Python's %-string-formatting isn't actually a special case - the str class just implements the __mod__ method.

One side effect of this is that a few people commented that %-formatting is to be replaced with .format formatting... So I'd like to take this opportunity to explain why .format string formatting is unsafe in Python 2.X.

With %-formatting, if the format string is a str while one of the replacements is a unicode the result will be unicode:

>>> "Hello %s" %(u"world", )
u'Hello world'

However, .format will always return the same type of string (str or unicode) as the format string:

>>> "Hello {}".format(u"world")
'Hello world'

This is a problem in Python 2.X because unqualified string literals are instances of str, and the implicit encoding of unicode arguments will almost certainly explode at the least opportune moments:

>>> "Hello {}".format(u"\u263a")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
UnicodeEncodeError: 'ascii' codec can't encode character u'\u263a' in position 0: ordinal not in range(128)

Of course, one possible solution to this is remembering to prefix all string literals with u:

>>> u"Hello {}".format(u"\u263a")
u'Hello \u263a'

But I prefer to simply use %-style formatting, because then I don't need to remember anything:

>>> "Hello %s" %(u"\u263a", )
u'Hello \u263a'
>>> print _.encode('utf-8')
Hello ☺

Of course, as you've probably noticed, this means that the format string is being implicitly decoded to unicode... But since my string literals generally don't contain non-ASCII characters it's not much of an issue.

Note that this is not a problem in Py 3k because string literals are unicode.

Lies, More Lies and Python Packaging Documentation on `package_data`

2011-07-16T00:35:18Z

My slice of Python packaging hell today was thanks to the lie that is package_data.

You see, I've been trying to create an package that includes non-Python files in the distribution... So I did what any good developer would do and hit the documentation:

Package data can be added to packages using the package_data keyword argument to the setup() function.

—Distutils documentation

and

If you want finer-grained control over what files are included (for example, if you have documentation files in your package directories and want to exclude them from installation), then you can also use the package_data keyword.

—Distribute documentation

Over the last hour, though, I've learned that these statements are somewhere between “dangerously misleading” and “damn lies”.

This is because the primary type of Python package is a source package, and the canonical method for creating a source package is by using setup.py sdist. However, the data specified in package_data are not included in source distributions — they are only included in binary (setup.py bdist) distributions and installs (setup.py install).

The only way to get package data included in source packages is the MANIFEST.in file... Which will also include data in binary distributions and installs.

Which renders the package_data option useful only if sdist is not used… And dangerously misleading if sdist is used.

tl;dr: package_data is a lie. Ignore it. Only use MANIFEST.in.

Tips for Managing a Django Project

2011-06-22T20:44:05Z

During the time I've spent with Django, I've picked up a couple tricks for making life a little bit less terrible.

First, split the project project into three (or more) parts, each with its own settings.py: the main project, the development environment and the production environment. For example, my current project, code named eos, has a directory structure something like this:

eos/
    .hg/
    .hgignore
    manage.py
    run
    eos/
        __init__.py
        settings.py
        templates/
        urls.py
        ...
    hacking/
        __init__.py
        settings.py
        db.sqlite3
        ...
    production/
        __init__.py
        settings.py
        run.wsgi
    ...

The eos/ directory is more or less a standard Django project (ie, created by django-admin.py startproject), except that eos/settings.py does not have any environment-specific information in it (for example, it doesn't have any database settings or URLs).

The hacking/ and production/ directories also contain settings.py files, except they define only environment specific settings. For example, hacking/settings.py looks a bit like this:

from eos.settings import *
path = lambda *parts: os.path.join(os.path.dirname(__file__), *parts)

DATABASE_ENGINE = "sqlite3"
DATABASE_NAME = path("db.sqlite3")

DEBUG = True

While production/settings.py contains:

from eos.settings import *

DATABASE_ENGINE = "psycopg2"
DATABASE_NAME = "eos"
DATABASE_USER = "eos"
DATABASE_PASSWORD = "secret"

DEBUG = False

Then, instead of configuring Django (ie, calling setup_environment) on eos.settings, it is called on either hacking.settings or production.settings. For example, manage.py contains:

...
import hacking.settings
execute_manager(hacking.settings)

And production/run.wsgi contains:

...
os.environ["DJANGO_SETTINGS_MODULE"] = "production.settings"
...

Second, every settings.py file should contain the path lambda:

path = lambda *parts: os.path.join(os.path.dirname(__file__), *parts)

It will make specifying paths relative to the settings.py file very easy, and completely do away with relative-path-related issues. For example:

MEDIA_ROOT = path("media/")
DATA_ROOT = path("data/")
DATABASE_NAME = path("db.sqlite3")

Third, there should be scripts for running, saving and re-building the environment. I use two scripts for this: run and dump_dev_data. By default the run script calls ./manage.py runserver 8631 (specifying a port is useful so that web browsers can distinguish between different applications - keeping passwords, history, etc. separate). Run can also be passed a reset argument, which will delete the development database and rebuild it from the dev fixtures. These fixtures are created by the dump_dev_data script, which calls ./manage.py dumpdata for each application, saving the data to fixtures named dev (these fixtures are committed along side the code, so all developers can work off the same data).

So, for example, when I'm developing a new model, my workflow will look something like this:

... add new model to models.py ...
$ ./run reset # Reset the database adding the new model
... use the website to create data for the new model ...
$ ./dump_dev_data # Dump the newly created data
$ hg commit -m "Adding new model + test data"

Python security tip: urllib/urllib2 will read `file://` URLs

2011-06-06T03:03:00Z

I discovered, entirely by accident, that urllib2.urlopen, urllib.urlretrieve, and probably others, will happily read file:// urls and filesystem paths. For example:

>>> import urllib, urllib2
>>> urllib.urlretrieve("database_connection_settings.txt", "/tmp/temp_file")
('/tmp/temp_file', <mimetools.Message instance at 0x…>)
>>> urllib2.urlopen("file:///dev/urandom").read(10)
'\xf1r?\x0fC\x86p\x05\xa4\xdd'

This means that applications which blindly urlopen untrusted URLs (for example, from RSS feeds) are potentially vulnerable to information disclosure and denial of service attacks.

Bug caused by Python's significant whitespace

2011-05-25T19:12:00Z

I encountered my first bug (in recent memory) that was caused by Python's significant whitespace today.

As I was editing a class, I accidentally left-shifted an entire method, effectively removing the rest of the methods from the class:

class Foo:
    def foo(self):
        …

def accidentally_shifted_left(self):
    …

    def bar(self):
        …

PyCon 2011 Recommended Watching

2011-03-19T01:05:00Z

Like always, the best parts of PyCon 2011 happened outside of scheduled talks (one particular highlight was a long conversation with Tavis Rudd, author of the Cheeta template engine, about why HTML templates are bad)… But since those parts weren't recorded, I can't very well recommend watching them. The talks were recorded, though, and here are the ones I'd recommend watching.

(NB: this is not a complete list of good talks, just the ones I found/will find interesting. Check the PyCon 2011 schedule for a complete list of talks, then search Google for {talk title} site:blip.tv to find the videos.)

Talks I Attended

Ordered roughly by how much I enjoyed them.

Using Python 3 to Build a Cloud Computing Service for my Superboard II by David Beazley (video link) — very amusing
How to write obfuscated python by Rev. Johnny Healey (video link) — also very amusing
Everything You Wanted To Know About Pickling, But Were Afraid To Ask! by Richard T. Saunders (video link) — enjoyable, informative
"Dude, Where's My RAM?" - A deep dive into how Python uses memory by Dave Malcolm (video link) — it would be hard to get much lower-level than this talk
Reverse-engineering Ian Bicking's brain: inside pip and virtualenv by Carl Meyer (video link) — Carl builds a virtualenv from scratch to show how virtualenv works
API Design: Lessons Learned by Raymond Hettinger (video link) — Raymond Hettinger wrote many of Python's core data structures, and he presents some good advice on API design with examples to back it up
Genetic Programming in Python by Eric Floehr (video link) — enjoyable, good examples, interesting stuff
The Python That Wasn't by Larry Hastings (video link) — rejected PEPs and features which didn't make it into Python (also, I enjoy Larry's talks)
Testing with mock by Michael Foord (video link) — the title says it all (Michael Foord is the author of Mock)
Advanced Network Architectures With ZeroMQ by Zed Shaw (video link) — ZeroMQ looks really neat, talk is a nice overview
Fun with Python's Newer Tools by Raymond Hettinger (video link) — another talk by Hettinger, shows some interesting tidbits
Best Practices for Impossible Deadlines by Christopher Groskopf (video link) — makes me glad I don't work for a newspaper

Talks I want to watch

In alphabetical order.

Get new contributors (and diversity) through outreach by Asheesh Laroia (video link) — Asheesh is an awesome guy, I'm looking forward to hearing this talk
Handling ridiculous amounts of data with probabilistic data structures by C. Titus Brown (video link) — Titus is a good presenter, and I heard a lot of good things about this talk
How to kill a patent with Python by Van Lindberg (video link) — Van is also a good presenter, heard good things about this talk
Linguistics of Twitter by Michael D. Healy (video link) — looks interesting
Python and Robots: Teaching Programming in High School by Vern Ceder (video link) — heard lots of good things about this talk
Python-Aware Python by Ned Batchelder (video link) — looks interesting
Status of Unicode in Python 3 by Victor Stinner (video link) — looks interesting (but, then, I'm abnormally interested in Unicode)
Swarming the Web: Evolving the Perfect Config File by Kurt Grandis (video link) — looks interesting
Through the Side Channel: Timing and Implementation Attacks in Python by Geremy Condra (video link) — looks interesting
Useful Namespaces: Context Managers and Decorators by Jack Diederich (video link) — looks interesting
Using Blender's new BPY Python API by Christopher Allan Webber (video link) — heard good things about it, I'd like to learn Blender's API
Using Python to debug C and C++ code (using gdb) by Dave Malcolm (video link) — looks interesting
Why is Python slow and how PyPy can help? by Maciej Fijałkowski and Alex Gaynor (video link) — PyPy is freaking awesome, I want to learn more about it

Python quickie: using `itertools.product` to generate binary strings

2011-03-18T20:08:00Z

Problem: you need to enumerate the binary strings between 000 and 111 (ie, 000, 001, 010, …).

Solution: itertools.product:

>>> from itertools import product
>>> for bits in product([0, 1], repeat=3):
...     print "".join(str(bit) for bit in bits)
...
000
001
010
011
…
>>>

For more like this, check out Raymond Hettinger's (really good) talk Fun with Python's Newer Tools, from PyCon 2011.

Why I like `nose`

2010-12-23T21:15:00Z

Four reasons nose rocks:

Test discovery

After I've written my test_*.py files, I just run nosetests:

$ ls
foo.py bar.py test_foo.py test_bar.py
$ nosetests
........
--------
Ran 9 tests in 0.03s

Nose is more Pythonic

The xUnit-esque frameworks fit well in languages like Java where methods can be called without the this prefix, but they don't work so well in Python which forces the explicit self. xUnit-esque frameworks also assume that tests will always exist inside a class and camelCase is pretty. Compare:

from unittest import TestCase
class UnittestTestCase(TestCase):
    def testStuff(self):
        self.assertEqual(foo, bar)

from nose.tools import assert_equal
def test_stuff():
    assert_equal(foo, bar)
class NoseTestCase(object):
    def test_stuff(self):
        assert_equal(foo, bar)

Test generators

The name basically says it all:

$ cat test_add.py
add_tests = [ (1, 2, 3), (1, 3, 4), (0, 0, 0) ]
def test_add():
    def test_add_helper(a, b, expected):
        assert_equal(a + b, expected)
    for test in add_tests:
        yield (test_add_helper, test)
$ nosetests
...
------
Ran 3 tests in 0.03s

Logging/stdout capturing

Nose automatically captures all text sent to stdout during tests, discarding it if the test passes or printing it if the test fails. For example: $ cat test_stuff.py from nose.tools import assert_equals

def passing_test():
    print "everything is happy!"
    assert_equals(1+2, 3)

def failing_test():
    print "oh no..."
    assert_equals(1+2, 0)
$ nosetests
.F
======================================================================
FAIL: test_stuff.failing_test
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/Library/Python/2.6/site-packages/nose/case.py", line 186, in runTest
    self.test(*self.arg)
  File "/private/tmp/test_stuff.py", line 9, in failing_test
    assert_equals(1+2, 0)
AssertionError: 3 != 0
-------------------- >> begin captured stdout << ---------------------
oh no...

--------------------- >> end captured stdout << ----------------------

----------------------------------------------------------------------
Ran 2 tests in 0.001s

FAILED (failures=1)

NOTE: Michael Foord has been doing some crazy stuff with unittest2, so it's possible that it may be as awesome as nose.