Skip to content

API Reference

This page is auto-generated from Python docstrings.

pup_check

pup-check package.

__main__

Run as a module.

base

Base package.

types

Typed records.

CheckResult dataclass

Result of one deterministic repository consistency check.

Source code in src/pup_check/base/types.py 
 8
 9
10
11
12
13
14
@dataclass(frozen=True)
class CheckResult:
    """Result of one deterministic repository consistency check."""

    name: str
    passed: bool
    detail: str

checks

Checks package.

entry_points

Project entry-point checks.

check_entry_points 
check_entry_points(root: Path) -> tuple[CheckResult, ...]

Check that declared project-script modules exist.

Source code in src/pup_check/checks/entry_points.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def check_entry_points(root: Path) -> tuple[CheckResult, ...]:
    """Check that declared project-script modules exist."""
    try:
        info = inspect_pyproject(root)
    except PyprojectError:
        return ()

    if not info.scripts:
        return (
            CheckResult(
                name="entry points",
                passed=True,
                detail="no project scripts declared",
            ),
        )

    results: list[CheckResult] = []

    for script_name, target in sorted(info.scripts.items()):
        module_name, separator, function_name = target.partition(":")

        if not separator or not module_name or not function_name:
            results.append(
                CheckResult(
                    name=f"entry point {script_name}",
                    passed=False,
                    detail=f"invalid target {target}",
                )
            )
            continue

        exists = module_exists(root, module_name)

        results.append(
            CheckResult(
                name=f"entry point {script_name}",
                passed=exists,
                detail=(
                    f"{target} module exists"
                    if exists
                    else f"{target} module not found"
                ),
            )
        )

    return tuple(results)

files

Repository file checks.

check_required_files 
check_required_files(
    context: RepositoryContext,
) -> tuple[CheckResult, ...]

Check required project files.

Source code in src/pup_check/checks/files.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
def check_required_files(context: RepositoryContext) -> tuple[CheckResult, ...]:
    """Check required project files."""
    required_files = ("pyproject.toml",)

    results: list[CheckResult] = []

    for path in required_files:
        exists = path in context.files

        results.append(
            CheckResult(
                name=f"file {path}",
                passed=exists,
                detail="exists" if exists else "missing",
            )
        )

    return tuple(results)

packages

Python package structure checks.

check_package_structure 
check_package_structure(
    context: RepositoryContext,
) -> CheckResult

Check that a src/ repository contains a detectable Python package.

Source code in src/pup_check/checks/packages.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
def check_package_structure(context: RepositoryContext) -> CheckResult:
    """Check that a src/ repository contains a detectable Python package."""
    has_src = "src" in context.files or "src/" in context.files

    if not has_src:
        return CheckResult(
            name="package structure",
            passed=True,
            detail="no src/ layout detected; check not applicable",
        )

    if context.src_package:
        return CheckResult(
            name="package structure",
            passed=True,
            detail=f"detected package {context.src_package}",
        )

    return CheckResult(
        name="package structure",
        passed=False,
        detail="src/ exists but no Python package was detected",
    )

pyproject

pyproject.toml consistency checks.

check_pyproject 
check_pyproject(root: Path) -> CheckResult

Check that pyproject.toml can be read and identifies the project.

Source code in src/pup_check/checks/pyproject.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
def check_pyproject(root: Path) -> CheckResult:
    """Check that pyproject.toml can be read and identifies the project."""
    try:
        info = inspect_pyproject(root)
    except PyprojectError as exc:
        return CheckResult(
            name="pyproject.toml",
            passed=False,
            detail=str(exc),
        )

    if not info.project_name:
        return CheckResult(
            name="pyproject.toml",
            passed=False,
            detail="project.name is missing",
        )

    return CheckResult(
        name="pyproject.toml",
        passed=True,
        detail=f"project name is {info.project_name}",
    )

cli

Command-line interface for pup-check.

This module parses arguments and dispatches repository checking behavior.

Commands: uv run pup-check

Equivalent uvx usage after release: uvx pup-check uvx pup-check@latest

build_parser 

build_parser() -> argparse.ArgumentParser

Build the argument parser.

Source code in src/pup_check/cli.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def build_parser() -> argparse.ArgumentParser:
    """Build the argument parser."""
    parser = argparse.ArgumentParser(
        prog="pup-check",
        description=(
            "Check a professional Python repository for deterministic "
            "internal consistency."
        ),
    )

    parser.add_argument(
        "--root",
        type=Path,
        default=None,
        help=(
            "Repository root to check. Defaults to the nearest parent "
            "directory containing .git, or the current directory."
        ),
    )

    return parser

main 

main(argv: Sequence[str] | None = None) -> int

Run the command-line interface.

Parameters:

Name Type Description Default
argv Sequence[str] | None

Optional command-line arguments. If None, uses sys.argv.

 None

Returns:

Type Description
int

Exit code from the check command.
Source code in src/pup_check/cli.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def main(argv: Sequence[str] | None = None) -> int:
    """Run the command-line interface.

    Args:
        argv: Optional command-line arguments. If None, uses sys.argv.

    Returns:
        Exit code from the check command.
    """
    parser = build_parser()
    args = parser.parse_args(argv)

    return check.run(
        root=args.root,
    )

commands

Command modules.

Each command module exposes a stable run(...) -> int entry point.

The CLI parser lives in pup_check.cli. Behavior lives here.

check

Check the repository for self-consistency.

run 
run(*, root: Path | None = None) -> int

Check a repository for deterministic internal consistency.

Parameters:

Name Type Description Default
root Path | None

Repository root. If None, detect the current repository root.

 None

Returns:

Type Description
int

Process exit code. Zero means all checks passed.
Source code in src/pup_check/commands/check.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
def run(
    *,
    root: Path | None = None,
) -> int:
    """Check a repository for deterministic internal consistency.

    Args:
        root: Repository root. If None, detect the current repository root.

    Returns:
        Process exit code. Zero means all checks passed.
    """
    repository = detect_repository(root)

    results: list[CheckResult] = []

    results.extend(check_required_files(repository))

    pyproject_result = check_pyproject(repository.root)
    results.append(pyproject_result)

    results.append(check_package_structure(repository))

    if pyproject_result.passed:
        results.extend(check_entry_points(repository.root))

    print_check_results(repository, results)

    return 0 if all(result.passed for result in results) else 1

write_terminal

Terminal reporting.

print_check_results 

print_check_results(
    context: RepositoryContext,
    results: Sequence[CheckResult],
) -> None

Print repository check results.

Source code in src/pup_check/write_terminal.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def print_check_results(
    context: RepositoryContext,
    results: Sequence[CheckResult],
) -> None:
    """Print repository check results."""
    print("[pup-check] CHECK")
    print(f"[pup-check] repo: {context.repo_name}")
    print(f"[pup-check] root: {context.root}")
    print()

    for result in results:
        status = "PASS" if result.passed else "FAIL"
        print(f"{status:5} {result.name}: {result.detail}")

    passed = sum(result.passed for result in results)
    failed = len(results) - passed

    print()
    print(f"[pup-check] summary: {passed} passed, {failed} failed")