diff --git a/pyguide.md b/pyguide.md
index b2c7f2e..5d9938c 100644
--- a/pyguide.md
+++ b/pyguide.md
@@ -7,8 +7,10 @@ See README.md for details.
# Google Python Style Guide
+
+
-## 1 Background
+## 1 Background
Python is the main dynamic language used at Google. This style guide is a list
of *dos and don'ts* for Python programs.
@@ -21,17 +23,24 @@ auto-formatter to avoid arguing over formatting.
+
+
-## 2 Python Language Rules
+## 2 Python Language Rules
+
+
-### 2.1 Lint
+### 2.1 Lint
Run `pylint` over your code.
-#### 2.1.1 Definition
+
+
+
+#### 2.1.1 Definition
`pylint` is a tool for finding bugs and style problems in Python source
code. It finds problems that are typically caught by a compiler for less dynamic
@@ -40,18 +49,27 @@ warnings may be incorrect; however, spurious warnings should be fairly
infrequent.
-#### 2.1.2 Pros
+
+
+
+#### 2.1.2 Pros
Catches easy-to-miss errors like typos, using-vars-before-assignment, etc.
-#### 2.1.3 Cons
+
+
+
+#### 2.1.3 Cons
`pylint` isn't perfect. To take advantage of it, we'll need to sometimes: a)
Write around it b) Suppress its warnings or c) Improve it.
-#### 2.1.4 Decision
+
+
+
+#### 2.1.4 Decision
Make sure you run `pylint` on your code.
@@ -103,32 +121,46 @@ encouraged. The first two break callers that pass arguments by name, while the
last does not enforce that the arguments are actually unused.
+
+
-### 2.2 Imports
+### 2.2 Imports
Use `import` statements for packages and modules only, not for individual
classes or functions. Note that there is an explicit exemption for imports from
the [typing module](#typing-imports).
-#### 2.2.1 Definition
+
+
+
+#### 2.2.1 Definition
Reusability mechanism for sharing code from one module to another.
-#### 2.2.2 Pros
+
+
+
+#### 2.2.2 Pros
The namespace management convention is simple. The source of each identifier is
indicated in a consistent way; `x.Obj` says that object `Obj` is defined in
module `x`.
-#### 2.2.3 Cons
+
+
+
+#### 2.2.3 Cons
Module names can still collide. Some module names are inconveniently long.
-#### 2.2.4 Decision
+
+
+
+#### 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
@@ -150,28 +182,41 @@ Do not use relative names in imports. Even if the module is in the same package,
use the full package name. This helps prevent unintentionally importing a
package twice.
-Imports from the [typing module](#typing-imports) are exempt from this rule.
+Imports from the [typing module](#typing-imports) and the
+[six.moves module](https://six.readthedocs.io/#module-six.moves)
+are exempt from this rule.
+
+
-### 2.3 Packages
+### 2.3 Packages
Import each module using the full pathname location of the module.
-#### 2.3.1 Pros
+
+
+
+#### 2.3.1 Pros
Avoids conflicts in module names or incorrect imports due to the module search
path not being what the author expected. Makes it easier to find modules.
-
-#### 2.3.2 Cons
+
+
+
+
+#### 2.3.2 Cons
Makes it harder to deploy code because you have to replicate the package
hierarchy. Not really a problem with modern deployment mechanisms.
-#### 2.3.3 Decision
+
+
+
+#### 2.3.3 Decision
All new code should import each module by its full package name.
@@ -209,20 +254,29 @@ The directory the main binary is located in should not be assumed to be in
code should assume that `import jodie` refers to a third party or top level
package named `jodie`, not a local `jodie.py`.
+
+
+
-### 2.4 Exceptions
+### 2.4 Exceptions
Exceptions are allowed but must be used carefully.
-#### 2.4.1 Definition
+
+
+
+#### 2.4.1 Definition
Exceptions are a means of breaking out of the normal flow of control of a code
block to handle errors or other exceptional conditions.
-#### 2.4.2 Pros
+
+
+
+#### 2.4.2 Pros
The control flow of normal operation code is not cluttered by error-handling
code. It also allows the control flow to skip multiple frames when a certain
@@ -230,13 +284,19 @@ condition occurs, e.g., returning from N nested functions in one step instead of
having to carry-through error codes.
-#### 2.4.3 Cons
+
+
+
+#### 2.4.3 Cons
May cause the control flow to be confusing. Easy to miss error cases when making
library calls.
-#### 2.4.4 Decision
+
+
+
+#### 2.4.4 Decision
Exceptions must follow certain conditions:
@@ -245,12 +305,13 @@ Exceptions must follow certain conditions:
message'`).
- Make use of built-in exception classes when it makes sense. For example,
- raise a `ValueError` if you were passed a negative number but were expecting
- a positive one. Do not use `assert` statements for validating argument
- values of a public API. `assert` is used to ensure internal correctness, not
- to enforce correct usage nor to indicate that some unexpected event
- occurred. If an exception is desired in the latter cases, use a raise
- statement. For example:
+ raise a `ValueError` to indicate a programming mistake like a violated
+ precondition (such as if you were passed a negative number but required a
+ positive one). Do not use `assert` statements for validating argument values
+ of a public API. `assert` is used to ensure internal correctness, not to
+ enforce correct usage nor to indicate that some unexpected event occurred.
+ If an exception is desired in the latter cases, use a raise statement. For
+ example:
```python
@@ -260,13 +321,17 @@ Exceptions must follow certain conditions:
Args:
minimum: A port value greater or equal to 1024.
- Raises:
- ValueError: If the minimum port specified is less than 1024.
- ConnectionError: If no available port is found.
+
Returns:
The new minimum port.
+
+ Raises:
+ ConnectionError: If no available port is found.
"""
if minimum < 1024:
+ # Note that this raising of ValueError is not mentioned in the doc
+ # string's "Raises:" section because it is not appropriate to
+ # guarantee this specific behavioral reaction to API misuse.
raise ValueError('Minimum port must be at least 1024, not %d.' % (minimum,))
port = self._find_next_open_port(minimum)
if not port:
@@ -282,6 +347,7 @@ Exceptions must follow certain conditions:
Args:
minimum: A port value greater or equal to 1024.
+
Returns:
The new minimum port.
"""
@@ -296,11 +362,17 @@ Exceptions must follow certain conditions:
`Error` and should not introduce stutter (`foo.FooError`).
- Never use catch-all `except:` statements, or catch `Exception` or
- `StandardError`, unless you are re-raising the exception or in the outermost
- block in your thread (and printing an error message). Python is very
- tolerant in this regard and `except:` will really catch everything including
- misspelled names, sys.exit() calls, Ctrl+C interrupts, unittest failures and
- all kinds of other exceptions that you simply don't want to catch.
+ `StandardError`, unless you are
+
+ - re-raising the exception, or
+ - creating an isolation point in the program where exceptions are not
+ propagated but are recorded and suppressed instead, such as protecting a
+ thread from crashing by guarding its outermost block.
+
+ Python is very tolerant in this regard and `except:` will really catch
+ everything including misspelled names, sys.exit() calls, Ctrl+C interrupts,
+ unittest failures and all kinds of other exceptions that you simply don't
+ want to catch.
- Minimize the amount of code in a `try`/`except` block. The larger the body
of the `try`, the more likely that an exception will be raised by a line of
@@ -322,29 +394,43 @@ Exceptions must follow certain conditions:
```
+
+
-### 2.5 Global variables
+### 2.5 Global variables
Avoid global variables.
-#### 2.5.1 Definition
+
+
+
+#### 2.5.1 Definition
Variables that are declared at the module level or as class attributes.
-#### 2.5.2 Pros
+
+
+
+#### 2.5.2 Pros
Occasionally useful.
-#### 2.5.3 Cons
+
+
+
+#### 2.5.3 Cons
Has the potential to change module behavior during the import, because
assignments to global variables are done when the module is first imported.
-#### 2.5.4 Decision
+
+
+
+#### 2.5.4 Decision
Avoid global variables.
@@ -357,21 +443,29 @@ the module by prepending an `_` to the name. External access must be done
through public module-level functions. See [Naming](#s3.16-naming) below.
-
-### 2.6 Nested/Local/Inner Classes and Functions
+
+
+
+### 2.6 Nested/Local/Inner Classes and Functions
Nested local functions or classes are fine when used to close over a local
variable. Inner classes are fine.
-#### 2.6.1 Definition
+
+
+
+#### 2.6.1 Definition
A class can be defined inside of a method, function, or class. A function can be
defined inside a method or function. Nested functions have read-only access to
variables defined in enclosing scopes.
-#### 2.6.2 Pros
+
+
+
+#### 2.6.2 Pros
Allows definition of utility classes and functions that are only used inside of
a very limited scope. Very
@@ -379,48 +473,69 @@ a very limited scope. Very
Commonly used for implementing decorators.
-#### 2.6.3 Cons
+
+
+
+#### 2.6.3 Cons
Instances of nested or local classes cannot be pickled. Nested functions and
classes cannot be directly tested. Nesting can make your outer function longer
and less readable.
-#### 2.6.4 Decision
+
+
+
+#### 2.6.4 Decision
They are fine with some caveats. Avoid nested functions or classes except when
closing over a local value. Do not nest a function just to hide it from users
of a module. Instead, prefix its name with an \_ at the module level so that it
can still be accessed by tests.
-
+
-### 2.7 Comprehensions & Generator Expressions
+
+
+
+### 2.7 Comprehensions & Generator Expressions
Okay to use for simple cases.
-#### 2.7.1 Definition
+
+
+
+#### 2.7.1 Definition
List, Dict, and Set comprehensions as well as generator expressions provide a
concise and efficient way to create container types and iterators without
resorting to the use of traditional loops, `map()`, `filter()`, or `lambda`.
-#### 2.7.2 Pros
+
+
+
+#### 2.7.2 Pros
Simple comprehensions can be clearer and simpler than other dict, list, or set
creation techniques. Generator expressions can be very efficient, since they
avoid the creation of a list entirely.
-#### 2.7.3 Cons
+
+
+
+#### 2.7.3 Cons
Complicated comprehensions or generator expressions can be hard to read.
-#### 2.7.4 Decision
+
+
+
+#### 2.7.4 Decision
Okay to use for simple cases. Each portion must fit on one line: mapping
expression, `for` clause, filter expression. Multiple `for` clauses or filter
@@ -478,33 +593,46 @@ No:
```
-
-### 2.8 Default Iterators and Operators
+
+
+### 2.8 Default Iterators and Operators
Use default iterators and operators for types that support them, like lists,
dictionaries, and files.
-#### 2.8.1 Definition
+
+
+
+#### 2.8.1 Definition
Container types, like dictionaries and lists, define default iterators and
membership test operators ("in" and "not in").
-#### 2.8.2 Pros
+
+
+
+#### 2.8.2 Pros
The default iterators and operators are simple and efficient. They express the
operation directly, without extra method calls. A function that uses default
operators is generic. It can be used with any type that supports the operation.
-#### 2.8.3 Cons
+
+
+
+#### 2.8.3 Cons
You can't tell the type of objects by reading the method names (e.g. has\_key()
means a dictionary). This is also an advantage.
-#### 2.8.4 Decision
+
+
+
+#### 2.8.4 Decision
Use default iterators and operators for types that support them, like lists,
dictionaries, and files. The built-in types define iterator methods, too. Prefer
@@ -529,63 +657,91 @@ No: for key in adict.keys(): ...
```
+
+
-### 2.9 Generators
+### 2.9 Generators
Use generators as needed.
-#### 2.9.1 Definition
+
+
+
+#### 2.9 Definition
A generator function returns an iterator that yields a value each time it
executes a yield statement. After it yields a value, the runtime state of the
generator function is suspended until the next value is needed.
-#### 2.9.2 Pros
+
+
+
+#### 2.9.2 Pros
Simpler code, because the state of local variables and control flow are
preserved for each call. A generator uses less memory than a function that
creates an entire list of values at once.
-#### 2.9.3 Cons
+
+
+
+#### 2.9.3 Cons
None.
-#### 2.9.4 Decision
+
+
+
+#### 2.9.4 Decision
Fine. Use "Yields:" rather than "Returns:" in the docstring for generator
functions.
-
-### 2.10 Lambda Functions
+
+
+
+### 2.10 Lambda Functions
Okay for one-liners.
-#### 2.10.1 Definition
+
+
+
+#### 2.10.1 Definition
Lambdas define anonymous functions in an expression, as opposed to a statement.
They are often used to define callbacks or operators for higher-order functions
like `map()` and `filter()`.
-#### 2.10.2 Pros
+
+
+
+#### 2.10.2 Pros
Convenient.
-#### 2.10.3 Cons
+
+
+
+#### 2.10.3 Cons
Harder to read and debug than local functions. The lack of names means stack
traces are more difficult to understand. Expressiveness is limited because the
function may only contain an expression.
-#### 2.10.4 Decision
+
+
+
+#### 2.10.4 Decision
Okay to use them for one-liners. If the code inside the lambda function is
longer than 60-80 chars, it's probably better to define it as a regular [nested
@@ -596,43 +752,82 @@ module instead of lambda functions. For example, prefer `operator.mul` to
`lambda x, y: x * y`.
-
-### 2.11 Conditional Expressions
+
-Okay for one-liners.
+
+### 2.11 Conditional Expressions
+
+Okay for simple cases.
-#### 2.11.1 Definition
+
+
+
+#### 2.11.1 Definition
Conditional expressions (sometimes called a “ternary operator”) are mechanisms
that provide a shorter syntax for if statements. For example:
`x = 1 if cond else 2`.
-#### 2.11.2 Pros
+
+
+
+#### 2.11.2 Pros
Shorter and more convenient than an if statement.
-#### 2.11.3 Cons
+
+
+
+#### 2.11.3 Cons
May be harder to read than an if statement. The condition may be difficult to
locate if the expression is long.
-#### 2.11.4 Decision
+
-Okay to use for one-liners. In other cases prefer to use a complete if
-statement.
+
+#### 2.11.4 Decision
+
+Okay to use for simple cases. Each portion must fit on one line:
+true-expression, if-expression, else-expression. Use a complete if statement
+when things get more complicated.
+
+```python
+one_line = 'yes' if predicate(value) else 'no'
+slightly_split = ('yes' if predicate(value)
+ else 'no, nein, nyet')
+the_longest_ternary_style_that_can_be_done = (
+ 'yes, true, affirmative, confirmed, correct'
+ if predicate(value)
+ else 'no, false, negative, nay')
+```
+
+```python
+bad_line_breaking = ('yes' if predicate(value) else
+ 'no')
+portion_too_long = ('yes'
+ if some_long_module.some_long_predicate_function(
+ really_long_variable_name)
+ else 'no, false, negative, nay')
+```
-
-### 2.12 Default Argument Values
+
+
+
+### 2.12 Default Argument Values
Okay in most cases.
-#### 2.12.1 Definition
+
+
+
+#### 2.12.1 Definition
You can specify values for variables at the end of a function's parameter list,
e.g., `def foo(a, b=0):`. If `foo` is called with only one argument,
@@ -640,16 +835,22 @@ e.g., `def foo(a, b=0):`. If `foo` is called with only one argument,
second argument.
-#### 2.12.2 Pros
+
-Often you have a function that uses lots of default values, but-rarely-you want
-to override the defaults. Default argument values provide an easy way to do
-this, without having to define lots of functions for the rare exceptions. Also,
-Python does not support overloaded methods/functions and default arguments are
-an easy way of "faking" the overloading behavior.
+
+#### 2.12.2 Pros
+
+Often you have a function that uses lots of default values, but on rare
+occasions you want to override the defaults. Default argument values provide an
+easy way to do this, without having to define lots of functions for the rare
+exceptions. As Python does not support overloaded methods/functions, default
+arguments are an easy way of "faking" the overloading behavior.
-#### 2.12.3 Cons
+
+
+
+#### 2.12.3 Cons
Default arguments are evaluated once at module load time. This may cause
problems if the argument is a mutable object such as a list or a dictionary. If
@@ -657,7 +858,10 @@ the function modifies the object (e.g., by appending an item to a list), the
default value is modified.
-#### 2.12.4 Decision
+
+
+
+#### 2.12.4 Decision
Okay to use with the following caveat:
@@ -685,20 +889,28 @@ No: def foo(a, b=FLAGS.my_thing): # sys.argv has not yet been parsed...
```
+
+
-### 2.13 Properties
+### 2.13 Properties
Use properties for accessing or setting data where you would normally have used
simple, lightweight accessor or setter methods.
-#### 2.13.1 Definition
+
+
+
+#### 2.13.1 Definition
A way to wrap method calls for getting and setting an attribute as a standard
attribute access when the computation is lightweight.
-#### 2.13.2 Pros
+
+
+
+#### 2.13.2 Pros
Readability is increased by eliminating explicit get and set method calls for
simple attribute access. Allows calculations to be lazy. Considered the Pythonic
@@ -708,13 +920,19 @@ access is reasonable. This also allows accessor methods to be added in the
future without breaking the interface.
-#### 2.13.3 Cons
+
+
+
+#### 2.13.3 Cons
Must inherit from `object` in Python 2. Can hide side-effects much like operator
overloading. Can be confusing for subclasses.
-#### 2.13.4 Decision
+
+
+
+#### 2.13.4 Decision
Use properties in new code to access or set data where you would normally have
used simple, lightweight accessor or setter methods. Properties should be
@@ -749,7 +967,7 @@ Yes: import math
@property
def area(self):
- """Gets or sets the area of the square."""
+ """Area of the square."""
return self._get_area()
@area.setter
@@ -770,42 +988,53 @@ Yes: import math
```
+
+
-### 2.14 True/False evaluations
+### 2.14 True/False Evaluations
Use the "implicit" false if at all possible.
-#### 2.14.1 Definition
+
+
+
+#### 2.14.1 Definition
Python evaluates certain values as `False` when in a boolean context. A quick
"rule of thumb" is that all "empty" values are considered false, so
`0, None, [], {}, ''` all evaluate as false in a boolean context.
-#### 2.14.2 Pros
+
+
+
+#### 2.14.2 Pros
Conditions using Python booleans are easier to read and less error-prone. In
most cases, they're also faster.
-#### 2.14.3 Cons
+
+
+
+#### 2.14.3 Cons
May look strange to C/C++ developers.
-#### 2.14.4 Decision
+
-Use the "implicit" false if at all possible, e.g., `if foo:` rather than
-`if foo != []:`. There are a few caveats that you should keep in mind though:
+
+#### 2.14.4 Decision
-- Never use `==` or `!=` to compare singletons like `None`. Use `is` or
- `is not`.
+Use the "implicit" false if possible, e.g., `if foo:` rather than `if foo !=
+[]:`. There are a few caveats that you should keep in mind though:
-- Beware of writing `if x:` when you really mean `if x is not None:`-e.g.,
- when testing whether a variable or argument that defaults to `None` was set
- to some other value. The other value might be a value that's false in a
- boolean context!
+- Always use `if foo is None:` (or `is not None`) to check for a `None`
+ value-e.g., when testing whether a variable or argument that defaults to
+ `None` was set to some other value. The other value might be a value that's
+ false in a boolean context!
- Never compare a boolean variable to `False` using `==`. Use `if not x:`
instead. If you need to distinguish `False` from `None` then chain the
@@ -852,8 +1081,10 @@ Use the "implicit" false if at all possible, e.g., `if foo:` rather than
- Note that `'0'` (i.e., `0` as string) evaluates to true.
-
-### 2.15 Deprecated Language Features
+
+
+
+### 2.15 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
@@ -861,13 +1092,19 @@ of `filter` and `map` when the function argument would have been an inlined
lambda anyway. Use `for` loops instead of `reduce`.
-#### 2.15.1 Definition
+
+
+
+#### 2.15.1 Definition
Current versions of Python provide alternative constructs that people find
generally preferable.
-#### 2.15.2 Decision
+
+
+
+#### 2.15.2 Decision
We do not use any Python version which does not support these features, so there
is no reason not to use the new styles.
@@ -891,13 +1128,18 @@ No: words = string.split(foo, ':')
```
+
+
-### 2.16 Lexical Scoping
+### 2.16 Lexical Scoping
Okay to use.
-#### 2.16.1 Definition
+
+
+
+#### 2.16.1 Definition
A nested Python function can refer to variables defined in enclosing functions,
but can not assign to them. Variable bindings are resolved using lexical
@@ -918,13 +1160,19 @@ def get_adder(summand1):
```
-#### 2.16.2 Pros
+
+
+
+#### 2.16.2 Pros
Often results in clearer, more elegant code. Especially comforting to
experienced Lisp and Scheme (and Haskell and ML and ...) programmers.
-#### 2.16.3 Cons
+
+
+
+#### 2.16.3 Cons
Can lead to confusing bugs. Such as this example based on
[PEP-0227](http://www.google.com/url?sa=D&q=http://www.python.org/dev/peps/pep-0227/):
@@ -946,19 +1194,28 @@ So `foo([1, 2, 3])` will print `1 2 3 3`, not `1 2 3
4`.
-#### 2.16.4 Decision
+
+
+
+#### 2.16.4 Decision
Okay to use.
+
-### 2.17 Function and Method Decorators
+
+
+### 2.17 Function and Method Decorators
Use decorators judiciously when there is a clear advantage. Avoid
`@staticmethod` and limit use of `@classmethod`.
-#### 2.17.1 Definition
+
+
+
+#### 2.17.1 Definition
[Decorators for Functions and
Methods](https://docs.python.org/3/glossary.html#term-decorator)
@@ -985,13 +1242,19 @@ class C(object):
```
-#### 2.17.2 Pros
+
+
+
+#### 2.17.2 Pros
Elegantly specifies some transformation on a method; the transformation might
eliminate some repetitive code, enforce invariants, etc.
-#### 2.17.3 Cons
+
+
+
+#### 2.17.3 Cons
Decorators can perform arbitrary operations on a function's arguments or return
values, resulting in surprising implicit behavior. Additionally, decorators
@@ -999,7 +1262,10 @@ execute at import time. Failures in decorator code are pretty much impossible to
recover from.
-#### 2.17.4 Decision
+
+
+
+#### 2.17.4 Decision
Use decorators judiciously when there is a clear advantage. Decorators should
follow the same import and naming guidelines as functions. Decorator pydoc
@@ -1022,8 +1288,10 @@ Use `@classmethod` only when writing a named constructor or a class-specific
routine that modifies necessary global state such as a process-wide cache.
+
+
-### 2.18 Threading
+### 2.18 Threading
Do not rely on the atomicity of built-in types.
@@ -1039,13 +1307,18 @@ primitives. Learn about the proper use of condition variables so you can use
`threading.Condition` instead of using lower-level locks.
+
+
-### 2.19 Power Features
+### 2.19 Power Features
Avoid these features.
-#### 2.19.1 Definition
+
+
+
+#### 2.19.1 Definition
Python is an extremely flexible language and gives you many fancy features such
as custom metaclasses, access to bytecode, on-the-fly compilation, dynamic
@@ -1053,12 +1326,18 @@ inheritance, object reparenting, import hacks, reflection (e.g. some uses of
`getattr()`), modification of system internals, etc.
-#### 2.19.2 Pros
+
+
+
+#### 2.19.2 Pros
These are powerful language features. They can make your code more compact.
-#### 2.19.3 Cons
+
+
+
+#### 2.19.3 Cons
It's very tempting to use these "cool" features when they're not absolutely
necessary. It's harder to read, understand, and debug code that's using unusual
@@ -1067,7 +1346,10 @@ but when revisiting the code, it tends to be more difficult than code that is
longer but is straightforward.
-#### 2.19.4 Decision
+
+
+
+#### 2.19.4 Decision
Avoid these features in your code.
@@ -1076,15 +1358,20 @@ to use (for example, `abc.ABCMeta`, `collections.namedtuple`, `dataclasses`,
and `enum`).
+
+
-### 2.20 Modern Python: Python 3 and from \_\_future\_\_ imports
+### 2.20 Modern Python: Python 3 and from \_\_future\_\_ imports
Python 3 is here! While not every project is ready to
use it yet, all code should be written to be 3 compatible (and tested under
3 when possible).
-#### 2.20.1 Definition
+
+
+
+#### 2.20.1 Definition
Python 3 is a significant change in the Python language. While existing code is
often written with 2.7 in mind, there are some simple things to do to make code
@@ -1092,20 +1379,29 @@ more explicit about its intentions and thus better prepared for use under Python
3 without modification.
-#### 2.20.2 Pros
+
+
+
+#### 2.20.2 Pros
Code written with Python 3 in mind is more explicit and easier to get running
under Python 3 once all of the dependencies of your project are ready.
-#### 2.20.3 Cons
+
+
+
+#### 2.20.3 Cons
Some people find the additional boilerplate to be ugly. It's unusual to add
imports to a module that doesn't actually require the features added by the
import.
-#### 2.20.4 Decision
+
+
+
+#### 2.20.4 Decision
##### from \_\_future\_\_ imports
@@ -1124,10 +1420,11 @@ imports](https://www.python.org/dev/peps/pep-0328/), [new `/` division
behavior](https://www.python.org/dev/peps/pep-0238/), and [the print
function](https://www.python.org/dev/peps/pep-3105/).
-Please don't omit or remove these imports, even if they're not currently used
-in the module. It is better to always have the future imports in all files
-so that they are not forgotten during later edits when someone starts using
-such a feature.
+
+Please don't omit or remove these imports, even if they're not currently used in
+the module, unless the code is Python 3 only. It is better to always have the
+future imports in all files so that they are not forgotten during later edits
+when someone starts using such a feature.
There are other `from __future__` import statements. Use them as you see fit. We
do not include `unicode_literals` in our recommendations as it is not a clear
@@ -1135,15 +1432,20 @@ win due to implicit default codec conversion consequences it introduces in many
places within Python 2.7. Most code is better off with explicit use of `b''` and
`u''` bytes and unicode string literals as necessary.
-##### The six, future, or past libraries.
+##### The six, future, or past libraries
When your project needs to actively support use under both Python 2 and 3, use
-of these libraries is encouraged as you see fit. They exist to make your code
-cleaner and life easier.
+the [six](https://pypi.org/project/six/),
+[future](https://pypi.org/project/future/), and
+[past](https://pypi.org/project/past/) libraries as you see fit. They exist to
+make your code cleaner and life easier.
+
-### 2.21 Type Annotated Code
+
+
+### 2.21 Type Annotated Code
You can annotate Python 3 code with type hints according to
[PEP-484](https://www.python.org/dev/peps/pep-0484/), and type-check the code at
@@ -1158,7 +1460,10 @@ modules.
-#### 2.21.1 Definition
+
+
+
+#### 2.21.1 Definition
Type annotations (or "type hints") are for function or method arguments and
return values:
@@ -1174,42 +1479,64 @@ a = SomeFunc() # type: SomeType
```
-#### 2.21.2 Pros
+
+
+
+#### 2.21.2 Pros
Type annotations improve the readability and maintainability of your code. The
type checker will convert many runtime errors to build-time errors, and reduce
your ability to use [Power Features](#power-features).
-#### 2.21.3 Cons
+
+
+
+#### 2.21.3 Cons
You will have to keep the type declarations up to date. You might see type errors that you think are valid code. Use of a [type checker](https://github.com/google/pytype)
may reduce your ability to use [Power Features](#power-features).
-#### 2.21.4 Decision
+
-This highly depends on the complexity of your project. Give it a try.
+
+#### 2.21.4 Decision
+You are strongly encouraged to enable Python type analysis when updating code.
+When adding or modifying public APIs, include type annotations and enable
+checking via pytype in the build system. As static analysis is relatively new to
+Python, we acknowledge that undesired side-effects (such as
+wrongly
+inferred types) may prevent adoption by some projects. In those situations,
+authors are encouraged to add a comment with a TODO or link to a bug describing
+the issue(s) currently preventing type annotation adoption in the BUILD file or
+in the code itself as appropriate.
+
+
-## 3 Python Style Rules
+## 3 Python Style Rules
+
+
-### 3.1 Semicolons
+### 3.1 Semicolons
Do not terminate your lines with semicolons, and do not use semicolons to put
two statements on the same line.
+
+
-### 3.2 Line length
+### 3.2 Line length
Maximum line length is *80 characters*.
-Exceptions:
+Explicit exceptions to the 80 character limit:
- Long import statements.
- URLs, pathnames, or long flags in comments.
@@ -1279,9 +1606,16 @@ Yes: with very_long_first_expression_function() as spam:
Make note of the indentation of the elements in the line continuation examples
above; see the [indentation](#s3.4-indentation) section for explanation.
+In all other cases where a line exceeds 80 characters, and the
+[yapf](https://github.com/google/yapf/)
+auto-formatter does not help bring the line below the limit, the line is allowed
+to exceed this maximum.
+
+
+
-### 3.3 Parentheses
+### 3.3 Parentheses
Use parentheses sparingly.
@@ -1314,10 +1648,11 @@ No: if (x):
return (foo)
```
-
+
+
-### 3.4 Indentation
+### 3.4 Indentation
Indent your code blocks with *4 spaces*.
@@ -1378,9 +1713,11 @@ No: # Stuff on first line forbidden
```
+
-### 3.4.1 Trailing commas in sequences of items?
+
+### 3.4.1 Trailing commas in sequences of items?
Trailing commas in sequences of items are recommended only when the closing
container token `]`, `)`, or `}` does not appear on the same line as the final
@@ -1408,8 +1745,10 @@ No: golomb4 = [
```
+
+
-### 3.5 Blank Lines
+### 3.5 Blank Lines
Two blank lines between top-level definitions, be they function or class
definitions. One blank line between method definitions and between the `class`
@@ -1417,8 +1756,10 @@ line and the first method. No blank line following a `def` line. Use single
blank lines as you judge appropriate within functions or methods.
+
+
-### 3.6 Whitespace
+### 3.6 Whitespace
Follow standard typographic rules for the use of spaces around punctuation.
@@ -1467,6 +1808,8 @@ Yes: dict['key'] = list[index]
No: dict ['key'] = list [index]
```
+No trailing whitespace.
+
Surround binary operators with a single space on either side for assignment
(`=`), comparisons (`==, <, >, !=, <>, <=, >=, in, not in, is, is not`), and
Booleans (`and, or, not`). Use your better judgment for the insertion of spaces
@@ -1523,8 +1866,10 @@ No:
+
+
-### 3.7 Shebang Line
+### 3.7 Shebang Line
Most `.py` files do not need to start with a `#!` line. Start the main file of a
program with
@@ -1536,15 +1881,20 @@ by Python when importing modules. It is only necessary on a file that will be
executed directly.
-
-### 3.8 Comments and Docstrings
+
+
+
+### 3.8 Comments and Docstrings
Be sure to use the right style for module, function, method docstrings and
inline comments.
+
-#### 3.8.1 Docstrings
+
+
+#### 3.8.1 Docstrings
Python uses _docstrings_ to document code. A docstring is a string that is the
first statement in a package, module, class or function. These strings can be
@@ -1560,16 +1910,40 @@ the first quote of the first line. There are more formatting guidelines for
docstrings below.
+
-#### 3.8.2 Modules
-Every file should contain license boilerplate. Choose the appropriate
-boilerplate for the license used by the project (for example, Apache 2.0, BSD,
-LGPL, GPL)
+
+#### 3.8.2 Modules
+
+Every file should contain license boilerplate.
+Choose the appropriate boilerplate for the license used by the project (for
+example, Apache 2.0, BSD, LGPL, GPL)
+
+Files should start with a docstring describing the contents and usage of the
+module.
+```python
+"""A one line summary of the module or program, terminated by a period.
+
+Leave one blank line. The rest of this docstring should contain an
+overall description of the module or program. Optionally, it may also
+contain a brief description of exported classes and functions and/or usage
+examples.
+
+ Typical usage example:
+
+ foo = ClassFoo()
+ bar = foo.FunctionBar()
+"""
+```
+
+
-#### 3.8.3 Functions and Methods
+
+
+#### 3.8.3 Functions and Methods
In this section, "function" means a method, function, or generator.
@@ -1580,11 +1954,13 @@ A function must have a docstring, unless it meets all of the following criteria:
- obvious
A docstring should give enough information to write a call to the function
-without reading the function's code. The docstring should be descriptive
-(`"""Fetches rows from a Bigtable."""`) rather than imperative
-(`"""Fetch rows from a Bigtable."""`). A docstring should describe the
-function's calling syntax and its semantics, not its implementation. For tricky
-code, comments alongside the code are more appropriate than using docstrings.
+without reading the function's code. The docstring should be descriptive-style
+(`"""Fetches rows from a Bigtable."""`) rather than imperative-style (`"""Fetch
+rows from a Bigtable."""`), except for `@property` data descriptors, which
+should use the same style as attributes. A docstring
+should describe the function's calling syntax and its semantics, not its
+implementation. For tricky code, comments alongside the code are more
+appropriate than using docstrings.
A method that overrides a method from a base class may have a simple docstring
sending the reader to its overridden method's docstring, such as `"""See base
@@ -1596,31 +1972,38 @@ side effects), a docstring with at least those differences is required on the
overriding method.
Certain aspects of a function should be documented in special sections, listed
-below. Each section begins with a heading line, which ends with a colon.
-Sections should be indented two spaces, except for the heading.
+below. Each section begins with a heading line, which ends with a colon. All
+sections other than the heading should maintain a hanging indent of two or four
+spaces (be consistent within a file). These sections can be omitted in cases
+where the function's name and signature are informative enough that it can be
+aptly described using a one-line docstring.
[*Args:*](#doc-function-args)
: List each parameter by name. A description should follow the name, and be
-separated by a colon and a space. If the description is too long to fit on a
-single 80-character line, use a hanging indent of 2 or 4 spaces (be
-consistent with the rest of the file).
-The description should include required type(s) if the code does not contain
-a corresponding type annotation.
-If a function accepts `*foo` (variable length argument lists) and/or `**bar`
-(arbitrary keyword arguments), they should be listed as `*foo` and `**bar`.
+ separated by a colon and a space. If the description is too long to fit on a
+ single 80-character line, use a hanging indent of 2 or 4 spaces (be
+ consistent with the rest of the file).
+
+ The description should include required type(s) if the code does not contain
+ a corresponding type annotation. If a function accepts `*foo` (variable
+ length argument lists) and/or `**bar` (arbitrary keyword arguments), they
+ should be listed as `*foo` and `**bar`.
[*Returns:* (or *Yields:* for generators)](#doc-function-returns)
: Describe the type and semantics of the return value. If the function only
-returns None, this section is not required. It may also be omitted if the
-docstring starts with Returns or Yields (e.g.
-`"""Returns row from Bigtable as a tuple of strings."""`) and the opening
-sentence is sufficient to describe return value.
+ returns None, this section is not required. It may also be omitted if the
+ docstring starts with Returns or Yields (e.g. `"""Returns row from Bigtable
+ as a tuple of strings."""`) and the opening sentence is sufficient to
+ describe return value.
[*Raises:*](#doc-function-raises)
-: List all exceptions that are relevant to the interface.
+: List all exceptions that are relevant to the interface. You should not
+ document exceptions that get raised if the API specified in the docstring is
+ violated (because this would paradoxically make behavior under violation of
+ the API part of the API).
```python
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
@@ -1655,8 +2038,11 @@ def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
```
+
-#### 3.8.4 Classes
+
+
+#### 3.8.4 Classes
Classes should have a docstring below the class definition describing the class.
If your class has public attributes, they should be documented here in an
@@ -1686,7 +2072,10 @@ class SampleClass(object):
-#### 3.8.5 Block and Inline Comments
+
+
+
+#### 3.8.5 Block and Inline Comments
The final place to have comments is in tricky parts of the code. If you're going
to have to explain it at the next [code
@@ -1703,8 +2092,9 @@ commence. Non-obvious ones get comments at the end of the line.
if i & (i-1) == 0: # True if i is 0 or a power of 2.
```
-To improve legibility, these comments should be at least 2 spaces away from the
-code.
+To improve legibility, these comments should start at least 2 spaces away from
+the code with the comment character `#`, followed by at least one space before
+the text of the comment itself.
On the other hand, never describe the code. Assume the person reading the code
knows Python (though not what you're trying to do) better than you do.
@@ -1715,9 +2105,15 @@ knows Python (though not what you're trying to do) better than you do.
```
+
-
-#### 3.8.6 Punctuation, Spelling and Grammar
+
+
+
+
+
+
+#### 3.8.6 Punctuation, Spelling and Grammar
Pay attention to punctuation, spelling, and grammar; it is easier to read
well-written comments than badly written ones.
@@ -1733,8 +2129,10 @@ source code maintain a high level of clarity and readability. Proper
punctuation, spelling, and grammar help with that goal.
+
+
-### 3.9 Classes
+### 3.9 Classes
If a class inherits from no other base classes, explicitly inherit from
`object`. This also applies to nested classes.
@@ -1773,12 +2171,14 @@ including `__new__`, `__init__`, `__delattr__`, `__getattribute__`,
`__setattr__`, `__hash__`, `__repr__`, and `__str__`.
+
+
-### 3.10 Strings
+### 3.10 Strings
Use the `format` method or the `%` operator for formatting strings, even when
-the parameters are all strings. Use your best judgement to decide between `+`
-and `%` (or `format`) though.
+the parameters are all strings. Use your best judgment to decide between `+` and
+`%` (or `format`) though.
```python
Yes: x = a + b
@@ -1819,8 +2219,7 @@ No: employee_table = ''
Be consistent with your choice of string quote character within a file. Pick `'`
or `"` and stick with it. It is okay to use the other quote character on a
-string to avoid the need to `\\` escape within the string. `gpylint` enforces
-this.
+string to avoid the need to `\\ ` escape within the string.
```python
Yes:
@@ -1838,26 +2237,54 @@ No:
Prefer `"""` for multi-line strings rather than `'''`. Projects may choose to
use `'''` for all non-docstring multi-line strings if and only if they also use
-`'` for regular strings. Docstrings must use `"""` regardless. Note that it is
-often cleaner to use implicit line joining since multi-line strings do not flow
-with the indentation of the rest of the program:
+`'` for regular strings. Docstrings must use `"""` regardless.
-```python
- Yes:
- print("This is much nicer.\n"
- "Do it this way.\n")
-```
+Multi-line strings do not flow with the indentation of the rest of the program.
+If you need to avoid embedding extra space in the string, use either
+concatenated single-line strings or a multi-line string with
+[`textwrap.dedent()`](https://docs.python.org/3/library/textwrap.html#textwrap.dedent)
+to remove the initial space on each line:
```python
No:
- print("""This is pretty ugly.
+ long_string = """This is pretty ugly.
Don't do this.
-""")
+"""
+```
+
+```python
+ Yes:
+ long_string = """This is fine if your use case can accept
+ extraneous leading spaces."""
+```
+
+```python
+ Yes:
+ long_string = ("And this is fine if you can not accept\n" +
+ "extraneous leading spaces.")
+```
+
+```python
+ Yes:
+ long_string = ("And this too is fine if you can not accept\n"
+ "extraneous leading spaces.")
+```
+
+```python
+ Yes:
+ import textwrap
+
+ long_string = textwrap.dedent("""\
+ This is also fine, because textwrap.dedent()
+ will collapse common leading spaces in each line.""")
```
+
-### 3.11 Files and Sockets
+
+
+### 3.11 Files and Sockets
Explicitly close files and sockets when done with them.
@@ -1906,8 +2333,10 @@ with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page:
```
-
-### 3.12 TODO Comments
+
+
+
+### 3.12 TODO Comments
Use `TODO` comments for code that is temporary, a short-term solution, or
good-enough but not perfect.
@@ -1933,8 +2362,10 @@ either include a very specific date ("Fix by November 2009") or a very specific
event ("Remove this code when all clients can handle XML responses.").
+
+
-### 3.13 Imports formatting
+### 3.13 Imports formatting
Imports should be on separate lines.
@@ -1954,21 +2385,31 @@ Imports are always put at the top of the file, just after any module comments
and docstrings and before module globals and constants. Imports should be
grouped from most generic to least generic:
-1. Python standard library imports. For example:
+1. Python future import statements. For example:
+
+ ```python
+ from __future__ import absolute_import
+ from __future__ import division
+ from __future__ import print_function
+ ```
+
+ See [above](#from-future-imports) for more information about those.
+
+2. Python standard library imports. For example:
```python
import sys
```
-2. [third-party](https://pypi.org/)
- module or package imports. For example:
+3. [third-party](https://pypi.org/) module
+ or package imports. For example:
```python
import tensorflow as tf
```
-3. Code repository
+4. Code repository
sub-package imports. For example:
@@ -1976,7 +2417,7 @@ grouped from most generic to least generic:
from otherproject.ai import mind
```
-4. **Deprecated:** application-specific imports that are part of the same
+5. **Deprecated:** application-specific imports that are part of the same
top level
sub-package as this file. For example:
@@ -1986,9 +2427,9 @@ grouped from most generic to least generic:
```
You may find older Google Python Style code doing this, but it is no longer
- required. **New code is encouraged not to bother with this.** Simply
- treat application-specific sub-package imports the same as other
- sub-package imports.
+ required. **New code is encouraged not to bother with this.** Simply treat
+ application-specific sub-package imports the same as other sub-package
+ imports.
Within each grouping, imports should be sorted lexicographically, ignoring case,
@@ -2020,8 +2461,10 @@ from otherproject.ai import soul
+
+
-### 3.14 Statements
+### 3.14 Statements
Generally only one statement per line.
@@ -2051,8 +2494,11 @@ No:
```
+
-### 3.15 Access Control
+
+
+### 3.15 Accessors
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
@@ -2068,20 +2514,15 @@ access the variable by the old method should break visibly so they are made
aware of the change in complexity.
+
+
-### 3.16 Naming
+### 3.16 Naming
+
+`module_name`, `package_name`, `ClassName`, `method_name`, `ExceptionName`,
+`function_name`, `GLOBAL_CONSTANT_NAME`, `global_var_name`, `instance_var_name`,
+`function_parameter_name`, `local_var_name`.
-`module_name`,
-`package_name`,
-`ClassName`,
-`method_name`,
-`ExceptionName`,
-`function_name`,
-`GLOBAL_CONSTANT_NAME`,
-`global_var_name`,
-`instance_var_name`,
-`function_parameter_name`,
-`local_var_name`.
Function names, variable names, and filenames should be descriptive; eschew
abbreviation. In particular, do not use abbreviations that are ambiguous or
@@ -2091,8 +2532,10 @@ letters within a word.
Always use a `.py` filename extension. Never use dashes.
+
+
-#### 3.16.1 Names to Avoid
+#### 3.16.1 Names to Avoid
- single character names except for counters or iterators. You may use "e" as
an exception identifier in try/except statements.
@@ -2100,8 +2543,10 @@ Always use a `.py` filename extension. Never use dashes.
- `__double_leading_and_trailing_underscore__` names (reserved by Python)
+
+
-#### 3.16.2 Naming Convention
+#### 3.16.2 Naming Conventions
- "Internal" means internal to a module, or protected or private within a
class.
@@ -2130,8 +2575,10 @@ Always use a `.py` filename extension. Never use dashes.
test methods.
+
+
-#### 3.16.3 File Naming
+#### 3.16.3 File Naming
Python filenames must have a `.py` extension and must not contain dashes (`-`).
This allows them to be imported and unittested. If you want an executable to be
@@ -2139,8 +2586,10 @@ accessible without the extension, use a symbolic link or a simple bash wrapper
containing `exec "$0.py" "$@"`.
+
+
-#### 3.16.4 Guidelines derived from Guido's Recommendations
+#### 3.16.4 Guidelines derived from Guido's Recommendations
@@ -2226,8 +2675,10 @@ unittests. Lint warnings take care of invalid access to protected members.
+
+
-### 3.17 Main
+### 3.17 Main
Even a file meant to be used as an executable should be importable and a mere
import should not have the side effect of executing the program's main
@@ -2250,8 +2701,10 @@ careful not to call functions, create objects, or perform other operations that
should not be executed when the file is being `pydoc`ed.
+
+
-### 3.18 Function length
+### 3.18 Function length
Prefer small and focused functions.
@@ -2271,12 +2724,16 @@ you want to use a piece of it in several different contexts, consider breaking
up the function into smaller and more manageable pieces.
+
+
-### 3.19 Type Annotations
+### 3.19 Type Annotations
+
+
+
-
-#### 3.19.1 General Rules
+#### 3.19.1 General Rules
* Familiarize yourself with [PEP-484](https://www.python.org/dev/peps/pep-0484/).
* In methods, only annotate `self`, or `cls` if it is necessary for proper type
@@ -2295,8 +2752,10 @@ up the function into smaller and more manageable pieces.
+
+
-#### 3.19.2 Line Breaking
+#### 3.19.2 Line Breaking
Try to follow the existing [indentation](#indentation) rules.
@@ -2335,7 +2794,7 @@ closing parenthesis with the def.
```python
Yes:
def my_method(
- self, **kw_args: Optional[MyLongType]
+ self, other_arg: Optional[MyLongType]
) -> Dict[OtherLongType, MyLongType]:
...
```
@@ -2346,7 +2805,7 @@ with the opening one, but this is less readable.
```python
No:
def my_method(self,
- **kw_args: Optional[MyLongType]
+ other_arg: Optional[MyLongType]
) -> Dict[OtherLongType, MyLongType]:
...
```
@@ -2387,8 +2846,10 @@ def my_function(
```
-
-#### 3.19.3 Forward Declarations
+
+
+
+#### 3.19.3 Forward Declarations
If you need to use a class name from the same module that is not yet defined --
for example, if you need the class inside the class declaration, or if you use a
@@ -2402,8 +2863,10 @@ class MyClass(object):
```
+
+
-#### 3.19.4 Default Values
+#### 3.19.4 Default Values
As per
[PEP-008](https://www.python.org/dev/peps/pep-0008/#other-recommendations), use
@@ -2422,8 +2885,10 @@ def func(a:int=0) -> int:
```
+
+
-#### 3.19.5 NoneType
+#### 3.19.5 NoneType
In the Python type system, `NoneType` is a "first class" type, and for typing
purposes, `None` is an alias for `NoneType`. If an argument can be `None`, it
@@ -2451,14 +2916,18 @@ def implicit_optional(a: Text = None) -> Text:
```
+
-#### 3.19.6 Type Aliases
+
+
+#### 3.19.6 Type Aliases
You can declare aliases of complex types. The name of an alias should be
CapWorded. If the alias is used only in this module, it should be
\_Private.
-For example, if the name of module together with the type is too long:
+For example, if the name of the module together with the name of the type is too
+long:
```python
_ShortName = module_with_long_name.TypeWithLongName
@@ -2469,8 +2938,10 @@ Other examples are complex nested types and multiple return variables from a
function (as a tuple).
+
+
-#### 3.19.7 Ignoring Types
+#### 3.19.7 Ignoring Types
You can disable type checking on a line with the special comment
`# type: ignore`.
@@ -2482,18 +2953,35 @@ You can disable type checking on a line with the special comment
```
-
-#### 3.19.8 Typing internal variables
+
+
+
+#### 3.19.8 Typing Variables
If an internal variable has a type that is hard or impossible to infer, you can
-supply it as a special comment:
+specify its type in a couple ways.
+
+
+[*Type Comments:*](#type-comments)
+: Use a `# type:` comment on the end of the line
+
+ ```python
+ a = SomeUndecoratedFunction() # type: Foo
+ ```
+
+[*Annotated Assignments*](#annotated-assignments)
+: Use a colon and type between the variable name and value, as with function
+ arguments.
+
+ ```python
+ a: Foo = SomeUndecoratedFunction()
+ ```
-```python
-a = SomeUndecoratedFunction() # type: Foo
-```
+
+
-#### 3.19.9 Tuples vs Lists
+#### 3.19.9 Tuples vs Lists
Unlike Lists, which can only have a single type, Tuples can have either a single
repeated type or a set number of elements with different types. The latter is
@@ -2506,8 +2994,11 @@ c = (1, "2", 3.5) # type: Tuple[int, Text, float]
```
+
-#### 3.19.10 TypeVar
+
+
+#### 3.19.10 TypeVars
The Python type system has
[generics](https://www.python.org/dev/peps/pep-0484/#generics). The factory
@@ -2544,9 +3035,10 @@ def check_length(x: AnyStr) -> AnyStr:
```
-
+
-#### 3.19.11 String types
+
+#### 3.19.11 String types
The proper type for annotating strings depends on what versions of Python the
code is intended for.
@@ -2555,11 +3047,11 @@ For Python 3 only code, prefer to use `str`. `Text` is also acceptable. Be
consistent in using one or the other.
For Python 2 compatible code, use `Text`. In some rare cases, `str` may make
-sense; typically to aid compatiblity when the return types aren't the same
+sense; typically to aid compatibility when the return types aren't the same
between the two Python versions. Avoid using `unicode`: it doesn't exist in
Python 3.
-The reason this discreprency exists is because `str` means different things
+The reason this discrepancy exists is because `str` means different things
depending on the Python version.
```python
@@ -2607,8 +3099,10 @@ return type is the same as the argument type in the code above, use
Writing it like this will simplify the process of porting the code to Python 3.
+
+
-#### 3.19.12 Imports For Typing
+#### 3.19.12 Imports For Typing
For classes from the `typing` module, always import the class itself. You are
explicitly allowed to import multiple specific classes on one line from the
@@ -2629,8 +3123,10 @@ from typing import Any as AnyType
```
+
+
-#### 3.19.13 Conditional Imports
+#### 3.19.13 Conditional Imports
Use conditional imports only in exceptional cases where the additional imports
needed for type checking must be avoided at runtime. This pattern is
@@ -2658,8 +3154,10 @@ def f(x: "sketch.Sketch"): ...
```
+
+
-#### 3.19.14 Circular Dependencies
+#### 3.19.14 Circular Dependencies
Circular dependencies that are caused by typing are code smells. Such code is a
good candidate for refactoring. Although technically it is possible to keep
@@ -2683,8 +3181,10 @@ def my_method(self, var: some_mod.SomeType) -> None:
+
-#### 3.19.15 Generics
+
+#### 3.19.15 Generics
When annotating, prefer to specify type parameters for generic types; otherwise,
[the generics' parameters will be assumed to be `Any`](https://www.python.org/dev/peps/pep-0484/#the-any-type).
@@ -2719,7 +3219,10 @@ def get_names(employee_ids: List[T]) -> Dict[T, Text]:
```
-## 4 Parting Words
+
+
+
+## 4 Parting Words
*BE CONSISTENT*.