Configuration

The Precommit configuration file is a YAML type file that should exist at the root of your repository, and is called .pre-commit-config.yaml. This configuration file refrences external repositories that have been setup to work with Precommit, and provide some code quality control. Most of these are to follow PEP standards, which is a universal Python coding standard. Here are some common repositories CHIME uses as hooks in Precommit:

1. pyupgrade: Upgrade your code to follow new Python conventions
2. absolufy-imports: Make your imports absolute instead of relative
3. isort: Sort your module imports into a readable format
4. autoflake: Remove unused imports and unused variables
5. docformatter: Format docstrings to a specified standard
6. black: Use the uncompromising Black formatter to format your code to a universal standard
7. pre-commit-hooks: Default pre-commit hooks to check for whitespaces, etc
8. mypy: Check for correct type-hinting in your code
9. flake8: A Python linting tool that checks your codebase for errors, styling issues, and line complexity
10. pydocstyle: Check for any missing docstrings/incorrect docstring format
11. bandit: Check for security vulnerabilities in your codebase

Each of these are "repos", and each repo can contain multiple "hooks" (tools), with specified "arguments".

Example .pre-commit-config.yaml file

exclude: ^(docs/.*|tests/.*|data/.*|.venv/.*)$
repos:
- repo: https://github.com/asottile/pyupgrade
    rev: v3.3.1
    hooks:
    - id: pyupgrade
        args:
        - --py38-plus

- repo: https://github.com/MarcoGorelli/absolufy-imports
    rev: v0.3.1
    hooks:
    - id: absolufy-imports

- repo: https://github.com/pycqa/isort
    rev: 5.12.0
    hooks:
    - id: isort
        args:
        - --profile=black
        - --verbose

- repo: https://github.com/pycqa/autoflake
    rev: v2.2.0
    hooks:
    - id: autoflake
        args:
        - --in-place # Overwrite contents
        - --remove-all-unused-imports

- repo: https://github.com/pycqa/docformatter
    rev: v1.7.5
    hooks:
    - id: docformatter
        args:
        # Add a "--style=numpy" or "--style=google" once support is added
        - --in-place
        - --black # Wraps descriptions and summaries if over 88 length
        - --pre-summary-newline
        - --close-quotes-on-newline
        # Avoid adding "--make-summary-multiline" to enforce no single-line docstrings
        # as this conflicts with Black and causes perpetual formatting by both of them

- repo: https://github.com/psf/black
    rev: 22.12.0
    hooks:
    - id: black
        args:
        - --preview # Allows Black to fix "line too long" issues in strings
        - --verbose

- repo: https://github.com/pre-commit/mirrors-mypy
    rev: v0.991
    hooks:
    - id: mypy
        additional_dependencies:
        # Add to these types as needed to allow for type checking, based on various module imports
        - types-attrs
        - types-pytz
        args:
        # Add --strict to verify the entire codebase is using type-hinting
        - --ignore-missing-imports # mypy uses a local venv, so ignore the inevitable missing CHIME package import errors
        - --follow-imports=skip # If you follow imports, mypy will check more than just the diff

- repo: https://github.com/pycqa/flake8
    rev: 6.0.0
    hooks:
    - id: flake8
        args:
        - --max-complexity=15
        - --max-line-length=88 # To be equivalent to Black's format
        - --extend-ignore=E203,E731
        # E203: Black formats in such a way that this error will always be triggered
        # E731: Allow assigning of lambda expressions, they're useful

- repo: https://github.com/pycqa/pydocstyle
    rev: 6.3.0
    hooks:
    - id: pydocstyle
        args:
        - --convention=pep257 # Change to "numpy" or "google" once support is added to pycqa/docformatter,D400,D401
        # D400/D401: semantic errors