styleguide | Style guides for Google-originated open-source projects
styleguide
Google Python Style Guide
Table of Contents
1 Background
2 Python Language Rules
2.1 Lint
2.2 Imports
2.3 Packages
2.4 Exceptions
2.5 Mutable Global State
2.6 Nested/Local/Inner Classes and Functions
2.7 Comprehensions & Generator Expressions
2.8 Default Iterators and Operators
2.9 Generators
2.10 Lambda Functions
2.11 Conditional Expressions
2.12 Default Argument Values
2.13 Properties
2.14 True/False Evaluations
2.16 Lexical Scoping
2.17 Function and Method Decorators
2.18 Threading
2.19 Power Features
2.20 Modern Python: from __future__ imports
2.21 Type Annotated Code
3 Python Style Rules
3.1 Semicolons
3.2 Line length
3.3 Parentheses
3.4 Indentation
3.4.1 Trailing commas in sequences of items?
3.5 Blank Lines
3.6 Whitespace
3.7 Shebang Line
3.8 Comments and Docstrings
3.8.1 Docstrings
3.8.2 Modules
3.8.2.1 Test modules
3.8.3 Functions and Methods
3.8.3.1 Overridden Methods
3.8.4 Classes
3.8.5 Block and Inline Comments
3.8.6 Punctuation, Spelling, and Grammar
3.10 Strings
3.10.1 Logging
3.10.2 Error Messages
3.11 Files, Sockets, and similar Stateful Resources
3.12 TODO Comments
3.13 Imports formatting
3.14 Statements
3.15 Accessors
3.16 Naming
3.16.1 Names to Avoid
3.16.2 Naming Conventions
3.16.3 File Naming
3.16.4 Guidelines derived from Guido’s Recommendations
3.17 Main
3.18 Function length
3.19 Type Annotations
3.19.1 General Rules
3.19.2 Line Breaking
3.19.3 Forward Declarations
3.19.4 Default Values
3.19.5 NoneType
3.19.6 Type Aliases
3.19.7 Ignoring Types
3.19.8 Typing Variables
3.19.9 Tuples vs Lists
3.19.10 Type variables
3.19.11 String types
3.19.12 Imports For Typing
3.19.13 Conditional Imports
3.19.14 Circular Dependencies
3.19.15 Generics
3.19.16 Build Dependencies
4 Parting Words
1 Background
Python is the main dynamic language used at Google. This style guide is a list<br>of dos and don’ts for Python programs.
To help you format code correctly, we’ve created a settings file for Vim. For Emacs, the default settings should be fine.
Many teams use the Black or Pyink<br>auto-formatter to avoid arguing over formatting.
2 Python Language Rules
2.1 Lint
Run pylint over your code using this pylintrc.
2.1.1 Definition
pylint<br>is a tool for finding bugs and style problems in Python source code. It finds<br>problems that are typically caught by a compiler for less dynamic languages like<br>C and C++. Because of the dynamic nature of Python, some<br>warnings may be incorrect; however, spurious warnings should be fairly<br>infrequent.
2.1.2 Pros
Catches easy-to-miss errors like typos, using-vars-before-assignment, etc.
2.1.3 Cons
pylint<br>isn’t perfect. To take advantage of it, sometimes we’ll need to write around it,<br>suppress its warnings or fix it.
2.1.4 Decision
Make sure you run<br>pylint<br>on your code.
Suppress warnings if they are inappropriate so that other issues are not hidden.<br>To suppress warnings, you can set a line-level comment:
def do_PUT(self): # WSGI name, so pylint: disable=invalid-name<br>...
pylint<br>warnings are each identified by symbolic name (empty-docstring)<br>Google-specific warnings start with g-.
If the reason for the suppression is not clear from the symbolic name, add an<br>explanation.
Suppressing in this way has the advantage that we can easily search for<br>suppressions and revisit them.
You can get a list of<br>pylint<br>warnings by doing:
pylint --list-msgs
To get more information on a particular message, use:
pylint --help-msg=invalid-name
Prefer pylint: disable to the deprecated older form pylint: disable-msg.
Unused argument warnings can be suppressed by deleting the variables at the<br>beginning of the function. Always include a comment explaining why you are<br>deleting it. “Unused.” is sufficient. For example:
def viking_cafe_order(spam: str, beans: str, eggs: str | None = None) -> str:<br>del beans, eggs # Unused by vikings.<br>return spam + spam + spam
Other common forms of suppressing this warning include using ‘_’ as the<br>identifier for the unused argument or prefixing the argument name with<br>‘unused_’, or assigning them to ‘_’. These forms are allowed but no longer<br>encouraged. These break callers that pass arguments by name and do not enforce<br>that the arguments are actually unused.
2.2 Imports
Use import statements for packages and modules only, not for individual types,<br>classes, or functions.
2.2.1 Definition
Reusability mechanism for sharing code from one module to another.
2.2.2 Pros
The namespace management convention is simple. The source of each identifier is<br>indicated in a consistent way; x.Obj says that object Obj is defined in<br>module x.
2.2.3 Cons
Module names can still collide. Some module names are inconveniently long.
2.2.4 Decision
Use import x for importing packages and modules.
Use from x import y where x is the package prefix and y is the module<br>name with no prefix.
Use from x import y as z in any of the...