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:
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.
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.
Async code follows rules/04 unconditionally: TaskGroup scopes, no blocking calls in
coroutines, timeouts on external awaits, no unreferenced create_task.
Security posture is non-optional even when unrequested: parameterized SQL, argv-list
subprocess, secrets for tokens, safe extraction, no pickle/eval on external data.
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.
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:
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.
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.
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.
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/Self/ParamSpec; Any leaks; assert_never exhaustiveness; where runtime validation belongs
rules/03-idioms-pitfalls.md
any general Python code; mutable defaults, closures, comprehensions, context managers, pathlib, EAFP, dataclass/enum patterns, itertools/functools; designing exceptions; logging setup
rules/04-async.md
any async def in sight: TaskGroup vs gather, blocking-the-loop, fire-and-forget, timeouts/cancellation, async generators, anyio, sync-ORM-in-async bugs
rules/05-security.md
auditing for vulnerabilities; handling untrusted input; subprocess/SQL/paths/archives/secrets; pickle/eval/yaml; SSRF/XML; dependency auditing and supply chain
rules/06-performance.md
anything slow: profiling tool choice, hot-loop suspects, numpy/polars vectorization, functools caching caveats, threads vs processes vs asyncio, lazy imports/startup
rules/07-frameworks-testing.md
FastAPI (DI, boundary models, sync-in-async), Django (N+1, select_related, migrations), pytest (fixtures, parametrize, independence, hypothesis). Test strategy — suite shape, TDD, doubles, test data, flake policy — lives in sota-testing; load it for any build that writes logic. This file owns Python runner mechanics only.
Top-10 non-negotiables
uv + committed lockfile; CI installs --locked. No unlocked pip install in
pipelines or images. (rules/01)
One strict type checker gating CI; public APIs fully annotated; no Any leaking
across module boundaries. (rules/02)
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)
Never eval/exec/pickle.loads/yaml.load on data you don't fully control.
(rules/05)
SQL via bound parameters only; subprocess via argv lists with shell=False, --
before user args. (rules/05)
No bare except:; no except Exception: pass; chain with raise ... from e;
except Exception only at top-level boundaries with logger.exception. (rules/03)
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)
No mutable default arguments; context managers for every resource; pathlib +
explicit encoding="utf-8". (rules/03)
secrets (never random) for anything security-relevant; compare_digest for
secret comparison; no hardcoded credentials; no verify=False. (rules/05)
Tests are independent (random order + parallel safe), fixture-based, parametrized;
performance claims require a profile. (rules/06, rules/07)
