Overview

It constructs a new instance -- the class acts as a factory, and __init__ runs automatically as part of that construction, assigning onto self to give the new object its own state. The smallest proof is type(d) is Dog: confirming the built object's exact type is the class that constructed it (Example 1).

Uncontrolled field access lets any code path set account.balance = -50 directly if the field is public and unguarded. Routing every mutation through a method turns "balance never goes negative" into a rule the class itself enforces in one place, rather than a convention every caller must remember (Examples 15-17).

is compares object identity (the same address in memory); == compares value, via __eq__. Two separately constructed Dog("Rex") objects are never is each other, and are only == each other once the class defines what "equal" means -- before that, == silently falls back to identity too (Examples 10-12).

__repr__ gives an unambiguous, developer-facing string (ideally one that round-trips through eval()); __str__ gives a readable, end-user-facing string. print() calls str(), which prefers __str__ when defined and falls back to __repr__ when it is not (Examples 8-9, 53).

Python sets __hash__ = None automatically, making every instance unhashable -- attempting to place one in a set or use it as a dict key raises TypeError (Example 35). Sets and dicts rely on hash() to bucket objects before __eq__ ever runs a comparison, so a class overriding equality that still wants to live inside a set must define a consistent __hash__ explicitly too (Example 34).

frozen=True makes every field read-only after construction and (with the default eq=True) auto-generates a __hash__; slots=True (Python 3.10+) drops the per-instance __dict__, rejecting undeclared attribute assignment; order=True adds __lt__/__le__/__gt__/__ge__ for tuple-style comparisons. field(default_factory=...) is a fourth worth knowing: it gives a fresh mutable default per instance instead of one shared object (Examples 20-25, 36, 39, 40).

@property exposes a computed or guarded value through ordinary attribute syntax (obj.attr, never obj.attr()), and a matching setter enforces invariants on assignment. Because the external syntax never changes, a class can grow from a stored field into a validated or computed one with zero changes at any call-site (Examples 29-32).

super().__init__(...) calls the base class's constructor from inside the subclass's own __init__, chaining base and subclass construction into one call. isinstance(cat, Animal) is True for every Cat instance, regardless of how many subclassing levels separate Cat from Animal (Examples 41, 42, 46).

The subclass's method completely shadows the base implementation -- overriding is Python's default, with no explicit keyword required. To augment rather than fully replace the base behavior, the override calls super().method_name() explicitly inside its own body (Examples 43-44).

Each element's own class's .speak() implementation, decided entirely by that object's runtime type -- one call-site, one method name, a different method body per element. This is what lets a new subclass plug in later with zero changes to the loop itself (Example 45).

Instantiation raises TypeError immediately, at construction time -- not the first time the missing method is actually called. This is a much tighter feedback loop than a plain base class with an unimplemented method, which only fails whenever that method happens to be invoked (Examples 59-60).

Purely by the methods the argument actually has -- a function calling .area() accepts any object exposing an .area() method, regardless of its declared base class (Example 26). typing.Protocol formalizes that exact structural contract so a static checker (pyright) can verify it ahead of runtime, with @runtime_checkable additionally enabling isinstance() checks against it (Example 56).

Subclassing list inherits every list method, including insert(), which a stack was never meant to expose -- s.insert(0, 99) breaks the "push/pop at one end only" guarantee (Example 65). The fix holds a list as a private collaborator (self._items) instead of subclassing it, exposing only push/pop/peek -- insert simply does not exist on the refactored class (Example 66).

Declaring items: list[str] = [] directly on the class body creates ONE list shared by every instance -- mutating it through one instance is visible through every other instance of the same class. The fix moves the list literal inside __init__ (self.items: list[str] = []), so every instance genuinely gets its own fresh list (Example 51).

@classmethod receives cls -- whichever class the method was actually called on -- while @staticmethod receives neither self nor cls, behaving as a plain namespaced function. Only @classmethod can build cls() instead of hardcoding a class name, which is what lets a factory method return the calling subclass's own type automatically (Examples 47-49).

A single underscore (_balance) is a convention only -- external code can still reach it, but doing so is a documented violation of the class's contract. A double underscore (__pin) triggers Python's name mangling, rewriting the attribute to _ClassName__pin internally -- the unmangled name genuinely does not exist and raises AttributeError if accessed directly from outside the class (Examples 18-19).

If a later setter or mutating method can still push the object past the same boundary, the invariant only held "at construction time," not always -- every path that changes state needs the identical check (Examples 16-17, 52, 71, 77). A property-based test throws hundreds of randomized inputs (rather than a couple of hand-picked edge cases) at the same invariant, which is a meaningfully stronger claim that no input reaches an invalid state (Example 80).

Nothing extra is needed -- this is exactly what instance attributes already guarantee: every Dog(...) call runs __init__ fresh, assigning self.name onto that one object's own namespace. Looping over a list[Dog] and reading .name off each element never risks cross-contamination, because no instance attribute is ever shared unless explicitly declared on the class instead (Examples 5, 27).

Define __repr__ to return the constructor-call form (e.g. f"Point(x={self.x}, y={self.y})"). print() uses str(), which falls back to __repr__ when __str__ is absent, and a repr shaped like the constructor call is directly paste-able back into a REPL to reproduce the object (Examples 8, 53).

Define __eq__ comparing the relevant fields (Example 12), or use @dataclass, which auto-generates __eq__ from the declared fields with no hand-written code needed at all (Example 22) -- the dataclass version can never silently drift out of sync with the fields the way a hand-written __eq__ risks after a field is added later.

field(default_factory=list), not = [] directly on the field. Unlike a plain class body, @dataclass actually raises ValueError at class-definition time if you try a mutable default directly -- the default_factory calls its callable fresh for every new instance, giving each one its own list (Example 24).

@property on an area method -- it computes the value fresh on every access, so it is structurally impossible for it to go stale relative to width/height (Example 32). A plain stored field would need to be manually recomputed on every resize; a computed property cannot forget.

Cat.__init__ calls super().__init__(name) first (chaining into Animal's constructor), then sets its own additional field (self.breed = breed) afterward. This reuses Animal's logic exactly once rather than copy-pasting it into Cat (Examples 42, 44).

Duck typing alone (Example 26) makes this work at runtime with zero declared relationship between Circle and Square. typing.Protocol (Example 56) formalizes the exact same contract (class HasArea(Protocol): def area(self) -> float: ...) so pyright can verify describe's argument is safe ahead of time, without either shape class declaring any inheritance from the protocol at all.

@classmethod for from_string (it needs cls to build and return the actual Date); @staticmethod for is_leap (it is a plain function that only happens to live inside Date's namespace for organizational purposes, needing neither self nor cls) (Examples 47-48).

Define Shape as an abc.ABC with an abstract area() method, and type total_area's parameter against Shape (or, more loosely, against duck typing). Every concrete implementation is forced to supply area() at construction time (Examples 59-60), and the call-site dispatches polymorphically to whichever implementation it receives (Examples 61-62) -- a brand-new subclass plugs in with zero edits to total_area.

Inject the collaborator through the constructor, typed against an interface rather than a concrete class (def __init__(self, logger: SupportsLog) -> None: self.logger = logger). A test passes a fake implementing the same structural contract, and Service never needs to know or care that it received a fake instead of the real Logger (Examples 67-70).

__init_subclass__ on the base class, fired automatically by Python at every subclass's class-definition time, not at instantiation. Shape.registry[cls.__name__] = cls inside it registers every subclass with zero code required in Circle or Square themselves (Example 78) -- the same mechanism a full domain model (Example 79) and a property-based invariant test (Example 80) both build on top of.

class Cart:
    def __init__(self) -> None:
        # THE FIX: build the list INSIDE __init__, not on the class body.
        self.items: list[str] = []  # => a genuinely fresh list, per instance
 
    def add(self, item: str) -> None:
        self.items.append(item)  # => now mutates only THIS instance's own list
 
 
a = Cart()
b = Cart()
a.add("apple")
print(b.items)  # => b never saw a's item -- Output: []

Root cause: items: list[str] = [] on the class body evaluates the [] literal exactly once, at class-definition time -- every instance that never explicitly shadows it shares that one list object. Building the list inside __init__ guarantees a fresh object per instance.

Run: python3 kata.py

Output:

[]

class Point:
    def __init__(self, x: int, y: int) -> None:
        self.x = x
        self.y = y
 
    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Point):
            return NotImplemented
        return self.x == other.x and self.y == other.y
 
    # THE FIX: a __hash__ CONSISTENT with __eq__ -- equal objects must hash equal.
    def __hash__(self) -> int:
        return hash((self.x, self.y))  # => the same tuple-of-fields the eq comparison uses
 
 
points = {Point(1, 2), Point(1, 2)}  # => now hashable -- two equal Points dedupe to one
print(len(points))  # => Output: 1

Root cause: defining __eq__ alone tells Python "this class has custom equality," and Python's data model responds by disabling the default identity-based __hash__ entirely, since a class that redefines equality has almost certainly broken the default hash's consistency guarantee too. Adding an explicit __hash__ derived from the same fields __eq__ compares restores the contract.

Run: python3 kata.py

Output:

1

def move_right(p: Point) -> Point:
    # THE FIX: return a brand-new, still-frozen Point -- never mutate the input.
    return Point(p.x + 1, p.y)  # => a fresh instance, the original p is untouched
 
 
p = Point(1, 2)
p = move_right(p)  # => rebinds the NAME p to the new instance
print(p)  # => Output: Point(x=2, y=2)

Root cause: frozen=True makes every field read-only after __init__ completes -- any later p.x = ... raises dataclasses.FrozenInstanceError, a subclass of AttributeError, regardless of where the assignment happens. The fix embraces immutability: build and return a new instance instead of trying to change the existing one.

Run: python3 kata.py

Output:

Point(x=2, y=2)

class Square(Shape):
    def __init__(self, side: float) -> None:
        self.side = side
 
    # THE FIX: implement every abstract method the base class declares.
    def area(self) -> float:
        return self.side**2  # => now a COMPLETE Shape -- instantiation succeeds
 
 
s = Square(3.0)
print(s.area())  # => Output: 9.0

Root cause: abc.ABC plus @abstractmethod makes instantiation itself the enforcement point -- Python raises TypeError the moment Square(3.0) runs, listing exactly which abstract method is still missing, rather than waiting for the first call to .area() to fail somewhere else entirely.

Run: python3 kata.py

Output:

9.0

class Stack:
    def __init__(self) -> None:
        # THE FIX: HOLD a list as a private collaborator instead of subclassing list.
        self._items: list[int] = []
 
    def push(self, item: int) -> None:
        self._items.append(item)
 
    def pop_top(self) -> int:
        return self._items.pop()
 
 
s = Stack()
s.push(1)
s.push(2)
print(s._items)  # => Output: [1, 2]
print(hasattr(s, "insert"))  # => Output: False -- the leak is simply gone

Root cause: class Stack(list[int]) is-a list, inheriting every list method whether wanted or not. Composition (self._items: list[int] = []) makes the relationship has-a instead: the class chooses exactly which operations to re-expose (push/pop_top), and everything else the underlying list can do stays private.

Run: python3 kata.py

Output:

[1, 2]
False

class Wallet:
    def __init__(self, pin: str) -> None:
        self.__pin = pin
 
    # THE FIX: expose a sanctioned METHOD instead of reaching for the mangled field directly.
    def check_pin(self, guess: str) -> bool:
        return guess == self.__pin  # => inside the class, __pin still reads normally
 
 
w = Wallet("1234")
print(w.check_pin("1234"))  # => Output: True

Root cause: self.__pin inside the class body is silently rewritten by Python to self._Wallet__pin -- the literal name __pin genuinely does not exist as an attribute on the instance from outside the class. The fix is not to reach for the mangled spelling; it is to expose a method the class itself controls.

Run: python3 kata.py

Output:

True

class Temperature:
    def __init__(self, celsius: float) -> None:
        self.celsius = celsius  # even the constructor routes through the property setter
 
    @property
    def celsius(self) -> float:
        return self._celsius
 
    @celsius.setter
    def celsius(self, value: float) -> None:
        # THE FIX: the SAME guard, now enforced on every assignment, not just construction.
        if value < -273.15:
            raise ValueError("below absolute zero")
        self._celsius = value
 
 
t = Temperature(20.0)
try:
    t.celsius = -300.0  # => now routes through the setter -- the guard fires here too
except ValueError as exc:
    print(exc)  # => Output: below absolute zero

Root cause: checking an invariant only inside __init__ only protects the moment of construction -- any later direct attribute assignment bypasses that check entirely. Moving the same guard into a @property setter makes every assignment, including the one inside __init__ itself, go through the identical validation.

Run: python3 kata.py

Output:

below absolute zero

from typing import TypeVar
 
T = TypeVar("T", bound="Animal")
 
 
class Animal:
    @classmethod
    # THE FIX: cls() instead of a hardcoded Animal() -- cls IS whichever class this ran on.
    def create(cls: type[T]) -> T:
        return cls()  # => builds THIS class, not always Animal
 
 
class Cat(Animal):
    pass
 
 
c = Cat.create()
print(type(c).__name__)  # => Output: Cat

Root cause: hardcoding the base class name inside a @classmethod throws away the exact piece of information cls exists to carry -- which class the method was actually called on. cls() always builds the calling class; Animal() always builds Animal, no matter which subclass called create().

Run: python3 kata.py

Output:

Cat

The eq/hash contract requires that two objects comparing equal must also hash equal -- otherwise a set or dict could hold two "equal" entries that a lookup can never find each other through, because they land in different hash buckets. The default, identity-based __hash__ hashes by object address, which is completely inconsistent with any custom __eq__ that compares by value: two distinct Money(500, "USD") objects would be == but hash differently. Rather than silently ship a broken contract, Python disables the default hash entirely the moment __eq__ is overridden, forcing the class author to either declare the type genuinely unhashable (by omission) or supply a consistent __hash__ explicitly (Example 34) -- which is exactly taming-state: making it structurally impossible for the eq/hash invariant to quietly drift out of sync.

Failing at the first actual call to a missing method means the bug surfaces far from where it was introduced -- potentially deep inside unrelated code, long after the incomplete class was defined. abc.ABC moves that feedback to the earliest possible moment: the instant Square(3.0) runs, Python already knows every abstract method the class was required to implement and can check the full list immediately, reporting exactly which one is missing (Example 60). This is a direct instance of taming-state applied to a class's own definition, not just its instance data: an incomplete Shape implementation is treated as an invalid state the type system itself refuses to let exist, rather than a runtime landmine waiting to be stepped on later.

Inheritance is an all-or-nothing relationship: Stack(list[int]) inherits every single method list defines, whether or not any of them make sense for a stack's contract. insert(0, 99) genuinely breaks the "push/pop at one end only" guarantee a stack promises, and there is no way to selectively un-inherit just that one method (Example 65). Composition (Example 66) trades a few extra lines of delegation for the ability to expose exactly the methods that belong, and none that don't -- this is coupling-vs-cohesion directly: the composed Stack is more narrowly coupled to list (only append/pop are ever called on it internally) and more cohesive as a type (every public method it exposes genuinely belongs to "being a stack").

Python's "we're all consenting adults" design philosophy deliberately trades compiler-enforced privacy for convention plus a narrower, more surgical mechanism: name mangling exists primarily to avoid accidental name collisions between a base class's private attribute and a subclass's own attribute of the same name, not to make an attribute truly unreachable from outside (Example 19). A single leading underscore (_balance) already communicates "internal, don't touch" to every reader; __pin's mangling adds one more layer specifically for the subclass-collision case, while still leaving obj._Wallet__pin technically reachable for a determined (and clearly rule-breaking) caller.

An invariant is a claim about every state the object can ever be in, not just the state it starts in. If a setter or a mutating method can push celsius below absolute zero after construction, the class never actually enforced "always valid" -- it enforced "valid at the one moment __init__ happened to run" (Kata 7). taming-state requires closing every path that changes state, not just the most obvious one: __init__, __post_init__, every property setter, and every method that mutates state all need the identical check (Examples 16-17, 30, 52, 71, 77), which is exactly why Example 80's property-based test throws hundreds of randomized inputs at the same invariant -- a couple of hand-picked test cases only prove the paths a test author happened to think of, not every path that actually exists.

cls is the one piece of information a @classmethod receives that a @staticmethod or a module-level function cannot: exactly which class the method was actually called on, whether that is Animal itself or some subclass like Cat several levels down (Examples 47, 49). Writing Animal() literally discards that information and always builds the same fixed class, no matter which subclass the method was invoked through (Kata 8) -- cls() is what makes a factory method genuinely subclass-aware, and it is the exact mechanism this topic's capstone payment methods rely on implicitly by never hardcoding a concrete class where an interface or cls would do instead.