In the book The Pragmatic Programmer, the authors describe a the­ory that states the impor­tance of main­tain­ing high stan­dards in all parts of a code­base, because any time we let one poor deci­sion in, it opens the door for more. It’s a psy­cho­log­i­cal effect that makes us much more tol­er­ant of intro­duc­ing hacks and short­cuts into already sub­stan­dard code than we would be when work­ing with some­thing that feels ele­gant and pris­tine. You let one bad idea in, and it’s all down­hill from there. I’ve found this applies to the lay­out and for­mat­ting of code just as much as to its func­tion­al­ity and design, and so I try to be dili­gent in keep­ing my code as clean as possible.

When work­ing in teams it’s also impor­tant to have a com­mon cod­ing style if you want to keep a con­sis­tent look and feel to a code­base, and if you want to be sure that all the code is equally read­able to each team member.

Handily enough, in the Python world there’s already a some­what estab­lished for­mat­ting stan­dard, PEP8, which most folks seem to like well enough, and which a lot of 3rd party libraries largely adhere to. Even bet­ter, there’s a script that can check for con­for­mance to that stan­dard. Given that we use Git at Emma, and love automa­tion, it seemed nat­ural to com­bine the two to have our cod­ing style checked auto­mat­i­cally as part of our workflow.

The basic idea is to have a pre-commit script that calls pep8 on the source tree, return­ing non-zero to abort the com­mit if there are any issues. The only slight com­pli­ca­tion is that I really only want to check the parts that are included in the com­mit — if I have unstaged changes that I’m not ready to com­mit yet, I don’t want those to be checked.

Here’s the pre-commit script I use:

#!/usr/bin/env python
from __future__ import with_statement
import os
import re
import shutil
import subprocess
import sys
import tempfile


def system(*args, **kwargs):
    kwargs.setdefault('stdout', subprocess.PIPE)
    proc = subprocess.Popen(args, **kwargs)
    out, err = proc.communicate()
    return out


def main():
    modified = re.compile('^[AM]+\s+(?P<name>.*\.py)', re.MULTILINE)
    files = system('git', 'status', '--porcelain')
    files = modified.findall(files)

    tempdir = tempfile.mkdtemp()
    for name in files:
        filename = os.path.join(tempdir, name)
        filepath = os.path.dirname(filename)
        if not os.path.exists(filepath):
            os.makedirs(filepath)
        with file(filename, 'w') as f:
            system('git', 'show', ':' + name, stdout=f)
    output = system('pep8', '.', cwd=tempdir)
    shutil.rmtree(tempdir)
    if output:
        print output,
        sys.exit(1)


if __name__ == '__main__':
    main()

Download pre-commit script from GitHub

Essentially this just runs git status to get a list of the Python files that are staged in the com­mit, copies them to a tem­po­rary folder and runs pep8 on that folder. If the scripts finds any issues, it will dis­play them and abort the commit.

To include this script in a repos­i­tory you’d save as it as pre-commit in the .git/hooks direc­tory, mak­ing sure it’s marked as exe­cutable. You’ll also need to have the pep8 script installed (pip install pep8). If you’d like to include it in all your repos­i­to­ries, you can use hook tem­plates. (Git doesn’t really sup­port global hooks, but it does have system-wide tem­plates that will be included in every new repos­i­tory that’s cre­ated, includ­ing those cloned from else­where). To add the script as a tem­plate, put it in your templates/hooks direc­tory. The loca­tion of that will depend on how you install Git; on my machine the path is:

/usr/local/git/share/git-core/templates/hooks/pre-commit

If you have some exist­ing repos­i­to­ries to which you’d like to add this (or any other) tem­plate hook, you can sim­ply run git init on the repos­i­to­ries to re-initialize them. If, like me, you have a lot of repos­i­to­ries, a find com­mand might be a handy way to do a whole tree at once:

find . -name .git -exec git --git-dir {} init \;

Lastly, if there are occa­sions where you really do want to com­mit some­thing that’s not pep8-compliant, you can skip the checks with the --no-verify flag, like this:

git commit --no-verify

That can be handy if you’re mak­ing changes to some exist­ing code that’s not PEP8 com­pli­ant, and you want to sep­a­rate the func­tional changes and for­mat­ting changes into sep­a­rate com­mits (which is gen­er­ally a good idea).

I’ve been using a script like the above in my work­flow for about a year now, and I’ve found it very help­ful dur­ing that time. I hope you find some use in it too.