language-python

Python

Type hints

• Annotate all function signatures; Any is a smell unless at a genuine boundary.
• Use dataclass for data containers with behavior; TypedDict for dict-shaped data at boundaries.
• Prefer Protocol over ABC when duck typing suffices — no inheritance required.
• from __future__ import annotations for forward refs in 3.9 and earlier.

from dataclasses import dataclass, field

@dataclass
class Order:
    id: str
    items: list[str] = field(default_factory=list)
    total: float = 0.0

Errors and exceptions

• Use exceptions for exceptional paths, not flow control.
• Raise specific subclasses; catch the narrowest class you can handle.
• except Exception: is almost always wrong — at minimum log and re-raise.
• contextlib.suppress(SomeError) for intentional ignore; bare except: never.

try:
    result = load(path)
except FileNotFoundError:
    raise MissingConfigError(path) from None

Context managers

• with for any resource with a cleanup obligation: files, locks, DB connections.
• @contextlib.contextmanager for ad-hoc managers without a full class.
• Never hold a resource longer than the with block.

@contextlib.contextmanager
def managed_resource():
    r = acquire()
    try:
        yield r
    finally:
        release(r)

Generators and iterators

• Prefer generators over materializing full lists when you only iterate once.
• yield from to delegate to sub-generators.
• Reach for itertools before writing loops: chain, islice, groupby, product.

def read_chunks(path: Path, size: int = 4096):
    with open(path, "rb") as f:
        while chunk := f.read(size):  # walrus operator, 3.8+
            yield chunk

Concurrency

• GIL caveat: threads don't parallelize CPU-bound work — use ProcessPoolExecutor or multiprocessing.
• asyncio for IO-bound concurrency; asyncio.TaskGroup (3.11+) for structured fan-out.
• ThreadPoolExecutor for legacy sync IO or blocking C extensions.
• One event loop per process; never nest or mix loops.