diff --git a/pyguide.html b/pyguide.html new file mode 100644 index 0000000..704f980 --- /dev/null +++ b/pyguide.html @@ -0,0 +1,2026 @@ + + + +Google Python Style Guide + + + + + +

Google Python Style Guide

+

+ + Revision 2.12 +

+ +
+ 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. + +
+
+

Using apply, filter, map, reduce

+ + + Avoid in favor of list comprehensions and for-loops. + +
+
No:  map/filter:          map(lambda x: x[1], filter(lambda x: x[2] == 5, my_list))
+

+
+ +

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. + +
+
+

String Methods

+ + + Use string methods instead of the string module where + possible. + +
+
Yes: words = foo.split(':')
+

+
+ +

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.12 +

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