Check Python source code formatting, according to PEP 8: http://www.python.org/dev/peps/pep-0008/
For usage and a list of options, try this: $ python pep8.py -h
This program and its regression test suite live here: http://github.com/jcrocholl/pep8
Groups of errors and warnings: E errors W warnings 100 indentation 200 whitespace 300 blank lines 400 imports 500 line length 600 deprecation 700 statements
You can add checks to this program by writing plugins. Each plugin is a simple function that is called for each line of source code, either physical or logical.
Physical line: - Raw line of text from the input file.
Logical line: - Multi-line statements converted to a single line. - Stripped left and right. - Contents of strings replaced with ‘xxx’ of same length. - Comments removed.
The check function requests physical or logical lines by the name of the first argument:
def maximum_line_length(physical_line) def extraneous_whitespace(logical_line) def blank_lines(logical_line, blank_lines, indent_level, line_number)
The last example above demonstrates how check plugins can request additional information with extra arguments. All attributes of the Checker object are available. Some examples:
lines: a list of the raw lines from the input file tokens: the tokens that contribute to this logical line line_number: line number in the input file blank_lines: blank lines before this one indent_char: first indentation character in this file (‘ ‘ or ‘ ‘) indent_level: indentation (with tabs expanded to multiples of 8) previous_indent_level: indentation on previous line previous_logical: previous logical line
The docstring of each check function shall be the relevant part of text from PEP 8. It is printed if the user enables –show-pep8. Several docstrings contain examples directly from the PEP 8 document.
Okay: spam(ham[1], {eggs: 2}) E201: spam( ham[1], {eggs: 2})
These examples are verified automatically when pep8.py is run with the –doctest option. You can add examples for your own check functions. The format is simple: “Okay” or error/warning code followed by colon and space, the rest of the line is example source code. If you put ‘r’ before the docstring, you can use
for newline, for tab and s
for space.
Bases: object
Load a Python source file, tokenize it, check coding style.
Separate top-level function and class definitions with two blank lines.
Method definitions inside a class are separated by a single blank line.
Extra blank lines may be used (sparingly) to separate groups of related functions. Blank lines may be omitted between a bunch of related one-liners (e.g. a set of dummy implementations).
Use blank lines in functions, sparingly, to indicate logical sections.
Okay: def a():n passnnndef b():n pass Okay: def a():n passnnn# Foon# Barnndef b():n pass
E301: class Foo:n b = 0n def bar():n pass E302: def a():n passnndef b(n):n pass E303: def a():n passnnnndef b(n):n pass E303: def a():nnnn pass E304: @decoratornndef a():n pass
Compound statements (multiple statements on the same line) are generally discouraged.
While sometimes it’s okay to put an if/for/while with a small body on the same line, never do this for multi-clause statements. Also avoid folding such long lines!
Okay: if foo == ‘blah’:n do_blah_thing() Okay: do_one() Okay: do_two() Okay: do_three()
E701: if foo == ‘blah’: do_blah_thing() E701: for x in lst: total += x E701: while t < 10: t = delay() E701: if foo == ‘blah’: do_blah_thing() E701: else: do_non_blah_thing() E701: try: something() E701: finally: cleanup() E701: if foo == ‘blah’: one(); two(); three()
E702: do_one(); do_two(); do_three()
Return the amount of indentation. Tabs are expanded to the next multiple of 8.
>>> expand_indent(' ')
4
>>> expand_indent('\t')
8
>>> expand_indent(' \t')
8
>>> expand_indent(' \t')
8
>>> expand_indent(' \t')
16
Avoid extraneous whitespace in the following situations:
Okay: spam(ham[1], {eggs: 2}) E201: spam( ham[1], {eggs: 2}) E201: spam(ham[ 1], {eggs: 2}) E201: spam(ham[1], { eggs: 2}) E202: spam(ham[1], {eggs: 2} ) E202: spam(ham[1 ], {eggs: 2}) E202: spam(ham[1], {eggs: 2 })
E203: if x == 4: print x, y; x, y = y , x E203: if x == 4: print x, y ; x, y = y, x E203: if x == 4 : print x, y; x, y = y, x
Get statistics for message codes that start with the prefix.
prefix=’’ matches all errors and warnings prefix=’E’ matches all errors prefix=’W’ matches all warnings prefix=’E4’ matches all errors that have to do with imports
Imports should usually be on separate lines.
Okay: import osnimport sys E401: import sys, os
Okay: from subprocess import Popen, PIPE Okay: from myclas import MyClass Okay: from foo.bar.yourclass import YourClass Okay: import myclass Okay: import foo.bar.yourclass
Use 4 spaces per indentation level.
For really old code that you don’t want to mess up, you can continue to use 8-space tabs.
Okay: a = 1 Okay: if a == 0:n a = 1 E111: a = 1
Okay: for item in items:n pass E112: for item in items:npass
Okay: a = 1nb = 2 E113: a = 1n b = 2
Limit all lines to a maximum of 79 characters.
There are still many devices around that are limited to 80 character lines; plus, limiting windows to 80 characters makes it possible to have several windows side-by-side. The default wrapping on such devices looks ugly. Therefore, please limit all lines to a maximum of 79 characters. For flowing long blocks of text (docstrings or comments), limiting the length to 72 characters is recommended.
JCR: Each comma, semicolon or colon should be followed by whitespace.
Okay: [a, b] Okay: (3,) Okay: a[1:4] Okay: a[:4] Okay: a[1:] Okay: a[1:4:2] E231: [‘a’,’b’] E231: foo(bar,baz)
Okay: i = i + 1 Okay: submitted += 1 Okay: x = x * 2 - 1 Okay: hypot2 = x * x + y * y Okay: c = (a + b) * (a - b) Okay: foo(bar, key=’word’, *args, **kwargs) Okay: baz(**kwargs) Okay: negative = -1 Okay: spam(-1) Okay: alpha[:-i] Okay: if not -5 < x < +5:n pass Okay: lambda *args, **kw: (args, kw)
E225: i=i+1 E225: submitted +=1 E225: x = x*2 - 1 E225: hypot2 = x*x + y*y E225: c = (a+b) * (a-b) E225: c = alpha -4 E225: z = x **y
Replace contents with ‘xxx’ to prevent syntax matching.
>>> mute_string('"abc"')
'"xxx"'
>>> mute_string("'''abc'''")
"'''xxx'''"
>>> mute_string("r'abc'")
"r'xxx'"
The {}.has_key() method will be removed in the future version of Python. Use the ‘in’ operation instead, like: d = {“a”: 1, “b”: 2} if “b” in d:
print d[“b”]
When raising an exception, use “raise ValueError(‘message’)” instead of the older form “raise ValueError, ‘message’”.
The paren-using form is preferred because when the exception arguments are long or include string formatting, you don’t need to use line continuation characters thanks to the containing parentheses. The older form will be removed in Python 3000.
For new projects, spaces-only are strongly recommended over tabs. Most editors have features that make this easy to do.
Okay: if True:n return W191: if True:ntreturn
Never mix tabs and spaces.
The most popular way of indenting Python is with spaces only. The second-most popular way is with tabs only. Code indented with a mixture of tabs and spaces should be converted to using spaces exclusively. When invoking the Python command line interpreter with the -t option, it issues warnings about code that illegally mixes tabs and spaces. When using -tt these warnings become errors. These options are highly recommended!
Okay: if a == 0:n a = 1n b = 1 E101: if a == 0:n a = 1ntb = 1
JCR: Trailing blank lines are superfluous.
Okay: spam(1) W391: spam(1)n
JCR: Trailing whitespace is superfluous.
Okay: spam(1) W291: spam(1)s
Avoid extraneous whitespace in the following situations:
JCR: This should also be applied around comma etc. Note: these checks are disabled by default
Okay: a = (1, 2) E241: a = (1, 2) E242: a = (1, 2)
Don’t use spaces around the ‘=’ sign when used to indicate a keyword argument or a default parameter value.
Okay: def complex(real, imag=0.0): Okay: return magic(r=real, i=imag) Okay: boolean(a == b) Okay: boolean(a != b) Okay: boolean(a <= b) Okay: boolean(a >= b)
E251: def complex(real, imag = 0.0): E251: return magic(r = real, i = imag)
Avoid extraneous whitespace in the following situations:
Okay: a = 12 + 3 E221: a = 4 + 5 E222: a = 4 + 5 E223: a = 4 + 5 E224: a = 4 + 5
Separate inline comments by at least two spaces.
An inline comment is a comment on the same line as a statement. Inline comments should be separated by at least two spaces from the statement. They should start with a # and a single space.
Okay: x = x + 1 # Increment x Okay: x = x + 1 # Increment x E261: x = x + 1 # Increment x E262: x = x + 1 #Increment x E262: x = x + 1 # Increment x
Avoid extraneous whitespace in the following situations:
Okay: spam(1) E211: spam (1)
Okay: dict[‘key’] = list[index] E211: dict [‘key’] = list[index] E211: dict[‘key’] = list [index]