Python Style Guide PEP 8

Sahdev Garg — Wed, 29 Dec 2021 06:29:07 +0000

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:

Standard library imports.
Related third party imports.
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.

Python code formatter Black

Sahdev Garg — Tue, 28 Dec 2021 10:15:47 +0000

Writing well-formatted code is very important, breaking the actual programs in easy to understand small programs as compared to having a more complex program helps in better understanding of code and helps in maintaining code quality. In python we have an automated package Black which helps in ensures code quality.

What is Black?

Black is known as the uncompromised Python code formatter. Unlike flake8 or pycodestyle rather then telling where the issue is and ask you to manually fix it Black not only report format errors but also fixes them. Black does not have a lot of options to tinker with and has a lot of opinion on how your code should look and feel.
Black isn't for everyone and you may find something that is a dealbreaker for you personally, which is okay! The current Black code style is described here.
Black can be easily integrated with many editors such as Vim, Emacs, VSCode, Atom or a version control system like GIT.

Installation

Black requires Python 3.6.2+ to run but has a capability to format Python 2 code too.
For Python 3.6.2+ using pip.

pip install black

Python 2 support needs the typed_ast dependency, which will be installed with pip install black[python2]. If you want to format Jupyter Notebooks, install pip install black[jupyter].
If you can't wait for the latest hotness and want to install from GitHub, use:

pip install git+git://github.com/psf/black

Usage of Black

In simplest if we just want to format a file or a folder of files simple run the following command in terminal.
$ black {source_file_or_directory}...
You can run Black as a package if running it as a script doesn't work:
$ python -m black {source_file_or_directory}...
You can also pass code as a string using the -c / --code option.
$ black --code "print ( 'hello, black world' )" print("hello, black world")
you can pass -v / --verbose that will cause Black to also emit messages about files that were not changed or were ignored due to exclusion patterns.

$ black -v spell_checker/
spell_checker/pycache ignored: matches the .gitignore file content
spell_checker/init.py wasn't modified on disk since last run.
spell_checker/spell_checker_util.py wasn't modified on disk since last run.
spell_checker/spelling_checker.py wasn't modified on disk since last run.
All done! ✨ 🍰 ✨
3 files left unchanged.

Black Magic in action

Let's create an unformatted file name "black_test.py" and we want to format it using black. Below is the code snippet from the file before formatting.

def find_no_in_list(
s,
no
):
s = list(s
)
for i in range(len(s) - 1):
if s[i] == no:
return i
else:
return -1
if name == "main":
print(
find_no_in_list([1,
2,
3,
4],
3)
)

After running the following command in terminal

$ black black_test.py
Output file:
def find_no_in_list(s, no):
s = list(s)
for i in range(len(s) - 1):
if s[i] == no:
return i
else:
return -1
if name == "main":
print(find_no_in_list([1, 2, 3, 4], 3))

Conclusion

It's always a good practise to write a well formatted code so that it will easier to understand and manage in future so Black is must to have in your IDE when working with python so that you have a well formatted code everytime automatically.
Next read understand pep8

DEV Community: Sahdev Garg