writing-python

name	writing-python
description	Idiomatic Python 3.14+ development. Use when writing Python code, CLI tools, scripts, or services. Emphasizes stdlib, type hints, uv/ruff toolchain, and minimal dependencies.
allowed-tools	Read, Bash, Grep, Glob

Python Development (3.14+)

Core Principles

• Stdlib first: External deps only when justified
• Type hints everywhere: All functions, all parameters
• Explicit over implicit: Clear is better than clever
• Fail fast: Raise early with informative errors

Toolchain

uv           # Package management (not pip/poetry)
ruff         # Lint + format (not flake8/black)
pytest       # Testing
mypy         # Type checking

Quick Patterns

Type Hints

def process_users(users: list[User], limit: int | None = None) -> list[Result]:
    ...

async def fetch_data(url: str, timeout: float = 30.0) -> dict[str, Any]:
    ...

Dataclasses

from dataclasses import dataclass, field

@dataclass
class Config:
    host: str
    port: int = 8080
    tags: list[str] = field(default_factory=list)

Pattern Matching

match event:
    case {"type": "click", "x": x, "y": y}:
        handle_click(x, y)
    case {"type": "key", "code": code}:
        handle_key(code)
    case _:
        raise ValueError(f"Unknown event: {event}")

Python 3.14 Features

• Deferred annotations: No more from __future__ import annotations
• Template strings (t""): t"Hello {name}" returns Template object
• except without parens: except ValueError, TypeError:
• concurrent.interpreters: True parallelism via subinterpreters
• compression.zstd: Zstandard in stdlib
• Free-threaded build: No GIL (opt-in)

References

• PATTERNS.md - Code patterns and style
• CLI.md - CLI application patterns
• TESTING.md - Testing with pytest

Tooling

uv sync                    # Install deps
ruff check --fix .         # Lint and autofix
ruff format .              # Format
pytest -v                  # Test
mypy .                     # Type check

---

Absorbed sub-skills (post-consolidation)

This skill now subsumes the former python-code-style and python-type-safety skills. Their original SKILL.md content is preserved as deep reference:

Subject	Path
ruff, mypy, naming, imports, docstrings (Google style)	References/code-style.md
Type annotations, generics, protocols, strict checking patterns	References/type-safety.md

For system-reliability concerns (background jobs, retries, observability), see the sibling python-infrastructure skill. For dependency management and project scaffolding, see uv.

---

Gotchas

• from __future__ import annotations makes ALL annotations strings — runtime introspection (typing.get_type_hints) needs the actual types available; forward refs to local-scope classes fail.
• f-string debug syntax (f"{var=}") is 3.8+ — quietly fails (treats = as literal) in 3.7 and earlier.
• dataclass(slots=True) is 3.10+ — silently does nothing in 3.9. Use __slots__ manually for portability.
• PEP 604 union syntax (int | None) is 3.10+ at runtime — works as a string annotation in 3.9 with from __future__ import annotations, fails at runtime introspection.
• async def vs def for FastAPI dependencies: async deps run in the event loop; sync deps run in a thread pool. Mixing without thought causes either blocking or extra context-switch overhead.