Modern Python skill for Claude Code

Done well means: one pyproject.toml describes the project, uv.lock pins it, uv run works on a fresh clone, ruff check and ruff format --check pass, the type checker runs in strict mode on new code, and nobody activates a virtualenv by hand.

Ground rules

• Use uv for Python versions, venvs, dependencies, locking, tools, and builds. Do not mix pip installs into a uv-managed .venv.
• Commit uv.lock for applications and libraries alike; CI installs with --locked.
• Target the oldest Python you support in requires-python, then let ruff’s UP rules and the type checker enforce syntax for that version.
• Types on every public function signature; validate untrusted data at the edge with Pydantic (or msgspec), use plain dataclasses inside.
• Never edit uv.lock by hand. Never pin with == in a library’s dependencies.

Inspect before changing

ls pyproject.toml setup.py setup.cfg requirements*.txt poetry.lock Pipfile uv.lock 2>/dev/null
python3 --version; uv --version
grep -nE "requires-python|build-backend|\[tool\." pyproject.toml

Found	Action
requirements.txt only	uv init --bare, then uv add -r requirements.txt, move test/lint deps with uv add --dev
poetry.lock / [tool.poetry]	Convert metadata to PEP 621 [project]; uvx migrate-to-uv automates most of it, review the diff
setup.py	Move metadata to [project]; keep setup.py only if a C extension build needs it
uv.lock present	Use uv sync / uv add; never pip install

New project workflow

uv init --package myapp          # src/ layout, build backend, console script
cd myapp
uv python pin 3.13               # writes .python-version
uv add httpx pydantic
uv add --dev pytest ruff mypy    # goes to [dependency-groups] dev
uv run pytest
uv run python -m myapp

• Library: uv init --lib. App that is never installed as a package: uv init --app.
• Global CLI tools: uv tool install ruff or one-off uvx ruff check.
• Lock-only changes: uv lock --upgrade-package httpx; everything: uv lock --upgrade.
• CI install: uv sync --locked (fails if the lock is stale) — never a bare uv sync.
• Export for platforms that need it: uv export --format requirements-txt --no-hashes > requirements.txt.

For a full annotated pyproject.toml (ruff, mypy, pytest, coverage settings), read references/pyproject-template.md when creating or overhauling the config.

Single-file scripts (PEP 723)

# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx>=0.27", "rich"]
# ///
import httpx
from rich import print
print(httpx.get("https://example.org").status_code)

Run with uv run fetch.py; add deps with uv add --script fetch.py typer. Prefer this over a throwaway venv for utilities and one-off data jobs.

Typing: modern syntax

from collections.abc import Callable, Iterable, Mapping, Sequence
from typing import Self, override, TypedDict, NotRequired

type JSON = dict[str, "JSON"] | list["JSON"] | str | int | float | bool | None   # 3.12 alias

def first[T](items: Sequence[T], default: T | None = None) -> T | None:   # 3.12 generics
    return items[0] if items else default

class Repo[ModelT]:
    def get(self, id: int) -> ModelT | None: ...

class Builder:
    def with_name(self, name: str) -> Self: ...

class Child(Base):
    @override                       # type checker errors if Base has no such method
    def save(self) -> None: ...

class Event(TypedDict):
    id: str
    payload: NotRequired[dict[str, object]]

Rules:

• X | None, list[int], dict[str, int] — never Optional, List, Dict.
• Accept abstract (Iterable, Mapping, Sequence), return concrete (list, dict).
• Callbacks: Callable[[int, str], bool]; for complex signatures use a Protocol with __call__.
• Structural typing with typing.Protocol instead of ABCs for dependency seams.
• TypeIs (3.13, or typing_extensions) for narrowing helpers; prefer it to TypeGuard.
• Only add from __future__ import annotations on 3.12/3.13 if you need forward refs everywhere; 3.14 evaluates annotations lazily by default.

Type checker choice: mypy --strict is the conservative default; pyright (strict mode) is faster and stricter on inference. Pick one per repo and run it in CI. Astral’s ty is promising but check its release status before relying on it as the only gate.

Data modeling decision

Need	Use
Internal value object, trusted data	@dataclass(slots=True, frozen=True, kw_only=True)
Parse/validate untrusted JSON, env, API bodies	Pydantic v2 BaseModel / pydantic-settings
Very hot decode path, simple schemas	msgspec Struct
Dict shape for a JSON payload you only pass through	TypedDict
Fixed set of values	enum.StrEnum / enum.IntEnum

from dataclasses import dataclass, field
from datetime import datetime, UTC

@dataclass(slots=True, frozen=True, kw_only=True)
class Invoice:
    id: str
    amount_cents: int
    tags: tuple[str, ...] = ()
    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))

Never use a mutable default (tags: list[str] = []); dataclasses reject it, plain functions silently share it.

Language features worth reaching for (3.11+)

• match for structural dispatch on tagged dicts/dataclasses, not as a long if chain over plain values.
• asyncio.TaskGroup instead of bare gather for structured concurrency; failures cancel siblings and surface as ExceptionGroup (except* ValueError:).
• tomllib (read-only TOML) in the stdlib; zoneinfo instead of pytz.
• datetime.now(UTC) — never naive datetime.utcnow() (deprecated in 3.12).
• pathlib.Path over os.path; Path.read_text(encoding="utf-8") always with encoding.
• f-string debugging f"{value=}"; 3.12 allows nested quotes in f-strings.

Ruff configuration essentials

[tool.ruff]
line-length = 100
target-version = "py312"     # inferred from requires-python if omitted

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "UP", "SIM", "RUF", "C4", "PTH", "DTZ", "S", "N", "PL", "TID"]
ignore = ["PLR0913", "S101"]  # many args ok; assert ok (tests)

[tool.ruff.lint.per-file-ignores]
"tests/**" = ["S", "PLR2004"]

Commands: uv run ruff check --fix ., uv run ruff format .. Ruff replaces flake8, isort, pyupgrade, and black; remove their configs when adopting it.

Packaging and publishing

uv build                          # sdist + wheel in dist/
uvx twine check dist/*            # metadata sanity
uv publish                        # uses trusted publishing in GitHub Actions, or UV_PUBLISH_TOKEN

• Build backend: hatchling is the safe default; uv_build is fine for pure-Python projects on current uv.
• Version single source: [project] version or a dynamic version from VCS (hatch-vcs); not both.
• Ship a py.typed marker in the package for typed libraries.
• Prefer PyPI trusted publishing (OIDC) over long-lived tokens.

Gotchas

• A src/ layout prevents tests from importing the working tree accidentally; keep it.
• uv run syncs the environment first; in CI use uv run --locked or uv sync --locked then uv run --no-sync.
• requires-python = ">=3.12" without an upper bound is correct; <4 caps cause resolver pain for downstream users.
• Dev tools in [project.optional-dependencies] leak into published metadata; use [dependency-groups] (PEP 735) instead.
• except Exception: pass is never acceptable; ruff’s S110/BLE rules catch it.
• Free-threaded (no-GIL) builds exist (3.13t, supported in 3.14); C extensions must declare support or the GIL is re-enabled at import. Do not promise speedups untested.

Verification

uv sync --locked
uv run ruff check . && uv run ruff format --check .
uv run mypy src        # or: uv run pyright
uv run pytest -q
uv build               # for packages: wheel builds cleanly

All five must pass on a fresh clone. If uv sync --locked fails, run uv lock, review the lock diff, and commit it separately from code changes.

Output for a migration

**From:** requirements.txt + setup.py  **To:** pyproject.toml + uv.lock
**Python:** requires-python >=3.12, pinned 3.13 for dev
**Tooling:** ruff (replaced black, isort, flake8), mypy --strict on src/
**Commands:** `uv sync`, `uv run pytest`, `uv run ruff check --fix .`
**Follow-ups:** 41 mypy errors in legacy/ excluded via per-module override