The Python Software Foundation is responsible for developing and maintaining Python language standards. The Python foundation uses Python Enhancement Proposals (PEPs) to document the language and capture guidelines. Two PEPs are relevant to the topic of code style.
PEP 8 – Style Guide for Python Code
PEP 8 specifies the conventions used to develop the standard libraries that ship as part of a Python distribution.
PEP 257 – Docstring Conventions
PEP 257 builds on PEP 8 to add the semantics and conventions for Python docstrings. Following these conventions enables off the shelf tools to process the docstrings.
Pylint is the recommended code analysis tool for verifying compliance with the PEP 8 style guide. Pylint can be run from the command-line for integrating in CI environment. There are also Pylint integrations for most Python IDEs and many text editors.
When a rule violation is the result of a conscious decision a rule can be disabled with a comment of the form
# pylint: disable=no-member
To help enforce the standard, you can hook into Git. This can easily be applied to any language enforcement tooling.
Here’s an example using Python’s
$ pip install pre-commit
$ pre-commit install
- Create a file named
.pre-commit-config.yamlin the root directory.
# file: .pre-commit-config.yaml
- repo: https://github.com/pycqa/pylint
- id: pylint
It’s strongly advised to write type annotated code whenever possible. The following PEP is relevant to this:
PEP 484 – Type Hints
PEP 484 introduces type hints to Python code. It enables annotating function and variable types to improve code clarity and maintainability.
Annotated code is already checked during build time with static type checking tools. mypy is recommended. It works like a linter, and uses type annotations of variables and functions to ensure that they are used correctly. In this way, possible problems in the code are revealed even before a program is run.
mypy can also be added to the
pre-commit-config.yaml in the following way:
- repo: https://github.com/pre-commit/mirrors-mypy
rev: '' # Use the sha / tag you want to point at
- id: mypy
Just in case, conscious type checking violations can be silenced using:
# type: ignore[<code>]