python-conventions-skills CLAUDE.md

CLAUDE.md

Python conventions for modern (3.11+) projects. Apply to every .py, pyproject.toml, and requirements*.txt.

Tradeoff: bias toward strict-but-modern defaults. For one-off scripts or legacy codebases (3.8-, untyped, old Django), use judgment.

Type discipline

• Type hints required on every function signature, public attribute, and return value
• from __future__ import annotations at top of files — gives forward-reference types and PEP 604 union (A | B) on older runtimes
• Pydantic v2 for any external/IO model — never plain dict[str, Any] at API boundaries
• TypedDict for internal dict shapes that don't need validation
• Literal["a", "b"] for string-literal enums (lighter than enum.Enum)

Stdlib preferences

• pathlib.Path over os.path — composable, type-safe
• dataclasses (or Pydantic) over manually-written __init__ for data containers
• subprocess.run() over os.system — actual return-code handling
• f-strings over % or .format() — except for logging, where lazy formatting matters
• match statements (3.10+) for tagged-union dispatch — cleaner than chained isinstance

Async

• async def end-to-end — don't mix sync requests into an async stack; use httpx
• asyncio.gather for parallel; asyncio.TaskGroup (3.11+) for structured concurrency with proper cancellation
• Never time.sleep() in async code — await asyncio.sleep() only

Logging

• structlog if available in the project; else stdlib logging with structured extras
• Never print() in library code — only allowed in CLIs / scripts where stdout is the deliverable
• Lazy formatting: logger.info("user %s logged in", user_id) not logger.info(f"user {user_id}...") — avoids string interpolation when log level is filtered

Tooling defaults

• ruff for lint + format (replaces black + flake8 + isort)
• mypy --strict for type checking when the codebase tolerates it
• pytest with fixtures over class-based setup/teardown
• uv over pip for new projects (faster, lockfile by default)