Intermediate Examples

"""Example 29: A Read-Only Property."""
 
 
class Rectangle:  # => begins the Rectangle class body
    def __init__(
        self, width: float, height: float
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.width = width  # => stores width on this instance
        self.height = height  # => stores height on this instance
 
    @property  # => marks the next method as a computed attribute
    def area(
        self,
    ) -> float:  # => computed on every access -- never stored as its own field
        return (
            self.width * self.height
        )  # => always reflects the CURRENT width and height
 
 
r: Rectangle = Rectangle(3.0, 4.0)  # => constructs r
print(r.area)  # => read like a plain attribute -- no parentheses at the call site
# => Output: 12.0
# => `@property` on a method makes `obj.method_name` (no parentheses) call it

12.0

"""Example 29: pytest verification for A Read-Only Property."""
 
from example import Rectangle
 
 
def test_area_reads_as_plain_attribute() -> None:
    r: Rectangle = Rectangle(3.0, 4.0)
    assert r.area == 12.0  # => r.area, not r.area() -- property syntax, computed value
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 30: A Property Setter That Validates."""
 
 
class Rectangle:  # => begins the Rectangle class body
    def __init__(
        self, width: float, height: float
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.width = width  # => routes through the setter below, even during __init__
        self.height = height  # => stores height on this instance
 
    @property  # => marks the next method as a computed attribute
    def width(self) -> float:  # => defines the width() method
        return self._width  # => returns this value to the caller
 
    @width.setter  # => marks the next method as width's validating setter
    def width(
        self, value: float
    ) -> None:  # => every assignment to .width passes through here
        if value <= 0:  # => guards the invariant: a rectangle's width must be positive
            raise ValueError(
                "width must be positive"
            )  # => rejects the assignment entirely
        self._width = value  # => only reached when the value passed validation
 
 
r: Rectangle = Rectangle(3.0, 4.0)  # => constructs r
try:  # => the block below is expected to raise
    r.width = -1  # => triggers the guard above, ordinary attribute-assignment syntax
except ValueError as exc:  # => catches the ValueError raised above
    print(exc)  # => prints the exact rejection message
# => Output: width must be positive
# => `@width.setter` intercepts every `obj.width = value` assignment, including the one `__init__` performs

width must be positive

"""Example 30: pytest verification for A Property Setter That Validates."""
 
import pytest
 
from example import Rectangle
 
 
def test_negative_width_assignment_raises() -> None:
    r: Rectangle = Rectangle(3.0, 4.0)
    with pytest.raises(
        ValueError
    ):  # => r.width = -1 must raise, not silently accept it
        r.width = -1
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 31: A Property Backed by a Private Field."""
 
 
class Rectangle:  # => begins the Rectangle class body
    def __init__(
        self, width: float
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.width = (
            width  # => external code always uses THIS name, never _width directly
        )
 
    @property  # => marks the next method as a computed attribute
    def width(self) -> float:  # => defines the width() method
        return (
            self._width
        )  # => internally-named storage field, hidden behind the property
 
    @width.setter  # => marks the next method as width's validating setter
    def width(self, value: float) -> None:  # => defines the width() method
        self._width = value  # => the ONLY place _width is ever assigned
 
 
r: Rectangle = Rectangle(5.0)  # => constructs r
print(r.width)  # => external code never spells out ._width anywhere
# => Output: 5.0
print(
    hasattr(r, "_width")
)  # => the storage field exists, but is not the public interface
# => Output: True
# => A property's public name (`width`) and its private storage name (`_width`) can differ

5.0
True

"""Example 31: pytest verification for A Property Backed by a Private Field."""
 
from example import Rectangle
 
 
def test_external_code_reads_through_public_property() -> None:
    r: Rectangle = Rectangle(5.0)
    assert r.width == 5.0  # => callers use .width, never ._width, by convention
    assert r._width == 5.0  # => the private field genuinely backs the property
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 32: A Computed Property Derived from Two Fields."""
 
 
class Rectangle:  # => begins the Rectangle class body
    def __init__(
        self, width: float, height: float
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.width = width  # => stores width on this instance
        self.height = height  # => stores height on this instance
 
    @property  # => marks the next method as a computed attribute
    def perimeter(self) -> float:  # => recomputed from width/height every single access
        return 2 * (self.width + self.height)  # => returns this value to the caller
 
 
r: Rectangle = Rectangle(3.0, 4.0)  # => constructs r
print(r.perimeter)  # => baseline perimeter before mutating width below
# => Output: 14.0
r.width = 10.0  # => mutating a plain field the property depends on
print(r.perimeter)  # => perimeter reflects the NEW width -- nothing was cached
# => Output: 28.0
# => A property with no explicit cache always recomputes from its dependencies

14.0
28.0

"""Example 32: pytest verification for A Computed Property Derived from Two Fields."""
 
from example import Rectangle
 
 
def test_perimeter_updates_after_width_changes() -> None:
    r: Rectangle = Rectangle(3.0, 4.0)
    assert r.perimeter == 14.0
    r.width = 10.0  # => mutate the field the property is derived from
    assert (
        r.perimeter == 28.0
    )  # => the computed value tracks the mutation automatically
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 33: A Money Value Object with __eq__."""
 
 
class Money:  # => begins the Money class body
    def __init__(
        self, amount: int, currency: str
    ) -> None:  # => amount in integer cents
        self.amount = amount  # => stores amount on this instance
        self.currency = currency  # => stores currency on this instance
 
    def __eq__(self, other: object) -> bool:  # => defines the __eq__() method
        if not isinstance(other, Money):
            return NotImplemented  # => returns this value to the caller
        return (
            self.amount == other.amount and self.currency == other.currency
        )  # => returns this value to the caller
        # => equal ONLY when BOTH fields match -- a partial match is not equality
 
 
a: Money = Money(500, "USD")  # => constructs a
b: Money = Money(500, "USD")  # => same amount and currency, different object
c: Money = Money(500, "EUR")  # => same amount, DIFFERENT currency
print(a == b, a == c)  # => value equality on both fields together
# => Output: True False
# => A multi-field value object's `__eq__` must compare every field that participates in its value

True False

"""Example 33: pytest verification for A Money Value Object with __eq__."""
 
from example import Money
 
 
def test_equal_amount_and_currency_compare_equal() -> None:
    assert Money(500, "USD") == Money(500, "USD")
 
 
def test_matching_amount_different_currency_compares_unequal() -> None:
    assert Money(500, "USD") != Money(500, "EUR")  # => amount alone is not enough
 
 
# => Run: pytest -- Output: 2 passed

2 passed

"""Example 34: A Consistent __hash__ Alongside __eq__."""
 
 
class Money:  # => begins the Money class body
    def __init__(
        self, amount: int, currency: str
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.amount = amount  # => stores amount on this instance
        self.currency = currency  # => stores currency on this instance
 
    def __eq__(self, other: object) -> bool:  # => defines the __eq__() method
        if not isinstance(
            other, Money
        ):  # => guards against comparing a Money to an unrelated type
            return NotImplemented  # => returns this value to the caller
        return (
            self.amount == other.amount and self.currency == other.currency
        )  # => returns this value to the caller
 
    def __hash__(self) -> int:  # => MUST hash the SAME fields __eq__ compares
        return hash(
            (self.amount, self.currency)
        )  # => tuple hash -- combines both fields at once
 
 
wallet: set[Money] = {Money(500, "USD"), Money(500, "USD"), Money(100, "USD")}
# => two equal Money objects were inserted above; a correct hash/eq pair deduplicates them
print(len(wallet))  # => only 2 distinct (amount, currency) pairs survive
# => Output: 2
# => `hash((self.amount, self.currency))` combines the exact same fields `__eq__` compares into a single hash

2

"""Example 34: pytest verification for A Consistent __hash__ Alongside __eq__."""
 
from example import Money
 
 
def test_equal_money_objects_deduplicate_in_a_set() -> None:
    wallet: set[Money] = {Money(500, "USD"), Money(500, "USD"), Money(100, "USD")}
    assert len(wallet) == 2  # => the duplicate Money(500, "USD") collapses to one entry
 
 
def test_equal_objects_share_a_hash() -> None:
    assert hash(Money(500, "USD")) == hash(
        Money(500, "USD")
    )  # => required by the eq/hash contract
 
 
# => Run: pytest -- Output: 2 passed

2 passed

"""Example 35: __eq__ Without __hash__ Is Unhashable."""
 
 
class Money:  # => begins the Money class body
    def __init__(
        self, amount: int, currency: str
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.amount = amount  # => stores amount on this instance
        self.currency = currency  # => stores currency on this instance
 
    def __eq__(self, other: object) -> bool:  # => defining __eq__ ALONE
        if not isinstance(other, Money):
            return NotImplemented  # => returns this value to the caller
        return (
            self.amount == other.amount and self.currency == other.currency
        )  # => returns this value to the caller
 
    # => Python sets __hash__ = None automatically the moment __eq__ is defined without __hash__
 
 
try:  # => the block below is expected to raise
    {Money(500, "USD")}  # type: ignore  # => building a set calls hash() on each element (static checkers correctly flag Money as unhashable)
except TypeError as exc:  # => catches the TypeError raised above
    print(exc)  # => confirms the instance is genuinely unhashable
# => Output: unhashable type: 'Money'
# => Defining `__eq__` without `__hash__` does not silently inherit `object`'s default hash

unhashable type: 'Money'

"""Example 35: pytest verification for __eq__ Without __hash__ Is Unhashable."""
 
import pytest
 
from example import Money
 
 
def test_eq_only_class_is_unhashable() -> None:
    with pytest.raises(
        TypeError
    ):  # => hash(Money(...)) must raise, not silently succeed
        {Money(500, "USD")}  # type: ignore  # => set construction calls hash() internally (static checkers correctly flag Money as unhashable)
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 36: A Frozen Dataclass Rejects Field Assignment."""
 
from dataclasses import dataclass  # => imports dataclass from dataclasses
 
 
@dataclass(frozen=True)  # => frozen=True makes every field read-only after construction
class Point:  # => begins the Point class body
    x: int  # => a required dataclass field, part of the generated __init__
    y: int  # => a required dataclass field, part of the generated __init__
 
 
p: Point = Point(1, 2)  # => constructs p
try:  # => the block below is expected to raise
    p.x = 99  # type: ignore  # => assignment to a frozen field always raises (static checkers also flag it as read-only)
except (
    Exception
) as exc:  # => dataclasses.FrozenInstanceError, a subclass of AttributeError
    print(type(exc).__name__)  # => confirms the exact exception type raised
# => Output: FrozenInstanceError
# => `dataclasses.FrozenInstanceError` (a subclass of `AttributeError`) fires on every attempted field assignment after construction

FrozenInstanceError

"""Example 36: pytest verification for A Frozen Dataclass Rejects Field Assignment."""
 
import dataclasses
 
import pytest
 
from example import Point
 
 
def test_assigning_frozen_field_raises_frozen_instance_error() -> None:
    p: Point = Point(1, 2)
    with pytest.raises(
        dataclasses.FrozenInstanceError
    ):  # => the exact documented exception type
        p.x = 99  # type: ignore  # => static checkers also flag frozen-field assignment as an error
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 37: A Frozen Dataclass Is Hashable by Default."""
 
from dataclasses import dataclass  # => imports dataclass from dataclasses
 
 
@dataclass(
    frozen=True
)  # => frozen=True (with the default eq=True) auto-generates __hash__ too
class Point:  # => begins the Point class body
    x: int  # => a required dataclass field, part of the generated __init__
    y: int  # => a required dataclass field, part of the generated __init__
 
 
lookup: dict[Point, str] = {
    Point(1, 2): "origin-ish"
}  # => works as a dict key -- it is hashable
members: set[Point] = {
    Point(1, 2),
    Point(1, 2),
}  # => equal frozen instances deduplicate
print(
    lookup[Point(1, 2)], len(members)
)  # => a NEW equal Point still finds the same entry
# => Output: origin-ish 1
# => `@dataclass(frozen=True)` is the shortest path to a fully correct, hashable value object

origin-ish 1

"""Example 37: pytest verification for A Frozen Dataclass Is Hashable by Default."""
 
from example import Point
 
 
def test_frozen_dataclass_works_as_dict_key() -> None:
    lookup: dict[Point, str] = {Point(1, 2): "origin-ish"}
    assert (
        lookup[Point(1, 2)] == "origin-ish"
    )  # => a NEW, equal Point finds the same entry
 
 
def test_frozen_dataclass_deduplicates_in_a_set() -> None:
    members: set[Point] = {Point(1, 2), Point(1, 2)}
    assert len(members) == 1
 
 
# => Run: pytest -- Output: 2 passed

2 passed

"""Example 38: eq=False Falls Back to Identity Equality."""
 
from dataclasses import dataclass  # => imports dataclass from dataclasses
 
 
@dataclass(
    eq=False
)  # => suppresses the generated __eq__ entirely -- object's default is used
class Point:  # => begins the Point class body
    x: int  # => a required dataclass field, part of the generated __init__
    y: int  # => a required dataclass field, part of the generated __init__
 
 
a: Point = Point(1, 2)  # => constructs a
b: Point = Point(1, 2)  # => equal field values, but no __eq__ was generated
print(a == b, a == a)  # => identity is the only equality left: only a == a is True
# => Output: False True
# => `eq=False` is the escape hatch when a dataclass genuinely needs identity semantics

False True

"""Example 38: pytest verification for eq=False Falls Back to Identity Equality."""
 
from example import Point
 
 
def test_eq_false_disables_value_equality() -> None:
    a: Point = Point(1, 2)
    b: Point = Point(1, 2)
    assert a != b  # => no generated __eq__ -- falls back to identity, and a is not b
 
 
def test_eq_false_still_allows_self_equality() -> None:
    a: Point = Point(1, 2)
    assert a == a  # => identity comparison: an object always equals itself
 
 
# => Run: pytest -- Output: 2 passed

2 passed

"""Example 39: slots=True Drops Per-Instance __dict__."""
 
from dataclasses import dataclass  # => imports dataclass from dataclasses
 
 
@dataclass(
    slots=True
)  # => added in Python 3.10 -- generates __slots__ from the field list
class Point:  # => begins the Point class body
    x: int  # => a required dataclass field, part of the generated __init__
    y: int  # => a required dataclass field, part of the generated __init__
 
 
p: Point = Point(1, 2)  # => constructs p
print(hasattr(p, "__dict__"))  # => slots instances have NO per-instance __dict__ at all
# => Output: False
try:  # => the block below is expected to raise
    p.z = 3  # type: ignore  # => z was never declared as a field -- slots rejects undeclared attributes (static checkers flag it too)
except AttributeError as exc:  # => catches the AttributeError raised above
    print(type(exc).__name__)  # => confirms the exact exception type
# => Output: AttributeError
# => `slots=True` trades attribute flexibility for a smaller memory footprint per instance

False
AttributeError

"""Example 39: pytest verification for slots=True Drops Per-Instance __dict__."""
 
import pytest
 
from example import Point
 
 
def test_slots_instance_has_no_dict() -> None:
    p: Point = Point(1, 2)
    assert not hasattr(
        p, "__dict__"
    )  # => __slots__ replaces the usual per-instance __dict__
 
 
def test_undeclared_attribute_assignment_raises() -> None:
    p: Point = Point(1, 2)
    with pytest.raises(AttributeError):
        p.z = 3  # type: ignore  # => z is not a declared field -- slots rejects it outright
 
 
# => Run: pytest -- Output: 2 passed

2 passed

"""Example 40: order=True Adds Field-Tuple Comparisons."""
 
from dataclasses import dataclass  # => imports dataclass from dataclasses
 
 
@dataclass(order=True)  # => generates __lt__, __le__, __gt__, __ge__ from field ORDER
class Point:  # => begins the Point class body
    x: int  # => a required dataclass field, part of the generated __init__
    y: int  # => comparisons check x first, then y -- exactly like tuple comparison
 
 
points: list[Point] = [
    Point(2, 1),
    Point(1, 5),
    Point(1, 2),
]  # => deliberately out of order
points.sort()  # => sort() uses the generated __lt__ under the hood
print(points)  # => sorted by (x, y) as a tuple: (1,2) < (1,5) < (2,1)
# => Output: [Point(x=1, y=2), Point(x=1, y=5), Point(x=2, y=1)]
# => `order=True` makes instances directly sortable with `list.sort()` or `sorted()`

[Point(x=1, y=2), Point(x=1, y=5), Point(x=2, y=1)]

"""Example 40: pytest verification for order=True Adds Field-Tuple Comparisons."""
 
from example import Point
 
 
def test_instances_sort_by_field_tuple() -> None:
    points: list[Point] = [Point(2, 1), Point(1, 5), Point(1, 2)]
    points.sort()  # => uses the generated __lt__
    assert points == [Point(1, 2), Point(1, 5), Point(2, 1)]  # => (x, y) tuple order
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 41: A Subclass Inherits Fields and Methods."""
 
 
class Animal:  # => begins the Animal class body
    def __init__(
        self, name: str
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.name = name  # => defined ONCE, on the base class
 
 
class Cat(Animal):  # => Cat inherits EVERYTHING Animal defines, with no body of its own
    pass  # => an intentionally empty body
 
 
c: Cat = Cat(
    "Whiskers"
)  # => Animal.__init__ ran, even though Cat wrote no __init__ itself
print(c.name)  # => the inherited field, set by the inherited __init__
# => Output: Whiskers
# => A subclass with no `__init__` of its own falls back to the nearest ancestor's `__init__` automatically

Whiskers

"""Example 41: pytest verification for A Subclass Inherits Fields and Methods."""
 
from example import Cat
 
 
def test_subclass_inherits_base_init_field() -> None:
    c: Cat = Cat(
        "Whiskers"
    )  # => Cat has no __init__ of its own -- Animal's runs instead
    assert c.name == "Whiskers"
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 42: Chaining Construction with super().__init__()."""
 
 
class Animal:  # => begins the Animal class body
    def __init__(
        self, name: str
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.name = name  # => set by the BASE class's own __init__
 
 
class Cat(Animal):  # => Cat extends Animal
    def __init__(
        self, name: str, indoor: bool
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        super().__init__(name)  # => explicitly runs Animal.__init__ first
        self.indoor = indoor  # => THEN adds the subclass's own field
 
 
c: Cat = Cat("Whiskers", indoor=True)  # => constructs c
print(c.name, c.indoor)  # => both the base field and the subclass field are set
# => Output: Whiskers True
# => `super().__init__(...)` is how a subclass reuses the base class's construction logic instead of duplicating it

Whiskers True

"""Example 42: pytest verification for Chaining Construction with super().__init__()."""
 
from example import Cat
 
 
def test_super_init_sets_base_and_subclass_fields() -> None:
    c: Cat = Cat("Whiskers", indoor=True)
    assert c.name == "Whiskers"  # => set by Animal.__init__ via super()
    assert c.indoor is True  # => set by Cat.__init__ itself, after the super() call
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 43: Overriding a Method."""
 
 
class Animal:  # => begins the Animal class body
    def speak(self) -> str:  # => the base implementation
        return "..."  # => returns this value to the caller
 
 
class Cat(Animal):  # => Cat extends Animal
    def speak(self) -> str:  # => SAME name -- completely replaces the base version
        return "Meow"  # => returns this value to the caller
 
 
a: Animal = Animal()  # => constructs a
c: Cat = Cat()  # => constructs c
print(a.speak(), c.speak())  # => c.speak() runs Cat's version, not Animal's
# => Output: ... Meow
# => Defining a method with the same name as a base class method overrides it completely by default

... Meow

"""Example 43: pytest verification for Overriding a Method."""
 
from example import Animal, Cat
 
 
def test_subclass_override_replaces_base_behavior() -> None:
    assert Animal().speak() == "..."  # => the unmodified base behavior
    assert Cat().speak() == "Meow"  # => Cat's override runs instead of Animal's
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 44: Calling super() Inside an Override."""
 
 
class Animal:  # => begins the Animal class body
    def speak(self) -> str:  # => defines the speak() method
        return "..."  # => returns this value to the caller
 
 
class Cat(Animal):  # => Cat extends Animal
    def speak(self) -> str:  # => defines the speak() method
        base: str = (
            super().speak()
        )  # => explicitly invokes Animal's own implementation first
        return f"Meow (base said: {base})"  # => AUGMENTS the base result instead of discarding it
 
 
c: Cat = Cat()  # => constructs c
print(c.speak())  # => combines both the base and the override's own contribution
# => Output: Meow (base said: ...)
# => An override is not forced to choose between "replace entirely" (Example 43) and "reuse entirely" (Example 41)

Meow (base said: ...)

"""Example 44: pytest verification for Calling super() Inside an Override."""
 
from example import Cat
 
 
def test_override_combines_base_and_subclass_output() -> None:
    result: str = Cat().speak()
    assert "Meow" in result  # => the subclass's own contribution
    assert "..." in result  # => the base implementation's contribution, via super()
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 45: Polymorphic Dispatch Over a Mixed List."""
 
 
class Animal:  # => begins the Animal class body
    def speak(self) -> str:  # => defines the speak() method
        return "..."  # => returns this value to the caller
 
 
class Cat(Animal):  # => Cat extends Animal
    def speak(self) -> str:  # => defines the speak() method
        return "Meow"  # => returns this value to the caller
 
 
class Dog(Animal):  # => Dog extends Animal
    def speak(self) -> str:  # => defines the speak() method
        return "Woof"  # => returns this value to the caller
 
 
animals: list[Animal] = [
    Cat(),
    Dog(),
    Animal(),
]  # => ONE list, THREE different runtime types
sounds: list[str] = [
    a.speak() for a in animals
]  # => same .speak() call-site for every element
print(sounds)  # => each element dispatched to its OWN class's implementation
# => Output: ['Meow', 'Woof', '...']
# => `[a.speak() for a in animals]` never branches on `type(a)` anywhere

['Meow', 'Woof', '...']

"""Example 45: pytest verification for Polymorphic Dispatch Over a Mixed List."""
 
from example import Animal, Cat, Dog
 
 
def test_each_element_dispatches_to_its_own_override() -> None:
    animals: list[Animal] = [Cat(), Dog(), Animal()]
    sounds: list[str] = [
        a.speak() for a in animals
    ]  # => one shared call-site, three behaviors
    assert sounds == ["Meow", "Woof", "..."]
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 46: isinstance Across a Hierarchy."""
 
 
class Animal:  # => begins the Animal class body
    pass  # => an intentionally empty body
 
 
class Cat(Animal):  # => Cat extends Animal
    pass  # => an intentionally empty body
 
 
c: Cat = Cat()  # => constructs c
print(isinstance(c, Cat))  # => True: c's own, exact class
# => Output: True
print(
    isinstance(c, Animal)
)  # => ALSO True: isinstance checks the WHOLE hierarchy, not exact type
# => Output: True
# => `isinstance` answers "is this object a Cat, or anything that IS-A Cat's ancestor"

True
True

"""Example 46: pytest verification for isinstance Across a Hierarchy."""
 
from example import Animal, Cat
 
 
def test_isinstance_holds_across_the_hierarchy() -> None:
    c: Cat = Cat()
    assert isinstance(c, Cat)  # => matches its own, exact class
    assert isinstance(c, Animal)  # => ALSO matches every ancestor class
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 47: A classmethod Alternative Constructor."""
 
from __future__ import (
    annotations,
)  # => lets "Date" be used as a forward-referenced return type
 
 
class Date:  # => begins the Date class body
    def __init__(
        self, year: int, month: int, day: int
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.year = year  # => stores year on this instance
        self.month = month  # => stores month on this instance
        self.day = day  # => stores day on this instance
 
    @classmethod  # => marks the next method as receiving cls, not self
    def from_string(
        cls, s: str
    ) -> Date:  # => cls is the Date class itself, passed automatically
        year_s, month_s, day_s = s.split(
            "-"
        )  # => parses "YYYY-MM-DD" into three string pieces
        return cls(
            int(year_s), int(month_s), int(day_s)
        )  # => builds an instance via cls(...)
 
 
d: Date = Date.from_string(
    "2026-07-14"
)  # => an alternative entry point beside Date(...)
print(
    d.year, d.month, d.day
)  # => confirms the parsed pieces landed in the right fields
# => Output: 2026 7 14
# => `@classmethod` alternative constructors give a class more than one named entry point

2026 7 14

"""Example 47: pytest verification for A classmethod Alternative Constructor."""
 
from example import Date
 
 
def test_from_string_builds_instance_from_parsed_text() -> None:
    d: Date = Date.from_string("2026-07-14")
    assert (d.year, d.month, d.day) == (
        2026,
        7,
        14,
    )  # => parsed pieces landed in the right fields
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 48: A staticmethod Namespaced Utility."""
 
 
class Date:  # => begins the Date class body
    @staticmethod  # => marks the next method as needing neither self nor cls
    def is_leap(
        year: int,
    ) -> bool:  # => neither self nor cls -- an ordinary function in a namespace
        return year % 4 == 0 and (
            year % 100 != 0 or year % 400 == 0
        )  # => returns this value to the caller
 
 
print(
    Date.is_leap(2024)
)  # => callable directly on the class -- no instance needed anywhere
# => Output: True
print(Date.is_leap(1900))  # => divisible by 100 but not 400 -- not a leap year
# => Output: False
# => `Date.is_leap(year)` never touches `self` or `cls`

True
False

"""Example 48: pytest verification for A staticmethod Namespaced Utility."""
 
from example import Date
 
 
def test_staticmethod_callable_without_an_instance() -> None:
    assert (
        Date.is_leap(2024) is True
    )  # => called on the class itself, no Date(...) constructed
    assert Date.is_leap(1900) is False  # => the century-not-divisible-by-400 exception
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 49: A classmethod Factory Returns the Subclass Type."""
 
from typing import TypeVar  # => imports TypeVar from typing
 
# => bound="Animal" ties T to Animal or any of its subclasses
T = TypeVar(
    "T", bound="Animal"
)  # => T stands for "whatever concrete subclass calls create()"
 
 
class Animal:  # => begins the Animal class body
    @classmethod  # => marks the next method as receiving cls, not self
    def create(
        cls: type[T],
    ) -> T:  # => cls: type[T] lets the return type track the CALLING class
        return cls()  # => NOT "return Animal()" -- cls() adapts to the calling subclass
 
 
class Cat(Animal):  # => Cat extends Animal
    pass  # => an intentionally empty body
 
 
a: Animal = Animal.create()  # => cls is Animal here, so T resolves to Animal
c: Cat = Cat.create()  # => cls is Cat here -- the SAME method body, T resolves to Cat
print(type(a).__name__, type(c).__name__)  # => each call returned its OWN calling class
# => Output: Animal Cat
# => `cls()` inside a `@classmethod` resolves to whatever class the method was called through

Animal Cat

"""Example 49: pytest verification for A classmethod Factory Returns the Subclass Type."""
 
from example import Animal, Cat
 
 
def test_classmethod_factory_returns_calling_subclass() -> None:
    assert type(Animal.create()) is Animal  # => called on Animal -- cls is Animal
    assert type(Cat.create()) is Cat  # => called on Cat -- cls is Cat, same method body
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 50: A Class-Attribute Instance Counter."""
 
 
class Dog:  # => begins the Dog class body
    population: int = 0  # => ONE shared counter, living on the class, not any instance
 
    def __init__(
        self, name: str
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.name = name  # => stores name on this instance
        Dog.population += (
            1  # => mutates the CLASS attribute -- every instance sees the update
        )
 
 
Dog("Rex")  # => constructs one Dog, incrementing Dog.population to 1
Dog("Fido")  # => constructs a second Dog, incrementing Dog.population to 2
Dog("Max")  # => constructs a third Dog, incrementing Dog.population to 3
print(Dog.population)  # => reflects the total number of Dog() calls made so far
# => Output: 3
# => `Dog.population += 1` (mutating through the class name) updates the ONE shared counter every instance reads

3

"""Example 50: pytest verification for A Class-Attribute Instance Counter."""
 
from example import Dog
 
 
def test_population_counts_every_constructed_instance() -> None:
    before: int = (
        Dog.population
    )  # => baseline, in case another test constructed Dogs first
    Dog("Rex")
    Dog("Fido")
    Dog("Max")
    assert Dog.population == before + 3  # => exactly three more instances were created
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 51: The Mutable Class-Attribute Pitfall, Reproduced and Fixed."""
 
 
class BuggyCart:  # => begins the BuggyCart class body
    items: list[
        str
    ] = []  # => BUG: declared on the CLASS -- ONE list shared by every instance
 
    def add(self, item: str) -> None:  # => defines the add() method
        self.items.append(
            item
        )  # => looks like instance state, but mutates the SHARED list
 
 
class Cart:  # => begins the Cart class body
    def __init__(
        self,
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.items: list[
            str
        ] = []  # => FIX: a fresh list is created INSIDE __init__, per instance
 
    def add(self, item: str) -> None:  # => defines the add() method
        self.items.append(
            item
        )  # => now genuinely mutates only THIS instance's own list
 
 
if (
    __name__ == "__main__"
):  # => guards the demo so IMPORTING this module (for pytest) stays side-effect-free
    buggy_a, buggy_b = (
        BuggyCart(),
        BuggyCart(),
    )  # => two "separate" carts sharing one class list
    buggy_a.add(
        "apple"
    )  # => appends to the class-level list every BuggyCart instance sees
    print(buggy_b.items)  # => the bug: buggy_b sees buggy_a's item too
    # => Output: ['apple']
 
    fixed_a, fixed_b = (
        Cart(),
        Cart(),
    )  # => two GENUINELY separate carts, each with its own list
    fixed_a.add("apple")  # => appends to fixed_a's own list only
    print(fixed_b.items)  # => the fix: fixed_b's own list stays empty
    # => Output: []
    # => `items: list[str] = []` in the class body creates ONE list shared by every instance forever

['apple']
[]

"""Example 51: pytest verification for The Mutable Class-Attribute Pitfall."""
 
from example import BuggyCart, Cart
 
 
def test_buggy_cart_shares_state_across_instances() -> None:
    a, b = BuggyCart(), BuggyCart()
    a.add("apple")
    assert b.items == [
        "apple"
    ]  # => reproduces the bug: b sees a's item through the shared list
 
 
def test_fixed_cart_isolates_state_per_instance() -> None:
    a, b = Cart(), Cart()
    a.add("apple")
    assert b.items == []  # => the fix: each instance's __init__ built its own list
 
 
# => Run: pytest -- Output: 2 passed

2 passed

"""Example 52: The Same Invariant Enforced in __init__ and a Setter."""
 
 
class Percentage:  # => begins the Percentage class body
    def __init__(
        self, value: float
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.value = (
            value  # => routes through the setter below -- validated on construction too
        )
 
    @property  # => marks the next method as a computed attribute
    def value(self) -> float:  # => defines the value() method
        return self._value  # => returns this value to the caller
 
    @value.setter  # => marks the next method as value's validating setter
    def value(
        self, v: float
    ) -> None:  # => the ONE place the 0-100 invariant is actually checked
        if not (
            0 <= v <= 100
        ):  # => guards the invariant on every assignment, not just __init__
            raise ValueError(
                "value must be between 0 and 100"
            )  # => rejects the whole assignment
        self._value = v  # => stores _value on this instance
 
 
try:  # => the block below is expected to raise
    Percentage(
        150
    )  # => rejected by __init__, because __init__ assigns through the setter
except ValueError:  # => catches the ValueError raised above
    print(
        "constructor path rejected 150"
    )  # => proves the CONSTRUCTOR path enforces the invariant
# => Output: constructor path rejected 150
 
p: Percentage = Percentage(50)  # => constructs p
try:  # => the block below is expected to raise
    p.value = 150  # => rejected by the setter path too -- the SAME guard, reused
except ValueError:  # => catches the ValueError raised above
    print(
        "setter path rejected 150"
    )  # => proves the SETTER path enforces the SAME invariant
# => Output: setter path rejected 150
# => Writing the invariant check exactly once, inside the setter, covers both `__init__` and later assignments

constructor path rejected 150
setter path rejected 150

"""Example 52: pytest verification for The Same Invariant Enforced in __init__ and a Setter."""
 
import pytest
 
from example import Percentage
 
 
def test_constructor_path_rejects_out_of_range_value() -> None:
    with pytest.raises(ValueError):
        Percentage(
            150
        )  # => __init__ assigns through the property setter -- same guard fires
 
 
def test_setter_path_rejects_out_of_range_value() -> None:
    p: Percentage = Percentage(50)
    with pytest.raises(ValueError):
        p.value = 150  # => neither construction NOR later assignment can violate the invariant
 
 
# => Run: pytest -- Output: 2 passed

2 passed

"""Example 53: A __repr__ That Round-Trips Through eval()."""
 
 
class Point:  # => begins the Point class body
    def __init__(
        self, x: int, y: int
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.x = x  # => stores x on this instance
        self.y = y  # => stores y on this instance
 
    def __repr__(
        self,
    ) -> str:  # => shows the EXACT constructor call needed to rebuild this object
        return f"Point({self.x!r}, {self.y!r})"  # => returns this value to the caller
 
    def __eq__(
        self, other: object
    ) -> bool:  # => needed so eval(repr(obj)) == obj can be checked
        if not isinstance(
            other, Point
        ):  # => guards against comparing a Point to an unrelated type
            return NotImplemented  # => returns this value to the caller
        return (
            self.x == other.x and self.y == other.y
        )  # => returns this value to the caller
 
 
p: Point = Point(3, 4)  # => constructs p
rebuilt: Point = eval(
    repr(p)
)  # => literally re-executes the repr string as Python source
print(rebuilt == p)  # => the round-tripped object is equal to the original
# => Output: True
# => A repr shaped exactly like the constructor call (`Point(3, 4)`) is not just readable

True

"""Example 53: pytest verification for A __repr__ That Round-Trips Through eval()."""
 
from example import Point
 
 
def test_repr_round_trips_through_eval() -> None:
    p: Point = Point(3, 4)
    rebuilt: Point = eval(repr(p))  # => reconstructs a Point from its own repr() string
    assert rebuilt == p  # => the reconstructed object is equal to the original
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 54: Exposing a Read-Only View of an Internal Collection."""
 
 
class Playlist:  # => begins the Playlist class body
    def __init__(
        self,
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self._songs: list[
            str
        ] = []  # => internal, mutable storage -- never handed out directly
 
    def add(self, song: str) -> None:  # => defines the add() method
        self._songs.append(song)  # => the ONLY sanctioned way to grow the internal list
 
    @property  # => marks the next method as a computed attribute
    def songs(
        self,
    ) -> tuple[str, ...]:  # => returns an IMMUTABLE copy, not the internal list itself
        return tuple(
            self._songs
        )  # => a tuple cannot be appended to -- mutation cannot leak back
 
 
p: Playlist = Playlist()  # => constructs p
p.add("Song A")
view: tuple[str, ...] = p.songs  # => a snapshot copy, not a reference to _songs
print(view)  # => shows the current contents
# => Output: ('Song A',)
p.add("Song B")  # => mutates the internal list AFTER the view was taken
print(
    view, p.songs
)  # => the old view is frozen; a fresh .songs call reflects the new song
# => Output: ('Song A',) ('Song A', 'Song B')
# => `tuple(self._songs)` builds a genuinely separate, immutable copy on every access

('Song A',)
('Song A',) ('Song A', 'Song B')

"""Example 54: pytest verification for Exposing a Read-Only View of an Internal Collection."""
 
from example import Playlist
 
 
def test_returned_view_is_a_tuple_not_the_internal_list() -> None:
    p: Playlist = Playlist()
    p.add("Song A")
    view: tuple[str, ...] = p.songs
    assert view == ("Song A",)
    assert not hasattr(
        view, "append"
    )  # => a tuple has no mutating methods -- callers cannot leak in
 
 
def test_mutating_the_playlist_does_not_retroactively_change_a_taken_view() -> None:
    p: Playlist = Playlist()
    p.add("Song A")
    view: tuple[str, ...] = p.songs  # => a frozen snapshot at THIS point in time
    p.add("Song B")  # => mutates internal state after the snapshot was taken
    assert view == ("Song A",)  # => the old snapshot is untouched
    assert p.songs == ("Song A", "Song B")  # => a fresh call reflects the current state
 
 
# => Run: pytest -- Output: 2 passed

2 passed

"""Example 55: A Duck-Typed Function Over Mixed Types."""
 
from typing import Iterable  # => imports Iterable from typing
 
 
class Circle:  # => begins the Circle class body
    def __init__(
        self, radius: float
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.radius = radius  # => stores radius on this instance
 
    def area(self) -> float:  # => defines the area() method
        return 3.14159 * self.radius**2  # => returns this value to the caller
 
 
class Square:  # => begins the Square class body
    def __init__(
        self, side: float
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.side = side  # => stores side on this instance
 
    def area(self) -> float:  # => defines the area() method
        return self.side**2  # => returns this value to the caller
 
 
def total_area(
    shapes: Iterable[object],
) -> float:  # => accepts ANY iterable of area()-having objects
    return sum(shape.area() for shape in shapes)  # type: ignore
    # => duck typing: only .area() is required, not a shared base class
 
 
shapes: list[object] = [
    Circle(1.0),
    Square(2.0),
    Circle(2.0),
]  # => two unrelated types, mixed
print(
    round(total_area(shapes), 5)
)  # => sums every shape's own area formula in one pass
# => Output: 19.70795
# => `total_area` never imports or checks `Circle`/`Square` at all

19.70795

"""Example 55: pytest verification for A Duck-Typed Function Over Mixed Types."""
 
from example import Circle, Square, total_area
 
 
def test_mixed_unrelated_types_sum_correctly() -> None:
    shapes: list[object] = [Circle(1.0), Square(2.0), Circle(2.0)]
    assert (
        round(total_area(shapes), 5) == 19.70795
    )  # => 3.14159 + 4.0 + 12.56636 (rounded)
 
 
# => Run: pytest -- Output: 1 passed

1 passed

"""Example 56: typing.Protocol Formalizes Duck Typing."""
 
from typing import (
    Protocol,
    runtime_checkable,
)  # => imports Protocol, runtime_checkable from typing
 
 
@runtime_checkable  # => opts this Protocol into isinstance() checks at runtime, not just static
class HasArea(
    Protocol
):  # => a STRUCTURAL type: "anything with an area() -> float method"
    def area(
        self,
    ) -> float: ...  # => no implementation -- just the shape of the contract
 
 
class Circle:  # => NEVER declares `class Circle(HasArea)` -- no inheritance link at all
    def __init__(
        self, radius: float
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.radius = radius  # => stores radius on this instance
 
    def area(
        self,
    ) -> float:  # => satisfies HasArea purely by having this exact method shape
        return 3.14159 * self.radius**2  # => returns this value to the caller
 
 
def describe(
    shape: HasArea,
) -> str:  # => type-hinted against the PROTOCOL, not a concrete class
    return f"area is {shape.area()}"  # => returns this value to the caller
 
 
print(
    describe(Circle(2.0))
)  # => a static checker accepts this with zero inheritance declared
# => Output: area is 12.56636
print(
    isinstance(Circle(2.0), HasArea)
)  # => @runtime_checkable makes THIS check work too
# => Output: True
# => `Protocol` gives duck typing a name a static checker can verify ahead of time

area is 12.56636
True

"""Example 56: pytest verification for typing.Protocol Formalizes Duck Typing."""
 
from example import Circle, HasArea
 
 
def test_class_satisfies_protocol_without_inheriting() -> None:
    circle: Circle = Circle(2.0)
    assert isinstance(
        circle, HasArea
    )  # => structural match, with no `class Circle(HasArea)` anywhere
 
 
def test_class_bases_do_not_mention_the_protocol() -> None:
    assert (
        HasArea not in Circle.__bases__
    )  # => confirms there is genuinely no inheritance link
 
 
# => Run: pytest -- Output: 2 passed

2 passed

"""Example 57: A Type-Strict __eq__ Across a Subclass."""
 
 
class Money:  # => begins the Money class body
    def __init__(
        self, amount: int
    ) -> None:  # => the constructor -- runs once, automatically, per instantiation
        self.amount = amount  # => stores amount on this instance
 
    def __eq__(self, other: object) -> bool:  # => defines the __eq__() method
        if type(other) is not type(
            self
        ):  # => STRICT: exact type match, not isinstance()
            return NotImplemented  # => a subclass instance is deliberately never equal to a Money
        return self.amount == other.amount  # type: ignore
 
 
class Cash(Money):  # => a subclass adding no new fields, just a different TYPE
    pass  # => an intentionally empty body
 
 
m: Money = Money(500)  # => constructs m
c: Cash = Cash(500)  # => same amount, but a DIFFERENT exact type than Money
print(m == c)  # => the type-strict contract: equal amount is not enough across types
# => Output: False
# => `type(other) is not type(self)` is a stricter equality contract than `isinstance(other, Money)`

False

"""Example 57: pytest verification for A Type-Strict __eq__ Across a Subclass."""
 
from example import Cash, Money
 
 
def test_type_strict_eq_rejects_cross_subclass_comparison() -> None:
    m: Money = Money(500)
    c: Cash = Cash(500)  # => same amount, different exact type
    assert m != c  # => the chosen (type-strict) contract holds
 
 
def test_same_exact_type_still_compares_by_value() -> None:
    assert Money(500) == Money(500)  # => same exact type, same amount -- equal
 
 
# => Run: pytest -- Output: 2 passed

2 passed

"""Example 58: A Dataclass Subclassing Another Dataclass."""
 
from dataclasses import dataclass  # => imports dataclass from dataclasses
 
 
@dataclass  # => generates boilerplate methods from the field list below
class Vehicle:  # => begins the Vehicle class body
    make: str  # => a required dataclass field, part of the generated __init__
    model: str  # => a required dataclass field, part of the generated __init__
 
 
@dataclass  # => generates boilerplate methods from the field list below
class Car(Vehicle):  # => inherits make/model, adds its OWN field after them
    doors: int = (
        4  # => new fields must come AFTER inherited fields in the generated __init__
    )
 
 
c: Car = Car(
    "Toyota", "Corolla", doors=4
)  # => positional order: make, model, THEN doors
print(
    c.make, c.model, c.doors
)  # => confirms all three fields, from both classes, are set
# => Output: Toyota Corolla 4
# => `@dataclass` inheritance concatenates field lists, base class first, subclass second

Toyota Corolla 4

"""Example 58: pytest verification for A Dataclass Subclassing Another Dataclass."""
 
from example import Car
 
 
def test_combined_init_field_order_is_base_then_subclass() -> None:
    c: Car = Car(
        "Toyota", "Corolla", doors=4
    )  # => positional: make, model (base), doors (subclass)
    assert (c.make, c.model, c.doors) == ("Toyota", "Corolla", 4)
 
 
# => Run: pytest -- Output: 1 passed

1 passed