SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillspython-code-quality

python-code-quality

Coding & development

View repository

Updated 10-16 00:30

About this skill

Python Code Quality

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


Poe and the pytest toolchain stay in the cross-version development
environment. Ruff and the type checkers use pinned
`tooling/requirements-*.txt` files; prek is selected from the `tool-hooks`
dependency group only when needed.

## Pre-commit Hooks (prek)

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

```bash
# Install hooks
uv run poe prek-install

# Run all hooks manually
uv run --group tool-hooks prek run -a

# Run on last commit
uv run --group tool-hooks 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:

Target Checker(s) Mode Config
Source (agent_framework*) pyright strict [tool.pyright] in pyproject.toml
Tests pyright, mypy, pyrefly, ty, zuban relaxed/basic pyrightconfig.tests.json, [tool.mypy], pyrefly.toml, ty rules
Samples pyright, pyrefly, ty basic pyrightconfig.samples.json, pyrefly.samples.toml, ty.samples.toml
  • 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.
  • pyrefly.samples.toml enables fallback lookup for standalone sibling imports. The ty sample profile uses first-party root = ["."] for PEP 723 sibling helpers, preserving automatic extra-path lookup for the existing samples.
  • 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)