pyrig 11.3.1

pyrig is a python toolkit that rigs up your project by standardizing and automating project setup, configuration and maintenance

pyrig

---

pyrig is a python toolkit that rigs up your project by standardizing and automating project setup, configuration and maintenance

---

What is pyrig?

pyrig generates and maintains a complete, production-ready Python project from a single command. It creates all the files you need — source structure, tests, CI/CD, documentation, configs — and keeps them in sync as your project evolves. Rerun it anytime: pyrig is idempotent.

Quick Start

uv init
uv add pyrig
uv run pyrig init

See the Getting Started Guide for detailed setup instructions.

Features

Idempotent Project Scaffolding

pyrig init generates a complete project in one command — source tree, tests, CI/CD workflows, documentation, configs, and a working CLI. Run it again anytime to sync everything; pyrig never overwrites your customizations.

→ Getting Started · Generated Structure

Config File System

Every generated file is backed by a Python class that validates and merges automatically. Override any config by subclassing, or define entirely new config files — pyrig discovers and manages them for you.

→ Config Architecture

Automatic CLI

pyrig init sets up a CLI for your project that works immediately. Add commands by defining functions in <package>.rig.cli.subcommands — they're discovered automatically. Shared commands propagate across the entire dependency chain.

→ CLI docs

Testing Infrastructure

• pytest as the test runner with autouse fixtures that enforce best practices
• pyrig mktests generates test skeletons mirroring your source structure
• Autouse fixtures validate project invariants — init files, config correctness, dependency freshness

→ Test Structure · Autouse Fixtures

Multi-Package Inheritance (.I pattern)

Override almost any behavior — configs, tools, CLI commands, builders — by subclassing the pyrig-provided class. pyrig discovers your implementation automatically and uses it instead of the default.

This enables creating a personal pyrig package with your own standards, adding it as a dependency to any project, and having pyrig init apply everything automatically.

→ Tool Architecture · Config Architecture

Tool Wrappers

Type-safe wrappers around uv, git, ruff, pytest, bandit, and more. Customizable via subclassing for organization-wide or per-project overrides.

→ Tools · Tooling Choices

Builders, Resources & Packaging

• Builders — PyInstaller integration and extensible build system
• Resources — Reliable file access in both development and PyInstaller bundles
• Packaging — uv_build backend with console script integration

→ Builders · Resources

CI/CD & Repository Automation

Generates GitHub Actions workflows, branch protection configs, issue/PR templates, and release flows. Verbosity flags (-v, -vv, -q) provide flexible logging across all commands.

→ Workflows · Branch Protection

CLI Commands

uv run pyrig init           # Full project initialization
uv run pyrig mkroot         # Create/update all config files
uv run pyrig mktests        # Generate test skeletons
uv run pyrig mkinits        # Create missing __init__.py files
uv run pyrig build          # Build artifacts (PyInstaller, etc.)
uv run pyrig protect-repo   # Configure repository protection
uv run pyrig scratch        # Execute the project's .scratch file
uv run pyrig rmpyc          # Remove __pycache__ directories
uv run my-project --help    # Your project's CLI
uv run my-project version   # Show pyrig or project version

→ CLI Reference

Documentation

Getting Started	Complete setup guide
Full Documentation	Comprehensive reference
Trade-offs	What you give up and what you gain
CodeWiki	AI-generated docs
Tutorials	YouTube tutorials for pyrig