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:
Newer release available (0.2.2)

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.0.tar.gz (884.5 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.0-py3-none-win_amd64.whl (775.1 kB view details)

Uploaded Python 3Windows x86-64

madoqua-0.2.0-py3-none-manylinux_2_28_x86_64.whl (867.6 kB view details)

Uploaded Python 3manylinux: glibc 2.28+ x86-64

madoqua-0.2.0-py3-none-macosx_11_0_arm64.whl (756.0 kB view details)

Uploaded Python 3macOS 11.0+ ARM64

File details

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

File metadata

  • Download URL: madoqua-0.2.0.tar.gz
  • Upload date:
  • Size: 884.5 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.0.tar.gz
Algorithm Hash digest
SHA256 f24565c60b12e9b68f2bee7f8273b42911028bc9a8650a1c2e2817fcc7d8a674
MD5 276fe38216a191c6dd08284cc1166a4b
BLAKE2b-256 ae4ac11002f6365d924f54e8a9fc44782161f95312fedad9dfe7f00f2fce186b

See more details on using hashes here.

Provenance

The following attestation bundles were made for madoqua-0.2.0.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.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: madoqua-0.2.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 775.1 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.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 57b67aaa900b303bbc74ccc0053063e15c294c4e1d3c1a0da11cd0f9d26d33ad
MD5 aeeede6bad9a33a01d494a75264dbad0
BLAKE2b-256 88c5105dd35f4aa428f78369a12918b8eb553826be0893487459ae29be4182cd

See more details on using hashes here.

Provenance

The following attestation bundles were made for madoqua-0.2.0-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.0-py3-none-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for madoqua-0.2.0-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 5bf3080eb9e8a0165f5efaed8b2f96a8d8ae3a6582aaabb2f0c62dd979c48635
MD5 93bceb4ee5e1700e44862b3e7c54e686
BLAKE2b-256 2c51270b3507c75a6d236b59fed744de02c88fb189da0c181cd8e26185daeb07

See more details on using hashes here.

Provenance

The following attestation bundles were made for madoqua-0.2.0-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.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for madoqua-0.2.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2a1b54d9e28c0d5594cd9f7737187632f8c98f2c0cb55e9caf3a6b578e0ee92c
MD5 39c51b47c3a2570d3d10f58dcf1a5399
BLAKE2b-256 dba6d023cf4b919247752c4754c0befddd25e6aec6b02364275138cc395640ac

See more details on using hashes here.

Provenance

The following attestation bundles were made for madoqua-0.2.0-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

0.2.2

4 files

0.2.1

4 files

This release

0.2.0 This release

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