pyproject-pre-commit 0.6.1

pre-commit hooks for python projects using pyproject.toml.

pyproject-pre-commit

pre-commit hooks for python projects. prek also works as well (current default depends on prek).

.pre-commit-hooks.yaml provides pre-defined ids which you just need to add these ids to your .pre-commit-config.yaml.

By installing pyproject-pre-commit package, all necessary tools are installed as dependencies.

• Requirement
• Usage
  • Install pyproject-pre-commit
  • Optional dependencies
  • Prepare .pre-commit-config.yaml
  • Run prek/pre-commit
• Available ids
• Options for tools
• pyproject.toml

Requirement

• Python >= 3.9.0

Usage

Install pyproject-pre-commit

Using uv:

$ uv add --group dev pyproject-pre-commit

Using poetry:

$ poetry add --dev pyproject-pre-commit

Using pip:

$ pip install pyproject-pre-commit

This will install pyproject-pre-commit and

    "prek>=0.3.2",
    "ruff>=0.15.0",
    "ty>=0.0.15",
    "numpydoc>=1.11.0",
    "shellcheck-py>=0.9.0.5",
    "mdformat>=0.7.22",
    "mdformat-pyproject>=0.0.1",
    "mdformat-ruff>=0.1.3",
    "mdformat-beautysh>=0.1.1",
    "mdformat-config>=0.2.1",
    "mdformat-gofmt>=0.0.2",
    "mdformat-rustfmt>=0.0.3",
    "mdformat-footnote>=0.1.1",
    "mdformat-frontmatter>=2.0.1",
    "mdformat-gfm>=0.3.5",
    "mdformat-tables>=1.0.0",
    "mdformat-web>=0.2.0",
    "mdformat-toc>=0.3.0",
    "validate-pyproject[all]>=0.22",

Optional dependencies

if you want to install pre-commit, do:

$ uv add --dev pyproject-pre-commit[pre-commit]

If you want to use black/autoflake/autopep8/flake8/isort/bandit for linting/formatting, do:

$ uv add --dev pyproject-pre-commit[black]

If you need mypy, do:

$ uv add --dev pyproject-pre-commit[mypy]

If you wish to install all, do:

$ uv add --dev pyproject-pre-commit[all]

Prepare .pre-commit-config.yaml

Add https://github.com/rcmdnk/pyproject-pre-commit to your .pre-commit-config.yaml, like:

repos:
  - repo: https://github.com/rcmdnk/pyproject-pre-commit
    rev: v0.6.0
    hooks:
      - id: ruff-lint-diff
      - id: ruff-lint
      - id: ruff-format-diff
      - id: ruff-format
      - id: ty
      - id: numpydoc-validation
      - id: shellcheck
      - id: mdformat-check
      - id: mdformat
      - id: actionlint
      - id: validate-pyproject

By using pyproject-pre-commit, you can simplify your .pre-commit-config.yaml that you need only repo of https://github.com/rcmdnk/pyproject-pre-commit.

These hooks uses local installation of tools, so pre-commit will use tools installed in your working environment.

This can be made by ppc command:

$ ppc pre-commit > .pre-commit-config.yaml

[!NOTE] If you are using poetry, run poetry run ppc ... or run after poetry shell.

If you already have it, add hooks w/o repos: by

$ ppc --pre-commit |grep -v "^repos:" >> .pre-commit-config.yaml

You may want to modify after adding these configurations.

To use black, flake8, isort and mypy, instead of ruff/ty, add following hooks:

repos:
  - repo: https://github.com/rcmdnk/pyproject-pre-commit
    rev: v0.6.0
    hooks:
      - id: black-diff
      - id: black
      - id: blacken-docs
      - id: autoflake-diff
      - id: autoflake
      - id: autopep8-diff
      - id: autopep8
      - id: isort-diff
      - id: isort
      - id: flake8
      - id: bandit
      - id: mypy
      - id: numpydoc-validation
      - id: shellcheck
      - id: mdformat-check
      - id: mdformat
      - id: actionlint
      - id: validate-pyproject

This can be made by ppc command:

$ ppc pre-commit --black --mypy > .pre-commit-config.yaml

Run prek/pre-commit

prek command is installed as dependencies of pyproject-pre-commit package.

After installing pyproject-pre-commit package, you can run prek command.

First, install pre-commit hooks by:

$ prek install

then you can run pre-commit by:

$ prek run -a

[!NOTE] If you are using uv, run uv run pre-commit ...

If you want to use pre-commit command, install pyproject-pre-commit[pre-commit] and use pre-commit command.

Available ids

You can find ids in .pre-commit-hooks.yaml.

There are ids for following tools:

• For Python linting/formatting
  • ruff-lint-diff: Just show ruff check result.
  • ruff-lint: Fix by ruff for lint.
  • ruff-format-diff: Just show ruff format result.
  • ruff-format: Format by ruff.
  • black-diff: Just show Black result.
  • black: Black: The uncompromising Python code formatter.
  • blacken-docs: Run black on python code blocks in documentation files.
  • autoflake-diff: Just show autoflake result.
  • autoflake: autoflake removes unused imports and unused variables from Python code.
  • autopep8-diff: Just show autopep8.
  • autopep8: autopep8 automatically formats Python code to conform to the PEP 8 style guide.
  • isort-diff: Just show isort result.
  • isort: isort your imports, so you don't have to.
  • flake8: flake8 is a command-line utility for enforcing style consistency across Python projects.
    • With following plugins:
      • flake8-pyproject
      • flake8-annotations-complexity
      • flake8-bugbear
      • flake8-builtins
      • flake8-comprehensions
      • flake8-debugger
      • flake8-docstrings
      • flake8-executable
      • flake8-pep3101
      • flake8-print
      • flake8-rst-docstrings
      • flake8-string-format
      • pep8-naming
      • pycodestyle
  • bandit: Bandit is a tool for finding common security issues in Python code.
• For Python type checking
  • ty: An extremely fast Python type checker and language server, written in Rust.
  • mypy: Mypy is a static type checker for Python.
• For Shell script
  • shellcheck: ShellCheck - A shell script static analysis tool
• For Markdown
  • mdformat-check: Just show mdformat result.
  • mdformat: CommonMark compliant Markdown formatter.
    • with following plugins:
      • mdformat-gfm
      • mdformat-frontmatter
      • mdformat-footnote
• For GitHub Actions
  • actionlint: Lint GitHub workflows with actionlint.
• For pyproject.toml
  • validate-pyproject: Validate pyproject.toml file.

All tools are installed as dependencies of pyproject-pre-commit package.

shellcheck and mdformat are given in addition to python tools as they can be managed by pip and most projects have README.md and some have shell scripts.

For tools which can format files, there are additional ids with -diff or --check which show the results before modifying files. You can see the differences after formatting if you place these ids before ids w/o --diff or --check.

Options for tools

You can set options in pyproject.toml for all tools above.

For flake8, flake8-pyproject allows to read options from pyproject.toml

About bandit, there is a plugin for the flake8, but plugin version does not read options from pyproject.toml even with pyproject.toml. Therefore, use bandit directly and give -c pyproject.toml option in the hooks.

pyproject.toml

You can set options in pyproject.toml for all tools.

Example options can be made by ppc command:

$ ppc --pyproject >> pyproject.toml

or

$ ppc --pyproject --black --mypy >> pyproject.toml

You may want to modify after adding these configurations.