This article is based on a presentation I gave at PyMNtos in January, 2012.

Every Pythonista should be familiar with PEP 8, Guido’s “Style Guide for Python Code.” It’s a wonderful document that, should it be followed, ensures that your code is stylistically consistent with code written by other developers. Greater consistency is a huge win, since it makes everyone’s life easier when interacting with your code.

Amongst PEP 8’s many recommendations are things like:

• Use 4 spaces per indentation level.
• Separate top-level function and class definitions with two blank lines.
• Use spaces around arithmetic operators.
• Imports should usually be on separate lines.
• Limit all lines to a maximum of 79 characters.

But how do you remember all of those? Enter: pep8.

pep8: A Style Checker for Python Code

The pep8 script simply checks your code against PEP 8 and warns you about inconsistencies. You can install it with pip install pep8.

Let’s look at a quick example. Check out the code below:

import os, sys
from csv import *

def double(x):
    return x+x

def square(x):
    return x*x

It’s simple, and it works, but the style is all wrong!

• I have two imports, os and sys, on the same line.
• I only have one blank line in between function definitions.
• I don’t have any spaces around my + and * operators.

Let’s see what happens when I run it through pep8:

$ pep8 -r mymath.py
mymath.py:1:10: E401 multiple imports on one line
mymath.py:4:1: E302 expected 2 blank lines, found 1
mymath.py:5:13: E225 missing whitespace around operator
mymath.py:7:1: E302 expected 2 blank lines, found 1
mymath.py:8:13: E225 missing whitespace around operator

Not only did it find those mistakes, but I can also use the --show-pep8 option to get it to quote PEP 8 at me for each transgression!

But what about other problems, like the fact that those useless imports are there at all? That’s whare PyFlakes comes in.

pyflakes: An Error Checker for Python

The pyflakes script reads your code and warns you about common sources of errors. You can install it with pip install pyflakes.

Pyflakes catches things like:

• Unused imports and variables.
• Shadowed or clobbered names.
• Redefined functions.

Check it out:

$ pyflakes mymath.py
mymath.py:1: 'sys' imported but unused
mymath.py:1: 'os' imported but unused
mymath.py:2: 'from csv import *' used; unable to detect undefined names

Awesome!

But what if I cared about style and sources of error?

flake8: pep8 + pyflakes + more

Tarek Ziadé wrote Flake8, which brings together pep8 and pyflakes in one convenient standalone package. You don’t even need separate installations of pep8 or pyflakes, since those come baked in to Flake8. You can install it with pip install flake8.

To these scripts, Tarek also added:

• A Mercurial commit hook.
• A way to exempt files or lines from being checked.
• An optional cyclomatic complexity checker.

(Cyclomatic complexity is a measure of your code’s “complexity,” derived primarily from its degree of nesting and branching. Too much in any one function, and the code is likely difficult to read, maintain, or reason about.)

The output is what you might expect:

$ flake8 mymath.py
mymath.py:1: 'sys' imported but unused
mymath.py:1: 'os' imported but unused
mymath.py:2: 'from csv import *' used; unable to detect undefined names
mymath.py:1:10: E401 multiple imports on one line
mymath.py:4:1: E302 expected 2 blank lines, found 1
mymath.py:5:13: E225 missing whitespace around operator
mymath.py:7:1: E302 expected 2 blank lines, found 1
mymath.py:8:13: E225 missing whitespace around operator

But hey, that’s super useful! You should install it!

Special Bonus Mention: Syntastic: Syntax Checking for Vim

If you use Vim and like the ideas behind flake8, you should absolutely install the Syntastic plugin. When you save a file, Syntastic runs it through an error checker and warns you about potential issues. For Python, it defaults to using Flake8.

Check out what happens when I try to save the mymath.py script shown above:

Erroneous lines get highlighted, and the Location List gets filled with a listing of all of the errors. Cool, right?

What’s even better is that Syntastic is able to take advantage of syntax checkers for a ton of languages, both mainstream and obscure. To wit, it supports C, CoffeeScript, Go, Haskell, JavaScript, Puppet, Vala, and more.

Resources

You can download a copy of the slides (PDF) that I used for my presentation.

You can also find links to the previously mentioned projects below:

• PEP 8
• pep8
• Pyflakes
• Flake8
• Syntastic