Object-Oriented Python Best Practices

Python is not Java - lean toward simple objects, functions, and protocols rather than deep inheritance hierarchies. These rules keep OO code Pythonic and testable.

How to Use This List

• Apply in design reviews for new domain models.
• Use when refactoring god-classes or mixin soup.
• Pair with mypy protocols and Pydantic at system edges.
• Revisit after incidents caused by shared mutable class state.

A - Modeling

• Use @dataclass for data records; add methods only when behavior is intrinsic. Not every dict needs a class.
• Prefer composition (has-a) over inheritance (is-a) beyond one level. Inject collaborators in __init__.
• Use Enum/StrEnum instead of string constants. Exhaustive match and typo prevention.
• Model money, IDs, and quantities as small value types. Not bare int/str across layers.
• Keep classes focused - one reason to change. Split read models from write services when needed.

B - Inheritance and APIs

• Limit mixins to one concern (logging, serialization). Document MRO when using multiple.
• Call super().__init__ in cooperative multiple inheritance chains. Broken chains skip initialization.
• Prefer Protocol or ABC only when multiple implementations exist. YAGNI for single impl.
• Use @classmethod factories for alternate constructors. Not overloaded __init__ patterns.
• Public API small; prefix internals with _. Properties expose stable attributes over raw fields.

C - Correctness

• Align __eq__ and __hash__ for value objects used in sets/dicts. Or use frozen=True dataclass.
• Never mutate frozen or supposedly immutable objects. Tuple fields inside dataclass still mutable.
• Validate invariants in __post_init__ or setters. Fail fast at construction.
• Return NotImplemented from __eq__ for unknown types. Let other operand try reverse comparison.
• Avoid mutable class attributes as shared defaults. Set per-instance in __init__.

D - Metaprogramming Discipline

• Default to __init_subclass__ for registration hooks. Not custom metaclasses.
• Reach for descriptors/properties only when validation or lazy compute repeats. Simple __init__ otherwise.
• Use __slots__ only with measured memory pressure. Accept inheritance constraints.
• Document plugin registries and clear them in tests. Prevent cross-test pollution.
• Skip operator overloading unless domain is naturally numeric/vector-like. Surprising + hurts readers.

E - Testing and Boundaries

• Inject dependencies (clock, storage, notifier) in constructors. Not hard-coded globals.
• Fake implementations for ABC/Protocol ports in unit tests. No network in domain tests.
• Use Pydantic 2 at HTTP boundaries; plain dataclasses inside. Separation of transport and domain.
• Prefer functions for stateless transforms between rich objects. Methods when behavior belongs to data.
• Keep Django/FastAPI views thin - domain logic in testable services.

FAQs

Related

• OOP Basics - intro examples
• Inheritance & MRO - super and mixins
• Protocols & Structural Typing - interfaces
• dataclasses - record pattern

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.