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.1.0.tar.gz (883.9 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.1.0-py3-none-win_amd64.whl (774.9 kB view details)

Uploaded Python 3Windows x86-64

madoqua-0.1.0-py3-none-manylinux_2_28_x86_64.whl (867.5 kB view details)

Uploaded Python 3manylinux: glibc 2.28+ x86-64

madoqua-0.1.0-py3-none-macosx_11_0_arm64.whl (755.8 kB view details)

Uploaded Python 3macOS 11.0+ ARM64

File details

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

File metadata

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

File hashes

Hashes for madoqua-0.1.0.tar.gz
Algorithm Hash digest
SHA256 11da662076cf51650b9aa29cefd8c07f9237dd2272fdfd64b46e3c44a3388e29
MD5 d0a5bbe671f34ab1e38dd60d5c1661db
BLAKE2b-256 67e3b92d3465410d9cb82f8081aea4bf1bbc4c434cf63d3e4435adc039f61418

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: madoqua-0.1.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 774.9 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.1.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 791e3f31bcbd646775ed1c8ba3c4345074d3aa40d2de994908267ef25f6e8733
MD5 82455a5bf32956b03d8c629626cfba77
BLAKE2b-256 1a8ac1700d32f11aef7b38d24bea7d216c2d5f92cf20e548ff4aa1ed4dbbb14f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for madoqua-0.1.0-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 ecc1a8c1246bfb1ef9c80890b0e0cfe0ff91f6f181d859081b9d25c38a691e57
MD5 2962ea1eedcab228da0fae11ff6c578b
BLAKE2b-256 be6aa658dddf02004d88658b6a9c7ef940df8d77a18a1a0fa8fe8f5dc77225ed

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for madoqua-0.1.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 260f9a7d0fc8a93762e97723018b80941c15416a35fc0211896b4c95afc9ba48
MD5 4f67f86734acc6c3d9858e38dd24e46b
BLAKE2b-256 734792b900ae5d4dceba341ca192fbc568555f8a4e907a72efe0a1144d487cb8

See more details on using hashes here.

Provenance

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

0.2.0

4 files

This release

0.1.0 This release

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