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.1.tar.gz (885.0 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.1-py3-none-win_amd64.whl (775.2 kB view details)

Uploaded Python 3Windows x86-64

madoqua-0.2.1-py3-none-manylinux_2_28_x86_64.whl (867.7 kB view details)

Uploaded Python 3manylinux: glibc 2.28+ x86-64

madoqua-0.2.1-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.1.tar.gz.

File metadata

  • Download URL: madoqua-0.2.1.tar.gz
  • Upload date:
  • Size: 885.0 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.1.tar.gz
Algorithm Hash digest
SHA256 451d4eac66e3d9d5c4967253d3901831a8f20cc96d97ab599fffe47b0a2527f6
MD5 bdd270b4fa6fd76beaff7a1d1d229c4a
BLAKE2b-256 0e4be320c86e322a935c6dcb5953a2895f4d7a903c2453b3f53c1a417f84c31a

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: madoqua-0.2.1-py3-none-win_amd64.whl
  • Upload date:
  • Size: 775.2 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.1-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 efd7468d8435375d1bcf15128c01d87cad719052e6a0f9f03cdeb0131585381c
MD5 87df038f98b08c16caa91a7539000589
BLAKE2b-256 c4e669ee14d082f24e0de06702341d6adb9cf56b2e905f5c15cc5d8cf53f678b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for madoqua-0.2.1-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 1a22d4b7acc8d676ac307378e527764e01d1401ebef899d416f6be94759dbcf7
MD5 ce0b4e71dcaf138177af6a5009e6bf0b
BLAKE2b-256 23fb6be9ff5e7c18fead8e3863b8cc91748b59e9778cdb349ca062288bcdeae3

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for madoqua-0.2.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f87e4a5a581d5a081b177c69a7df2cbfa9cb7e5989ad6184b96bb40896c78f9b
MD5 954c58b0b0110df7e8430f0cdbb751b2
BLAKE2b-256 56aec84cf2396ca84d8b2b7911cae5f6003ae563817e42f4b29d2ca54c7a0254

See more details on using hashes here.

Provenance

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

This release

0.2.1 This release

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