Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Loaded automatically when its description matches the active task. This is the foundation skill for all Python work — sibling skills (fastapi, django, pandas, polars, scikit-learn, pytorch, cuda-python) layer on top of these primitives. Read only the section you need, then follow the link to the relevant reference file.
Python is a dynamic, gradually typed language with a strong ecosystem and a maturing toolchain. The 2026 baseline is with deferred annotation evaluation (PEP 649/749), template strings (PEP 750), and officially-supported free-threaded builds (PEP 703 / PEP 779). The toolchain has consolidated around (Rust-based package/project manager, replaces pip+virtualenv+pip-tools+poetry), (Rust linter+formatter, replaces flake8+isort+black), and (or pyright) for static typing. This skill captures the language and toolchain decisions every Python project needs before any framework-specific work begins.
CPython 3.14
uv
ruff
mypy
This is the foundation skill — narrower skills (FastAPI, Django, pandas, etc.) assume you have the basics right. Get packaging, types, async, and error handling correct here, and downstream skills can focus on their domain instead of relitigating which package manager or formatter to use.
Capabilities
Modern syntax and the type system
Python 3.12 introduced PEP 695 type parameter syntax (def fn[T](x: T) -> T) and the type statement; 3.14 adds deferred annotation evaluation and t-strings. Walrus (:=), structural pattern matching (match/case), and exception groups (except* + ExceptionGroup) are mainstream. The type system supports Protocol (structural typing), TypedDict (dict shapes), Self, Literal, Annotated, ParamSpec, and override from typing — covering most static-typing needs without third-party libraries.
uv is the default in 2026 — it manages Python interpreters (uv python install), virtual environments (uv venv), dependencies (uv add/uv remove/uv sync), lockfiles (uv.lock), tool installations (uv tool install ruff), and one-shot script runs (uv run script.py). It is a drop-in replacement for pip, virtualenv, pip-tools, pipx, and most of poetry. pyproject.toml is the single configuration source (PEP 621 project metadata, PEP 735 dependency groups, build-system table).
ruff check replaces flake8 + isort + pyupgrade + many smaller linters. ruff format replaces black. Configure via [tool.ruff] in pyproject.toml: select enables rule families (E, F, I, UP, B, SIM, RUF), ignore disables specific rules, target-version sets the Python version for upgrade fixes. One tool, one config, milliseconds-fast on a full repo.
Four idiomatic options: @dataclass (stdlib, ergonomic with slots=True, frozen=True, kw_only=True), NamedTuple (immutable tuple subclass, lightweight), TypedDict (typed dict at the type-checker level only — no runtime enforcement), and Pydantic / attrs (when you need validation, parsing, or serialization). Pick by question: "do I need runtime validation?" → Pydantic. "Immutable record with equality?" → frozen dataclass. "Dict shape for an API payload?" → TypedDict.
asyncio is the standard async runtime. The 2026 idiom is asyncio.run(main()) at the entry point and async with TaskGroup() as tg: tg.create_task(...) for structured concurrency (PEP 654 — replaces gather-based patterns for most cases). anyio bridges asyncio and Trio. Decision matrix: I/O-bound concurrency → asyncio; CPU-bound parallelism → multiprocessing or free-threaded interpreter (PEP 703); throughput on many cores with shared state → concurrent.interpreters (PEP 734, new in 3.14).
Exceptions are the only sanctioned error-signaling mechanism. Build a small custom exception hierarchy rooted at one AppError(Exception) for your domain, use raise NewError(...) from cause to chain, and rely on ExceptionGroup + except* for concurrent or batched failures (PEP 654). contextlib covers context managers (@contextmanager, ExitStack, suppress). PEP 765 (3.14) now warns when return/break/continue exits a finally block.
Most Python work needs no third-party library: pathlib.Path (filesystem), itertools + functools (composition, cache, partial, reduce), collections (Counter, defaultdict, deque), json (with default= for custom types), datetime + zoneinfo (timezone-aware datetimes — never use naive datetime.utcnow()), subprocess.run (with check=True, never shell=True on untrusted input), logging (configure once at startup, never print in libraries), and argparse for CLIs (or typer/click for richer UX).
pytest is the de facto runner. Fixtures (@pytest.fixture), parametrization (@pytest.mark.parametrize), monkeypatch, tmp_path, caplog, conftest.py for shared scope, pytest-asyncio for async tests. Mocking via unittest.mock (patch, MagicMock, AsyncMock). A separate pytest skill covers depth; this section gives the foundation.
CPython has a Global Interpreter Lock (GIL) — one thread executes Python bytecode at a time. In 3.14 the free-threaded build (no-GIL, PEP 703/779) is officially supported; the experimental copy-and-patch JIT (PEP 744) shipped in 3.13 and stabilized in 3.14. Profile before optimizing: cProfile for call counts, py-spy for sampling without instrumentation, scalene for line-level CPU + memory + GPU. For CPU-bound work, prefer NumPy/Polars/Numba/Cython over hand-rolled optimization.
Common Python failure modes are highly recognizable: ModuleNotFoundError vs ImportError (one is missing package, the other is the package itself failing to import), circular imports (move import to function scope or restructure), venv pollution (system site-packages bleeding in), encoding errors (always encoding="utf-8" on open()), asyncio.run() inside a running loop (you nested two event loops), and silent thread/coroutine swallows when exceptions don't propagate.
How to use: open the specific topic file. Foundation skill — sibling skills (fastapi, django, pandas, polars, scikit-learn, pytorch, cuda-python) layer on top and assume packaging/types/async fundamentals are already in place.
