The default wrapping in most tools disrupts the visual structure of the code, making it more difficult to understand. The limits are chosen to avoid wrapping in editors with the window width set to 80, even if the tool places a marker glyph in the final column when wrapping lines. Some web based tools may not offer dynamic line wrapping at all.
-Some teams strongly prefer a longer line length. For code maintained 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.
+Some teams strongly prefer a longer line length. For code maintained exclusively or primarily by a team that can reach agreement on this issue, it is okay to increase the line length limit up to 99 characters, provided that comments and docstrings are still wrapped at 72 characters.
The Python standard library is conservative and requires limiting lines to 79 characters (and docstrings/comments to 72).
@@ -371,7 +371,7 @@ result = some_function_that_takes_arguments(Make sure to indent the continued line appropriately.
-For decades the recommended style was to break after binary operators. But this can hurt readability in two ways: the operators tend to get scattered across different columns on the screen, and each operator is moved away from its operand and onto the previous line. Here, the eye has to do extra work to tell which items are added and which are subtracted:
@@ -429,7 +429,7 @@ income = (gross_wagesImports should usually be on separate lines, e.g.:
+Imports should usually be on separate lines
Yes:
import os
@@ -447,9 +447,9 @@ import sysImports should be grouped in the following order:
You should put a blank line between each group of imports.
@@ -474,7 +474,7 @@ from .sibling import examplefrom myclass import MyClass
from foo.bar.yourclass import YourClassIf 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.yourclassModule level "dunders" (i.e. names with two leading and two trailing 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:
-"""This is the example module.
This module does stuff.
@@ -632,18 +630,6 @@ x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)Don’t use spaces around the = sign when used to indicate a keyword argument or a default parameter value.
Yes:
- -def complex(real, imag=0.0):
- return magic(r=real, i=imag)No:
- -def complex(real, imag = 0.0):
- return magic(r = real, i = imag)Function annotations should use the normal rules for colons and always have spaces around the -> arrow if present. (See Function Annotations below for more about function annotations.)
Yes:
@@ -656,7 +642,19 @@ def munge() -> AnyStr: ...def munge(input:AnyStr): ...
def munge()->PosInt: ...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).
Don’t use spaces around the = sign when used to indicate a keyword argument,or when used to indicate a default value for an unannotated function parameter.
Yes:
+ +def complex(real, imag=0.0):
+ return magic(r=real, i=imag)No:
+ +def complex(real, imag = 0.0):
+ return magic(r = real, i = imag)When combining an argument annotation with a default value, however, do use spaces around the = sign:
Yes:
@@ -786,7 +784,7 @@ initialize(FILES, error=True,)def line.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.:
PEP 257 describes good docstring conventions. Note that most importantly, the """ that ends a multiline docstring should be on a line by itself:
"""Return a foobang
@@ -846,7 +844,7 @@ Optional plotz says to frobnicate the bizbaz first.
-_single_leading_underscore: weak “internal use” indicator. E.g. from M import * does not import objects whose name starts with an underscore._single_leading_underscore: weak “internal use” indicator. E.g. from M import * does not import objects whose name start with an underscore.single_trailing_underscore_: used by convention to avoid conflicts with Python keyword, e.g.:
@@ -901,7 +899,7 @@ Optional plotz says to frobnicate the bizbaz first.
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
@@ -968,7 +966,7 @@ or contravariant behavior correspondingly. Examples
Always decide whether a class’s methods and instance variables (collectively: “attributes”) should be public or non-public. If in doubt, choose non-public; it’s easier to make it public later than to make a public attribute non-public.
-Public attributes are those that you expect unrelated clients of your class to use, with your commitment to avoid backward incompatible changes. Non-public attributes are those that are not intended to be used by third parties; you make no guarantees that non-public attributes won’t change or even be removed.
+Public attributes are those that you expect unrelated clients of your class to use, with your commitment to avoid backwards incompatible changes. Non-public attributes are those that are not intended to be used by third parties; you make no guarantees that non-public attributes won’t change or even be removed.
We don’t use the term “private” here, since no attribute is really private in Python (without a generally unnecessary amount of work).
@@ -1079,8 +1077,6 @@ or contravariant behavior correspondingly. Examples
When catching exceptions, mention specific exceptions whenever possible instead of using a bare except: clause.
-For example, use:
-
try:
import platform_specific_module
except ImportError:
@@ -1130,7 +1126,7 @@ except KeyError:
- When a resource is local to a particular section of code, use a
with statement to ensure it is cleaned up promptly and reliably after use. A try/finally statement is also acceptable.
-Context managers should be invoked through separate functions or methods whenever they do something other than acquire and release resources. For example:
+Context managers should be invoked through separate functions or methods whenever they do something other than acquire and release resources.
Yes:
@@ -1176,7 +1172,7 @@ def bar(x):
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:
@@ -1235,7 +1231,7 @@ if not len(seq):
- In order to be forward compatible, function annotations in Python 3 code should preferably use PEP 484 syntax. (There are some formatting recommendations for annotations in the previous section.)
-
+
- The experimentation with annotation styles that was recommended previously in this PEP is no longer encouraged.
- However, outside the stdlib, experiments within the rules of PEP 484 are now encouraged. For example, marking up a large third party library or application with PEP 484 style type annotations, reviewing how easy it was to add those annotations, and observing whether their presence increases code understandability.
@@ -1256,6 +1252,37 @@ if not len(seq):
+
+Variable Annotations
+
+
+PEP 526 introduced variable annotations. The style recommendations for them are similar to those on function annotations described above:
+
+- Annotations for module level variables, class and instance variables, and local variables should have a single space after the colon.
+
+- There should be no space before the colon.
+
+- If an assignment has a right hand side, then the equality sign should have exactly one space on both sides.
+
+-
+
Yes:
+code: int
+
+class Point:
+ coords: Tuple[int, int]
+ label: str = '<unknown>'
+
+-
+
No:
+code:int # No space after colon
+code : int # Space before colon
+
+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 (see PEP 484 for details).
+
+
Footnotes