pup-check: Professional Python Project: Repo Self Consistency Checker

Opinionated professional Python repository self-consistency checker

Purpose

Professional Python repositories contain many declarations that should agree with one another.

Examples include:

• project and package names
• src/ package structure
• pyproject.toml metadata
• command-line entry points
• Python module paths
• dependency declarations
• Python version declarations
• repository-relative file paths
• workflow and tooling configuration

Small inconsistencies can remain unnoticed until a command, build, test, documentation workflow, or release fails.

pup-check performs deterministic checks for internal repository consistency and reports problems that should be reviewed.

Check a Repository

# check the current repository
uvx pup-check

# check using the latest published version
uvx pup-check@latest

A successful check returns exit code 0.

A failed consistency check returns a nonzero exit code and reports the detected problem.

Checks

This release checks:

• pyproject.toml exists
• pyproject.toml can be read and identifies the project
• a Python package can be detected when a src/ layout is present
• modules referenced by [project.scripts] entry points exist

Developer Command Reference

Show command reference

In a machine terminal

Open a machine terminal where you want the project:

git clone https://github.com/pup-pack/pup-check

cd pup-check
code .

In a VS Code terminal

uv self update
uv python pin 3.15
uv python install
uv lock --upgrade
uv sync

uv run pre-commit install
uv run pre-commit autoupdate

git add -A
uv run pre-commit run --all-files
# repeat if changes were made
uv run pre-commit run --all-files

# run locally to test
uv run pup-check

# types, tests, docs
uv run ty check
uv run python -m pytest
uv run python -m zensical build

# save progress
git add -A
git commit -m "update"
git push -u origin main

Documentation

• Documentation

Annotations

.annotations/annotations.md

Citation

CITATION.cff

License

MIT