.pre-commit-config.yaml

# By default, `pre-commit` only runs against changed files (i.e. files that have been
# modified and added to your `git` staging area with `git add`). Unstaged files will not
# be checked and `pre-commit` will not run if you have unstaged changes to your
# `.pre-commit-config.yaml`.
#
# So, when you first add a new hook to this repo, it is a good idea to save a local backup
# of your files on your branch
#
# git stash push -m 'WIP on your-branch'
#
# and then run the hook against all files in the repo
#
# pre-commit run your-new-hook --all-files
#
# This will show you how it works by default so you can add arguments to the hook or
# configure it to work exactly how you want. To restore your backup, run
#
# git reset --hard HEAD
# git stash apply
#
# Once you're sure you back to where you started, you can clear the stash
#
# git stash clear
#
# Individual hooks can be run by specifying their `id` to `pre-commit run`. All hooks in
# your `.pre-commit-config.yaml` can be run with `pre-commit run --all`.
#
# We often want to run against the latest version of the linter/formatters available. We
# also want to make sure all our hook configuration options are respected so we know it
# runs the way we expect across all systems (virtual environments, CI, different OS's,
# etc.)
#
# In general, you pass the hook repo url to `repo` and `pre-commit` creates an isolated
# (virtual) environment where it clones (downloads) necessary files and installs them.
# This is nice so that
#
# - you don't have to require developers to install the dependency (`pip install x` for
#   Python)
# - the testing is independent of your system, which reduces gotcha's like "it works on
#   my machine, but not yours" (forces you to be deliberate about passing configuration
#   arguments to the hook)
#
# Because `pre-commit` runs in an isolated environment, it won't have access to your
# locally-installed dependencies. Hence, if the hook requires additional dependencies
# (like `toml`), you must specify them as additional dependencies to the hook:
#
# repo: https://yourhook.com
# rev: x.y.z
# hooks:
# - id: do-the-thing
#   additiona_dependencies: [
#     "toml"
#   ]
#
# However, some hooks have special environment requirements that don't allow them to be
# run in isolation (e.g. `pylint` and `pytest`). For these, you pass the argument
# `'local'` to `repo` without a `rev` to specify that it will be run on the current
# machine (local or CI). `pre-commit` will not run these in an isolated virtual
# environment, so you must setup the virtual environment and install dependencies
# manually (typically from a maintained `requirements.txt` or `pyproject.toml` file).
#
# In addition, sometimes there are conflicts between the files `pre-commit` passes to
# your hook (the changed files in your staging area) and the hook that can't be well-
# managed with include or exclude configuration options. Other times, you may simply
# want to always to run a hook against the same set of files before commit (not just
# changed files in your staging area). For this, you can use
#
# `pass_filenames: false`
#
# Note that, in general, you want to avoid this because the hook will take longer to
# run (since you're always running against a fixed set of files in this case rather than
# just changed files). Alternatively, it is better to specify files to include and
# exclude:
#
# `files: ...`
# `exclude: ...`
#
# To ensure hooks stay up to date:
#
# 1. For non-local hooks (using the repo url), run
#
#    pre-commit autoupdate --repo hook-repo-url
#
#    To update all hooks in your `.pre-commit-config.yaml` automatically, run
#
#    pre-commit autoupdate
#
#    (NOTE: You usually ALWAYS want `rev`` hard-coded to a specific release tag and let
#    `autoupdate` handle updating the hook version. This way, you know exactly which
#     version of the hook is running. Also, `pre-commit` typically warns about "floating"
#     or imprecise revs) To update to the latest rev, use.
#
# 2. For local hooks, dependencies must be updated manually (e.g. `pip install --upgrade`)
#
# Note that for local hooks, all the following properties must be specified for the hook
# to run:
#
#   - id
#   - name
#   - language
#   - entry
#   - files/types
#
# Finally, By default, `pre-commit` runs all hooks sequentially in the order they are
# listed in the `.pre-commit-config.yaml`. However, since version `v1.13.0`, `pre-commit`
# runs each _individual hook operation_ on all the files passed to it in parallel. The is
# beneficial for the majority of cases since it means each hook will execute faster, but
# there are some scenarios where this may present a problem:
#
# - if a hook reads from other files not passed to it (e.g. a configuration file), or
# - if a hook writes to other files not passed to it (e.g. a log file)
#
# In the above cases, this may lead to a race condition or deadlock. In the event your
# hook needs to access the same file across multiple processes, you can specify the hook
# be run on files sequentially by passing
#
# `require_serial: true`
#
fail_fast: true
repos:
  - repo: https://github.com/andrei-shabanski/poetry-plugin-sort
    rev: v0.2.0
    hooks:
      - id: poetry-sort
        name: (poetry-sort) Sort dependencies alphabetically

  # - repo: https://github.com/adam-grant-hendry/poetry_plugin_constrain
  #   rev: 0.1.0
  #   hooks:
  #     - id: poetry-plugin-constrain
  #       name: (poetry-plugin-constrain) Replace upper-bound constraints with lower-bound

  - repo: https://github.com/asottile/pyupgrade
    rev: v3.0.0
    hooks:
      - id: pyupgrade
        name: (pyupgrade) Format source to latest python syntax
        language: python
        files: .*\.pyi?$
        entry: pyupgrade
        args: ["--py38-plus"]
        minimum_pre_commit_version: 0.15.0

  - repo: https://github.com/hadialqattan/pycln
    rev: v2.1.1
    hooks:
      - id: pycln
        name: (pycln) Remove unused imports
        language: python
        files: .*\.pyi?$
        entry: pycln
        args: ["--config=pyproject.toml"]

  - repo: https://github.com/psf/black
    rev: 22.8.0
    hooks:
      - id: black
        name: (black) Format source code
        language: python
        files: .*\.pyi?$
        entry: black
        args: ["--config=pyproject.toml"]
        minimum_pre_commit_version: 2.9.2

  - repo: local
    hooks:
      - id: isort
        name: (isort) Sort imports per PEP8
        language: system
        files: .*\.pyi?$
        entry: isort
        types_or: [cython, pyi, python]
        args: ["--filter-files"]
        require_serial: true
        minimum_pre_commit_version: 2.9.2

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.3.0
    hooks:
      - id: trailing-whitespace
        name: (pre-commit-hooks) Fix trailing whitespace (ignores Markdown)
        args: [--markdown-linebreak-ext=md]
      - id: double-quote-string-fixer
        name: (pre-commit-hooks) Replace double quotes with single
      - id: end-of-file-fixer
        name: (pre-commit-hooks) Ensure files end with one new line
      - id: check-docstring-first
        name: (pre-commit-hooks) Check docstrings defined before code
      - id: name-tests-test
        name: (pre-commit-hooks) Check tests named correctly ('test_*.py')
        args: [
            "--django", # `test_*.py` style
          ]
        exclude: ^tests/helpers\.py
      - id: check-merge-conflict
        name: (pre-commit-hooks) Check no files contain merge conflict strings
      - id: check-toml
        name: (pre-commit-hooks) Check TOML files parseable
      - id: check-yaml
        name: (pre-commit-hooks) Check YAML files parseable

  - repo: https://github.com/asottile/add-trailing-comma
    rev: v2.3.0
    hooks:
      - id: add-trailing-comma
        name: (add-trailing-comma) Add trailing commas to calls and literals

  - repo: https://github.com/asottile/blacken-docs
    rev: v1.12.1
    hooks:
      - id: blacken-docs
        name: (blacken-docs) Run `black` on python code blocks in docs

  # `markdownlint` is only available through npm (Node.js), not pip (PyPI).
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.32.2
    hooks:
      - id: markdownlint
        name: (markdownlint) Check Markdown syntax
        args: ["--config=.markdownlint.yml"]

  - repo: https://github.com/pre-commit/pygrep-hooks
    rev: v1.9.0
    hooks:
      - id: python-check-blanket-noqa
        name: (pygrep-hooks) Check `noqa` annotations have codes
      - id: python-check-blanket-type-ignore
        name: (pygrep-hooks) Check `type ignore` comments have codes
      - id: rst-backticks
        name: (pygrep-hooks) Check double-backticks used in rst files
      - id: rst-directive-colons
        name: (pygrep-hooks) Check directives end in double-colon in rst files

  - repo: local
    hooks:
      - id: pydocstyle
        name: (pydocstyle) Check docstrings formatted correctly (PEP257, Numpy convention)
        language: system
        types: [python, pyi, rst, markdown]
        entry: pydocstyle
        require_serial: true

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.0.285
    hooks:
      - id: ruff
        # args: [ --fix, --exit-non-zero-on-fix ]

  # cspell is only available through npm (Node.js), not pip (PyPI).
  - repo: https://github.com/streetsidesoftware/cspell-cli
    rev: v6.12.0
    hooks:
      - id: cspell
        name: (cspell) Check spelling

  - repo: https://gitlab.com/bmares/check-json5
    rev: v1.0.0
    hooks:
      - id: check-json5
        name: (check-json5) Check JSON5 files parseable (json5 = json with comments)

  - repo: local
    hooks:
      - id: mypy
        name: (mypy) Check static type hinting
        entry: mypy
        language: system
        types: [python]
        require_serial: true

      - id: pytest
        name: (pytest) Run tests
        stages: [push]
        entry: coverage run -m pytest
        types: [python]
        language: system
        require_serial: true
        pass_filenames: false
        always_run: true

      - id: coverage
        name: (coverage) Output test coverage
        stages: [push]
        entry: coverage html
        types: [python]
        language: system
        require_serial: true
        pass_filenames: false
        always_run: true