madoqua

A pre-commit hook for Python repos: fix what you staged, re-stage it, run the checks in parallel, say one line. Small, fast, silent until there's something to say.

pre-commit ok (3 py files, 1.8s, slowest: ty check 1.6s): ruff fix, ruff format applied & staged; ruff check, ty check passed

That is the entire output of a clean commit. A commit with a problem prints only the tool that had one.

Documentation · Configuration · Commands

Install

uv tool install madoqua
# or
pipx install madoqua
# or, per project
uv add --dev madoqua

Use

madoqua install   # write hooks/pre-commit and point git at it
madoqua run       # what the hook does; also what a bare `madoqua` does
madoqua stats     # what the hook has been costing you

madoqua needs a virtualenv at <repo_root>/.venv with the tools it calls installed — it refuses to run a ruff from outside it, because a version that disagrees with CI produces failures that look like your code's fault. With the defaults that means uv venv && uv sync.

Configure

Zero configuration gets you ruff check --fix, ruff format, ruff check and ty check. To change that, add [tool.madoqua] to pyproject.toml:

[tool.madoqua]
fix = ["ruff check --fix --quiet", "ruff format --quiet"]
check = [
  "ruff check --quiet",
  { name = "ty", cmd = "ty check", timeout_s = 120, max_output_lines = 200 },
]

.git/hooks.local.toml is a personal, uncommitted overlay on the same schema: check/fix replace a list, extend_check/extend_fix append to it, scalars win. MADOQUA_SKIP="ty,ruff check" drops checks by name for one run.

See Configuration.

Exit codes

Code Meaning
0 Clean — the commit may proceed
1 A check failed, or the virtualenv guard refused — the commit is blocked
2 The run could not complete — madoqua itself is misconfigured or broken

Using it from Claude Code

Paste this into your project's CLAUDE.md:

## madoqua

`madoqua` is this repo's pre-commit hook. It runs the fixers on the staged
Python files, re-stages them, runs the checks in parallel, and prints one line.
It runs itself on `git commit` — invoke it directly to see what a commit would
say before making one.

```sh
madoqua guide                     # what to do here, right now
madoqua run                       # what `git commit` will do; one line if clean
MADOQUA_SKIP="ty check" madoqua run   # drop a check by name, this run only
madoqua stats                     # which check is costing the most time

Start with madoqua guide: it prints setup instructions in a repo that is not wired up yet, and triage instructions in one that is. madoqua guide tune is the configuration reference.

Exit codes: 0 clean, 1 a check failed (the commit would be blocked), 2 madoqua could not run. Failing checks print only the failing tool's output, on stderr.

Configuration is [tool.madoqua] in pyproject.toml. Set max_output_lines on a noisy check to keep its failures inside a context window.

<!-- END SHARED:claude-snippet -->

## Development

```sh
make review-quick   # fmt, clippy, tests
make review         # the above plus cargo-audit and cargo-deny
make docs           # build the mdBook site + llms.txt
make wheel          # build the Python wheel with maturin

Installing from a checkout:

cargo install --path .

See docs/dev/ARCHITECTURE.md and docs/adr/.

License

MIT — see LICENSE.

Project links

Data verified by PyPI on Sep 6, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for mojzis from gravatar.com mojzis

Credits

Author: mojzis

GitHub Statistics

Data verified by PyPI on Sep 6, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.10

Provides Extra

dev

Tags

cli rust

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

madoqua-0.2.2.tar.gz (886.4 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

madoqua-0.2.2-py3-none-win_amd64.whl (775.3 kB view details)

Uploaded Python 3Windows x86-64

madoqua-0.2.2-py3-none-manylinux_2_28_x86_64.whl (867.9 kB view details)

Uploaded Python 3manylinux: glibc 2.28+ x86-64

madoqua-0.2.2-py3-none-macosx_11_0_arm64.whl (756.1 kB view details)

Uploaded Python 3macOS 11.0+ ARM64

File details

Details for the file madoqua-0.2.2.tar.gz.

File metadata

  • Download URL: madoqua-0.2.2.tar.gz
  • Upload date:
  • Size: 886.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for madoqua-0.2.2.tar.gz
Algorithm Hash digest
SHA256 799f70ae2eebaf8e3d8e296a1bc6af96459aa5ad6d6f683d2d0e85d2ef186d92
MD5 9c995e9db24189fe738614d283eac27c
BLAKE2b-256 9d47b638680853d3a3fd05678acb31c125b2ee73c083998f45118fd201f01623

See more details on using hashes here.

Provenance

The following attestation bundles were made for madoqua-0.2.2.tar.gz:

Publisher: release.yml on mojzis/madoqua

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file madoqua-0.2.2-py3-none-win_amd64.whl.

File metadata

  • Download URL: madoqua-0.2.2-py3-none-win_amd64.whl
  • Upload date:
  • Size: 775.3 kB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for madoqua-0.2.2-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 8cde9b4a776a39c6b92d72379c9d72f0de77e4019967a5ed7c275e1793b39725
MD5 b65aadb3b1e603bdf37bba103c5a822e
BLAKE2b-256 f5ab16170ffe43b4b0a088cf29507fe8102533a68afa620fa8d696c3f4c2dddd

See more details on using hashes here.

Provenance

The following attestation bundles were made for madoqua-0.2.2-py3-none-win_amd64.whl:

Publisher: release.yml on mojzis/madoqua

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file madoqua-0.2.2-py3-none-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for madoqua-0.2.2-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f56ee6598683e276dcf5a00fccec2960cd166a8c4aa1dda61c82c6ef5c2de31f
MD5 5e592840770762951436a42a17558ff2
BLAKE2b-256 c4e0edffd6b495454d77ece7a0bf522f7028f0ec6db60a4554cdd2c96c1890f3

See more details on using hashes here.

Provenance

The following attestation bundles were made for madoqua-0.2.2-py3-none-manylinux_2_28_x86_64.whl:

Publisher: release.yml on mojzis/madoqua

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file madoqua-0.2.2-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for madoqua-0.2.2-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 465a237666d16fa3365b92cfa58750e5bb94f8a95f7c6a3c022ffd342c6ff0e6
MD5 3ee8040db2a4390254603afc29e7a69c
BLAKE2b-256 5cc1558f9dff51b20e30297dfe144564313ca5eec797372e91af46e19883f0fd

See more details on using hashes here.

Provenance

The following attestation bundles were made for madoqua-0.2.2-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on mojzis/madoqua

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.2 This release

4 files

0.2.1

4 files

0.2.0

4 files

0.1.0

4 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page