version: "1.0.1" 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: uv init, src/ layout, ruff with the standard select, strict checker, pre-commit.

1. 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.

1. Async code follows rules/04 unconditionally: TaskGroup scopes, no blocking calls in

coroutines, timeouts on external awaits, no unreferenced create_task.

1. Security posture is non-optional even when unrequested: parameterized SQL, argv-list

subprocess, secrets for tokens, safe extraction, no pickle/eval on external data.

1. Tests accompany code: pytest, fixtures + parametrize, independent tests; property

tests (hypothesis) for invariant-bearing code (rules/07 §3).

1. 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.

1. 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 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 §1 has the counted form).

1. 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.

1. 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.

1. 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

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

Top-10 non-negotiables

1. uv + committed lockfile; CI installs `--locked`. No unlocked pip install in

pipelines or images. (rules/01)

1. **One strict type checker gating CI; public APIs fully annotated; no Any leaking

across module boundaries.** (rules/02)

1. Validate at the boundary, trust inside: pydantic v2 (extra="forbid") where data

enters; typed dataclasses within. Never pass raw parsed JSON deep into the core. (rules/02)

1. Never `eval`/`exec`/`pickle.loads`/`yaml.load` on data you don't fully control.

(rules/05)

1. **SQL via bound parameters only; subprocess via argv lists with shell=False, --

before user args.** (rules/05)

1. **No bare except:; no except Exception: pass; chain with raise ... from e;

except Exception only at top-level boundaries with logger.exception.** (rules/03)

1. **Async: TaskGroup-owned tasks only; zero blocking calls in coroutines

(to_thread/process pool instead); asyncio.timeout on every external await; re-raise CancelledError.** (rules/04)

1. **No mutable default arguments; context managers for every resource; pathlib +

explicit encoding="utf-8".** (rules/03)

1. **secrets (never random) for anything security-relevant; compare_digest for

secret comparison; no hardcoded credentials; no verify=False.** (rules/05)

1. **Tests are independent (random order + parallel safe), fixture-based, parametrized;

performance claims require a profile.** (rules/06, rules/07)