Python Code Style

On this page

Reference Code Standard

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.

Exceptions to the Standard

None.

Implementing the Standard

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

Sample implementation

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 pre-commit package: 

$ pip install pre-commit
$ pre-commit install
  • Create a file named .pre-commit-config.yaml in the root directory. 
# file: .pre-commit-config.yaml
repos:
  - repo: https://github.com/pycqa/pylint
    rev: pylint-2.6.0
    hooks:
      - id: pylint
        args:
          - --rcfile=.pylintrc
        verbose: true

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
    hooks:
    -   id: mypy

Just in case, conscious type checking violations can be silenced using: 

# type: ignore[<code>]

Bibliography

View on GitHub