Python Style Policy

This is Vexcalibur’s enforceable Python style policy. It is inspired by the vendored Google Python Style Guide, but this document and the checked-in tool configuration are authoritative for this repository.

If this policy conflicts with the vendored Google guide, follow this policy. In particular, Vexcalibur does not require pylint, 80-character lines, Black, or Pyink just because those appear in the upstream guide.

Tooling

  • Ruff is the formatter and linter source of truth.

  • Line length is 100 characters.

  • MyPy strict mode is required for src/vexcalibur.

  • Pytest is the test runner.

  • pyproject.toml is the canonical machine-readable configuration.

Run the usual local quality gate:

make check

For a full pre-PR pass, run:

uv lock --check
uv sync --frozen
uv run --frozen ruff format --check src tests scripts/*.py docs/conf.py
uv run --frozen ruff check src tests scripts/*.py docs/conf.py
uv run --frozen mypy src
uv run --frozen pytest -m "not live" --cov-fail-under=75
make docs
uv build --clear --no-create-gitignore --no-sources
uv run --frozen pip-audit --cache-dir /tmp/vexcalibur-pip-audit-cache
git ls-files -z | xargs -0 uv run --frozen detect-secrets-hook --baseline .secrets.baseline --
git show origin/main:.secrets.baseline > /tmp/vexcalibur-base.secrets.baseline
git ls-files -z | xargs -0 uv run --frozen detect-secrets-hook --baseline /tmp/vexcalibur-base.secrets.baseline --

Use make secrets for current-branch baseline enforcement, make secrets-pr for PR-mode base-baseline enforcement, and make secrets-baseline only for an intentional, separately reviewed baseline refresh.

Conventions

  • Prefer precise types on public functions and domain boundaries.

  • Keep imports grouped and sorted by Ruff.

  • Use Google-style docstrings for public APIs when the signature and name do not fully explain behavior.

  • Keep exceptions explicit and user-facing CLI messages free of tracebacks for expected input/configuration errors.

  • Keep functions small enough to scan. Extract helpers when a workflow starts mixing parsing, policy, I/O, and rendering concerns.

  • Do not add comments that restate obvious code. Add short comments only when they prevent misreading of non-obvious logic.

  • Treat public-service access as security-sensitive; code must fail closed unless the caller explicitly opts in.

Tests

  • Put tests under tests/.

  • Mark external-service tests with @pytest.mark.live.

  • Prefer deterministic fixtures and golden files for VEX output.

  • Add regression tests for security, compatibility, and parsing fixes.

  • For SBOM and VEX changes, test both successful behavior and malformed or unsafe input.