I’ve been programming in Python for several years now, and understanding several ideas helped me make step changes in the quality of my code and thinking.

The first is using a code linter to ensure my code conforms to Python style conventions.

The final authority on Python code style is PEP 8, and Python linting tools all interpret some subset of it for code analysis.

The larger ethos of Python is encapsulated in Tim Peters’ “The Zen of Python” (PEP 20), which is also an Easter egg (typing import this into a Python interpreter returns the text of Peters’ poem).

Why Style Matters

Most people don’t start out programming in Python with a browser cued to PEP 8, so it’s easy to develop your own style dialect (read: bad habits that can be hard to break). Furthermore, programmers from other languages often bring their idioms to Python, without realizing that more elegant “Pythonic” approaches are available.

Style inconsistencies can create nightmares for code maintenance. Non-Pythonic idioms also make code harder to read and can sometimes run measurably slower than their Pythonic counterparts.

When to Break the Rules

Of course, sometimes there are good reasons for deviating from style guidelines. Many large projects have style conventions of their own, and in these cases it’s better to retain consistency with the project than naively enforce PEP 8 retroactively (as GvR himself notes in PEP 8, with his memorable “a foolish consistency” quote from Ralph Waldo Emerson’s Self Reliance).

Furthermore, some PEP 8 guidelines are arguably archaic. The 79-character line limit seems rather quaint in today’s world of high definition displays. (PEP 8’s rationale here is that this allows for viewing multiple files side-by-side, e.g. comparing changes between versions.)

Bottom line: while a “slavish devotion” (as Norton Juster’s Humbug might say) to PEP 8 can inspire unnecessarily fervent religious debates, the intent of PEP 8 is to provide sensible guidelines for improving readability and enforcing consistency across a Python project.

What is a Code Linter?

Linting tools analyze the quality of your code statically (i.e. your code is not executed). Linters can catch bugs, certain design flaws and antipatterns, redundant code, and PEP 8 style violations. Essentially, they function as automated code review tools.

Also, many linters can be integrated with common IDEs. This is useful because you get immediate feedback as you type, rather than having to manually run the linter at the command line when mood strikes you.

The Python Linting Landscape (pylint et al.)

Pylint is likely the biggest and best known linter for Python code. Other linting tools include:

Finally, some linting tools are actually several tools bundled together. For example, flake8 is a wrapper around pyflakes, pycodestyle, and Ned Batchelder’s McCabe script.

Settle Down, Pylint: Taming the Output

A common criticism of pylint is that it’s too sensitive to be useful (i.e. running pylint on your project returns an overwhelming deluge of style warnings). Fortunately, pylint provides several levels of granularity in controlling the output.

The pylint rc file sets the global configuration. In a marvelous bit of convenience, pylint can generate a template configuration file for you with

pylint --generate-rcfile

which you can then customize to taste.

You can also control pylint’s output for individual projects, modules, and single lines of code.

Further Reading

Jeff Knupp’s excellent How Python Linters Will Save Your Large Python Project details how to make pylint a part of your build process. In Knupp’s setup, if pylint reports issues, the build fails. This effectively institutionalizes pylint usage, and by extension, reasonable code quality and documentation.