designing-python-apis

Follow four principles: simplicity, consistency, least surprise, and discoverability. Use progressive disclosure so simple calls work with defaults, apply verb-based naming like encode() and get_user(), and make options keyword-only so call sites stay readable.

Follow a three-phase lifecycle: emit a DeprecationWarning naming the replacement in a minor release, document the removal version and migration path, then remove only in a later major release. Use stacklevel=2 so the warning points at the caller's code.

Additive changes like new functions or keyword-only parameters with defaults keep existing code running and fit minor releases. Breaking changes like removing names, changing return types, or tightening accepted argument types require a major release.

Prefer a frozen dataclass config object by default since it is easy to construct, compare, and serialize. Use a fluent builder only when construction is genuinely stepwise or conditional, and return a new instance from each step.

Silent failures come from setting success sentinels in except blocks, swallowing exceptions into generic messages, returning partial results as if complete, or no-op behavior on unexpected input. Catch specific exceptions, validate before mutating, and raise on empty filtered sets.

Use typing.Protocol when you only need to define the shape callers must satisfy, since it type-checks without coupling users to your hierarchy. Reserve abstract base classes for cases where you must share implementation, not merely an interface.