Python Coding Style Guide

Programming with Style!

Style Guide for Python Code

Code is read much more often than it is written.
Guido van Rossum, creator of the Python language

A style guide is about consistency: within a project, within a module, within a function.

Resources

• PEP 8 – Style Guide for Python Code | peps.python.org
• Style guide for Google-originated Python projects

Indentation

• Use 4 spaces (per indentation level (preferred to 1 tab character that represents 4 spaces).
• Do NOT mix spaces with tabs.
• Do not use 1-tab character for the TAB key!

Documentation Strings or docstrings

• Written for all modules, functions, classes, and methods.
  • Start with three double quotes """ followed immediately by text
  • End with """ on a new line by itself for multiple line docstrings
• Ends on the same line for one line docstring.

Example

def greeting():
"""Print out a greeting to the standard output."""

Import Statements

Always at the top of the file, just after the module docstring

Line Size Limit

• Limit all lines to a maximum of 79 characters.
• Limits are chosen to avoid wrapping
• Good programming practice to have the editor window and terminal window side by side to test code in interactive mode.

Blank Lines

• Surround top-level function and class definitions with two blank lines.

Block Comments

Block comments generally apply to the code that follows them:

• must be indented to the same level as that code.
• each line must start with # followed by a single space.

Inline Comments

Inline comments are used sparingly.

An inline comment is a comment on the same line as a statement, and

• should be separated by at least 2 spaces from the statement
• should start with # and a single space
• _ should NOT state the obvious _

Naming Conventions

Naming conventions of Python’s library are a bit of a mess, as it reflects the evolution of the language. New modules and packages (including third-party frameworks) should be written to the latest Python Code Style Guide. Names that are visible to developers as public parts of the API should reflect usage not implementation.

Naming styles:

• Module names: lowercase
• Function and variable names: snake_case
• Class names: CamelCase
• Method names: mixedCase with initial word lowercase character
• Defined constants: UPPERCASE or UPPER_CASE_WITH_UNDERSCORE
• __double_leading_underscore_and_trailing_double_undersore__ is reserved for Python library defined variables

Continuation Line Indentation

The preferred way of wrapping long lines is by using_ Python’s implied line continuation inside parentheses, brackets, and braces, after a comma. Long lines can also be broken over multiple lines by wrapping expressions in parentheses, after an operator.

Python implied line continuation

• Breaks the line inside ( ), [], { } after a comma or operator
• Aligns wrapped elements vertically with elements in the first line

Examples

# Closing brace/ bracket/ parenthesis on multi-line list lines up
# under the first non-whitespace character of the last line of the list.
my_list = [
    1, 2, 3,
    4, 5, 6,
    ]
result = long_function_name_that_does_something(
    'a', 'b', 'c',
    'd', 'e', 'f',
    )

# One level of indentation for the continuation line
# for a long list of parameters in a function definition.
# Break before the first argument in the function call.
# All continuation lines are indented at the same level.
foo = long_function_name_that_does_something(
    var_one, var_two,			# this is a continuation line
    var_three, var_four)		# this is another continuation line

# Add a comment after continuation line,
# which will provide some distinction in editors supporting syntax
# highlighting.
if (this_is_one_thing and
        that_is_another_thing):
    # Since both conditions are true, we can do something.
    long_function_name_that_does_something()

# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
        and that_is_another_thing):
    long_function_name_that_does_something()


# Two extra indentations included to distinguish this from the rest.
def long_function_name(
        param_one, param_two, param_three,  # this is a continuation line
        param_four):				        # this is another continuation line
    print(param_one)

Incorrect Examples

# Vertical alignment is NOT used for the arguments in the function call.
foo = long_function_name_that_does_something(var_one, var_two,
var_three, var_four)

# Further indentation required as indentation is not distinguishable
# between the 2nd continuation line and the following statement, print( ).
def long_function_name(
param_one, param_two, param_three,
param_four):
    print(param_one)