pyrig 8.2.3

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

pyrig

---

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

---

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

Project Scaffolding & Idempotent Init

pyrig's init command scaffolds a complete, production-ready Python project (source layout, tests, CI/CD, docs, configs, working CLI) and is safe to re-run due to its idempotency. See the Getting Started Guide for details and full generated project structure for the full layout.

Config File System

pyrig generated Files are modeled as Python classes in pyrig. They validate, and merge automatically. Extend or override configurations by subclassing. You can create your onw Config File classes as well and pyrig will handle them for you, you just need to define behaviour. See the Config Architecture documentation for details.

Dynamic Multi-Package CLI Discovery

pyrig init also sets up a CLI for your project, that works out of the box and can be extended with custom commands very easily. Just define a function in <package>.rig.cli.subcommands and it will be available as a CLI command automatically. pyrig also supports multi-package CLI discovery via defining a function in <package>.rig.cli.shared_subcommands which will be available in all downstream packages in the dependency chain, just like the version command provided by pyrig. See the CLI docs for details.

Pytest Enforcement, Autouse Fixtures && Test Skeleton Generation

pyrig comes with pytest configured as the test runner, and includes autouse fixtures that enforce best practices, validate project invariants, and auto-generate missing test skeletons. To generate test skeletons for missing tests, just run uv run pyrig mktests and pyrig will create test skeletons for any missing tests based on the source code structure. See the Test Structure docs for more details. pyrig's autouse fixtures check some things like ensuring that all source files have corresponding test files, that all packages have __init__.py files, and that Config Files are correct. They also auto-upgrade your dependencies via uv lock --upgrade to the latest allowed version defined in your pyproject.toml. See the Autouse fixtures documentation for details on all the autouse fixtures provided by pyrig.

Multi-Project Inheritance Model

pyrig allows you to override and customize almost any and all behavior in a project via its .L inheritance system. Just define a class that inherits from the pyrig provided class, override the behaviour you want to change, and pyrig will use your implementation instead of the default one. This applies to all Config Files, CLI commands, tools, builders, and more. You can even define your own custom Config Files and pyrig will handle them for you as long as they inherit from ConfigFile. This is a very powerful feature and a bit hard to explain easily, so please check out the documentation for more details and examples. In our opinion, the best thing this enables is that you can define your very own personal pyrig package that defines your own standards and tools, and then just add it as a dependency to all your projects to have those standards and tools available everywhere automatically by just running uv add my-pyrig-package and uv run pyrig init in each project, which is pretty amazing. See the Tool Architecture docs and the Config Architecture docs for details and examples.

Tool Wrappers

pyrig provides type-safe Python wrappers for all tools that are used (uv, git, ruff, pytest, etc.) to standardize usage and expose clear, typed interfaces. Via pyrig's multi-package inheritance model, projects can adjust or replace tool implementations by subclassing and overriding the provided tool classes — this allows organization-wide customization or per-project overrides, making tool behavior highly flexible — see the Tools docs for details.

Builders

pyrig includes a builders system (for example, PyInstaller integration) to create distributables, standardize build processes, and integrate with packaging back-ends — see the Builders docs for details.

Resource Abstraction (Dev + PyInstaller)

Helpers provide reliable access to package resource files in development and when bundled with PyInstaller. See the Resources docs for resource handling details.

CI/CD & Repository Automation

pyrig generates GitHub workflows, branch protection configs, issue/PR templates and includes commands to help configure repository protections and release flows — see the Branch protection docs for repository automation details.

Logging & CLI Controls

Global CLI verbosity flags (-v, -vv, -q) provide flexible logging formatting and levels to improve developer ergonomics for commands and tools — see the CLI docs.

Packaging & Distribution Integration

pyrig integrates with packaging and build back-ends (console scripts, uv_build) to simplify publishing and distribution. See pyproject.toml and the Builders docs for packaging and build details.

CLI Commands

uv run pyrig init         # Complete project initialization
uv run pyrig mkroot       # Create/update all config files
uv run pyrig mktests      # Generate test skeletons
uv run pyrig mkinits      # Create __init__.py files
uv run pyrig build        # Build artifacts (PyInstaller, etc.)
uv run pyrig protect-repo # Configure repository protection
uv run my-project --help  # Your project's CLI

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