Style Guide for Programming Python Code

PEP 8 — Style-Guide for Python Code is the style guide for programming Python code. Study this.

One idiom that trips up many new Python developers is indentation. Python uses indentation (4 spaces) to logically organize code into sections called code blocks. A code block starts with an indent and ends with a dedent (un-indent?). Incorrect indentation will generate an error in Python preventing your code from executing. And this is exactly where having a properly setup code editor pays off, since it will catch indentation errors and highlight them for you. You should also use spaces instead of tabs when indenting. Most editors will allow you to convert tabs to spaces, so that when you tab it is actually applying 4 spaces.

Let’s revisit the errors from the above image…

1. Line 2 – No space around the < operator. As explained in PEP8, Python expects spaces around operators. This is not a critical error but problematic as your code should be clean and readable.
2. Line 4 – There are two errors here, including the show stopper. As stated above, Python uses indention to define code blocks. count = count + 1, is part of a block of code that starts on line 2, so that it must be indented 4 spaces in order for Python to include it in the code block.

Style Guide for Programming Python Code

As I’ve just started to learn python, I should make an effort to internalise these best-practice conventions. To help me do that, I’m going to summarise PEP 8 Style Guide and 257 here, as a quick reference of Style Guide for myself and anyone else who might find it useful.

This is not quite an exhaustive summary: I have omitted the really obvious stuff, and in some cases I’ve picked one approach where PEP8 Style Guide allows a few.

Indentation, line-length & code wrapping

• Always use 4 spaces for indentation (don’t use tabs)
• Write in ASCII in Python 2 and UTF-8 in Python 3
• Max line-length: 72 characters (especially in comments)
• Always indent wrapped code for readablility

# Good:
result = some_function_that_takes_arguments(
    'argument one,
    'argument two',
    'argument three'
)

# Bad:
result = some_function_that_takes_arguments(
'argument one,
'argument two', 'argument three')
result2 = some_function_that_takes_arguments('argument one', 'argument two', 'argument three')

Imports

• Don’t use wildcards
• Try to use absolute imports over relative ones
• When using relative imports, be explicit (with .)
• Don’t import multiple packages per line

# Good:
import os
import sys
from mypkg.sibling import example
from subprocess import Popen, PIPE # Acceptable
from .sibling import example # Acceptable

# Bad:
import os, sys # multiple packages
import sibling # local module without "."
from mypkg import * # wildcards

Whitespace and newlines

• 2 blank lines before top-level function and class definitions
• 1 blank line before class method definitions
• Use blank lines in functions sparingly
• Avoid extraneous whitespace
• Don’t use whitespace to line up assignment operators (=, : )
• Spaces around = for assignment
• No spaces around = for default parameter values
• Spaces around mathematical operators, but group them sensibly
• Multiple statements on the same line are discouraged

# Good:
spam(ham[1], {eggs: 2})
if x == 4:
    print x, y
    x, y = y, x
dict['key'] = list[index]
y = 2
long_variable = 3
hypot2 = x*x + y*y
c = (a+b) * (a-b)
def complex(real, imag=0.0):
    return magic(r=real, i=imag)
do_one()
do_two()

# Bad
spam ( ham[ 1 ], { eggs: 2 } ) # spaces inside brackets
if x == 4 : print x , y ; x , y = y , x # inline statements, space before commas
dict ['key'] = list [index] # space before dictionary key
y             = 2 # Using spaces to line up assignment operators
long_variable = 3
hypot2 = x * x + y * y # Too much space around operators
c = (a + b) * (a - b) # Too much space around operators
def complex(real, imag = 0.0):
    return magic(r = real, i = imag) # Spaces in default values

Comments

• Keep comments up to date – incorrect comments are worse than no comments
• Write in whole sentences
• Try to write in “Strunk & White” English
• Use inline comments sparingly & avoid obvious comments
• Each line of block comments should start with “# “
• Paragraphs in block comments should be separated by a line with a single “#”
• All public functions, classes and methods should have docstrings.
• Docstrings should start and end with “””
• Docstring one-liners can be all on the same line
• In docstrings, list each argument on a separate line
• Docstrings should have a blank line before the final “””

def my_function():
    """ A one-line docstring """

def my_other_function(parameter=False):
    """
    A multiline docstring.

    Keyword arguments:
    parameter -- an example parameter (default False)

    """

Naming conventions

• Class names in CapWords
• Method, function and variables names in lowercase_with_underscores
• Private methods and properties start with __double_underscore
• “Protected” methods and properties start with _single_underscore
• If you need to use a reserved word, add a _ to the end (e.g. class_)
• Always use self for the first argument to instance methods
• Always use cls for the first argument to class methods
• Never declare functions using lambda (f = lambda x: 2*x)

class MyClass:
    """ A purely illustrative class """

    __property = None

    def __init__(self, property_value):
        self.__property = property_value

    def get_property(self):
        """ A simple getter for "property" """

        return self.__property

    @classmethod
    def default(cls):
        instance = MyClass("default value")
        return instance