rhiza-tools

Extra utilities and tools serving the mothership rhiza.

📖 New to Rhiza? Check out the Getting Started Guide for a beginner-friendly introduction!

This package provides additional commands for the Rhiza ecosystem, such as version bumping, release management, and documentation helpers. It can be used as a plugin for rhiza-cli or as a standalone tool.

Installation

As a Rhiza Plugin (Recommended)

You can install rhiza-tools alongside rhiza-cli using uvx or pip. This automatically registers the tools as subcommands under rhiza tools.

Using uvx (run without installation)

uvx "rhiza[tools]" tools --help

Using pip

pip install "rhiza[tools]"

Standalone Usage

You can also use rhiza-tools independently if you don't need the full rhiza CLI.

Using uvx

uvx rhiza-tools --help

Using pip

pip install rhiza-tools

Commands

bump

Bump the version of the project in pyproject.toml using semantic versioning. Supports interactive selection, explicit version targets, and prerelease types.

Usage:

# Interactive (prompts for bump type)
rhiza-tools bump

# Explicit bump type
rhiza-tools bump patch
rhiza-tools bump minor
rhiza-tools bump major

# Explicit version
rhiza-tools bump 2.0.0

# Prerelease types
rhiza-tools bump alpha
rhiza-tools bump beta
rhiza-tools bump rc

Arguments:

• VERSION - The version to bump to. Can be an explicit version (e.g., 1.0.1), a bump type (patch, minor, major), a prerelease type (alpha, beta, rc, dev), or omitted for interactive selection.

Options:

• --dry-run - Show what would change without actually modifying files.
• --commit - Automatically commit the version change to git.
• --push - Push changes to remote after commit (implies --commit).
• --branch BRANCH - Branch to perform the bump on (switches back after).
• --allow-dirty - Allow bumping even with uncommitted changes.
• --verbose, -v - Show detailed output from bump-my-version.

release

Push a release tag to remote to trigger the automated release workflow. Optionally bumps the version before releasing.

Usage:

# Interactive (prompts for bump and push)
rhiza-tools release

# Dry-run preview
rhiza-tools release --dry-run

# Bump and release in one step
rhiza-tools release --bump MINOR --push

# Interactive bump selection with dry-run preview
rhiza-tools release --with-bump --push --dry-run

# Non-interactive (for CI/CD)
rhiza-tools release --bump PATCH --push --non-interactive

Options:

• --bump TYPE - Bump type (MAJOR, MINOR, PATCH) to apply before release.
• --with-bump - Interactively select bump type before release (works with --dry-run).
• --push - Push changes to remote (default: prompt in interactive mode).
• --dry-run - Show what would happen without making any changes.
• --non-interactive, -y - Skip all confirmation prompts (for CI/CD).

rollback

Reverse a release and/or version bump. Deletes the release tag locally and on the remote, and optionally reverts the version-bump commit. Uses git revert (not git reset), so it is safe even after the changes have been pushed.

Usage:

# Interactive (choose from recent tags)
rhiza-tools rollback

# Preview a specific tag's rollback
rhiza-tools rollback v1.2.3 --dry-run

# Also revert the version-bump commit, no prompts (for CI/CD)
rhiza-tools rollback v1.2.3 --revert-bump --non-interactive

Options:

• --revert-bump - Also revert the version-bump commit associated with the tag.
• --dry-run - Show what would happen without making any changes.
• --non-interactive, -y - Skip all confirmation prompts (for CI/CD).
• --verbose - Enable verbose debug output.

update-readme

Update README.md with the current output from make help.

Usage:

# As plugin
rhiza tools update-readme

# Standalone
rhiza-tools update-readme

Options:

• --dry-run - Print what would happen without actually changing files.

generate-coverage-badge

Generate a coverage badge JSON file from a pytest-cov coverage report. The badge color adjusts automatically based on the coverage percentage.

Usage:

# Default paths
rhiza-tools generate-coverage-badge

# Custom paths
rhiza-tools generate-coverage-badge \
    --coverage-json tests/coverage.json \
    --output assets/badge.json

Options:

• --coverage-json PATH - Path to the coverage.json file (default: _tests/coverage.json).
• --output PATH - Path to output badge JSON (default: _book/tests/coverage-badge.json).

version-matrix

Emit supported Python versions from pyproject.toml as a JSON array. Primarily used in GitHub Actions to compute the CI test matrix.

Usage:

# Default candidates
rhiza-tools version-matrix

# Custom pyproject path
rhiza-tools version-matrix --pyproject /path/to/pyproject.toml

# Custom candidate versions
rhiza-tools version-matrix --candidates "3.10,3.11,3.12"

Options:

• --pyproject PATH - Path to pyproject.toml (default: pyproject.toml).
• --candidates TEXT - Comma-separated list of candidate Python versions (default: 3.11,3.12,3.13,3.14).

analyze-benchmarks

Analyze pytest-benchmark results and generate an interactive HTML visualization. Prints a table of benchmark names, mean runtimes, and operations per second.

Usage:

# Default paths
rhiza-tools analyze-benchmarks

# Custom paths
rhiza-tools analyze-benchmarks \
    --benchmarks-json tests/benchmarks.json \
    --output-html reports/benchmarks.html

Options:

• --benchmarks-json PATH - Path to benchmarks.json file (default: _benchmarks/benchmarks.json).
• --output-html PATH - Path to save HTML visualization (default: _benchmarks/benchmarks.html).

pip-audit

Run pip-audit with a tiered vulnerability policy. Vulnerabilities in runtime dependencies fail the command; findings in build tooling (pip, setuptools, wheel, distribute) warn without failing. Any arguments after the command are forwarded verbatim to pip-audit.

Usage:

# Audit the current environment
rhiza-tools pip-audit

# Forward flags through to pip-audit
rhiza-tools pip-audit --ignore-vuln CVE-2024-1234

Options:

• --verbose, -v - Show verbose debug output.
• Any other arguments are forwarded to pip-audit.

suppression-audit

Scan the codebase for inline suppression comments (# noqa, # nosec, # type: ignore, # pragma: no cover, # noinspection) and print a per-file report, an ASCII histogram, and a suppression-density letter grade.

Usage:

# Report suppressions and grade
rhiza-tools suppression-audit

# Also fail on stale CVE-tagged # nosec comments
rhiza-tools suppression-audit --fail-stale-nosec-cve

Options:

• --fail-stale-nosec-cve - Fail when # nosec comments reference CVEs that pip-audit no longer reports.
• --verbose, -v - Show verbose debug output.
• Any other arguments are forwarded to pip-audit (for the stale-CVE gate).

Development

Prerequisites

• Python 3.11 or higher
• uv package manager (recommended) or pip
• Git

Setup Development Environment

# Clone the repository
git clone https://github.com/Jebel-Quant/rhiza-tools.git
cd rhiza-tools

# Install dependencies
make install

# Run tests
make test

Community

• Contributing guide
• Code of Conduct
• Architecture decisions
• Testing guide
• Release guide

License

This project is licensed under the MIT License.