Python Style Guide PEP 8

What is PEP 8 ?

Before going into details of PEP 8 the first thing that we need to understand that what exactly is PEP and what is 8 signifies in PEP 8.
PEP contains the index of all Python Enhancement Proposals, known as PEPs. This is an aggregate of documents which explains about information, new features, process and environment settings for python community.
PEP numbers are assigned by the PEP editors, and once assigned are never changed. It signifies the document number.
PEP 8 means Python Enhancement Proposal document number 8 which details about Style Guide for Python Code. This style guide evolves over time as additional conventions are identified and past conventions are rendered obsolete by changes in the language itself.
Although there is no restriction of using all the PEP 8 rule these are good to have as it helps in making code consistency and improve code readability.

You can install, upgrade, uninstall pycodestyle.py (formerly called pep8)with these commands:

$ pip install pycodestyle
$ pip install --upgrade pycodestyle
$ pip uninstall pycodestyle

Pycodestyle(formerly called pep8) Usage

For demo purpose lets created a test python file with a function to find the max between two numbers find_max.py having content as -

def find_max_number(a:int,b:int)->int:
    return a if a>b else b
if __name__ == "__main__":
    find_max_number(10,15)
Executing pycodestyle for this file
pycodestyle find_max.py
find_max.py:3:22: E231 missing whitespace after ':'
find_max.py:3:26: E231 missing whitespace after ','
find_max.py:3:28: E231 missing whitespace after ':'
find_max.py:3:33: E225 missing whitespace around operator
find_max.py:4:18: E225 missing whitespace around operator
find_max.py:6:1: E305 expected 2 blank lines after class or function definition, found 1
find_max.py:7:23: E231 missing whitespace after ','
find_max.py:7:27: W292 no newline at end of file

In this case we have 8 violations.
As you see above, it outputs the file name which has violations, location, error code and that content.

In order to get output summary of PEP 8 violations we need run the following command pycodestyle --statistics --qq <file_name>

pycodestyle  --statistics -qq find_max.py
2       E225 missing whitespace around operator
4       E231 missing whitespace after ':'
1       E305 expected 2 blank lines after class or function definition, found 1
1       W292 no newline at end of file

In order to have more details on the voilation we need to use show-source option as pycodestyle --show-source <file_name>

pycodestyle  --show-source  find_max.py 
find_max.py:3:22: E231 missing whitespace after ':'
def find_max_number(a:int,b:int)->int:
                     ^
find_max.py:3:26: E231 missing whitespace after ','
def find_max_number(a:int,b:int)->int:
                         ^
find_max.py:3:28: E231 missing whitespace after ':'
def find_max_number(a:int,b:int)->int:
                           ^
find_max.py:3:33: E225 missing whitespace around operator
def find_max_number(a:int,b:int)->int:
                                ^
find_max.py:4:18: E225 missing whitespace around operator
    return a if a>b else b
                 ^
find_max.py:6:1: E305 expected 2 blank lines after class or function definition, found 1
if __name__ == "__main__":
^
find_max.py:7:23: E231 missing whitespace after ','
    find_max_number(10,15)
                      ^
find_max.py:7:27: W292 no newline at end of file
    find_max_number(10,15)
                        ^

Moreover you can see the description of how to fix. This is --show-pep8 option.

pycodestyle --show-pep8 find_max.py
find_max.py:3:22: E231 missing whitespace after ':'
    Each comma, semicolon or colon should be followed by whitespace.
Okay: [a, b]
    Okay: (3,)
    Okay: a[1:4]
    Okay: a[:4]
    Okay: a[1:]
    Okay: a[1:4:2]
    E231: ['a','b']
    E231: foo(bar,baz)
    E231: [{'a':'b'}]
find_max.py:3:26: E231 missing whitespace after ','
    Each comma, semicolon or colon should be followed by whitespace.
Okay: [a, b]
    Okay: (3,)
    Okay: a[1:4]
    Okay: a[:4]
    Okay: a[1:]
    Okay: a[1:4:2]
    E231: ['a','b']
    E231: foo(bar,baz)
    E231: [{'a':'b'}]
find_max.py:3:28: E231 missing whitespace after ':'
    Each comma, semicolon or colon should be followed by whitespace.
Okay: [a, b]
    Okay: (3,)
    Okay: a[1:4]
    Okay: a[:4]
    Okay: a[1:]
    Okay: a[1:4:2]
    E231: ['a','b']
    E231: foo(bar,baz)
    E231: [{'a':'b'}]
find_max.py:3:33: E225 missing whitespace around operator
    Surround operators with a single space on either side.
- Always surround these binary operators with a single space on
      either side: assignment (=), augmented assignment (+=, -= etc.),
      comparisons (==, <, >, !=, <=, >=, in, not in, is, is not),
      Booleans (and, or, not).
- If operators with different priorities are used, consider adding
      whitespace around the operators with the lowest priorities.
Okay: i = i + 1
    Okay: submitted += 1
    Okay: x = x * 2 - 1
    Okay: hypot2 = x * x + y * y
    Okay: c = (a + b) * (a - b)
    Okay: foo(bar, key='word', *args, **kwargs)
    Okay: alpha[:-i]
E225: i=i+1
    E225: submitted +=1
    E225: x = x /2 - 1
    E225: z = x **y
    E225: z = 1and 1
    E226: c = (a+b) * (a-b)
    E226: hypot2 = x*x + y*y
    E227: c = a|b
    E228: msg = fmt%(errno, errmsg)
find_max.py:4:18: E225 missing whitespace around operator
    Surround operators with a single space on either side.
- Always surround these binary operators with a single space on
      either side: assignment (=), augmented assignment (+=, -= etc.),
      comparisons (==, <, >, !=, <=, >=, in, not in, is, is not),
      Booleans (and, or, not).
- If operators with different priorities are used, consider adding
      whitespace around the operators with the lowest priorities.
Okay: i = i + 1
    Okay: submitted += 1
    Okay: x = x * 2 - 1
    Okay: hypot2 = x * x + y * y
    Okay: c = (a + b) * (a - b)
    Okay: foo(bar, key='word', *args, **kwargs)
    Okay: alpha[:-i]
E225: i=i+1
    E225: submitted +=1
    E225: x = x /2 - 1
    E225: z = x **y
    E225: z = 1and 1
    E226: c = (a+b) * (a-b)
    E226: hypot2 = x*x + y*y
    E227: c = a|b
    E228: msg = fmt%(errno, errmsg)
find_max.py:6:1: E305 expected 2 blank lines after class or function definition, found 1
    Separate top-level function and class definitions with two blank
    lines.
Method definitions inside a class are separated by a single blank
    line.
Extra blank lines may be used (sparingly) to separate groups of
    related functions.  Blank lines may be omitted between a bunch of
    related one-liners (e.g. a set of dummy implementations).
Use blank lines in functions, sparingly, to indicate logical
    sections.
Okay: def a():\n    pass\n\n\ndef b():\n    pass
    Okay: def a():\n    pass\n\n\nasync def b():\n    pass
    Okay: def a():\n    pass\n\n\n# Foo\n# Bar\n\ndef b():\n    pass
    Okay: default = 1\nfoo = 1
    Okay: classify = 1\nfoo = 1
E301: class Foo:\n    b = 0\n    def bar():\n        pass
    E302: def a():\n    pass\n\ndef b(n):\n    pass
    E302: def a():\n    pass\n\nasync def b(n):\n    pass
    E303: def a():\n    pass\n\n\n\ndef b(n):\n    pass
    E303: def a():\n\n\n\n    pass
    E304: @decorator\n\ndef a():\n    pass
    E305: def a():\n    pass\na()
    E306: def a():\n    def b():\n        pass\n    def c():\n        pass
find_max.py:7:23: E231 missing whitespace after ','
    Each comma, semicolon or colon should be followed by whitespace.
Okay: [a, b]
    Okay: (3,)
    Okay: a[1:4]
    Okay: a[:4]
    Okay: a[1:]
    Okay: a[1:4:2]
    E231: ['a','b']
    E231: foo(bar,baz)
    E231: [{'a':'b'}]
find_max.py:7:27: W292 no newline at end of file
    Trailing blank lines are superfluous.
Okay: spam(1)
    W391: spam(1)\n
However the last line should end with a new line (warning W292).

If we want to exclude specific errors and warning while running pycodestyle we can use the option -ignore and provide the comma separated values of the error codes need to be excluded.

pycodestyle - ignore=E231,E225 find_max.py
find_max.py:6:1: E305 expected 2 blank lines after class or function definition, found 1
find_max.py:7:27: W292 no newline at end of file

As we have put E231,E225 in the ignore list the PEP 8 violation count reduced to 2 from 8 which is without ignoring these errors.

PEP 8 Error codes

Code can either denote an error or warning in case of error codes the code start with E followed by a 3 digit number for e.g E101 and for warning code it start with E followed by a 3 digit number for e.g W191.

Below is the classification of error code based on series number.
100 series … (E1 and W1) related to indentation.
200 series … (E2 and W2) related to whitespace.
300 series … (E3 and W3) related to blank lines.
400 series … (E4 and W4) related to imports.
500 series … (E5 and W5) related to line length.
600 series … (E6 and W6) related to deprecation.
700 series … (E7) related to statements.
900 series … (E9) related to syntax errors.

You can refer to official document for more detailing on error code link.

Customization of pep8

We can customise the PEP 8 config to meet our requirement as in we might need to ignore certain errors and warning and also we want to alter the max-line-length etc.
Default user configuration file is in '~/.config/pycodestyle'.
You can write the configuration file as below, this is same as option.

[pep8]
ignore = E231,E225
max-line-length = 160

You can specify the configuration file location by--config=<configration_file_location> .
By storing above configuration file in a certain location in respective projects, you can share it in the projects.
At the project level, a setup.cfg file or a tox.ini file is read if present (.pep8 file is also supported, but it is deprecated). If none of these files have a [pep8] section, no project specific configuration is loaded.

Commonly used PEP 8 guidelines

The PEP 8 guidelines can classified in 7 different categories as

Code Lay-out

• Use 4 spaces per indentation level.
• Use spaces not tabs python disallows mixing tabs and spaces for indentation.
• Limit all lines to a maximum of 79 characters.
• Should a line break before or after binary operator? In Python code, it is permissible to break before or after a binary operator, as long as the convention is consistent locally.
• Surround top-level function and class definitions with two blank lines.
• Code in the core Python distribution should always use UTF-8, and should not have an encoding declaration.

Imports should be grouped in the following order:

1. Standard library imports.
2. Related third party imports.
3. Local application/library specific imports. Wildcard imports (from import *) should be avoided.

Naming Conventions

Naming conventions are the most important pillar in maintaining the code consistency and readability there is as such no rule book to define the naming conventions but PEP 8 has recommendation that is good to follow.

• Never use the characters 'l' , 'O' , or 'I' (uppercase letter eye) as single character variable names. In some fonts, these characters are indistinguishable from the numerals one and zero.
• Class names should normally use the Cap Words (Camel case) convention.
• Variables and function names should have all lowercase letters and underscores to separate words.
• Constant should have all uppercase letters with words separated by underscores
• Use the suffix "Error" on your exception names (if the exception actually is an error).
• Use self for the first argument to instance methods or class methods.

String Quotes

• In Python, single-quoted strings and double-quoted strings are the same. PEP does not make a recommendation for this. Pick a rule and stick to it. When a string contains single or double quote characters, however, use the other one to avoid backslashes in the string. It improves readability.
• Whitespace in Expression and Statement
• Avoid trailing whitespace anywhere. Because it's usually invisible, it can be confusing: e.g. a backslash followed by a space and a newline does not count as a line continuation marker.
• Always surround these binary operators with a single space on either side: assignment (=), augmented assignment (+=, -= etc.), comparisons (==, <, >, !=, <>, <=, >=, in, not in, is, is not), Booleans (and, or, not).
• Use whitespace to communicate order of operations. x = 12*y + 22*z.
• Avoid excessive whitespace immediately inside of parenthesis, brackets, or braces.

When to use trailing commas

• Trailing commas are usually optional, except they are mandatory when making a tuple of one element. For clarity, it is recommended to surround the latter in parentheses:

# Correct:
FILES = ('setup.cfg',)
# Wrong:
FILES = 'setup.cfg',

Programming Recommendations

• Comparisons to singletons like None should always be done with is or is not, never the equality operators.
• Use is notoperator rather than not ... is for e.g if foo is not None rather than if not foo is None:
• When implementing ordering operations with rich comparisons, it is best to implement all six operations (eq, ne, lt, le, gt, ge) rather than relying on other code to only exercise a particular comparison.
• When catching exceptions, mention specific exceptions whenever possible instead of using a bare except.
• Object type comparisons should always use isinstance() instead of comparing types directly.

Comments

Each line of a block comment starts with a # and a single space.
Use inline comments only if it is unavoidable.
Write docstrings for all public modules, functions, classes, and methods.
Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does.

For more detailing on the PEP 8 guidelines please check out the official documentation PEP 8 Guidelines

Conclusion

Likewise pycodestyle there is flake8 which is also widely used for checking the code style PEP 8 guidelines in python code. It's always better to have these plugins in the ide and everytime you save or commit it will highlight the violations.
Maintaining the code style guideline helps in better readability and code consistency. Although it's a good to have but always prefer to have coding guidelines while writing code.