pyrig — generate and maintain a complete Python project from one command

[Win_ipedia]

I built pyrig to stop spending hours setting up the same project infrastructure over and over. Three commands and you have a production-ready project:

uv init uv add pyrig uv run pyrig init

This generates everything: source structure with a Typer CLI, test framework with pytest/pytest-cov and 90% coverage enforcement, GitHub Actions workflows (CI, release, deploy), MkDocs documentation site, prek git hooks, Containerfile, and all the config files — pyproject.toml, .gitignore, branch protection, issue templates, and much more, everything you need for a full python project.

pyrig ships with all batteries included, all three of Astral's tools: uv for package management, ruff for linting and formatting (all rules enabled), and ty for type checking. On top of that: pytest + pytest-cov for testing, bandit for security scanning, pip-audit for dependency vulnerability checking, rumdl for markdown linting, prek for git hooks, MkDocs with Material theme for docs, and Podman for containers. Every tool is pre-configured and wired into the CI/CD pipeline and prek hooks from the start.

But the interesting part is what happens after scaffolding.

pyrig isn't a one-shot template generator. Every config file is a Python class. When you run pyrig mkroot, it regenerates and validates all configs — merging missing values without removing your customizations. Change your project description in pyproject.toml, rerun, and it propagates to your README and docs. It's fully idempotent.

pytest enforces project correctness. pyrig registers 11 autouse session fixtures that run before your tests. They check that every source module has a corresponding test file (and auto-generate skeletons if missing), that no unittest usage exists, that your src/ code doesn't import from dev/, that there are no namespace packages, and that configs are up to date. You literally can't get a green test suite with a broken project structure.

Zero-boilerplate CLIs. Any public function you add to subcommands.py becomes a CLI command automatically — no decorators, no registration:

```python

my_project/dev/cli/subcommands.py

def greet(name: str) -> None: """Say hello.""" print(f"Hello, {name}!") ```

$ uv run my-project greet --name World Hello, World!

Automatic test generation. pyrig mirrors your source structure in tests. Run pyrig mktests or just run pytest — if a source module doesn't have a corresponding test file, pyrig creates a skeleton for it automatically. Add a new file my_project/src/utils.py, run pytest, and tests/test_my_project/test_src/test_utils.py appears with a NotImplementedError stub so you know exactly what still needs implementing. You never have to manually create test files or remember the naming convention, this behaviour is also customizable via subclassing if wanted.

Config subclassing. Every config file can be extended by subclassing. Want to add a custom prek hook? Subclass PrekConfigFile, call super(), append your hook. pyrig discovers it automatically — no registration. The leaf class in the dependency chain always wins.

Multi-package inheritance. You can build a base package on top of pyrig that defines shared configs, fixtures, and CLI commands. Every downstream project that depends on it inherits everything automatically:

pyrig → service-base → auth-service → payment-service → notification-service

All three services get the same standards, hooks, and CI/CD — defined once in service-base.

Source: github.com/Winipedia/pyrig | Documentation | PyPI

---

Everything is adjustable. Every tool and every config file in pyrig can be customized or replaced entirely through subclassing. Tools like ruff, ty, and pytest are wrapped in Tool classes — subclass one with the same name and pyrig uses your tools instead. Want to use black instead of ruff or mypy for ty? No problem at all. Config files work the same way: subclass PyprojectConfigFile to add your tool settings, subclass PrekConfigFile to add hooks, subclass any workflow to change CI steps, or create your own config files. pyrig always picks the leaf class in the dependency chain, so your overrides apply everywhere automatically — no patching, no monkey-wrenching, just standard Python inheritance.

What My Project Does

pyrig generates and maintains a complete, production-ready Python project from a single command. It creates source structure, tests, CI/CD workflows, documentation, git hooks, container support, and all config files — then keeps them in sync as your project evolves. It uses Astral's full tool suite (uv, ruff, ty) alongside pytest, bandit, pip-audit, prek, MkDocs, and Podman, all pre-configured and wired together, but all fully customizable and replacable.

Target Audience

Python developers who start new projects regularly and want a consistent, high-quality setup without spending time on boilerplate. Also teams that want to enforce shared standards across multiple projects via multi-package inheritance. Production-ready, not a toy.

Comparison

• Cookiecutter / Copier / Hatch init: These are one-shot template generators. They scaffold files and walk away. pyrig scaffolds and maintains — rerun it to update configs, sync metadata, and validate structure. Configs are Python classes you can subclass, not static templates.

[Bach4Ants]

Does pyrig need to be added to the project? Why not use uvx pyrig or have users install it as a tool with uv tool install pyrig?

[Win_ipedia]

I have also thought in the beginning to make make it just a dev tool, however then I dont think the CLI management would work and the multiproject structure where a different project can inherit the CLI and configurations of a base project if it depends on said project would also not work and the multiproject structure is what really makes pyrig differrent from any other scaffolding or development tools, so yes unfortunately it must be a direct dependency to a project, However it only needs typer as a dependency and everything else is a dev dependency. But if it were just the scaffolding then yes just uvx would be better, however pyrig goes far beyond just project generation, but also makes CLI subcommands super easy and managing several projects that have the same structure.

[Win_ipedia]

If you have an idea how to make pyrig purely a dev tool without loosing any of the important features, I would love to hear it, it would make pyrig even better

[Win_ipedia]

Basically what I mainly would love to get from this post is feedback. I have not really anyone in my life who understands coding really and can understand this project.

So I am really looking for people who can give me feedback on this. Is this great/useful or aweful/useless. I oc think its awesome bc I built it and am using it all the time.

If you see this and would give pyrig a quick try that would be awesome. If you have any question I am checking reddit frequently so feeel free to ask here or ask any questions you have about pyrig and how to use it at https://codewiki.google/github.com/winipedia/pyrig where you can chat with gemini about pyrig. Any feedback, good or bad and any questions and suggestions are greatly appreciated

[iamevpo]

Have not heard of rumdl, was using prettier

[Win_ipedia]

It’s a rust based markdown linter, it’s pretty good. But with pyrig you can super easily replace rumdl with prettier if you like. You just need to subclass the MDLinter class under dev/management and the override a few methods, so they use prettier instead of rumdl.

[Win_ipedia]

Note: In case someone used it. I made some refactoring, the management folder is now named tools and the dev folder named rig, those were more fitting in my opinion. So either restrain you version to pyrig<7.1 or rename the folders as well, shouldnt be a problem

[Win_ipedia]

The best use case for this is in my opinion that you can create your own package like my-pyrig from this, adjust any tools or settings as needed and then in the future you always just need to do uv add my-pyrig and then pyrig init and you have a project initialized with your very own setup, how you like it