martinholovsky 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., notypealiases 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 formatbefore presenting code, full annotations on everything public, pydantic v2 at trust boundaries, frozen+slots dataclasses inside,pathlib,loggingwith 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,
secretsfor tokens, safe extraction, no pickle/eval on external data. - Tests accompany code: pytest, fixtures + parametrize, independent tests; property tests (hypothesis) for invariant-bearing code (rules/07 §3).
- 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 viauv 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, thenuvx bandit -r src/ -llanduvx pip-auditfor 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.loadsof 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; in-band sentinels (-1 for absent) — the defect int | None exists to prevent, invisible to the type checker; 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 unlockedpip installin pipelines or images. (rules/01) - One strict type checker gating CI; public APIs fully annotated; no
Anyleaking 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.loadon 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:; noexcept Exception: pass; chain withraise ... from e;except Exceptiononly at top-level boundaries withlogger.exception. (rules/03) - Async: TaskGroup-owned tasks only; zero blocking calls in coroutines
(
to_thread/process pool instead);asyncio.timeouton every external await; re-raiseCancelledError. (rules/04) - No mutable default arguments; context managers for every resource;
pathlib+ explicitencoding="utf-8". (rules/03) secrets(neverrandom) for anything security-relevant;compare_digestfor secret comparison; no hardcoded credentials; noverify=False. (rules/05)- Tests are independent (random order + parallel safe), fixture-based, parametrized; performance claims require a profile. (rules/06, rules/07)