Google Python Style Guide

Revision 2.14

Amit Patel
Antoine Picard
Eugene Jhong
Jeremy Hylton
Matt Smart
Mike Shields

Each style point has a summary for which additional information is available by toggling the accompanying arrow button that looks this way: . You may toggle all summaries with the big arrow button:

Toggle all summaries
Table of Contents

Overview

Important Note

Displaying Hidden Details in this Guide

This style guide contains many details that are initially hidden from view. They are marked by the triangle icon, which you see here on your left. Click it now. You should see "Hooray" appear below.

Background

Python is the main scripting language used at Google. This style guide is a list of dos and don'ts for Python programs.

Python Language Rules

pychecker

Run pychecker over your code.

Imports

Use imports for packages and modules only.

Packages

Import and refer to each module using the full pathname location of that module.

Exceptions

Exceptions are allowed but must be used carefully.

Global variables

Avoid global variables.

Nested/Local/Inner Classes and Functions

Nested/local/inner classes and functions are fine.

List Comprehensions

Okay to use for simple cases.

Default Iterators and Operators

Use default iterators and operators for types that support them, like lists, dictionaries, and files.
No:   for key in adict.keys(): ...
      if not adict.has_key(key): ...
      for line in afile.readlines(): ...

Generators

Use generators as needed.

Lambda Functions

Okay for one-liners.

Default Argument Values

Okay in most cases.

Properties

Use properties for accessing or setting data where you would normally have used simple, lightweight accessor or setter methods.

True/False evaluations

Use the "implicit" false if at all possible.

Deprecated Language Features

Use string methods instead of the string module where possible. Use function call syntax instead of apply. Use list comprehensions and for loops instead of filter, map, and reduce.
Yes: words = foo.split(':')

     [x[1] for x in my_list if x[2] == 5]

     fn(*args, **kwargs)

Lexical Scoping

Okay to use.

So foo([1, 2, 3]) will print 1 2 3 3, not 1 2 3 4.

Decision: Okay to use.

Function and Method Decorators

Use decorators judiciously when there is a clear advantage.
is equivalent to:
class C(object):
    def method(self):
        # method body ...
    method = my_decorator(method)

Pros: Elegantly specifies some transformation on a method; the transformation might eliminate some repetitive code, enforce invariants, etc.

Cons: Decorators can perform arbitrary operations on a function's arguments or return values, resulting in surprising implicit behavior. Additionally, decorators execute at import time. Failures in decorator code are pretty much impossible to recover from.

Decision: Use decorators judiciously when there is a clear advantage. Decorators should follow the same import and naming guidelines as functions. Decorator pydoc should clearly state that the function is a decorator. Write unit tests for decorators.

Avoid external dependencies in the decorator itself (e.g. don't rely on files, sockets, database connections, etc.), since they might not be available when the decorator runs (at import time, perhaps from pychecker or other tools). A decorator that is called with valid parameters should (as much as possible) be guaranteed to succeed in all cases.

Decorators are a special case of "top level code" - see main for more discussion.

Threading

Do not rely on the atomicity of built-in types.

Power Features

Avoid these features.

Python Style Rules

Semicolons

Do not terminate your lines with semi-colons and do not use semi-colons to put two commands on the same line.

Line length

Maximum line length is 80 characters.

Parentheses

Use parentheses sparingly.

Indentation

Indent your code blocks with 4 spaces.

Blank Lines

Two blank lines between top-level definitions, one blank line between method definitions.

Whitespace

Follow standard typographic rules for the use of spaces around punctuation.

Python Interpreter

Modules should begin with #!/usr/bin/env python<version>

Comments

Be sure to use the right style for module, function, method and in-line comments.

Classes

If a class inherits from no other base classes, explicitly inherit from object. This also applies to nested classes.

Strings

Use the % operator for formatting strings, even when the parameters are all strings. Use your best judgement to decide between + and % though.

TODO Comments

Use TODO comments for code that is temporary, a short-term solution, or good-enough but not perfect.

Imports formatting

Imports should be on separate lines.

Statements

Generally only one statement per line.

Access Control

If an accessor function would be trivial you should use public variables instead of accessor functions to avoid the extra cost of function calls in Python. When more functionality is added you can use property to keep the syntax consistent.

Naming

module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_VAR_NAME, instance_var_name, function_parameter_name, local_var_name.

Main

Even a file meant to be used as a script should be importable and a mere import should not have the side effect of executing the script's main functionality. The main functionality should be in a main() function.

Parting Words

BE CONSISTENT.

If you're editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around all their arithmetic operators, you should too. If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too.

The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you're saying rather than on how you're saying it. We present global style rules here so people know the vocabulary, but local style is also important. If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Avoid this.

Revision 2.14

Amit Patel
Antoine Picard
Eugene Jhong
Jeremy Hylton
Matt Smart
Mike Shields