Linters, formatters and pre-commit hooks

Linters, formatters and pre-commit hooks#

Best Practices in Modern Software Development: 23.11.23

Henrik Finsberg

What is a linter?#

A linter is a tool that analyses your source code and reports potential problems.

Example linters#

flake8: points out general problems
ruff: similar to flake8 only more and faster (recommended). ruff also include features from isort, pyupgrade, black, …

You can install them with pip or pipx

Demo: linting#

# file.py
import math

def main():
    x = 1
    y = 2
    z = y + 2
    return z

ruff file.py

ruff file.py
file.py:1:8: F401 [*] `math` imported but unused
file.py:4:5: F841 [*] Local variable `x` is assigned to but never used
Found 2 errors.
[*] 2 potentially fixable with the --fix option.

Ignore errors#

# file.py
import math  # noqa: F401

def main():
    x = 1  # noqa: F841
    y = 2
    z = y + 2
    return z

Formatters#

Formatters are tools that will format your code to follow a certain code style
When collaborating with others you need to agree on a code style
black should be the default choice

It is also possible to setup VSCode to format you code when you save
It is also possible to use ruff for formatting (but is seems to currently be an experimental feature)

Demo#

Try to run black on the following code

import math

def main():
    x=1# Some comment
    y = 2
    #Some other comment
    z = y +2
    a_very_long_function_with_many_arguments(first_argument=x, second_argument=y, third_argument=z)



    return z

Static type checker#

Use mypy to check your types
mypy
Helps to catch bugs
Will only run on code with type hints

Demo: static type checking#

# file.py

class Person:
    def __init__(self, name: str, year_born: int) -> None:
        self.name = name
        self.year_born = year_born

    def __repr__(self) -> str:
        return f"{type(self).__name__}(name={self.name}, year_born={self.year_burn})"

$ mypy file.py

file.py:7: error: "Person" has no attribute "year_burn"; maybe "year_born"?  [attr-defined]
Found 1 error in 1 file (checked 1 source file)

Ignore line by using comment # type: ignore

Pre-commit hooks#

It is possible to set up pre-commit hooks that will run any time you commit to the repo
There is a convenient python package called pre-commit that makes it easy to configure, see https://pre-commit.com
pip install pre-commit (or pipx)

Example configuration#

Define configurations in .pre-commit-config.yaml

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v3.2.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
      - id: check-docstring-first
      - id: debug-statements
      - id: check-toml

  - repo: https://github.com/psf/black
    rev: 22.12.0
    hooks:
      - id: black

  - repo: https://github.com/charliermarsh/ruff-pre-commit
    rev: 'v0.0.254'
    hooks:
      - id: ruff

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v0.950
    hooks:
      - id: mypy

Install hooks using
```
pre-commit install
```
Run all hooks on all files using
```
pre-commit run --all
```

Exercise#

Install pre-commit hooks and run them on all the files in your repo

Run pre-commit in CI#

Add pre-commit as a part of your continuous integration by creating a file .github/workflows/pre-commit.yml with the following content

name: pre-commit

on:
  pull_request:
  push:
    branches: [main]

jobs:
  pre-commit:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v4
    - uses: pre-commit/action@v3.0.0