StarMirror/styleguide
1
0
Fork 0
mirror of https://github.com/google/styleguide.git synced 2024-03-22 13:11:43 +08:00
Code Issues Projects Releases Wiki Activity

Project import generated by Copybara.

Browse Source 
PiperOrigin-RevId: 325285627
This commit is contained in:
Google Python team 2020-08-06 19:30:10 +00:00 committed by Gregory P. Smith [Google LLC]
parent 5142f2245c
commit 7645d63652
1 changed files with 129 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

234
pyguide.md
View File

@ -6,7 +6,6 @@ See README.md for details.
# Google Python Style Guide # Google Python Style Guide
<!-- https://github.com/google/styleguide/issues/566: Can this render properly on Github Pages? --> <!-- https://github.com/google/styleguide/issues/566: Can this render properly on Github Pages? -->
<details> <details>
@ -198,9 +197,10 @@ Run `pylint` over your code.
<a id="lint-definition"></a> <a id="lint-definition"></a>
#### 2.1.1 Definition #### 2.1.1 Definition
`pylint` is a tool for finding bugs and style problems in Python source `pylint`
code. It finds problems that are typically caught by a compiler for less dynamic is a tool for finding bugs and style problems in Python source code. It finds
languages like C and C++. Because of the dynamic nature of Python, some problems that are typically caught by a compiler for less dynamic languages like
C and C++. Because of the dynamic nature of Python, some
warnings may be incorrect; however, spurious warnings should be fairly warnings may be incorrect; however, spurious warnings should be fairly
infrequent. infrequent.
@ -218,8 +218,9 @@ Catches easy-to-miss errors like typos, using-vars-before-assignment, etc.
<a id="lint-cons"></a> <a id="lint-cons"></a>
#### 2.1.3 Cons #### 2.1.3 Cons
`pylint` isn't perfect. To take advantage of it, we'll need to sometimes: a) `pylint`
Write around it b) Suppress its warnings or c) Improve it. 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.
<a id="s2.1.4-decision"></a> <a id="s2.1.4-decision"></a>
<a id="214-decision"></a> <a id="214-decision"></a>
@ -227,7 +228,9 @@ Write around it b) Suppress its warnings or c) Improve it.
<a id="lint-decision"></a> <a id="lint-decision"></a>
#### 2.1.4 Decision #### 2.1.4 Decision
Make sure you run `pylint` on your code. Make sure you run
`pylint`
on your code.
Suppress warnings if they are inappropriate so that other issues are not hidden. Suppress warnings if they are inappropriate so that other issues are not hidden.
@ -237,7 +240,8 @@ To suppress warnings, you can set a line-level comment:
dict = 'something awful' # Bad Idea... pylint: disable=redefined-builtin dict = 'something awful' # Bad Idea... pylint: disable=redefined-builtin
``` ```
`pylint` warnings are each identified by symbolic name (`empty-docstring`) `pylint`
warnings are each identified by symbolic name (`empty-docstring`)
Google-specific warnings start with `g-`. Google-specific warnings start with `g-`.
If the reason for the suppression is not clear from the symbolic name, add an If the reason for the suppression is not clear from the symbolic name, add an
@ -246,7 +250,9 @@ explanation.
Suppressing in this way has the advantage that we can easily search for Suppressing in this way has the advantage that we can easily search for
suppressions and revisit them. suppressions and revisit them.
You can get a list of `pylint` warnings by doing: You can get a list of
`pylint`
warnings by doing:
```shell ```shell
pylint --list-msgs pylint --list-msgs
@ -318,13 +324,13 @@ Module names can still collide. Some module names are inconveniently long.
<a id="imports-decision"></a> <a id="imports-decision"></a>
#### 2.2.4 Decision #### 2.2.4 Decision
* Use `import x` for importing packages and modules. * Use `import x` for importing packages and modules.
* Use `from x import y` where `x` is the package prefix and `y` is the module * Use `from x import y` where `x` is the package prefix and `y` is the module
name with no prefix. name with no prefix.
* Use `from x import y as z` if two modules named `y` are to be imported or if * Use `from x import y as z` if two modules named `y` are to be imported or if
`y` is an inconveniently long name. `y` is an inconveniently long name.
* Use `import y as z` only when `z` is a standard abbreviation (e.g., `np` for * Use `import y as z` only when `z` is a standard abbreviation (e.g., `np` for
`numpy`). `numpy`).
For example the module `sound.effects.echo` may be imported as follows: For example the module `sound.effects.echo` may be imported as follows:
@ -357,7 +363,7 @@ 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 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. path not being what the author expected. Makes it easier to find modules.
<a id="s2.3.2-cons"></a> <a id="s2.3.2-cons"></a>
<a id="232-cons"></a> <a id="232-cons"></a>
@ -366,7 +372,7 @@ 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 Makes it harder to deploy code because you have to replicate the package
hierarchy. Not really a problem with modern deployment mechanisms. hierarchy. Not really a problem with modern deployment mechanisms.
<a id="s2.3.3-decision"></a> <a id="s2.3.3-decision"></a>
<a id="233-decision"></a> <a id="233-decision"></a>
@ -406,7 +412,7 @@ import jodie
``` ```
The directory the main binary is located in should not be assumed to be in The directory the main binary is located in should not be assumed to be in
`sys.path` despite that happening in some environments. This being the case, `sys.path` despite that happening in some environments. This being the case,
code should assume that `import jodie` refers to a third party or top level code should assume that `import jodie` refers to a third party or top level
package named `jodie`, not a local `jodie.py`. package named `jodie`, not a local `jodie.py`.
@ -647,9 +653,9 @@ and less readable.
#### 2.6.4 Decision #### 2.6.4 Decision
They are fine with some caveats. Avoid nested functions or classes except when 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 closing over a local value. Do not nest a function just to hide it from users of
of a module. Instead, prefix its name with an \_ at the module level so that it a module. Instead, prefix its name with an \_ at the module level so that it can
can still be accessed by tests. still be accessed by tests.
<a id="s2.7-comprehensions"></a> <a id="s2.7-comprehensions"></a>
<a id="s2.7-list_comprehensions"></a> <a id="s2.7-list_comprehensions"></a>
@ -796,8 +802,8 @@ means a dictionary). This is also an advantage.
Use default iterators and operators for types that support them, like lists, Use default iterators and operators for types that support them, like lists,
dictionaries, and files. The built-in types define iterator methods, too. Prefer dictionaries, and files. The built-in types define iterator methods, too. Prefer
these methods to methods that return lists, except that you should not mutate a these methods to methods that return lists, except that you should not mutate a
container while iterating over it. Never use Python 2 specific iteration container while iterating over it. Never use Python 2 specific iteration methods
methods such as `dict.iter*()` unless necessary. such as `dict.iter*()` unless necessary.
```python ```python
Yes: for key in adict: ... Yes: for key in adict: ...
@ -903,8 +909,8 @@ 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 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 longer than 60-80 chars, it's probably better to define it as a regular
function](#lexical-scoping). [nested function](#lexical-scoping).
For common operations like multiplication, use the functions from the `operator` For common operations like multiplication, use the functions from the `operator`
module instead of lambda functions. For example, prefer `operator.mul` to module instead of lambda functions. For example, prefer `operator.mul` to
@ -925,8 +931,8 @@ Okay for simple cases.
#### 2.11.1 Definition #### 2.11.1 Definition
Conditional expressions (sometimes called a “ternary operator”) are mechanisms Conditional expressions (sometimes called a “ternary operator”) are mechanisms
that provide a shorter syntax for if statements. For example: that provide a shorter syntax for if statements. For example: `x = 1 if cond
`x = 1 if cond else 2`. else 2`.
<a id="s2.11.2-pros"></a> <a id="s2.11.2-pros"></a>
<a id="2112-pros"></a> <a id="2112-pros"></a>
@ -989,9 +995,9 @@ 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, 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, e.g., `def foo(a, b=0):`. If `foo` is called with only one argument, `b` is set
`b` is set to 0. If it is called with two arguments, `b` has the value of the to 0. If it is called with two arguments, `b` has the value of the second
second argument. argument.
<a id="s2.12.2-pros"></a> <a id="s2.12.2-pros"></a>
<a id="2122-pros"></a> <a id="2122-pros"></a>
@ -1163,8 +1169,8 @@ 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 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 "rule of thumb" is that all "empty" values are considered false, so `0, None,
`0, None, [], {}, ''` all evaluate as false in a boolean context. [], {}, ''` all evaluate as false in a boolean context.
<a id="s2.14.2-pros"></a> <a id="s2.14.2-pros"></a>
<a id="2142-pros"></a> <a id="2142-pros"></a>
@ -1351,8 +1357,8 @@ def foo(x):
bar() bar()
``` ```
So `foo([1, 2, 3])` will print `1 2 3 3`, not `1 2 3 So `foo([1, 2, 3])` will print `1 2 3 3`,
4`. not `1 2 3 4`.
<a id="s2.16.4-decision"></a> <a id="s2.16.4-decision"></a>
<a id="2164-decision"></a> <a id="2164-decision"></a>
@ -1378,8 +1384,7 @@ Use decorators judiciously when there is a clear advantage. Avoid
<a id="decorators-definition"></a> <a id="decorators-definition"></a>
#### 2.17.1 Definition #### 2.17.1 Definition
[Decorators for Functions and [Decorators for Functions and Methods](https://docs.python.org/3/glossary.html#term-decorator)
Methods](https://docs.python.org/3/glossary.html#term-decorator)
(a.k.a "the `@` notation"). One common decorator is `@property`, used for (a.k.a "the `@` notation"). One common decorator is `@property`, used for
converting ordinary methods into dynamically computed attributes. However, the converting ordinary methods into dynamically computed attributes. However, the
decorator syntax allows for user-defined decorators as well. Specifically, for decorator syntax allows for user-defined decorators as well. Specifically, for
@ -1514,8 +1519,8 @@ longer but is straightforward.
Avoid these features in your code. Avoid these features in your code.
Standard library modules and classes that internally use these features are okay Standard library modules and classes that internally use these features are okay
to use (for example, `abc.ABCMeta`, `collections.namedtuple`, `dataclasses`, to use (for example, `abc.ABCMeta`, `collections.namedtuple`, `dataclasses`, and
and `enum`). `enum`).
<a id="s2.20-modern-python"></a> <a id="s2.20-modern-python"></a>
<a id="220-modern-python"></a> <a id="220-modern-python"></a>
@ -1523,9 +1528,9 @@ and `enum`).
<a id="modern-python"></a> <a id="modern-python"></a>
### 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 Python 3 is here! While not every project is ready to use it yet,
use it yet, all code should be written to be 3 compatible (and tested under all code should be written to be 3 compatible (and tested under 3 when
3 when possible). possible).
<a id="s2.20.1-definition"></a> <a id="s2.20.1-definition"></a>
<a id="2201-definition"></a> <a id="2201-definition"></a>
@ -1610,14 +1615,13 @@ make your code cleaner and life easier.
You can annotate Python 3 code with type hints according to 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 [PEP-484](https://www.python.org/dev/peps/pep-0484/), and type-check the code at
build time with a type checking tool like build time with a type checking tool like [pytype](https://github.com/google/pytype).
[pytype](https://github.com/google/pytype).
Type annotations can be in the source or in a [stub pyi Type annotations can be in the source or in a
file](https://www.python.org/dev/peps/pep-0484/#stub-files). Whenever possible, [stub pyi file](https://www.python.org/dev/peps/pep-0484/#stub-files). Whenever
annotations should be in the source. Use pyi files for third-party or extension possible, annotations should be in the source. Use pyi files for third-party or
modules. extension modules.
<a id="s2.21.1-definition"></a> <a id="s2.21.1-definition"></a>
@ -1662,7 +1666,10 @@ your ability to use [Power Features](#power-features).
<a id="typed-code-cons"></a> <a id="typed-code-cons"></a>
#### 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) 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). may reduce your ability to use [Power Features](#power-features).
<a id="s2.21.4-decision"></a> <a id="s2.21.4-decision"></a>
@ -1710,13 +1717,13 @@ Explicit exceptions to the 80 character limit:
- URLs, pathnames, or long flags in comments. - URLs, pathnames, or long flags in comments.
- Long string module level constants not containing whitespace that would be - Long string module level constants not containing whitespace that would be
inconvenient to split across lines such as URLs or pathnames. inconvenient to split across lines such as URLs or pathnames.
- Pylint disable comments. (e.g.: `# pylint: disable=invalid-name`) - Pylint disable comments. (e.g.: `# pylint: disable=invalid-name`)
Do not use backslash line continuation except for `with` statements requiring Do not use backslash line continuation except for `with` statements requiring
three or more context managers. three or more context managers.
Make use of Python's [implicit line joining inside parentheses, brackets and Make use of Python's
braces](http://docs.python.org/reference/lexical_analysis.html#implicit-line-joining). [implicit line joining inside parentheses, brackets and braces](http://docs.python.org/reference/lexical_analysis.html#implicit-line-joining).
If necessary, you can add an extra pair of parentheses around an expression. If necessary, you can add an extra pair of parentheses around an expression.
```python ```python
@ -1972,7 +1979,6 @@ Yes: spam(1)
No: spam (1) No: spam (1)
``` ```
```python ```python
Yes: dict['key'] = list[index] Yes: dict['key'] = list[index]
``` ```
@ -1997,9 +2003,9 @@ No: x<1
``` ```
Never use spaces around `=` when passing keyword arguments or defining a default Never use spaces around `=` when passing keyword arguments or defining a default
parameter value, with one exception: [when a type annotation is parameter value, with one exception:
present](#typing-default-values), _do_ use spaces around the `=` for the default [when a type annotation is present](#typing-default-values), _do_ use spaces
parameter value. around the `=` for the default parameter value.
```python ```python
Yes: def complex(real, imag=0.0): return Magic(r=real, i=imag) Yes: def complex(real, imag=0.0): return Magic(r=real, i=imag)
@ -2049,9 +2055,7 @@ program with
`#!/usr/bin/python` with an optional single digit `2` or `3` suffix per `#!/usr/bin/python` with an optional single digit `2` or `3` suffix per
[PEP-394](https://www.google.com/url?sa=D&q=http://www.python.org/dev/peps/pep-0394/). [PEP-394](https://www.google.com/url?sa=D&q=http://www.python.org/dev/peps/pep-0394/).
This line is used by the kernel to find the Python interpreter, but is ignored This line is used by the kernel to find the Python interpreter, but is ignored by Python when importing modules. It is only necessary on a file that will be executed directly.
by Python when importing modules. It is only necessary on a file that will be
executed directly.
<a id="s3.8-comments-and-docstrings"></a> <a id="s3.8-comments-and-docstrings"></a>
<a id="s3.8-comments"></a> <a id="s3.8-comments"></a>
@ -2075,10 +2079,11 @@ first statement in a package, module, class or function. These strings can be
extracted automatically through the `__doc__` member of the object and are used extracted automatically through the `__doc__` member of the object and are used
by `pydoc`. by `pydoc`.
(Try running `pydoc` on your module to see how it looks.) Always use the three (Try running `pydoc` on your module to see how it looks.) Always use the three
double-quote `"""` format for docstrings (per [PEP double-quote `"""` format for docstrings (per
257](https://www.google.com/url?sa=D&q=http://www.python.org/dev/peps/pep-0257/)). [PEP 257](https://www.google.com/url?sa=D&q=http://www.python.org/dev/peps/pep-0257/)).
A docstring should be organized as a summary line (one physical line) terminated A docstring should be organized as a summary line (one physical line not
by a period, question mark, or exclamation point, followed by a blank line, exceeding 80 characters) terminated by a period, question mark, or exclamation
point. When writing more (encouraged), this must be followed by a blank line,
followed by the rest of the docstring starting at the same cursor position as followed by the rest of the docstring starting at the same cursor position as
the first quote of the first line. There are more formatting guidelines for the first quote of the first line. There are more formatting guidelines for
docstrings below. docstrings below.
@ -2090,9 +2095,7 @@ docstrings below.
<a id="module-docs"></a> <a id="module-docs"></a>
#### 3.8.2 Modules #### 3.8.2 Modules
Every file should contain license boilerplate. 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)
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 Files should start with a docstring describing the contents and usage of the
module. module.
@ -2158,11 +2161,10 @@ aptly described using a one-line docstring.
separated by a colon followed by either a space or newline. If the separated by a colon followed by either a space or newline. If the
description is too long to fit on a single 80-character line, use a hanging description is too long to fit on a single 80-character line, use a hanging
indent of 2 or 4 spaces more than the parameter name (be consistent with the indent of 2 or 4 spaces more than the parameter name (be consistent with the
rest of the docstrings in the file). rest of the docstrings in the file). The description should include required
The description should include required type(s) if the code does not contain type(s) if the code does not contain a corresponding type annotation. If a
a corresponding type annotation. If a function accepts `*foo` (variable function accepts `*foo` (variable length argument lists) and/or `**bar`
length argument lists) and/or `**bar` (arbitrary keyword arguments), they (arbitrary keyword arguments), they should be listed as `*foo` and `**bar`.
should be listed as `*foo` and `**bar`.
<a id="doc-function-returns"></a> <a id="doc-function-returns"></a>
[*Returns:* (or *Yields:* for generators)](#doc-function-returns) [*Returns:* (or *Yields:* for generators)](#doc-function-returns)
@ -2298,10 +2300,10 @@ class SampleClass:
#### 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 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 to have to explain it at the next [code review](http://en.wikipedia.org/wiki/Code_review),
review](http://en.wikipedia.org/wiki/Code_review), you should comment it you should comment it now. Complicated operations get a few lines of comments
now. Complicated operations get a few lines of comments before the operations before the operations commence. Non-obvious ones get comments at the end of the
commence. Non-obvious ones get comments at the end of the line. line.
```python ```python
# We use a weighted dictionary search to find out where i is in # We use a weighted dictionary search to find out where i is in
@ -2766,7 +2768,26 @@ Always use a `.py` filename extension. Never use dashes.
- `__double_leading_and_trailing_underscore__` names (reserved by Python) - `__double_leading_and_trailing_underscore__` names (reserved by Python)
- module. - offensive terms
<a id="s3.16.2-naming-conventions"></a>
<a id="3162-naming-convention"></a>
<a id="naming-conventions"></a>
#### 3.16.2 Naming Conventions
- "Internal" means internal to a module, or protected or private within a
class.
- Prepending a single underscore (`_`) has some support for protecting module
variables and functions (linters will flag protected member access). While
prepending a double underscore (`__` aka "dunder") to an instance variable
or method effectively makes the variable or method private to its class
(using name mangling) we discourage its use as it impacts readability and
testability and isn't *really* private.
- Place related classes and top-level functions together in a
module.
Unlike Java, there is no need to limit yourself to one class per module. Unlike Java, there is no need to limit yourself to one class per module.
- Use CapWords for class names, but lower\_with\_under.py for module names. - Use CapWords for class names, but lower\_with\_under.py for module names.
@ -2936,10 +2957,11 @@ Keeping your functions short and simple makes it easier for other people to read
and modify your code. and modify your code.
You could find long and complicated functions when working with You could find long and complicated functions when working with
some code. Do not be intimidated by modifying existing code: if working with such some
a function proves to be difficult, you find that errors are hard to debug, or code. Do not be intimidated by modifying existing code: if working with such a
you want to use a piece of it in several different contexts, consider breaking function proves to be difficult, you find that errors are hard to debug, or you
up the function into smaller and more manageable pieces. want to use a piece of it in several different contexts, consider breaking up
the function into smaller and more manageable pieces.
<a id="s3.19-type-annotations"></a> <a id="s3.19-type-annotations"></a>
<a id="319-type-annotations"></a> <a id="319-type-annotations"></a>
@ -2954,20 +2976,22 @@ up the function into smaller and more manageable pieces.
<a id="typing-general"></a> <a id="typing-general"></a>
#### 3.19.1 General Rules #### 3.19.1 General Rules
* Familiarize yourself with [PEP-484](https://www.python.org/dev/peps/pep-0484/). * Familiarize yourself with
* In methods, only annotate `self`, or `cls` if it is necessary for proper type [PEP-484](https://www.python.org/dev/peps/pep-0484/).
information. e.g., `@classmethod def create(cls: Type[T]) -> T: return cls()` * In methods, only annotate `self`, or `cls` if it is necessary for proper
* If any other variable or a returned type should not be expressed, use `Any`. type information. e.g., `@classmethod def create(cls: Type[T]) -> T: return
* You are not required to annotate all the functions in a module. cls()`
- At least annotate your public APIs. * If any other variable or a returned type should not be expressed, use `Any`.
- Use judgment to get to a good balance between safety and clarity on the * You are not required to annotate all the functions in a module.
one hand, and flexibility on the other. - At least annotate your public APIs.
- Annotate code that is prone to type-related errors (previous bugs or - Use judgment to get to a good balance between safety and clarity on the
complexity). one hand, and flexibility on the other.
- Annotate code that is hard to understand. - Annotate code that is prone to type-related errors (previous bugs or
- Annotate code as it becomes stable from a types perspective. In many complexity).
cases, you can annotate all the functions in mature code without losing - Annotate code that is hard to understand.
too much flexibility. - Annotate code as it becomes stable from a types perspective. In many
cases, you can annotate all the functions in mature code without losing
too much flexibility.
<a id="s3.19.2-line-breaking"></a> <a id="s3.19.2-line-breaking"></a>
<a id="3192-line-breaking"></a> <a id="3192-line-breaking"></a>
@ -3017,8 +3041,9 @@ def my_method(
... ...
``` ```
`pylint` allows you to move the closing parenthesis to a new line and align `pylint`
with the opening one, but this is less readable. allows you to move the closing parenthesis to a new line and align with the
opening one, but this is less readable.
```python ```python
No: No:
@ -3096,6 +3121,7 @@ Yes:
def func(a: int = 0) -> int: def func(a: int = 0) -> int:
... ...
``` ```
```python ```python
No: No:
def func(a:int=0) -> int: def func(a:int=0) -> int:
@ -3143,8 +3169,7 @@ 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 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 CapWorded. If the alias is used only in this module, it should be \_Private.
\_Private.
For example, if the name of the module together with the name of the type is too For example, if the name of the module together with the name of the type is too
long: long:
@ -3164,8 +3189,8 @@ function (as a tuple).
<a id="typing-ignore"></a> <a id="typing-ignore"></a>
#### 3.19.7 Ignoring Types #### 3.19.7 Ignoring Types
You can disable type checking on a line with the special comment You can disable type checking on a line with the special comment `# type:
`# type: ignore`. ignore`.
`pytype` has a disable option for specific errors (similar to lint): `pytype` has a disable option for specific errors (similar to lint):
@ -3342,8 +3367,8 @@ from typing import Any, Dict, Optional
Given that this way of importing from `typing` adds items to the local Given that this way of importing from `typing` adds items to the local
namespace, any names in `typing` should be treated similarly to keywords, and namespace, any names in `typing` should be treated similarly to keywords, and
not be defined in your Python code, typed or not. If there is a collision not be defined in your Python code, typed or not. If there is a collision
between a type and an existing name in a module, import it using between a type and an existing name in a module, import it using `import x as
`import x as y`. y`.
```python ```python
from typing import Any as AnyType from typing import Any as AnyType
@ -3360,8 +3385,8 @@ needed for type checking must be avoided at runtime. This pattern is
discouraged; alternatives such as refactoring the code to allow top level discouraged; alternatives such as refactoring the code to allow top level
imports should be preferred. imports should be preferred.
Imports that are needed only for type annotations can be placed within an Imports that are needed only for type annotations can be placed within an `if
`if TYPE_CHECKING:` block. TYPE_CHECKING:` block.
- Conditionally imported types need to be referenced as strings, to be forward - Conditionally imported types need to be referenced as strings, to be forward
compatible with Python 3.6 where the annotation expressions are actually compatible with Python 3.6 where the annotation expressions are actually
@ -3465,4 +3490,3 @@ 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 from the existing code around it, it throws readers out of their rhythm when
they go to read it. Avoid this. they go to read it. Avoid this.