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
+ + + + + + + + + +
Python Language Rules
+pychecker Imports Packages Exceptions Global variables Nested/Local/Inner Classes and Functions List Comprehensions Default Iterators and Operators Generators Using apply, filter, map, reduce Lambda Functions Default Argument Values Properties True/False evaluations String Methods Lexical Scoping Function and Method Decorators Threading Power Features
Python Style Rules
+Semicolons Line length Parentheses Indentation Blank Lines Whitespace Python Interpreter Comments Classes Strings TODO Comments Imports formatting Statements Access Control Naming Main
+
+

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