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>
### 2.2 Imports
Use `import`s 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).
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).
<a id="s2.2.1-definition"></a>
#### 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,
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
container while iterating over it.
container while iterating over it. Never use Python 2 specific iteration
methods such as `dict.iter*()` unless necessary.
```python
Yes: for key in adict: ...
if key not in adict: ...
if obj in alist: ...
for line in afile: ...
for k, v in dict.iteritems(): ...
for k, v in adict.items(): ...
for k, v in six.iteritems(adict): ...
```
```python
No: for key in adict.keys(): ...
if not adict.has_key(key): ...
for line in afile.readlines(): ...
for k, v in dict.iteritems(): ...
```
<a id="s2.9-generators"></a>
@ -584,9 +587,9 @@ function may only contain an expression.
<a id="s2.10.4-decision"></a>
#### 2.10.4 Decision
Okay to use them for one-liners. If the code inside the lambda function is any
longer than 60-80 chars, it's probably better to define it as a regular (nested)
function.
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
function](#lexical-scoping).
For common operations like multiplication, use the functions from the `operator`
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
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
3 without modification.
@ -1197,7 +1200,7 @@ This highly depends on the complexity of your project. Give it a try.
<a id="semicolons"></a>
### 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.
<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
comma, semicolon, or colon except at the end of the line.
comma, semicolon, or colon, except at the end of the line.
```python
Yes: if x == 4:
@ -1477,10 +1480,10 @@ Yes: x == 1
No: x<1
```
Never use spaces around the '=' sign when passing keyword arguments.
Only use spaces around the '=' sign defining a default parameter value
[when a type annotation is present](#typing-default-values),
do not use spaces around '=' for default parameter values otherwise.
Never use spaces around `=` when passing keyword arguments or defining a default
parameter value, with one exception: [when a type annotation is
present](#typing-default-values), _do_ use spaces around the `=` for the default
parameter value.
```python
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>
#### 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
extracted automatically through the `__doc__` member of the object and are used
by `pydoc`.
@ -1568,8 +1571,7 @@ LGPL, GPL)
<a id="functions-and-methods"></a>
#### 3.8.3 Functions and Methods
As used in this section "function" applies to methods, functions, and
generators.
In this section, "function" means a method, function, or generator.
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.
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 class."""`. The rationale is that there is no need to repeat in
many places documentation that is already present in the base method's
docstring. However, if the overriding method's behavior is substantially
different than that of the overridden method or details need to be provided
about it (e.g., documenting additional side-effects), a docstring is required on
the overriding method, with at least those differences.
sending the reader to its overridden method's docstring, such as `"""See base
class."""`. The rationale is that there is no need to repeat in many places
documentation that is already present in the base method's docstring. However,
if the overriding method's behavior is substantially different from the
overridden method, or details need to be provided (e.g., documenting additional
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.
@ -1764,9 +1766,9 @@ No: class SampleClass:
pass
```
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
also defines special methods that implement the default semantics of objects
Inheriting from `object` is needed to make properties work properly in Python 2
and can protect your code from potential incompatibility with Python 3. It also
defines special methods that implement the default semantics of objects
including `__new__`, `__init__`, `__delattr__`, `__getattribute__`,
`__setattr__`, `__hash__`, `__repr__`, and `__str__`.
@ -1860,28 +1862,28 @@ Don't do this.
Explicitly close files and sockets when done with them.
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
that deals with many such objects may exhaust those resources unnecessarily
if they're not returned to the system promptly after use.
- Holding files open may prevent other actions being performed on them, such
as moves or deletion.
- Holding files open may prevent other actions such as moving or deleting
them.
- 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
closed, attempts to read or write from them will throw exceptions, making
the problem known sooner.
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
file is poor practice, for several reasons:
object is destructed, tying the lifetime of the file object to the state of the
file is poor practice:
- There are no guarantees as to when the runtime will actually run the file's
destructor. Different Python implementations use different memory management
techniques, such as delayed Garbage Collection, which may increase the
object's lifetime arbitrarily and indefinitely.
- Unexpected references to the file may keep it around longer than intended
(e.g. in tracebacks of exceptions, inside globals, etc).
- Unexpected references to the file, e.g. in globals or exception tracebacks,
may keep it around longer than intended.
The preferred way to manage files is using the ["with"
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
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
of the person or issue with the best context about the problem referenced by the
`TODO`, in parentheses. A comment explaining what there is to do is required.
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 person referenced will fix the problem. Thus when you create a `TODO`, it is almost always your name that is given.
of the person or issue with the best context about the problem. This is followed
by an explanation of what there is to do.
The purpose is to have a consistent `TODO` format that can be searched to find
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
# 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
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:
@ -2049,10 +2054,10 @@ No:
<a id="access-control"></a>
### 3.15 Access Control
If an accessor function would be trivial you should use public variables instead
of accessor functions to avoid the extra cost of function calls in Python. When
more functionality is added you can use `property` to keep the syntax
consistent.
If an accessor function would be trivial, you should use public variables
instead of accessor functions to avoid the extra cost of function calls in
Python. When more functionality is added you can use `property` to keep the
syntax consistent.
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
@ -2098,7 +2103,7 @@ Always use a `.py` filename extension. Never use dashes.
<a id="naming-conventions"></a>
#### 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.
- 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.
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
a class. ("wait -- did I write `import StringIO` or
`from StringIO import StringIO`?")
a class. ("wait -- did I write `import StringIO` or `from StringIO import
StringIO`?")
- Underscores may appear in *unittest* method names starting with `test` to
separate logical components of the name, even if those components use
@ -2215,9 +2220,9 @@ containing `exec "$0.py" "$@"`.
</table>
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
of a single underscore. They are much easier to type, read, and to access from
small unittests. Lint warnings take care of invalid access to protected members.
`__` (aka. "dunder") prefix on a name, this is discouraged. Prefer the use of a
single underscore. They are easier to type, read, and to access from small
unittests. Lint warnings take care of invalid access to protected members.
<a id="s3.17-main"></a>
@ -2400,10 +2405,10 @@ class MyClass(object):
<a id="typing-default-values"></a>
#### 3.19.4 Default Values
As per [PEP-008](https://www.python.org/dev/peps/pep-0008/#other-recommendations)
when combining an argument annotation with a default value, use spaces around
the = sign (but only for those arguments that have both an annotation and a
default).
As per
[PEP-008](https://www.python.org/dev/peps/pep-0008/#other-recommendations), use
spaces around the `=` _only_ for arguments that have both a type annotation and
a default value.
```python
Yes:
@ -2540,7 +2545,8 @@ def check_length(x: AnyStr) -> AnyStr:
<a id="s3.19.11-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
code is intended for.
@ -2626,10 +2632,10 @@ from typing import Any as AnyType
<a id="typing-conditional-imports"></a>
#### 3.19.13 Conditional Imports
Use conditional imports only in exceptional cases, when the additional imports
needed for type checking must be avoided at runtime. This pattern is discouraged
and alternatives such as refactoring the code to allow top level imports should
be preferred.
Use conditional imports only in exceptional cases where the additional imports
needed for type checking must be avoided at runtime. This pattern is
discouraged; alternatives such as refactoring the code to allow top level
imports should be preferred.
Imports that are needed only for type annotations can be placed within an
`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
they go to read it. Avoid this.