Linters and formatters

Overview

A significant amount of effort is spent on manually ensuring Autonomy code adheres to the Autonomy Python coding style: Python Style Convention . This unnecessarily burdens both code authors and code reviewers and distracts them from focusing on writing functional and well structured code. Integrating full support for linters and formatters shifts the burden away from developers to the tools.

Integration

Impact: All of Autonomy's Python repositories, except the Autonomy bootcamp (can be included later if desired).

Tools

The tools do not currently support:

  • Type correctness (although Flake8 can be used as such, it requires a lot of work)

  • Spelling, punctuation, and grammar (SPAG)

Pylint

Pylint is a linter that analyzes Python code structure and indicates defects, but does not modify it. For example:

  • Naming convention

  • Unused variables and imports

  • Docstring existence

  • Loop iteration

  • Line length (disabled for Autonomy, handled by Black instead)

Black

Black is a formatter that automatically formats Python code to follow the Black style guide. The output code is semantically identical to the input code (i.e. running both versions will produce the same behaviour). For example:

  • Spacing

  • Line length and multiline formatting

Black has the option to format (modify) or indicate potential changes only (no modification). The indication option is used in the CI tool.

Flake8

Flake8 is another linter. Specifically, flake8-annotations is used by Autonomy for enforcing usage of type hints in function signatures: GitHub - sco1/flake8-annotations: Flake8 Type Annotation Checking

Process to add a new tool

Steps:

  1. Single lead PR as a template for review and approval

  2. Multiple PRs (1 per repository) based on lead PR for review and approval

  3. Once all PRs are approved, they include latest main and are then merged

Ensure that the tool is added to CI and that CI checks are passing.