codeality-py

Structural linter and config scaffolder for Python: atomic files, placement, size caps, no inline SQL. Brings the same discipline as @syntopica/eslint-config and cargo-baseline to Python projects.

• Design spec: docs/superpowers/specs/2026-08-31-python-baseline-design.md.

Install

uv add --dev syntopica-codeality-py

Usage

codeality-py init [--check|--apply|--force]  # scaffold ruff, mypy, deptry,
                                            # pytest, coverage and CI config
codeality-py check [PATH...]                 # run the structural rules
codeality-py gate                            # run the whole quality chain
codeality-py baseline create|update|check    # track migration debt

init never overwrites: it merges into existing configuration, or reports a conflict. check never writes. gate fails when a required tool is absent rather than skipping it.

Rules

Suite time budget

# codeality-py.toml
test-budget-seconds = 300

Past the budget a passing suite is a finding: the pytest stage reports over-budget, exits 1, and its detail carries the slowest tests. The procedure - profile, make the unit under test cheaper, parallelise, serialise what must stay shared - is in docs/standards/testing.md.

The budget is tuned to the machine the suite is developed on. A slower environment, such as a CI runner, sets its own for the run instead of raising the committed number for everyone:

# .github/workflows/quality.yml
env:
  CODEALITY_PY_TEST_BUDGET_SECONDS: '600'

When CODEALITY_PY_TEST_BUDGET_SECONDS is set it replaces test-budget-seconds; unset or empty, it changes nothing. A value that is not a positive integer is a configuration error (exit 2), never silently ignored. The pytest stage names the budget it was held to and where it came from - budget 600s from CODEALITY_PY_TEST_BUDGET_SECONDS - in its text line, its detail, and the budget_seconds and budget_source fields of gate --json.

Exit codes

License

MIT