Skip to main content

​
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

Get up and running with pyrig in under 2 minutes

Architecture

Understand the core systems that power pyrig

​
Key Features

Idempotent Scaffolding

Run pyrig init to generate a complete project. Run it again anytime to sync — pyrig never overwrites your customizations.

Config File System

Every generated file is backed by a Python class that validates and merges automatically. Override any config by subclassing.

Automatic CLI

Your project gets a working CLI immediately. Add commands by defining functions — they’re discovered automatically.

Testing Infrastructure

pytest with autouse fixtures that enforce best practices. pyrig mktests generates test skeletons mirroring your source.

Multi-Package Inheritance

Create a personal pyrig package with your own standards, add it as a dependency, and have everything apply automatically.

Tool Wrappers

Type-safe wrappers around uv, git, ruff, pytest, and more. Customizable via subclassing for org-wide overrides.

​
What You Get

When you run pyrig init, you get a complete project structure: 
my-project/
├── my_project/          # Source package
│   ├── __init__.py
│   ├── main.py          # CLI entry point
│   ├── src/             # Utility modules
│   ├── rig/             # Development infrastructure
│   │   ├── builders/    # Build system
│   │   ├── cli/         # CLI commands
│   │   ├── configs/     # Config file managers
│   │   ├── tools/       # Tool wrappers
│   │   └── tests/       # Test infrastructure
├── tests/               # Test suite
├── docs/                # Documentation
├── .github/             # CI/CD workflows
├── pyproject.toml       # Project metadata
├── .gitignore
└── README.md

​
Core Philosophy

pyrig is built around three principles:

​
1. Declarative Over Imperative

You declare what should exist, pyrig makes it happen. Configuration files are defined as Python classes that specify expected structure: 
from pathlib import Path
from pyrig.rig.configs.base.toml import TomlConfigFile

class MyConfigFile(TomlConfigFile):
    def parent_path(self) -> Path:
        return Path()

    def _configs(self) -> dict:
        return {
            "tool": {
                "myapp": {
                    "setting": "value"
                }
            }
        }
Run pyrig mkroot and the file is created or updated, preserving any user customizations.

​
2. Idempotent by Default

Every operation is safe to run multiple times. pyrig never overwrites your changes — it validates, merges, and preserves:
  • Missing keys are added
  • Extra keys you added are preserved
  • Final structure matches expected configuration
  • Opt-out by emptying the file

​
3. Extensible Through Inheritance

Almost everything in pyrig can be overridden by subclassing. The .I pattern (Instance) and .L pattern (Leaf) automatically discover your implementations: 
from pyrig.rig.tools.package_manager import PackageManager

class MyPackageManager(PackageManager):
    def install_dependencies_args(self) -> Args:
        # Custom implementation
        return self.args("sync", "--frozen")

# Automatically used everywhere
PackageManager.I.install_dependencies_args()
This enables creating organization-wide standards by publishing your own pyrig extension package.

​
Use Cases

New Projects

Bootstrap a production-ready Python project with full CI/CD, testing, and documentation in seconds.

Existing Projects

Standardize your existing project’s structure, tooling, and workflows incrementally.

Organization Standards

Create a company-wide pyrig extension with your organization’s standards and share across all projects.

Multi-Project Tooling

Build CLI tools that work consistently across multiple pyrig-based projects.

​
Requirements

  • Python: 3.12+
  • Package Manager: uv (recommended) or pip
  • Version Control: git
pyrig uses modern Python features including PEP 695 type parameters and PEP 692 Unpack. Python 3.12+ is required.

​
Project Status

Version: 10.2.3

Status: Production/Stable

License: MIT
pyrig is actively maintained and used in production. The API is stable with semantic versioning.

​
Next Steps

Install pyrig

Follow the quickstart guide to get pyrig running in your project

Learn the Architecture

Understand how pyrig’s config system, CLI, and inheritance work

Build docs developers (and LLMs) love

Get started for freeTalk to us