Designing Objects in Python
In this pack: sizing and rule strictness are set by the core
plugin's oo-design skill; each rule here keeps a core rule in this
language.
Overview
Python leaves much of a design to convention: a role has no declaration
unless a Protocol names it, a value stays changeable unless a
dataclass is frozen and holds no list, and state that a rule guards is
only as private as its leading underscore suggests. This skill applies
the pack's core rules to plain Python, from version 3.12 on, with no
framework and a type checker such as mypy. It says which feature keeps
each rule and where the runtime stops helping: a frozen dataclass that
still holds a mutable list, an isinstance check that reads only
method names, and a @final mark that only the checker enforces.
When to use
- Two or more classes play one role, and nothing in the code declares
which messages the role requires.
- A value is written as a plain dataclass, and any caller can change it
or the list it holds.
- A frozen dataclass holds a list or another mutable field.
- A rule on an attribute can be broken from outside the class.
- A mixin reads its host's attributes, or
super() reaches a class the
method's own class never names.
- Code asks
isinstance or type() before sending an object a
message.
When not to use
- A framework builds or wires the objects, such as a web framework with
its own models: outside this skill.
- The code is JavaScript, which
oo-javascript covers.
- The question is one no Python feature changes, such as which object
owns a rule or where a module boundary runs: the core skills,
starting from
oo-design.
Core rules
Default. Name each role a caller needs as a typing.Protocol,
annotate every parameter that takes the role with it, and have each
implementation declare the role as a base class, so a type checker
reports a class that does not match, as
oo-designing-interfaces rule 5 asks. Python matches an object by
the methods it happens to have, so a class that never names the role
can still satisfy the annotation at run time, and no runtime check
reads the method signatures. Listing the protocol as a base class is
how an implementation declares which role it plays, which is the
named role oo-designing-interfaces rule 5 asks for: a checker such
as mypy reports a signature that differs from the protocol's and
refuses to instantiate a class that leaves a required method out,
while Python builds it and the missing method answers None. The
annotation is what the checker reads at a call site, so a class that
only matches by shape is still checked against the role. The protocol
is also where the contract sits that every implementation keeps, as
oo-honouring-substitutability rule 4 asks.
The exception is a role whose whole contract is one call, such as a
callback: annotate the parameter with a Callable type, because the
call is the only message the caller sends and a Protocol would add a
class for a function.
Judgement. Choose a Protocol when the implementations share only
a promise, and an abstract base class when they share state or a
fixed order of steps the base class owns, as
oo-designing-interfaces rule 4 chooses an interface or a base
class. A protocol is never instantiated, so it holds no state and
fixes no order; an ABC carries its fields, its constructor and the
concrete methods its subclasses inherit, and a subclass that leaves
an @abstractmethod unoverridden raises TypeError when it is
instantiated. What tips the balance is whether the shared code needs
state: prefer the protocol unless the code would otherwise be
repeated.
Default. Write a value as a frozen dataclass whose __post_init__
checks its rules and whose fields hold immutable types, such as a
tuple in place of a list, and answer a changed copy with
dataclasses.replace, which builds the copy through __init__ and
runs the same checks, as oo-modeling-values-and-entities rules 2
and 3 and oo-constructing-valid-objects rule 3 ask. A frozen
dataclass refuses an assignment to a field with
FrozenInstanceError, and when it compares by value it derives
__hash__ from the same fields, so two equal copies hash alike; the
freeze is shallow, though, so a list held in a field still changes,
and hashing that value raises TypeError. Hold a tuple or another
immutable value, and let replace build every changed copy, because
it calls the class's __init__ and __post_init__, and a check
outside those runs for no copy.
The exception is state that must change while a caller holds it,
such as the observations a clinician adds during a visit: that is an
entity whose method owns the rule, because a frozen dataclass stops
a field being rebound and leaves the list it holds changeable.
Rule. Keep state that a rule guards in attributes whose names
start with an underscore, read it through a property with no
setter, and change it only through a method named for the domain
action, never through a setter or a descriptor's __set__, which
run on a plain assignment, as
oo-encapsulating-state-and-behaviour rules 1 and 2 ask. A
leading underscore marks a name internal by convention only, so a
caller can still assign it; a property with no setter makes the
assignment raise AttributeError, and a data descriptor's __set__
runs whenever holder.attribute = value runs. A method such as
reschedule reads the current state, checks the rule, and changes
only what the action allows.
Default. Share behaviour across classes with an object each one
holds, not a mixin, as oo-choosing-composition-over-inheritance
rule 5 asks; a mixin that stays holds no state, uses only the host's
public methods, and keeps each send a host may depend on in its
contract, so a host depends on no send the mixin keeps internal, as
rule 3 there asks, and calls super() knowing that it reaches the
next class in the instance's method resolution order. A held object
has its own attributes and offers only the messages its holder
sends. A mixin shares the host's attributes and can break a rule the
host keeps; an override in the host that works only because the
mixin sends it from another method depends on an internal send and
breaks when the mixin changes it, which is what rule 3 there forbids
from the host's side. It also makes super() reach a class the
mixin never names, because in class C(A, B) a super().save()
written in A calls B.save, and the route comes from the
instance's MRO.
The exception is a mixin that adds only behaviour built from the
host's public methods, such as an ordering built from a comparison
the host defines: it holds no state and touches no field, so it
cannot break the host's rules.
Rule. Never ask which class an object is, with isinstance or
type(), before sending it a message, as
oo-honouring-substitutability rule 6 asks. Such a check puts the
class into the caller: a new implementation must be added to the
check or it takes the other branch, and the caller depends on the
class rather than on the role's messages. When one implementation
needs a different message, the role's contract is wrong or that
implementation does not keep it, and rule 6 there says to fix the
subtype or the hierarchy, not the caller. A protocol is what lets a
checker report a message the declared role does not have (rule 1).
Default. Mark a class @final unless it was built for extension,
knowing that only a type checker enforces it, as
oo-honouring-substitutability rule 5 asks. typing.final tells
a reader and mypy that no subclass is part of the design; at run
time a subclass of a final class is created without error, so the
mark records the intent and the checker guards it. Built for
extension means the methods a subclass may override are named, each
with the contract an override must keep written beside it, and which
of the class's own methods send them.
The exception is a class that a framework subclasses with a declared
subclass in checked code, such as a generated adapter, even where no
override is part of the design: the mark does not stop a type()
subclass, but it reports the declared one, so leave the class open
and say in the code why.
Pattern
LabRequest is a request the clinic sends to a laboratory: the panel
it names and the tests it asks for. Two requests with the same panel
and tests are the same request, a value
(oo-modeling-values-and-entities rule 1).
Before:
from dataclasses import dataclass
@dataclass
class LabRequest:
panel: str
tests: list[str]
tests = ["full blood count", "ferritin"]
request = LabRequest("anaemia panel", tests)
tests.append("")
request.panel = ""
In the Before, LabRequest is a plain dataclass, so any caller can
assign request.panel or append to the list it holds (rule 3). The
constructor keeps the caller's list, so the later append changes the
request's tests as well (rule 3). Nothing refuses a blank panel or a
blank test (rule 3). The fence stores nothing: it leaves out where a
request is saved, under which identity, and in which transaction.
After:
from dataclasses import dataclass, replace
@dataclass(frozen=True)
class LabRequest:
panel: str
tests: tuple[str, ...]
def __post_init__(self) -> None:
if self.panel.strip() == "":
raise ValueError("a lab request names its panel")
if len(self.tests) == 0:
raise ValueError("a lab request asks for a test")
for test in self.tests:
if test.strip() == "":
raise ValueError("a test is named")
def with_tests(self, tests: tuple[str, ...]) -> "LabRequest":
return replace(self, tests=tests)
In the After, LabRequest is a frozen dataclass: assigning panel or
tests raises FrozenInstanceError (rule 3). tests is a tuple, so
no caller can append to it (rule 3). __post_init__ runs during
construction and refuses a blank panel, no tests, or a blank test
(rule 3). with_tests calls replace, which builds the copy through
__init__ and __post_init__, so the checks hold for the copy too
(rule 3). The generated equality reads both fields and the generated
hash reads the same fields, so two requests with equal contents hash
alike (rule 3). The fence stores nothing: it leaves out where a request
is saved, under which identity, and in which transaction.
Red flags
Places to look, not verdicts. A red flag becomes a finding only with
evidence: a measurement, a reproducible bug, or a failing test.
- A role played by two or more classes with no
Protocol naming it.
- A plain dataclass whose value any caller can assign.
- A frozen dataclass that holds a list or another mutable field.
- A rule kept only by a leading underscore.
- A property with a setter, or a descriptor's
__set__, that holds a
clinic rule.
- A mixin that reads or writes its host's attributes.
- A
super() call in a mixin with no note on the instance's MRO.
isinstance or type() compared before a message is sent.
- A class that is neither
@final nor written for extension.
Common mistakes
- Believing the annotation of a
Protocol checks anything at run time.
- Using
isinstance against a Protocol without
@runtime_checkable, so it raises TypeError.
- Believing a
@runtime_checkable protocol compares method
signatures.
- Freezing a dataclass and believing the list it holds is frozen too.
- Hashing a frozen dataclass whose field holds a list.
- Leaving a value's check in a factory, so
replace skips it.
- Treating a leading underscore as privacy.
- Adding a setter to quiet a caller that assigns a field.
- Calling
super() in a mixin without reading the instance's MRO.
- Writing
@final and expecting a runtime error on subclassing.
Related skills
oo-design sizes a task and defines the rule labels.
oo-designing-interfaces shapes a role around its caller.
oo-honouring-substitutability says what every implementation of a
role must keep.
oo-modeling-values-and-entities decides whether a concept is a
value or an entity, and what equality reads.
oo-constructing-valid-objects makes a constructor refuse broken
input.
oo-encapsulating-state-and-behaviour keeps an invariant with the
state it guards.
oo-choosing-composition-over-inheritance decides when to hold an
object instead of extending a class.
oo-javascript shows how the same rules read in a language with no
type checker.
Further reading
1---2name: oo-python3description: Use when plain Python with no framework needs a Protocol or an ABC, a frozen dataclass, a mixin and its MRO, or a property instead of a setter.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-python7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Designing Objects in Python1213**In this pack:** sizing and rule strictness are set by the core14plugin's `oo-design` skill; each rule here keeps a core rule in this15language.1617## Overview1819Python leaves much of a design to convention: a role has no declaration20unless a `Protocol` names it, a value stays changeable unless a21dataclass is frozen and holds no list, and state that a rule guards is22only as private as its leading underscore suggests. This skill applies23the pack's core rules to plain Python, from version 3.12 on, with no24framework and a type checker such as mypy. It says which feature keeps25each rule and where the runtime stops helping: a frozen dataclass that26still holds a mutable list, an `isinstance` check that reads only27method names, and a `@final` mark that only the checker enforces.2829## When to use3031- Two or more classes play one role, and nothing in the code declares32 which messages the role requires.33- A value is written as a plain dataclass, and any caller can change it34 or the list it holds.35- A frozen dataclass holds a list or another mutable field.36- A rule on an attribute can be broken from outside the class.37- A mixin reads its host's attributes, or `super()` reaches a class the38 method's own class never names.39- Code asks `isinstance` or `type()` before sending an object a40 message.4142## When not to use4344- A framework builds or wires the objects, such as a web framework with45 its own models: outside this skill.46- The code is JavaScript, which `oo-javascript` covers.47- The question is one no Python feature changes, such as which object48 owns a rule or where a module boundary runs: the core skills,49 starting from `oo-design`.5051## Core rules52531. Default. **Name each role a caller needs as a `typing.Protocol`,54 annotate every parameter that takes the role with it, and have each55 implementation declare the role as a base class, so a type checker56 reports a class that does not match, as57 `oo-designing-interfaces` rule 5 asks.** Python matches an object by58 the methods it happens to have, so a class that never names the role59 can still satisfy the annotation at run time, and no runtime check60 reads the method signatures. Listing the protocol as a base class is61 how an implementation declares which role it plays, which is the62 named role `oo-designing-interfaces` rule 5 asks for: a checker such63 as mypy reports a signature that differs from the protocol's and64 refuses to instantiate a class that leaves a required method out,65 while Python builds it and the missing method answers `None`. The66 annotation is what the checker reads at a call site, so a class that67 only matches by shape is still checked against the role. The protocol68 is also where the contract sits that every implementation keeps, as69 `oo-honouring-substitutability` rule 4 asks.7071 The exception is a role whose whole contract is one call, such as a72 callback: annotate the parameter with a `Callable` type, because the73 call is the only message the caller sends and a Protocol would add a74 class for a function.75762. Judgement. **Choose a `Protocol` when the implementations share only77 a promise, and an abstract base class when they share state or a78 fixed order of steps the base class owns, as79 `oo-designing-interfaces` rule 4 chooses an interface or a base80 class.** A protocol is never instantiated, so it holds no state and81 fixes no order; an ABC carries its fields, its constructor and the82 concrete methods its subclasses inherit, and a subclass that leaves83 an `@abstractmethod` unoverridden raises `TypeError` when it is84 instantiated. What tips the balance is whether the shared code needs85 state: prefer the protocol unless the code would otherwise be86 repeated.87883. Default. **Write a value as a frozen dataclass whose `__post_init__`89 checks its rules and whose fields hold immutable types, such as a90 tuple in place of a list, and answer a changed copy with91 `dataclasses.replace`, which builds the copy through `__init__` and92 runs the same checks, as `oo-modeling-values-and-entities` rules 293 and 3 and `oo-constructing-valid-objects` rule 3 ask.** A frozen94 dataclass refuses an assignment to a field with95 `FrozenInstanceError`, and when it compares by value it derives96 `__hash__` from the same fields, so two equal copies hash alike; the97 freeze is shallow, though, so a list held in a field still changes,98 and hashing that value raises `TypeError`. Hold a tuple or another99 immutable value, and let `replace` build every changed copy, because100 it calls the class's `__init__` and `__post_init__`, and a check101 outside those runs for no copy.102103 The exception is state that must change while a caller holds it,104 such as the observations a clinician adds during a visit: that is an105 entity whose method owns the rule, because a frozen dataclass stops106 a field being rebound and leaves the list it holds changeable.1071084. Rule. **Keep state that a rule guards in attributes whose names109 start with an underscore, read it through a `property` with no110 setter, and change it only through a method named for the domain111 action, never through a setter or a descriptor's `__set__`, which112 run on a plain assignment, as113 `oo-encapsulating-state-and-behaviour` rules 1 and 2 ask.** A114 leading underscore marks a name internal by convention only, so a115 caller can still assign it; a property with no setter makes the116 assignment raise `AttributeError`, and a data descriptor's `__set__`117 runs whenever `holder.attribute = value` runs. A method such as118 `reschedule` reads the current state, checks the rule, and changes119 only what the action allows.1201215. Default. **Share behaviour across classes with an object each one122 holds, not a mixin, as `oo-choosing-composition-over-inheritance`123 rule 5 asks; a mixin that stays holds no state, uses only the host's124 public methods, and keeps each send a host may depend on in its125 contract, so a host depends on no send the mixin keeps internal, as126 rule 3 there asks, and calls `super()` knowing that it reaches the127 next class in the instance's method resolution order.** A held object128 has its own attributes and offers only the messages its holder129 sends. A mixin shares the host's attributes and can break a rule the130 host keeps; an override in the host that works only because the131 mixin sends it from another method depends on an internal send and132 breaks when the mixin changes it, which is what rule 3 there forbids133 from the host's side. It also makes `super()` reach a class the134 mixin never names, because in `class C(A, B)` a `super().save()`135 written in `A` calls `B.save`, and the route comes from the136 instance's MRO.137138 The exception is a mixin that adds only behaviour built from the139 host's public methods, such as an ordering built from a comparison140 the host defines: it holds no state and touches no field, so it141 cannot break the host's rules.1421436. Rule. **Never ask which class an object is, with `isinstance` or144 `type()`, before sending it a message, as145 `oo-honouring-substitutability` rule 6 asks.** Such a check puts the146 class into the caller: a new implementation must be added to the147 check or it takes the other branch, and the caller depends on the148 class rather than on the role's messages. When one implementation149 needs a different message, the role's contract is wrong or that150 implementation does not keep it, and rule 6 there says to fix the151 subtype or the hierarchy, not the caller. A protocol is what lets a152 checker report a message the declared role does not have (rule 1).1531547. Default. **Mark a class `@final` unless it was built for extension,155 knowing that only a type checker enforces it, as156 `oo-honouring-substitutability` rule 5 asks.** `typing.final` tells157 a reader and mypy that no subclass is part of the design; at run158 time a subclass of a `final` class is created without error, so the159 mark records the intent and the checker guards it. Built for160 extension means the methods a subclass may override are named, each161 with the contract an override must keep written beside it, and which162 of the class's own methods send them.163164 The exception is a class that a framework subclasses with a declared165 subclass in checked code, such as a generated adapter, even where no166 override is part of the design: the mark does not stop a `type()`167 subclass, but it reports the declared one, so leave the class open168 and say in the code why.169170## Pattern171172`LabRequest` is a request the clinic sends to a laboratory: the panel173it names and the tests it asks for. Two requests with the same panel174and tests are the same request, a value175(`oo-modeling-values-and-entities` rule 1).176177Before:178179```python180from dataclasses import dataclass181182183@dataclass184class LabRequest:185 panel: str186 tests: list[str]187188189tests = ["full blood count", "ferritin"]190request = LabRequest("anaemia panel", tests)191tests.append("")192request.panel = ""193```194195In the Before, `LabRequest` is a plain dataclass, so any caller can196assign `request.panel` or append to the list it holds (rule 3). The197constructor keeps the caller's list, so the later append changes the198request's tests as well (rule 3). Nothing refuses a blank panel or a199blank test (rule 3). The fence stores nothing: it leaves out where a200request is saved, under which identity, and in which transaction.201202After:203204```python205from dataclasses import dataclass, replace206207208@dataclass(frozen=True)209class LabRequest:210 panel: str211 tests: tuple[str, ...]212213 def __post_init__(self) -> None:214 if self.panel.strip() == "":215 raise ValueError("a lab request names its panel")216 if len(self.tests) == 0:217 raise ValueError("a lab request asks for a test")218 for test in self.tests:219 if test.strip() == "":220 raise ValueError("a test is named")221222 def with_tests(self, tests: tuple[str, ...]) -> "LabRequest":223 return replace(self, tests=tests)224```225226In the After, `LabRequest` is a frozen dataclass: assigning `panel` or227`tests` raises `FrozenInstanceError` (rule 3). `tests` is a tuple, so228no caller can append to it (rule 3). `__post_init__` runs during229construction and refuses a blank panel, no tests, or a blank test230(rule 3). `with_tests` calls `replace`, which builds the copy through231`__init__` and `__post_init__`, so the checks hold for the copy too232(rule 3). The generated equality reads both fields and the generated233hash reads the same fields, so two requests with equal contents hash234alike (rule 3). The fence stores nothing: it leaves out where a request235is saved, under which identity, and in which transaction.236237## Red flags238239Places to look, not verdicts. A red flag becomes a finding only with240evidence: a measurement, a reproducible bug, or a failing test.241242- A role played by two or more classes with no `Protocol` naming it.243- A plain dataclass whose value any caller can assign.244- A frozen dataclass that holds a list or another mutable field.245- A rule kept only by a leading underscore.246- A property with a setter, or a descriptor's `__set__`, that holds a247 clinic rule.248- A mixin that reads or writes its host's attributes.249- A `super()` call in a mixin with no note on the instance's MRO.250- `isinstance` or `type()` compared before a message is sent.251- A class that is neither `@final` nor written for extension.252253## Common mistakes254255- Believing the annotation of a `Protocol` checks anything at run time.256- Using `isinstance` against a `Protocol` without257 `@runtime_checkable`, so it raises `TypeError`.258- Believing a `@runtime_checkable` protocol compares method259 signatures.260- Freezing a dataclass and believing the list it holds is frozen too.261- Hashing a frozen dataclass whose field holds a list.262- Leaving a value's check in a factory, so `replace` skips it.263- Treating a leading underscore as privacy.264- Adding a setter to quiet a caller that assigns a field.265- Calling `super()` in a mixin without reading the instance's MRO.266- Writing `@final` and expecting a runtime error on subclassing.267268## Related skills269270- `oo-design` sizes a task and defines the rule labels.271- `oo-designing-interfaces` shapes a role around its caller.272- `oo-honouring-substitutability` says what every implementation of a273 role must keep.274- `oo-modeling-values-and-entities` decides whether a concept is a275 value or an entity, and what equality reads.276- `oo-constructing-valid-objects` makes a constructor refuse broken277 input.278- `oo-encapsulating-state-and-behaviour` keeps an invariant with the279 state it guards.280- `oo-choosing-composition-over-inheritance` decides when to hold an281 object instead of extending a class.282- `oo-javascript` shows how the same rules read in a language with no283 type checker.284285## Further reading286287- [Roles and mixins](references/roles-and-mixins.md)