diff --git a/pep-0008.txt b/pep-0008.txt index 9b7fa0688..21cc99be1 100644 --- a/pep-0008.txt +++ b/pep-0008.txt @@ -68,7 +68,7 @@ Some other good reasons to ignore a particular guideline: Python that don't support the feature recommended by the style guide. -Code lay-out +Code Lay-out ============ Indentation @@ -179,7 +179,6 @@ starts the multiline construct, as in:: 'd', 'e', 'f', ) - Tabs or Spaces? --------------- @@ -198,7 +197,6 @@ the ``-t`` option, it issues warnings about code that illegally mixes tabs and spaces. When using ``-tt`` these warnings become errors. These options are highly recommended! - Maximum Line Length ------------------- @@ -249,7 +247,6 @@ Another such case is with ``assert`` statements. Make sure to indent the continued line appropriately. - Should a Line Break Before or After a Binary Operator? ------------------------------------------------------ @@ -287,7 +284,6 @@ In Python code, it is permissible to break before or after a binary operator, as long as the convention is consistent locally. For new code Knuth's style is suggested. - Blank Lines ----------- @@ -309,7 +305,6 @@ you may use them to separate pages of related sections of your file. Note, some editors and web-based code viewers may not recognize control-L as a form feed and will show another glyph in its place. - Source File Encoding -------------------- @@ -339,11 +334,10 @@ a transliteration of their names in this character set. Open source projects with a global audience are encouraged to adopt a similar policy. - Imports ------- -- Imports should usually be on separate lines, e.g.:: +- Imports should usually be on separate lines:: Yes: import os import sys @@ -370,16 +364,16 @@ Imports messages) if the import system is incorrectly configured (such as when a directory inside a package ends up on ``sys.path``):: - import mypkg.sibling - from mypkg import sibling - from mypkg.sibling import example + 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:: - from . import sibling - from .sibling import example + from . import sibling + from .sibling import example Standard library code should avoid complex package layouts and always use absolute imports. @@ -393,7 +387,7 @@ Imports from myclass import MyClass from foo.bar.yourclass import YourClass - If this spelling causes local name clashes, then spell them :: + If this spelling causes local name clashes, then spell them explicitly:: import myclass import foo.bar.yourclass @@ -412,8 +406,7 @@ Imports When republishing names this way, the guidelines below regarding public and internal interfaces still apply. - -Module level dunder names +Module Level Dunder Names ------------------------- Module level "dunders" (i.e. names with two leading and two trailing @@ -421,9 +414,7 @@ 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. - -For example:: +docstrings:: """This is the example module. @@ -524,7 +515,6 @@ Avoid extraneous whitespace in the following situations: y = 2 long_variable = 3 - Other Recommendations --------------------- @@ -642,6 +632,7 @@ Other Recommendations if foo == 'blah': one(); two(); three() + When to Use Trailing Commas =========================== @@ -748,7 +739,7 @@ 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, e.g.:: + on a line by itself:: """Return a foobang @@ -888,12 +879,12 @@ 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. Examples:: +or contravariant behavior correspondingly:: - 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 ~~~~~~~~~~~~~~~ @@ -966,7 +957,7 @@ Constants are usually defined on a module level and written in all capital letters with underscores separating words. Examples include ``MAX_OVERFLOW`` and ``TOTAL``. -Designing for inheritance +Designing for Inheritance ~~~~~~~~~~~~~~~~~~~~~~~~~ Always decide whether a class's methods and instance variables @@ -1041,7 +1032,6 @@ With this in mind, here are the Pythonic guidelines: need to avoid accidental name clashes with potential use by advanced callers. - Public and Internal Interfaces ------------------------------ @@ -1180,9 +1170,7 @@ Programming Recommendations continuation characters thanks to the containing parentheses. - When catching exceptions, mention specific exceptions whenever - possible instead of using a bare ``except:`` clause. - - For example, use:: + possible instead of using a bare ``except:`` clause:: try: import platform_specific_module @@ -1250,17 +1238,16 @@ Programming Recommendations - Context managers should be invoked through separate functions or methods whenever they do something other than acquire and release resources. - For example: Yes:: - with conn.begin_transaction(): - do_stuff_in_transaction(conn) + with conn.begin_transaction(): + do_stuff_in_transaction(conn) No:: - with conn: - do_stuff_in_transaction(conn) + with conn: + do_stuff_in_transaction(conn) The latter example doesn't provide any information to indicate that the ``__enter__`` and ``__exit__`` methods are doing something other @@ -1307,8 +1294,7 @@ Programming Recommendations - Use ``''.startswith()`` and ``''.endswith()`` instead of string slicing to check for prefixes or suffixes. - startswith() and endswith() are cleaner and less error prone. For - example:: + startswith() and endswith() are cleaner and less error prone:: Yes: if foo.startswith('bar'): No: if foo[:3] == 'bar': @@ -1328,7 +1314,7 @@ Programming Recommendations Note that in Python 3, ``unicode`` and ``basestring`` no longer exist (there is only ``str``) and a bytes object is no longer a kind of - string (it is a sequence of integers instead) + string (it is a sequence of integers instead). - For sequences, (strings, lists, tuples), use the fact that empty sequences are false. :: @@ -1336,8 +1322,8 @@ Programming Recommendations Yes: if not seq: if seq: - No: if len(seq): - if not len(seq): + No: if len(seq): + if not len(seq): - Don't write string literals that rely on significant trailing whitespace. Such trailing whitespace is visually indistinguishable @@ -1375,7 +1361,7 @@ annotations are changing. - For code that wants to make a different use of function annotations it is recommended to put a comment of the form:: - # type: ignore + # type: ignore near the top of the file; this tells type checker to ignore all annotations. (More fine-grained ways of disabling complaints from @@ -1397,7 +1383,7 @@ annotations are changing. can be added in the form of comments. See the relevant section of PEP 484 [6]_. -Variable annotations +Variable Annotations -------------------- PEP 526 introduced variable annotations. The style recommendations for them are @@ -1413,19 +1399,19 @@ similar to those on function annotations described above: - Yes:: - code: int + code: int - class Point: - coords: Tuple[int, int] - label: str = '' + class Point: + coords: Tuple[int, int] + label: str = '' - No:: - code:int # No space after colon - code : int # Space before colon + code:int # No space after colon + code : int # Space before colon - class Test: - result: int=0 # No spaces around equality sign + class Test: + result: int=0 # No spaces around equality sign - Although the PEP 526 is accepted for Python 3.6, the variable annotation syntax is the preferred syntax for stub files on all versions of Python @@ -1460,7 +1446,6 @@ References https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code - Copyright =========