Opinionated tooling for keeping professional Python repositories on a consistent baseline.
The PUP tools keep a fleet of Python repositories UP-to-date on a shared professional standard: syncing infrastructure files, checking structure, and cleaning up generated content.
Each command-line tool runs with no install via uvx.
Dry run is the default;
nothing is changed without an explicit flag.
| Tool | PyPI | Purpose |
|---|---|---|
| pup-up | PyPI | Syncs repo infrastructure from maintained templates |
| pup-down | PyPI | Reports repo infrastructure changes that may belong in canonical templates |
| pup-check | PyPI | Checks repo structure and configuration for consistency |
| pup-clean | PyPI | Cleans repo by removing generated artifacts |
| pup-core | PyPI | Shared inspection, metadata, and path-safety primitives (library) |
Default Templates: pup-pack/templates
The Professional Python Project Explainer is a browser-based Marimo app for exploring common files and folders in professional Python repositories.
It fetches the selected repository structure live from GitHub and explains the purpose and rationale for common project contents.
Open the Professional Python Project Explainer
Run a tool from inside a target repository.
All commands default to a dry run if no flags are provided.
No changes are made unless the user provides a flag, such as --write or --delete.
| Command | What happens |
|---|---|
uvx pup-up |
Show what infrastructure files would change |
uvx pup-up --diff |
Show the exact line-by-line changes |
uvx pup-up --write |
Apply the changes (destructive) |
uvx pup-down |
Report infrastructure changes for templates |
uvx pup-check |
Report structure and configuration issues |
uvx pup-clean |
Show what generated artifacts would be removed |
uvx pup-clean --delete |
Remove them (destructive) |
Add @latest to any command to force the newest published version
(e.g. uvx pup-up@latest).
- Dry run is the default for every tool.
- Only explicitly managed files are changed.
--write/--deleteare required to modify anything.- Selected paths must be safe, repository-relative, and managed.
Every supporting file documents its own purpose and decisions inline; the reason for each decision lives in the associated file. Repository structure and the layered file conventions are defined in templates.