Python Code Quality

Python Code Quality

When to invoke

• Formatting or linting Agent Framework Python changes.
• Running source, test, sample, or Markdown type checks.
• Diagnosing failures from the Python quality or typing CI jobs.

Quick Commands

All commands run from the python/ directory:

# Syntax formatting + checks (parallel across packages by default)
uv run poe syntax
uv run poe syntax -P core
uv run poe syntax -F    # Format only
uv run poe syntax -C    # Check only
uv run poe syntax -S    # Samples only

# Type checking
#
# Division of labor (see "Type checking architecture" below):
#   - Pyright (strict) is the source-code type checker.
#   - Pyright (relaxed `basic`), mypy, pyrefly, ty, zuban all check the TESTS;
#     pyright/pyrefly/ty also check the SAMPLES (mypy/zuban skip script-style samples).
uv run poe pyright       # Pyright (strict) over SOURCE, fan-out across packages
uv run poe pyright -P core
uv run poe pyright -A
uv run poe test-typing   # mypy + pyrefly + ty + zuban + pyright over each package's TESTS
uv run poe test-typing -P core
uv run poe test-typing -S                       # samples (pyrefly + ty + pyright)
uv run poe test-typing -P core --checker mypy   # narrow to one checker (repeatable)
uv run poe test-typing -P core --checker pyright # relaxed pyright over the tests
uv run poe mypy          # alias: MyPy over the tests only
uv run poe mypy -P core
uv run poe typing        # Pyright (source) + the tests checkers
uv run poe typing -P core
uv run poe typing -A

# All package-level checks in parallel (syntax + pyright)
uv run poe check-packages

# Full check (packages + samples + tests + markdown)
uv run poe check
uv run poe check -P core

# Samples only
uv run poe check -S
uv run poe pyright -S

# Markdown code blocks
uv run poe markdown-code-lint

Pre-commit Hooks (prek)

Prek hooks run automatically on commit. They stay lightweight and only check changed files.

# Install hooks
uv run poe prek-install

# Run all hooks manually
uv run prek run -a

# Run on last commit
uv run prek run --last-commit

They run changed-package syntax formatting/checking, markdown code lint only when markdown files change, and sample syntax lint/pyright only when files under samples/ change. They intentionally do not run workspace pyright or mypy by default.

Type checking architecture

Following the "too many type checkers" approach, type checkers are split by target:

• Pyright is the only strict source-code checker, and it ALSO runs in a relaxed basic profile over the tests and samples (so the surfaces customers copy from are validated by every checker, including pyright). MyPy was removed from source; its [tool.mypy] block is now a relaxed profile used only for tests/samples.
• The extra checkers run over tests/samples because those exercise the public API the way users do. The profile is intentionally relaxed (private access allowed, untyped test bodies allowed) so authors aren't forced into ugly over-annotation.
• Gating checkers are pyright, mypy, pyrefly, ty, and zuban — all five run by default and gate CI. zuban is the strictest of the mypy-compatible pair, so the same [tool.mypy] config yields more findings; suppress zuban-only friction with shared # type: ignore[code]. Suppress relaxed-pyright friction with # pyright: ignore[rule].
• Samples add pyright to pyrefly + ty — mypy/zuban can't resolve script-style sample layouts (numeric-prefixed dirs, duplicate main.py), but pyright handles them.
• The strict source-pyright ([tool.pyright]) enforces reportUnnecessaryTypeIgnoreComment and excludes tests/samples; the relaxed test/sample pyright configs do not flag unnecessary ignores.

Ruff Configuration

• Line length: 120
• Target: Python 3.10+
• Auto-fix enabled
• Rules: ASYNC, B, CPY, D, E, ERA, F, FIX, I, INP, ISC, Q, RET, RSE, RUF, SIM, T20, TD, W, T100, S
• Scripts directory is excluded from checks

Pyright Configuration

• Source: strict mode ([tool.pyright]), reportUnnecessaryTypeIgnoreComment = "error", excludes tests, samples, .venv, packages/devui/frontend.
• Tests: relaxed basic profile (pyrightconfig.tests.json) — private import/usage and not-required TypedDict access allowed; runs as the pyright checker in test-typing.
• Samples: relaxed basic profile (pyrightconfig.samples.json, with a py310 variant) — runs as the pyright checker in test-typing -S.

Parallel Execution

The task runner (scripts/task_runner.py) executes the cross-product of (package × task) in parallel using ThreadPoolExecutor. Single items run in-process with streaming output.

CI Workflow

CI splits into 4 parallel jobs:

1. Pre-commit hooks — lightweight hooks (SKIP=poe-check)
2. Package checks — syntax/pyright (source) via check-packages
3. Samples & markdown — check -S plus markdown-code-lint
4. Test Typing — change-detected mypy/pyrefly/ty over tests (ci-test-typing)

Output template

## Python quality result

- Scope: `<packages, tests, samples, or Markdown>`
- Commands: `<commands run>`
- Result: `<pass or fail>`
- Findings fixed: `<summary>`
- Remaining findings: `<none or details>`

Quality gate

• Checks were scoped to the changed Python surfaces first.
• Formatting, lint, and relevant type checkers completed successfully.
• Suppressions are targeted and justified.
• No generated or unrelated files were reformatted.
• Remaining failures are reported with their exact command and output.