python-code-quality

name	python-code-quality
description	Code quality checks, linting, formatting, and type checking commands for the Agent Framework Python codebase. Use this when running checks, fixing lint errors, or troubleshooting CI failures.

Python Code Quality

Quick Commands

All commands run from the python/ directory:

# Format code (ruff format, parallel across packages)
uv run poe fmt

# Lint and auto-fix (ruff check, parallel across packages)
uv run poe lint

# Type checking
uv run poe pyright       # Pyright (parallel across packages)
uv run poe mypy          # MyPy (parallel across packages)
uv run poe typing        # Both pyright and mypy

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

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

# Samples only
uv run poe samples-lint     # Ruff lint on samples/
uv run poe samples-syntax   # Pyright syntax check on samples/

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

Pre-commit Hooks (prek)

Prek hooks run automatically on commit. They check only changed files and run package-level checks in parallel for affected packages only.

# 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

When core package changes, type-checking (mypy, pyright) runs across all packages since type changes propagate. Format and lint only run in changed packages.

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

• Strict mode enabled
• Excludes: tests, .venv, packages/devui/frontend

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 — fmt/lint/pyright via check-packages
3. Samples & markdown — samples-lint, samples-syntax, markdown-code-lint
4. Mypy — change-detected mypy checks