python-idioms

Python Idioms and Patterns

Core Philosophy

Python rewards explicitness and readability over cleverness. Follow the Zen of Python. If it reads like plain English, it's probably idiomatic.

Scope: This skill covers Python-specific coding idioms. For file layout see references/project-structure.md. For safety/SAST/performance patterns see references/python-patterns-and-anti-patterns.md. For logging see logging-implementation skill. For quality commands see code-idioms-and-conventions rule.

Loading Guards

• If no pyproject.toml or *.py files, this skill does not apply
• If Django project (django in dependencies), co-load django-idioms skill alongside this one

When to Load References

Situation	Reference to Load
Starting a new project or setting up file layout	references/project-structure.md
Choosing packages, pyproject.toml setup, or ruff config	references/recommended-dependencies.md
Writing code that handles user input, async operations, or I/O	references/python-patterns-and-anti-patterns.md

Toolchain and Python Version

• Default to latest stable Python. As of August 2026, Python 3.14. Minimum target: 3.13+.
• Key version milestones:
  • 3.14+ — Deferred evaluation of annotations (PEP 649, no more from __future__ import annotations), template strings (PEP 750)
  • 3.13+ — Improved error messages, experimental free-threaded build, experimental JIT
  • 3.12+ — Type parameter syntax type X = ... (PEP 695), @override decorator, improved f-strings, itertools.batched
  • 3.11+ — StrEnum, ExceptionGroup + except*, asyncio.TaskGroup, tomllib, fine-grained error locations
  • 3.10+ — Pattern matching (match/case), X | Y union syntax, TypeAlias

Type Hints — Non-Negotiable

Type hints are required for all public APIs, class attributes, and function signatures.

• Use standard collections (list, dict, set) for typing, not typing.List etc.
• Use X | Y instead of Union[X, Y] or Optional[X].
• Use PEP 695 type parameter syntax (3.12+) for generic types: type Vector[T] = list[T]
• Use @override (3.12+) to ensure methods actually override a base class method.
• Use TypeVar with constraints and bounds when necessary.
• Use Never for functions that always raise an exception or never return.