python-abstractions

name	python-abstractions
description	Use for Python decorators, descriptors, context managers (function and class form), metaclasses, and multiple dispatch. The common question is "which abstraction hides this complexity at the right level?".
globs	["**/*.py"]

Python Abstractions

Use this when the design question is which abstraction mechanism — decorator, descriptor, context manager, metaclass, or dispatch — should carry a cross- cutting concern.

Working stance

• Reach for the lightest mechanism that works. Function ≺ decorator ≺ context manager ≺ descriptor ≺ metaclass.
• Decorators preserve call shape; pair them with ParamSpec so the type checker sees through them.
• Class-based context managers are right when there is state to hold and shut down; @contextmanager is right when the resource is try/finally shaped and a single function expresses it cleanly.
• Descriptors belong on classes whose attributes need consistent validation, lazy computation, or per-instance bookkeeping; never use them when a @property suffices.
• Metaclasses are a last resort. Most "I want to customize class creation" problems are solved by __init_subclass__, decorators, or dataclass_transform.
• For multi-argument dispatch, prefer functools.singledispatch for the one-argument case and a typed external library for the multi-argument case; never fall back to isinstance ladders in a public function.

Decision surface

• Decorator (P, R): a cross-cutting concern (logging, retry, caching, transactions) wraps a function with a fixed call shape; the wrapper must preserve the wrapped signature for callers and type checkers (ParamSpec).
• Function context manager (@contextlib.contextmanager): setup and teardown collapse into a single function with one yield; reuse is local.
• Class context manager (__enter__/__exit__): the manager holds state, exposes methods between __enter__ and __exit__, or needs custom exception suppression (__exit__ returning True).
• Async context manager (__aenter__/__aexit__, @asynccontextmanager): the resource is awaited (connection pool, HTTP session); never block in __aenter__.
• Descriptor (__get__/__set__/__set_name__): an attribute needs validation, lazy computation, or per-instance state and the rule repeats across attributes (validated fields, typed columns, cached_property variants).
• Metaclass: class-creation behaviour cannot be expressed via __init_subclass__, __class_getitem__, decorators, or dataclass_transform. Examples: ORM model registries with custom MRO, plugin systems with strict invariants, msgspec.Struct itself.
• Dispatch:
  • typing.overload — static-only narrowing, no runtime dispatch.
  • functools.singledispatch — one argument, stdlib, global registry.
  • plum-dispatch / ovld — multi-argument, type-hint native, fast; reach for these when isinstance chains grow in a public function.

Red flags

• a decorator typed Callable[..., Any] that erases the wrapped signature,
• a @contextmanager whose body spans tens of lines with branching cleanup (promote to a class-based manager),
• a class-based context manager that hides only a single try/finally (collapse to @contextmanager),
• a descriptor that stores per-instance state on the class object (data leaks across instances),
• a metaclass introduced for naming, validation, or registration that __init_subclass__ could handle,
• a multi-argument isinstance ladder in a public function,
• singledispatch used on a method that should be a regular polymorphism point on the class.

Read decorators-and-paramspec.md, context-manager-extraction.md, descriptors.md, and metaclasses-and-dispatch.md when one of those forks dominates.