TLDR: Configure your text editor to use flake8:

Sublime Text

Install flake8 then using Package Control, install SublimeLinter and SublimeLinter-flake8.

We follow PEP8 with an additional standard for ordering imports:

# First, standard libraries ordered alphabetically.
import abc
import urlparse

# Second, third-party libraries.
import requests

# Third, project libraries, using using relative paths where applicable.
from . import mymodule

Install the pycodestyle package and run it on one or more directories or files:

pip install pycodestyle

pycodestyle portal/core/admin.py  # Check a file
pycodestyle portal/mailers        # Check a folder

• PyCharm: Enable PEP8 Coding Style violation and PEP8 Naming Convention violation inspection rules.
• Sublime Text: Install a PEP8 plugins: PEP8 Autoformat or Sublime Linter PEP8.

Use autopep8:

pip install autopep8

autopep8 --diff portal/core/admin.py      # Spot issues and generate a diff
autopep8 --in-place portal/core/admin.py  # Fix issues in a file
autopep8 -i portal/core/*                 # Fix issues in a folder

# Fix issues in all files in a directory tree, recursively
find portal/core -name '*.py' -print -exec autopep8 --in-place {} \;

Use pep8radius limit fixes to areas that were modified:

pip install pep8radius

pep8radius -vv --in-place

pep8radius uses git to find changes in files that were modified but not commited. Use it before you commit.

There are a number of tools that can be used to check Python code for potential errors. Run these on code that passes PEP8!

The PyCharm IDE has built-in support for Python checking using the Inspect Code... tool. The default set of inspections is suitable for use on our code.

Pyflakes is another pip-installable code analysis tool that focuses on identifying coding issues (and less on code layout and formatting). "Pyflakes makes a simple promise: it will never complain about style, and it will try very, very hard to never emit false positives."

pip install pyflakes

pyflakes portal/core/admin.py  # Check one file
pyflakes portal/core           # Check all the files in a tree

Pyflakes has no configuration, and there is no way to suppress a warning by adding comments. However, it spots a smaller set of issues than PyLint (for example, it doesn't spot unused arguments). This does mean that anything it spots is worth checking.

PyLint is a Python package for Python source code linting. It is extremely thorough, but can also become very slow on large projects. In general, you will get acceptable results in much less time by using 'flake8'. If you do want to install PyLint:

pip install pylint


pylint portal/core/admin.py  # Lint a file
pylint portal/core           # Lint a folder

# Lint a file and output details to HTML
pylint -f html portal/core/admin.py > pylint.html

Linting is configured using a configuration file. Our reference config, pylintrc, is in this folder. Save it to a project's root folder and it will be used when pylint is run from there:

pylint --rcfile=pylint.rc mystuff/myapp/myfile.py

Fix the message or disable:

class Foo(object):
   def unused_arg1(self, arg):
       """Messages about unused argument."""
       print self

   def unused_arg2(self, arg):
       """No message because unused argument check is disabled."""
       # pylint: disable=unused-argument
       print self

Message codes can be found here.

Disable works for the block in which they are found, so include it at the module level to disable a message for a module or file.

We don't have a company-wide standard for Docstrings, but if you're starting a new project, a good choice is the Google style. The official Google documentation isn't always easy to follow, but there is an example file in example_google.py, in this repository.

Using correct Args and Returns descriptions in your code will make it easier for you (or others) to work with many IDEs and code-aware editors that can infer the types of parameters and return values for you.