From 14b827013edcf27633c9ba7b9618f14727af7f2a Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Fri, 8 Dec 2023 13:59:41 +0200 Subject: [PATCH] PEP 8: Add green side border for allowed examples Leave the multiple-with-statement-and-backslashes example uncoloured, it's for pre-3.10 --- peps/pep-0008.rst | 218 ++++++++++++++++++++++++++++------------------ 1 file changed, 133 insertions(+), 85 deletions(-) diff --git a/peps/pep-0008.rst b/peps/pep-0008.rst index bbd6811b40f..b2fce95b963 100644 --- a/peps/pep-0008.rst +++ b/peps/pep-0008.rst @@ -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`: @@ -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? --------------- @@ -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.) @@ -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 import *``) should be avoided, as they make it unclear which names are present in the namespace, @@ -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 @@ -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 @@ -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 @@ -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 ~~~~~~~~~~~~~~~ @@ -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 @@ -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