writing-python

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: 

Dataclasses

Pattern Matching

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

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:

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.