Skip to content

Commit

Permalink
PEP 8: Add green side border for allowed examples
Browse files Browse the repository at this point in the history 
Leave the multiple-with-statement-and-backslashes example uncoloured, it's for pre-3.10
  • Loading branch information
@hugovk
hugovk committed Dec 8, 2023
1 parent 6ac37de commit 14b8270
Showing 1 changed file with 133 additions and 85 deletions.
218 changes: 133 additions & 85 deletions peps/pep-0008.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,12 +117,15 @@ clearly distinguish itself as a continuation line:
The 4-space rule is optional for continuation lines.

Optional::
Optional:

# Hanging indents *may* be indented to other than 4 spaces.
foo = long_function_name(
var_one, var_two,
var_three, var_four)
.. code-block::
:class: good
# Hanging indents *may* be indented to other than 4 spaces.
foo = long_function_name(
var_one, var_two,
var_three, var_four)
.. _`multiline if-statements`:

Expand All @@ -135,52 +138,61 @@ conflict with the indented suite of code nested inside the ``if``-statement,
which would also naturally be indented to 4 spaces. This PEP takes no
explicit position on how (or whether) to further visually distinguish such
conditional lines from the nested suite inside the ``if``-statement.
Acceptable options in this situation include, but are not limited to::
Acceptable options in this situation include, but are not limited to:

.. code-block::
:class: good
# No extra indentation.
if (this_is_one_thing and
that_is_another_thing):
do_something()
# No extra indentation.
if (this_is_one_thing and
that_is_another_thing):
do_something()
# Add a comment, which will provide some distinction in editors
# supporting syntax highlighting.
if (this_is_one_thing and
that_is_another_thing):
# Since both conditions are true, we can frobnicate.
do_something()
# Add a comment, which will provide some distinction in editors
# supporting syntax highlighting.
if (this_is_one_thing and
that_is_another_thing):
# Since both conditions are true, we can frobnicate.
do_something()
# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
and that_is_another_thing):
do_something()
# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
and that_is_another_thing):
do_something()
(Also see the discussion of whether to break before or after binary
operators below.)

The closing brace/bracket/parenthesis on multiline constructs may
either line up under the first non-whitespace character of the last
line of list, as in::
line of list, as in:

my_list = [
1, 2, 3,
4, 5, 6,
]
result = some_function_that_takes_arguments(
'a', 'b', 'c',
'd', 'e', 'f',
)
.. code-block::
:class: good
my_list = [
1, 2, 3,
4, 5, 6,
]
result = some_function_that_takes_arguments(
'a', 'b', 'c',
'd', 'e', 'f',
)
or it may be lined up under the first character of the line that
starts the multiline construct, as in::
starts the multiline construct, as in:

.. code-block::
:class: good
my_list = [
1, 2, 3,
4, 5, 6,
]
result = some_function_that_takes_arguments(
'a', 'b', 'c',
'd', 'e', 'f',
)
my_list = [
1, 2, 3,
4, 5, 6,
]
result = some_function_that_takes_arguments(
'a', 'b', 'c',
'd', 'e', 'f',
)
Tabs or Spaces?
---------------
Expand Down Expand Up @@ -229,11 +241,13 @@ for line continuation.

Backslashes may still be appropriate at times. For example, long,
multiple ``with``-statements could not use implicit continuation
before Python 3.10, so backslashes were acceptable for that case::
before Python 3.10, so backslashes were acceptable for that case:

.. code-block::
with open('/path/to/some/file/you/want/to/read') as file_1, \
open('/path/to/some/file/being/written', 'w') as file_2:
file_2.write(file_1.read())
with open('/path/to/some/file/you/want/to/read') as file_1, \
open('/path/to/some/file/being/written', 'w') as file_2:
file_2.write(file_1.read())
(See the previous discussion on `multiline if-statements`_ for further
thoughts on the indentation of such multiline ``with``-statements.)
Expand Down Expand Up @@ -369,34 +383,46 @@ Imports
- Absolute imports are recommended, as they are usually more readable
and tend to be better behaved (or at least give better error
messages) if the import system is incorrectly configured (such as
when a directory inside a package ends up on ``sys.path``)::
when a directory inside a package ends up on ``sys.path``):

import mypkg.sibling
from mypkg import sibling
from mypkg.sibling import example
.. code-block::
:class: good
import mypkg.sibling
from mypkg import sibling
from mypkg.sibling import example
However, explicit relative imports are an acceptable alternative to
absolute imports, especially when dealing with complex package layouts
where using absolute imports would be unnecessarily verbose::
where using absolute imports would be unnecessarily verbose:

from . import sibling
from .sibling import example
.. code-block::
:class: good
from . import sibling
from .sibling import example
Standard library code should avoid complex package layouts and always
use absolute imports.

- When importing a class from a class-containing module, it's usually
okay to spell this::
okay to spell this:

from myclass import MyClass
from foo.bar.yourclass import YourClass
.. code-block::
:class: good
If this spelling causes local name clashes, then spell them explicitly::
from myclass import MyClass
from foo.bar.yourclass import YourClass
import myclass
import foo.bar.yourclass
If this spelling causes local name clashes, then spell them explicitly:

and use "myclass.MyClass" and "foo.bar.yourclass.YourClass".
.. code-block::
:class: good
import myclass
import foo.bar.yourclass
and use ``myclass.MyClass`` and ``foo.bar.yourclass.YourClass``.

- Wildcard imports (``from <module> import *``) should be avoided, as
they make it unclear which names are present in the namespace,
Expand All @@ -418,21 +444,24 @@ underscores) such as ``__all__``, ``__author__``, ``__version__``,
etc. should be placed after the module docstring but before any import
statements *except* ``from __future__`` imports. Python mandates that
future-imports must appear in the module before any other code except
docstrings::
docstrings:

"""This is the example module.
.. code-block::
:class: good
This module does stuff.
"""
"""This is the example module.
from __future__ import barry_as_FLUFL
This module does stuff.
"""
__all__ = ['a', 'b', 'c']
__version__ = '0.1'
__author__ = 'Cardinal Biggles'
from __future__ import barry_as_FLUFL
import os
import sys
__all__ = ['a', 'b', 'c']
__version__ = '0.1'
__author__ = 'Cardinal Biggles'
import os
import sys
String Quotes
Expand Down Expand Up @@ -842,17 +871,24 @@ Conventions for writing good documentation strings

- :pep:`257` describes good docstring conventions. Note that most
importantly, the ``"""`` that ends a multiline docstring should be
on a line by itself::
on a line by itself:

"""Return a foobang
.. code-block::
:class: good
Optional plotz says to frobnicate the bizbaz first.
"""
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""
- For one liner docstrings, please keep the closing ``"""`` on
the same line::
the same line:

.. code-block::
:class: good
"""Return an ex-parrot."""
"""Return an ex-parrot."""
Naming Conventions
Expand Down Expand Up @@ -919,9 +955,12 @@ case convention):
with an underscore.

- ``single_trailing_underscore_``: used by convention to avoid
conflicts with Python keyword, e.g. ::
conflicts with Python keyword, e.g. :

tkinter.Toplevel(master, class_='ClassName')
.. code-block::
:class: good
tkinter.Toplevel(master, class_='ClassName')
- ``__double_leading_underscore``: when naming a class attribute,
invokes name mangling (inside class FooBar, ``__boo`` becomes
Expand Down Expand Up @@ -984,12 +1023,15 @@ Type Variable Names
Names of type variables introduced in :pep:`484` should normally use CapWords
preferring short names: ``T``, ``AnyStr``, ``Num``. It is recommended to add
suffixes ``_co`` or ``_contra`` to the variables used to declare covariant
or contravariant behavior correspondingly::
or contravariant behavior correspondingly:

.. code-block::
:class: good
from typing import TypeVar
from typing import TypeVar
VT_co = TypeVar('VT_co', covariant=True)
KT_contra = TypeVar('KT_contra', contravariant=True)
VT_co = TypeVar('VT_co', covariant=True)
KT_contra = TypeVar('KT_contra', contravariant=True)
Exception Names
~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -1271,12 +1313,15 @@ Programming Recommendations
exception in the new exception message).

- When catching exceptions, mention specific exceptions whenever
possible instead of using a bare ``except:`` clause::
possible instead of using a bare ``except:`` clause:

.. code-block::
:class: good
try:
import platform_specific_module
except ImportError:
platform_specific_module = None
try:
import platform_specific_module
except ImportError:
platform_specific_module = None
A bare ``except:`` clause will catch SystemExit and
KeyboardInterrupt exceptions, making it harder to interrupt a
Expand Down Expand Up @@ -1503,9 +1548,12 @@ annotations have changed.
refactorings.

- For code that wants to make a different use of function annotations
it is recommended to put a comment of the form::
it is recommended to put a comment of the form:

.. code-block::
:class: good
# type: ignore
# type: ignore
near the top of the file; this tells type checkers to ignore all
annotations. (More fine-grained ways of disabling complaints from
Expand Down

0 comments on commit 14b8270

Please sign in to comment.