Additional clarifications based on discussion amongst the PEP authors.

This commit is contained in:
Barry Warsaw 2014-04-27 13:34:33 -04:00
parent c2e9b27e6a
commit eea38be724
1 changed files with 49 additions and 9 deletions

View File

@ -78,14 +78,14 @@ Use 4 spaces per indentation level.
Continuation lines should align wrapped elements either vertically
using Python's implicit line joining inside parentheses, brackets and
braces, or using a hanging indent. When using a hanging indent the
following considerations should be applied; there should be no
arguments on the first line and further indentation should be used to
clearly distinguish itself as a continuation line.
braces, or using a *hanging indent* [#fn-hi]_. When using a hanging
indent the following considerations should be applied; there should be
no arguments on the first line and further indentation should be used
to clearly distinguish itself as a continuation line.
Yes::
# Aligned with opening delimiter
# Aligned with opening delimiter.
foo = long_function_name(var_one, var_two,
var_three, var_four)
@ -95,25 +95,54 @@ Yes::
var_four):
print(var_one)
# Hanging indents should add a level.
foo = long_function_name(
var_one, var_two,
var_three, var_four)
No::
# Arguments on first line forbidden when not using vertical alignment
# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
var_three, var_four)
# Further indentation required as indentation is not distinguishable
# Further indentation required as indentation is not distinguishable.
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)
The 4-space rule is optional for indentation lines.
Optional::
# Extra indentation is not necessary.
# Hanging indents *may* be indented to other than 4 spaces.
foo = long_function_name(
var_one, var_two,
var_three, var_four)
This PEP explicitly takes no position on how or whether to further
visually distinguish continuation lines after multi-line ``if``
statements. Some acceptable options include::
# No extra indentation.
if (this
and that):
do_something()
# Add a comment, which will provide some distinction in editors
# supporting syntax highlighting.
if (this
and that):
# Since both conditions are true, we can frobnicate.
do_something()
# Add some extra indentation on the conditional continuation line.
if (this
and that):
do_something()
The closing brace/bracket/parenthesis on multi-line constructs may
either line up under the first non-whitespace character of the last
line of list, as in::
@ -183,7 +212,7 @@ exclusively or primarily by a team that can reach agreement on this
issue, it is okay to increase the nominal line length from 80 to
100 characters (effectively increasing the maximum length to 99
characters), provided that comments and docstrings are still wrapped
at 72 characters.
at 72 characters.
The Python standard library is conservative and requires limiting
lines to 79 characters (and docstrings/comments to 72).
@ -1155,6 +1184,16 @@ Programming Recommendations
automated utilities could be supported.
.. rubric:: Footnotes
.. [#fn-hi] *Hanging indentation* is a type-setting style where all
the lines in a paragraph are indented except the first line. In
the context of Python, the term is used to describe a style where
the opening parenthesis of a parenthesized statement is the last
non-whitespace character of the line, with subsequent lines being
indented until the closing parenthesis.
References
==========
@ -1168,6 +1207,7 @@ References
.. [4] PEP 8 modernisation, July 2013
http://bugs.python.org/issue18472
Copyright
=========