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: 224224079
This commit is contained in:
Google Python team 2018-12-05 14:40:50 -08:00 committed by Gregory P. Smith [Google LLC]
parent fdc20e8645
commit 6271f3f473
1 changed files with 68 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
pyguide.md
View File

@ -106,9 +106,9 @@ last does not enforce that the arguments are actually unused.
<a id="imports"></a> <a id="imports"></a>
### 2.2 Imports ### 2.2 Imports
Use `import`s for packages and modules only, not for individual classes or Use `import` statements for packages and modules only, not for individual
functions. Note that there is an explicit exemption for imports from the classes or functions. Note that there is an explicit exemption for imports from
[typing module](#typing-imports). the [typing module](#typing-imports).
<a id="s2.2.1-definition"></a> <a id="s2.2.1-definition"></a>
#### 2.2.1 Definition #### 2.2.1 Definition
@ -509,20 +509,23 @@ 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. container while iterating over it. Never use Python 2 specific iteration
methods such as `dict.iter*()` unless necessary.
```python ```python
Yes: for key in adict: ... Yes: for key in adict: ...
if key not in adict: ... if key not in adict: ...
if obj in alist: ... if obj in alist: ...
for line in afile: ... for line in afile: ...
for k, v in dict.iteritems(): ... for k, v in adict.items(): ...
for k, v in six.iteritems(adict): ...
``` ```
```python ```python
No: for key in adict.keys(): ... No: for key in adict.keys(): ...
if not adict.has_key(key): ... if not adict.has_key(key): ...
for line in afile.readlines(): ... for line in afile.readlines(): ...
for k, v in dict.iteritems(): ...
``` ```
<a id="s2.9-generators"></a> <a id="s2.9-generators"></a>
@ -584,9 +587,9 @@ function may only contain an expression.
<a id="s2.10.4-decision"></a> <a id="s2.10.4-decision"></a>
#### 2.10.4 Decision #### 2.10.4 Decision
Okay to use them for one-liners. If the code inside the lambda function is any 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 [nested
function. 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
@ -1084,7 +1087,7 @@ use it yet, all code should be written to be 3 compatible (and tested under
#### 2.20.1 Definition #### 2.20.1 Definition
Python 3 is a significant change in the Python language. While existing code is 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 often written with 2.7 in mind, there are some simple things to do to make code
more explicit about its intentions and thus better prepared for use under Python more explicit about its intentions and thus better prepared for use under Python
3 without modification. 3 without modification.
@ -1197,7 +1200,7 @@ This highly depends on the complexity of your project. Give it a try.
<a id="semicolons"></a> <a id="semicolons"></a>
### 3.1 Semicolons ### 3.1 Semicolons
Do not terminate your lines with semi-colons and do not use semi-colons to put Do not terminate your lines with semicolons, and do not use semicolons to put
two statements on the same line. two statements on the same line.
<a id="s3.2-line-length"></a> <a id="s3.2-line-length"></a>
@ -1430,7 +1433,7 @@ No: spam( ham[ 1 ], { eggs: 2 }, [ ] )
``` ```
No whitespace before a comma, semicolon, or colon. Do use whitespace after a No whitespace before a comma, semicolon, or colon. Do use whitespace after a
comma, semicolon, or colon except at the end of the line. comma, semicolon, or colon, except at the end of the line.
```python ```python
Yes: if x == 4: Yes: if x == 4:
@ -1477,10 +1480,10 @@ Yes: x == 1
No: x<1 No: x<1
``` ```
Never use spaces around the '=' sign when passing keyword arguments. Never use spaces around `=` when passing keyword arguments or defining a default
Only use spaces around the '=' sign defining a default parameter value parameter value, with one exception: [when a type annotation is
[when a type annotation is present](#typing-default-values), present](#typing-default-values), _do_ use spaces around the `=` for the default
do not use spaces around '=' for default parameter values otherwise. 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)
@ -1543,7 +1546,7 @@ inline comments.
<a id="comments-in-doc-strings"></a> <a id="comments-in-doc-strings"></a>
#### 3.8.1 Docstrings #### 3.8.1 Docstrings
Python uses docstrings for commenting code. A doc string is a string that is the 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 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`.
@ -1568,8 +1571,7 @@ LGPL, GPL)
<a id="functions-and-methods"></a> <a id="functions-and-methods"></a>
#### 3.8.3 Functions and Methods #### 3.8.3 Functions and Methods
As used in this section "function" applies to methods, functions, and In this section, "function" means a method, function, or generator.
generators.
A function must have a docstring, unless it meets all of the following criteria: A function must have a docstring, unless it meets all of the following criteria:
@ -1585,13 +1587,13 @@ function's calling syntax and its semantics, not its implementation. For tricky
code, comments alongside the code are more appropriate than using docstrings. 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 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 sending the reader to its overridden method's docstring, such as `"""See base
`"""See base class."""`. The rationale is that there is no need to repeat in class."""`. The rationale is that there is no need to repeat in many places
many places documentation that is already present in the base method's documentation that is already present in the base method's docstring. However,
docstring. However, if the overriding method's behavior is substantially if the overriding method's behavior is substantially different from the
different than that of the overridden method or details need to be provided overridden method, or details need to be provided (e.g., documenting additional
about it (e.g., documenting additional side-effects), a docstring is required on side effects), a docstring with at least those differences is required on the
the overriding method, with at least those differences. overriding method.
Certain aspects of a function should be documented in special sections, listed 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. below. Each section begins with a heading line, which ends with a colon.
@ -1764,9 +1766,9 @@ No: class SampleClass:
pass pass
``` ```
Inheriting from `object` is needed to make properties work properly in Python 2, Inheriting from `object` is needed to make properties work properly in Python 2
and can protect your code from some potential incompatibility with Python 3. It and can protect your code from potential incompatibility with Python 3. It also
also defines special methods that implement the default semantics of objects defines special methods that implement the default semantics of objects
including `__new__`, `__init__`, `__delattr__`, `__getattribute__`, including `__new__`, `__init__`, `__delattr__`, `__getattribute__`,
`__setattr__`, `__hash__`, `__repr__`, and `__str__`. `__setattr__`, `__hash__`, `__repr__`, and `__str__`.
@ -1860,28 +1862,28 @@ Don't do this.
Explicitly close files and sockets when done with them. Explicitly close files and sockets when done with them.
Leaving files, sockets or other file-like objects open unnecessarily has many Leaving files, sockets or other file-like objects open unnecessarily has many
downsides, including: downsides:
- They may consume limited system resources, such as file descriptors. Code - They may consume limited system resources, such as file descriptors. Code
that deals with many such objects may exhaust those resources unnecessarily that deals with many such objects may exhaust those resources unnecessarily
if they're not returned to the system promptly after use. if they're not returned to the system promptly after use.
- Holding files open may prevent other actions being performed on them, such - Holding files open may prevent other actions such as moving or deleting
as moves or deletion. them.
- Files and sockets that are shared throughout a program may inadvertently be - Files and sockets that are shared throughout a program may inadvertently be
read from or written to after logically being closed. If they are actually read from or written to after logically being closed. If they are actually
closed, attempts to read or write from them will throw exceptions, making closed, attempts to read or write from them will throw exceptions, making
the problem known sooner. the problem known sooner.
Furthermore, while files and sockets are automatically closed when the file Furthermore, while files and sockets are automatically closed when the file
object is destructed, tying the life-time of the file object to the state of the object is destructed, tying the lifetime of the file object to the state of the
file is poor practice, for several reasons: file is poor practice:
- There are no guarantees as to when the runtime will actually run the file's - There are no guarantees as to when the runtime will actually run the file's
destructor. Different Python implementations use different memory management destructor. Different Python implementations use different memory management
techniques, such as delayed Garbage Collection, which may increase the techniques, such as delayed Garbage Collection, which may increase the
object's lifetime arbitrarily and indefinitely. object's lifetime arbitrarily and indefinitely.
- Unexpected references to the file may keep it around longer than intended - Unexpected references to the file, e.g. in globals or exception tracebacks,
(e.g. in tracebacks of exceptions, inside globals, etc). may keep it around longer than intended.
The preferred way to manage files is using the ["with" The preferred way to manage files is using the ["with"
statement](http://docs.python.org/reference/compound_stmts.html#the-with-statement): statement](http://docs.python.org/reference/compound_stmts.html#the-with-statement):
@ -1910,13 +1912,16 @@ with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page:
Use `TODO` comments for code that is temporary, a short-term solution, or Use `TODO` comments for code that is temporary, a short-term solution, or
good-enough but not perfect. good-enough but not perfect.
`TODO`s should include the string `TODO` in all caps, followed by the A `TODO` comment begins with the string `TODO` in all caps and a parenthesized
name, e-mail address, or other identifier name, e-mail address, or other identifier
of the person or issue with the best context about the problem referenced by the of the person or issue with the best context about the problem. This is followed
`TODO`, in parentheses. A comment explaining what there is to do is required. by an explanation of what there is to do.
The main purpose is to have a consistent `TODO` format that can be searched to
find out how to get more details upon request. A `TODO` is not a commitment that The purpose is to have a consistent `TODO` format that can be searched to find
the person referenced will fix the problem. Thus when you create a `TODO`, it is almost always your name that is given. out how to get more details. A `TODO` is not a commitment that the person
referenced will fix the problem. Thus when you create a
`TODO`, it is almost always your name
that is given.
```python ```python
# TODO(kl@gmail.com): Use a "*" here for string repetition. # TODO(kl@gmail.com): Use a "*" here for string repetition.
@ -1947,7 +1952,7 @@ No: import os, sys
Imports are always put at the top of the file, just after any module comments 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 and docstrings and before module globals and constants. Imports should be
grouped with the order being most generic to least generic: grouped from most generic to least generic:
1. Python standard library imports. For example: 1. Python standard library imports. For example:
@ -2049,10 +2054,10 @@ No:
<a id="access-control"></a> <a id="access-control"></a>
### 3.15 Access Control ### 3.15 Access Control
If an accessor function would be trivial you should use public variables instead If an accessor function would be trivial, you should use public variables
of accessor functions to avoid the extra cost of function calls in Python. When instead of accessor functions to avoid the extra cost of function calls in
more functionality is added you can use `property` to keep the syntax Python. When more functionality is added you can use `property` to keep the
consistent. syntax consistent.
On the other hand, if access is more complex, or the cost of accessing the On the other hand, if access is more complex, or the cost of accessing the
variable is significant, you should use function calls (following the variable is significant, you should use function calls (following the
@ -2098,7 +2103,7 @@ Always use a `.py` filename extension. Never use dashes.
<a id="naming-conventions"></a> <a id="naming-conventions"></a>
#### 3.16.2 Naming Convention #### 3.16.2 Naming Convention
- "Internal" means internal to a module or protected or private within a - "Internal" means internal to a module, or protected or private within a
class. class.
- Prepending a single underscore (`_`) has some support for protecting module - Prepending a single underscore (`_`) has some support for protecting module
@ -2115,8 +2120,8 @@ Always use a `.py` filename extension. Never use dashes.
- 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.
Although there are some old modules named CapWords.py, this is now Although there are some old modules named CapWords.py, this is now
discouraged because it's confusing when the module happens to be named after discouraged because it's confusing when the module happens to be named after
a class. ("wait -- did I write `import StringIO` or a class. ("wait -- did I write `import StringIO` or `from StringIO import
`from StringIO import StringIO`?") StringIO`?")
- Underscores may appear in *unittest* method names starting with `test` to - Underscores may appear in *unittest* method names starting with `test` to
separate logical components of the name, even if those components use separate logical components of the name, even if those components use
@ -2215,9 +2220,9 @@ containing `exec "$0.py" "$@"`.
</table> </table>
While Python supports making things private by using a leading double underscore While Python supports making things private by using a leading double underscore
`__` (aka. "dunder") prefix on a name their use is discouraged. Prefer the use `__` (aka. "dunder") prefix on a name, this is discouraged. Prefer the use of a
of a single underscore. They are much easier to type, read, and to access from single underscore. They are easier to type, read, and to access from small
small unittests. Lint warnings take care of invalid access to protected members. unittests. Lint warnings take care of invalid access to protected members.
<a id="s3.17-main"></a> <a id="s3.17-main"></a>
@ -2400,10 +2405,10 @@ class MyClass(object):
<a id="typing-default-values"></a> <a id="typing-default-values"></a>
#### 3.19.4 Default Values #### 3.19.4 Default Values
As per [PEP-008](https://www.python.org/dev/peps/pep-0008/#other-recommendations) As per
when combining an argument annotation with a default value, use spaces around [PEP-008](https://www.python.org/dev/peps/pep-0008/#other-recommendations), use
the = sign (but only for those arguments that have both an annotation and a spaces around the `=` _only_ for arguments that have both a type annotation and
default). a default value.
```python ```python
Yes: Yes:
@ -2540,7 +2545,8 @@ def check_length(x: AnyStr) -> AnyStr:
<a id="s3.19.11-strings"></a> <a id="s3.19.11-strings"></a>
<a id="typing-strings"></a> <a id="typing-strings"></a>
#### 3.19.11 Strings types
#### 3.19.11 String types
The proper type for annotating strings depends on what versions of Python the The proper type for annotating strings depends on what versions of Python the
code is intended for. code is intended for.
@ -2626,10 +2632,10 @@ from typing import Any as AnyType
<a id="typing-conditional-imports"></a> <a id="typing-conditional-imports"></a>
#### 3.19.13 Conditional Imports #### 3.19.13 Conditional Imports
Use conditional imports only in exceptional cases, when the additional imports Use conditional imports only in exceptional cases where the additional imports
needed for type checking must be avoided at runtime. This pattern is discouraged needed for type checking must be avoided at runtime. This pattern is
and alternatives such as refactoring the code to allow top level imports should discouraged; alternatives such as refactoring the code to allow top level
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 TYPE_CHECKING:` block. `if TYPE_CHECKING:` block.
@ -2729,3 +2735,4 @@ 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.