/sota-python

name: sota-python
description: >-
  State-of-the-art Python engineering for both writing new Python and
  auditing existing Python code. Covers uv-based tooling and project setup, strict typing,
  idioms and pitfalls, asyncio structured concurrency, security (injection, deserialization,
  supply chain), performance, and FastAPI/Django/pytest practice. Use whenever the task
  involves Python source, pyproject.toml, requirements files, or Python tooling — building
  features, scaffolding projects, reviewing PRs, or hunting bugs/vulnerabilities.
  Trigger keywords: Python, pip, uv, pyproject, asyncio, Django, FastAPI, pytest, type hints,
  mypy, ruff, pydantic, SQLAlchemy, venv.

SOTA Python (2026)

Purpose

This skill encodes the 2026 state of the art for Python: modern toolchain (uv + ruff + one strict type checker), Python ≥3.12 idioms, structured async, security-by-default, and measured performance work. It serves two modes:

• **BUILD** — writing new code or modifying existing code to this standard.
• **AUDIT** — reviewing existing code against this standard and reporting findings.

The detailed rules live in `rules/*.md`. Read SKILL.md fully; load rules files on demand per the index table below. When in doubt between two rules files, the index's "read when" column decides.

BUILD mode

When creating or modifying Python code:

1. **Establish context first.** Check `pyproject.toml`, `uv.lock`, `.python-version`, ruff config, and the type checker in use. Match the project's floor (e.g., no `type` aliases on a 3.10 project). For a *new* project, scaffold per [rules/01](rules/01-tooling-project-setup.md): `uv init`, src/ layout, ruff with the standard select, strict checker, pre-commit. 2. **Default stack:** uv for env/deps (commit the lockfile), `ruff check --fix` + `ruff format` before presenting code, full annotations on everything public, pydantic v2 at trust boundaries, frozen+slots dataclasses inside, `pathlib`, `logging` with lazy `%` formatting. 3. **Async code** follows [rules/04](rules/04-async.md) unconditionally: TaskGroup scopes, no blocking calls in coroutines, timeouts on external awaits, no unreferenced `create_task`. 4. **Security posture is non-optional** even when unrequested: parameterized SQL, argv-list subprocess, `secrets` for tokens, safe extraction, no pickle/eval on external data. 5. **Tests accompany code:** pytest, fixtures + parametrize, independent tests; property tests (hypothesis) for invariant-bearing code ([rules/07](rules/07-frameworks-testing.md) §3). 6. **Performance:** correct data structures by default (set membership, join, generators); anything beyond that requires a profile first ([rules/06](rules/06-performance.md) §1). Don't micro-optimize cold code. 7. **Verify before declaring done:** run `ruff check`, the project's type checker, and the test suite via `uv run`. Code that doesn't pass these is not done.

AUDIT mode

**Coverage:** every `rules/` file's Audit checklist applies in AUDIT mode. Mark one *not applicable* only with its reason in the report — never skip a file because the thing it checks for is absent, since that absence may be the finding.

When reviewing existing Python code:

1. **Sweep mechanically first.** Run the "Audit checklist" block at the end of every relevant rules file — they are ordered grep/ruff/bandit commands. Start with `uvx ruff check --select F,B,S,ASYNC,DTZ,E722,BLE --statistics .` for a heat map, then `uvx bandit -r src/ -ll` and a pip-audit of the *project's* lock for security baselines — `uv export --format requirements-txt --no-emit-project | uvx pip-audit --disable-pip -r /dev/stdin` (bare `uvx pip-audit` audits its own tool venv and exits 0 on any project; a project with no third-party dependencies makes this pipe exit 1 — [rules/08](rules/08-supply-chain.md) §1 has the counted form). 2. **Then read for design:** trust-boundary placement (validation at edges?), exception strategy, async ownership of tasks, N+1 patterns, cache invalidation, test independence. Greps find syntax; you find architecture. 3. **Verify every finding** — open the file, confirm the context (a `pickle.loads` of a file the same process wrote with HMAC verification is not a CRITICAL). No finding ships on grep output alone. Note mitigations that are already present. 4. **Don't report style noise** a formatter/linter would auto-fix; mention once collectively ("run ruff format; 40 files drift") and move on.

Severity conventions

| Severity | Meaning | Examples | |---|---|---| | CRITICAL | Exploitable now, or data loss/corruption | SQL injection, `pickle.loads`/`eval` on untrusted input, `shell=True` with user data, auth bypass | | HIGH | Exploitable with preconditions, or production-breaking bug | path traversal, unsafe `extractall`, `random` for tokens, swallowed `CancelledError`, blocking call in async hot path, bare `except: pass` around critical logic, `verify=False` | | MEDIUM | Correctness/maintenance risk, degraded ops | mutable default args, fire-and-forget tasks, unbounded `@cache` on user input, N+1 queries, missing lockfile in an app, no type checker in CI, edited applied migrations | | LOW | Deviation from SOTA, friction, future risk | legacy typing forms, os.path usage, f-strings in log calls, flat layout in a library, bare `# type: ignore` | | INFO | Worth knowing, no action forced | tooling consolidation opportunities, 3.13/3.14 features available after floor bump |

Confidence accompanies severity: **confirmed** (you traced the data flow) vs **suspected** (pattern present, flow not fully traced — say what would confirm it).

Finding format

Expands the router's canonical row (`file:line | rule | severity | effort | fix`, which wins on a cross-domain roll-up); evidence block and report order: [`sota` rules/03](../sota/rules/03-audit-findings.md) §2 and §5.

[SEVERITY/confidence] short title
  File: src/pkg/module.py:42 (absolute p