/sota-python

name: sota-python
description: >-
  State-of-the-art Python engineering (2026 baseline) 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: `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 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 §3). 6. **Performance:** correct data structures by default (set membership, join, generators); anything beyond that requires a profile first (rules/06 §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

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 `uvx pip-audit` for security baselines. 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

[SEVERITY/confidence] short title
  File: src/pkg/module.py:42 (absolute path in final report)
  Issue: what is wrong, in one or two sentences, with the data-flow if security-relevant
  Evidence: the offending line(s), quoted
  Fix: concrete change — code snippet or exact rule reference (rules/05 §2)
  Effort: trivial | small | medium | large

Group findings by severity, CRITICAL first. End with: counts per severity, the mechanical sweep commands you ran, and explicit "checked and clean" areas (so absence of findings is information, not omission).

Rules index

| File | Read this when... | |---|---| | `rules/01-tooling-project-setup.md` | starting/scaffolding a project; reviewing pyproject/uv/ruff/CI setup; choosing type checker; questions about uv lockfiles, PEP 723 scripts, src/ layout, 3.12–3.14 features, free-threading | | `rules/02-typing-correctness.md` | annotating APIs; choosing TypedDict vs dataclass vs pydantic; Protocol vs ABC; generics/`Se