Hands-on lab — Day 68: Inheritance, Composition, and Dunder Methods

"""Step 1: break inheritance on purpose, then fix it.

A subclass that defines __init__ REPLACES the parent's __init__. If it does
not call super().__init__(...), the parent's setup never runs. The object is
still created — it is just incomplete, and the failure surfaces later in some
unrelated method, blaming a missing attribute instead of the constructor that
never ran. That displacement is the whole point of this script.

Run it:  python3 examples/01_inheritance_super.py
"""

import traceback


class Appliance:
    """The base class. It owns `name` and `watts`."""

    def __init__(self, name, watts):
        self.name = name
        self.watts = watts

    def describe(self):
        return f"{self.name} ({self.watts}W)"


class BrokenOven(Appliance):
    """A two-level hierarchy with the super() call deliberately missing."""

    def __init__(self, name, watts, capacity_litres):
        # BUG ON PURPOSE: no super().__init__(name, watts) here, so `name`
        # and `watts` are never set on this instance.
        self.capacity_litres = capacity_litres

    def describe(self):
        # Extending: override, but still call the parent through super().
        return f"{super().describe()}, {self.capacity_litres}L"


class FixedOven(Appliance):
    """The same class with the one missing line restored."""

    def __init__(self, name, watts, capacity_litres):
        super().__init__(name, watts)  # THE FIX: run the parent's setup first
        self.capacity_litres = capacity_litres

    def describe(self):
        return f"{super().describe()}, {self.capacity_litres}L"


def main():
    print("-- broken: subclass __init__ never calls super().__init__() --")
    oven = BrokenOven("Deck oven", 3200, 60)
    # Note that construction SUCCEEDED. Nothing raised yet.
    print(f"constructed fine: {type(oven).__name__}, capacity_litres = "
          f"{oven.capacity_litres}")
    try:
        oven.describe()
    except AttributeError as err:
        # Print only the final line, so the output is stable across machines.
        print(f"AttributeError: {err}")
        print("    ^ raised inside describe(), NOT inside __init__ —")
        print("      the constructor left the object incomplete and moved on.")
        # The full traceback shows both frames; kept short on purpose.
        frames = traceback.format_exc().strip().splitlines()
        print(f"    (traceback frames: {sum(1 for f in frames if 'File ' in f)})")

    print()
    print("-- fixed: super().__init__(name, watts) restores the parent's setup --")
    fixed = FixedOven("Deck oven", 3200, 60)
    print(fixed.describe())
    print(f"attributes now present: name={fixed.name!r}, watts={fixed.watts}")
    print(f"MRO: {' -> '.join(c.__name__ for c in FixedOven.__mro__)}")


if __name__ == "__main__":
    main()

"""Step 2: predict the MRO of a diamond, then check yourself.

BEFORE RUNNING THIS, write your prediction down on paper.

The hierarchy is a diamond: ToasterOven inherits from Heater and Timer, and
both of those inherit from Appliance. C3 linearization gives exactly one
order, and it guarantees two things you can re-derive by hand:

  * local precedence — a class always comes before its own parents;
  * monotonicity     — the order bases are listed in is preserved.

So: start at ToasterOven. Bases are (Heater, Timer), so Heater is next.
Heater's parent is Appliance — but Appliance cannot come yet, because Timer
also inherits from it and Timer must precede its own parent. So Timer, then
Appliance, then object. Appliance appears ONCE, which is why it is never
initialised or run twice.

Run it:  python3 examples/02_mro_diamond.py
"""


class Appliance:
    def power_on(self):
        return "Appliance: power on"


class Heater(Appliance):
    def power_on(self):
        return "Heater: elements warming -> " + super().power_on()


class Timer(Appliance):
    def power_on(self):
        return "Timer: clock started -> " + super().power_on()


class ToasterOven(Heater, Timer):
    def power_on(self):
        return "ToasterOven: ready -> " + super().power_on()


def main():
    print(" -> ".join(cls.__name__ for cls in ToasterOven.__mro__))
    print(ToasterOven().power_on())
    print()

    # The payoff: super() is NOT "my parent". It is "the next class in THIS
    # instance's MRO". Heater does not inherit from Timer and has never heard
    # of it, yet Heater's super() call lands there.
    mro = [cls.__name__ for cls in ToasterOven.__mro__]
    after_heater = mro[mro.index("Heater") + 1]
    print(f"Heater's super() lands on: {after_heater}")
    print(f"Heater actually inherits from: "
          f"{[c.__name__ for c in Heater.__bases__]}")
    print(f"Appliance appears in the MRO {mro.count('Appliance')} time(s) — "
          f"never run twice.")

    # If no consistent order exists, Python refuses at class-definition time
    # rather than guessing. Here the bases are listed parent-before-child.
    print()
    try:
        type("Impossible", (Appliance, Heater), {})
    except TypeError as err:
        print(f"TypeError: {err}")


if __name__ == "__main__":
    main()

"""Step 3: the same domain modelled twice — inheritance, then composition.

Both halves of this file produce the SAME behaviour for an Oven and a
Toaster. Only the structure differs:

  inheritance   Oven IS-A HeatingAppliance IS-A Appliance.
                Behaviour arrives implicitly, found by walking the MRO.
                Fixed at class-definition time.

  composition   Oven HAS-A HeatingElement and HAS-A Timer.
                Behaviour is forwarded explicitly (delegation).
                Swappable at runtime.

After running this, write your comparison into starter/comparison.md.

Run it:  python3 examples/03_composition.py
"""


# ---------------------------------------------------------------- inheritance
class Appliance:
    def __init__(self, name, watts):
        self.name = name
        self.watts = watts

    def describe(self):
        return f"{self.name} ({self.watts}W)"


class HeatingAppliance(Appliance):
    def __init__(self, name, watts, max_celsius):
        super().__init__(name, watts)
        self.max_celsius = max_celsius

    def heat(self, celsius):
        if celsius > self.max_celsius:
            raise ValueError(f"{self.name} cannot exceed {self.max_celsius}C")
        return f"heating to {celsius}C at {self.watts}W"


class InheritedOven(HeatingAppliance):
    def __init__(self, name, watts, max_celsius, capacity_litres):
        super().__init__(name, watts, max_celsius)
        self.capacity_litres = capacity_litres

    def describe(self):  # extend, do not replace
        return f"{super().describe()}, {self.capacity_litres}L"


class InheritedToaster(HeatingAppliance):
    def __init__(self, name, watts, max_celsius, slots):
        super().__init__(name, watts, max_celsius)
        self.slots = slots


# ---------------------------------------------------------------- composition
class HeatingElement:
    """A collaborator. Knows how to heat, and nothing else."""

    def __init__(self, watts):
        self.watts = watts

    def heat(self, celsius):
        return f"heating to {celsius}C at {self.watts}W"


class Timer:
    """A second collaborator, entirely independent of the first."""

    def __init__(self):
        self.minutes = 0

    def set(self, minutes):
        self.minutes = minutes
        return f"timer set to {minutes} min"


class FanAssistedElement(HeatingElement):
    """A drop-in replacement, to show the swap is real."""

    def heat(self, celsius):
        return f"fan-assisted to {celsius}C at {self.watts}W"


class ComposedOven:
    def __init__(self, name, watts):
        self.name = name
        self.element = HeatingElement(watts)  # has-a
        self.timer = Timer()                  # has-a

    def bake(self, celsius, minutes):         # delegation, written by hand
        return f"{self.name}: {self.element.heat(celsius)}; {self.timer.set(minutes)}"


class ComposedToaster:
    def __init__(self, name, watts):
        self.name = name
        self.element = HeatingElement(watts)  # has-a, no shared ancestor

    def toast(self, celsius):
        return f"{self.name}: {self.element.heat(celsius)}"


def main():
    print("-- inheritance: behaviour arrives implicitly through the MRO --")
    oven = InheritedOven("Deck oven", 3200, 260, 60)
    print(oven.describe())
    print(oven.heat(220), "   <- defined on HeatingAppliance, not on Oven")
    print(f"MRO: {' -> '.join(c.__name__ for c in InheritedOven.__mro__)}")
    print(f"Toaster shares the whole chain: "
          f"{' -> '.join(c.__name__ for c in InheritedToaster.__mro__)}")

    print()
    print("-- composition: behaviour is forwarded explicitly --")
    print(ComposedOven("Deck oven", 3200).bake(220, 35))
    print(ComposedToaster("Two-slice", 900).toast(260))
    print(f"ComposedOven inherits from: "
          f"{[c.__name__ for c in ComposedOven.__mro__]}  <- nothing but object")

    print()
    print("-- the practical difference: swap a collaborator at runtime --")
    swappable = ComposedOven("Deck oven", 3200)
    swappable.element = FanAssistedElement(3200)   # one assignment
    print(swappable.bake(220, 35))
    print("    ^ no class was edited, no subclass was written, nothing")
    print("      inherited changed. That swap has no equivalent on the")
    print("      inheritance side without defining a new subclass.")


if __name__ == "__main__":
    main()

"""Step 5: a context manager of your own, and the guarantee it makes.

`with` is not built into the file object. It is a protocol: any object with
__enter__ and __exit__ can be used with `with`. __exit__ runs on the way out
of the block whether the body finished normally or raised — which is exactly
the guarantee you relied on with files on Day 64, now implemented by you.

__exit__ receives three arguments describing the exception, or three Nones if
there was none:
    exc_type   the exception class      (or None)
    exc_value  the exception instance   (or None)
    traceback  the traceback object     (or None)

Its RETURN VALUE decides what happens next: False (or None) lets the
exception continue to the caller; True SWALLOWS it. Returning True by
accident is how exceptions silently vanish, so `Menu.__exit__` returns False
deliberately.

Run it:  python3 examples/05_context_manager.py
"""

import os
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

from kitchen import Dish, Menu  # noqa: E402


def main():
    print("-- normal run: the body succeeds --")
    brunch = Menu("Brunch", [Dish("Waffles", 9)])
    with brunch as service:
        print(f"  inside: {len(service)} dish, open = {service.open}")
    print(f"after: {brunch.open}")

    print()
    print("-- the case that matters: the body raises --")
    bad = Menu("Bad night", [Dish("Souffle", 45)])
    try:
        with bad:
            raise ValueError("burnt the souffle")
    except ValueError as err:
        # [service closed] printed BEFORE this line: __exit__ ran on the way
        # out, and returning False let the exception carry on to us here.
        print(f"caught: {err} | open = {bad.open}")

    print()
    print("-- proof the cleanup is unconditional --")
    print(f"cleanup ran after success: {brunch.open is False}")
    print(f"cleanup ran after failure: {bad.open is False}")
    print("exception still reached the caller: True")


if __name__ == "__main__":
    main()

"""Step 6: an abstract base class, and the duck typing that often replaces it.

An abstract base class cannot be instantiated, and it names the methods every
subclass must implement. Forget one and Python refuses to build the object at
the moment you asked for it, naming the class and the missing method — far
kinder than a mysterious failure hours into a run.

Note the shape of `Station.announce`: a CONCRETE method that calls an
ABSTRACT one. That is the template-method pattern, and it is exactly how
PyTorch's nn.Module works — the framework calls the `forward` you wrote.

Run it:  python3 examples/06_abstract_base.py
"""

from abc import ABC, abstractmethod
from collections.abc import Iterable, Sized


class Station(ABC):
    """Every station has a name and must know how to prepare a dish."""

    def __init__(self, name):
        self.name = name

    @abstractmethod
    def prepare(self, dish):
        """Return a string describing how this station prepares the dish."""

    def announce(self, dish):  # concrete, shared, calls the abstract method
        return f"{self.name}: {self.prepare(dish)}"


class GrillStation(Station):
    def prepare(self, dish):
        return f"grilling {dish} over charcoal"


class PastryStation(Station):
    """Deliberately incomplete: `prepare` was never implemented."""


def main():
    print(GrillStation("Grill").announce("mackerel"))

    try:
        PastryStation("Pastry")
    except TypeError as err:
        print(f"TypeError: {err}")

    print("    ^ refused at CONSTRUCTION, naming the class and the method.")
    print(f"abstract methods still outstanding: "
          f"{sorted(PastryStation.__abstractmethods__)}")

    print()
    print("-- but Python did not need the ABC to make this work --")

    class Ticket:
        """Inherits from nothing but object, yet satisfies a protocol."""

        def __init__(self, items):
            self.items = items

        def __iter__(self):
            return iter(self.items)

    ticket = Ticket(["mackerel", "gyoza"])
    print(f"isinstance(t, Iterable): {isinstance(ticket, Iterable)}")
    print(f"isinstance(t, Sized):    {isinstance(ticket, Sized)}")
    print(f'hasattr(t, "__iter__"):  {hasattr(ticket, "__iter__")}')
    try:
        len(ticket)
    except TypeError as err:
        print(f"len(t) -> TypeError: {err}")
    print("    ^ Iterable is True because Ticket defines __iter__ — the check")
    print("      is for the METHOD, not for the family tree.")


if __name__ == "__main__":
    main()

"""Reference implementation: a container class that plain Python accepts.

Step 4 of the Day 068 lab, "Protocols and Hierarchies".

`Menu` is an ordinary class holding `Dish` objects. It inherits from nothing
but `object`. Every capability below comes from implementing a dunder method
that the interpreter already knows how to call:

    len(menu)          -> Menu.__len__
    menu[0], menu[1:]  -> Menu.__getitem__
    for dish in menu   -> Menu.__iter__
    "Ramen" in menu    -> Menu.__contains__
    a == b             -> Menu.__eq__      (and __hash__, which it would break)
    sorted(menus)      -> Menu.__lt__      (via @total_ordering)
    with menu:         -> Menu.__enter__ / Menu.__exit__

The point of the demo at the bottom is that `sorted`, `max`, `list`, `set`,
`len`, `in` and the `for` statement are all UNMODIFIED — they were written
long before this file existed. They work because of the protocols, not
because of anything they know about `Menu`.

Run it directly:  python3 examples/kitchen.py
"""

from functools import total_ordering


class Dish:
    """One dish: a name and how many minutes it takes to prepare."""

    def __init__(self, name, minutes):
        self.name = name
        self.minutes = minutes

    def __repr__(self):
        # The unambiguous developer form, used inside containers too.
        return f"Dish({self.name!r}, {self.minutes})"

    def __eq__(self, other):
        # Return NotImplemented (not False) for types we do not know, so the
        # other operand still gets its chance to answer.
        if not isinstance(other, Dish):
            return NotImplemented
        return (self.name, self.minutes) == (other.name, other.minutes)

    def __hash__(self):
        # Required: defining __eq__ sets __hash__ to None. Hash the same
        # fields __eq__ compares, so equal dishes hash equal.
        return hash((self.name, self.minutes))


@total_ordering
class Menu:
    """A collection of dishes that behaves like a built-in collection."""

    def __init__(self, name, dishes=None):
        self.name = name
        self.dishes = list(dishes or [])
        self.open = False

    def __repr__(self):
        return f"Menu({self.name!r}, {len(self.dishes)} dishes)"

    # --- Exercise 1: sizing -------------------------------------------------
    def __len__(self):
        return len(self.dishes)

    # --- Exercise 2: indexing ----------------------------------------------
    def __getitem__(self, index):
        # Delegating to the list means slices work for free: a slice object
        # passed to list.__getitem__ returns a list.
        return self.dishes[index]

    # --- Exercise 3: iteration ---------------------------------------------
    def __iter__(self):
        return iter(self.dishes)

    # --- Exercise 4: membership --------------------------------------------
    def __contains__(self, item):
        # Accept either a Dish or a plain name string.
        name = item.name if isinstance(item, Dish) else item
        return any(dish.name == name for dish in self.dishes)

    def total_minutes(self):
        return sum(dish.minutes for dish in self.dishes)

    # --- Exercise 5: equality (and the hash it would otherwise break) ------
    def __eq__(self, other):
        if not isinstance(other, Menu):
            return NotImplemented
        return self.dishes == other.dishes

    def __hash__(self):
        return hash(tuple(self.dishes))

    # --- Exercise 6: ordering ----------------------------------------------
    def __lt__(self, other):
        # @total_ordering derives <=, > and >= from __lt__ plus __eq__.
        if not isinstance(other, Menu):
            return NotImplemented
        return self.total_minutes() < other.total_minutes()

    # --- Context manager protocol (step 5 of the lab) ----------------------
    def __enter__(self):
        self.open = True
        print(f"[service open] {self.name}")
        return self

    def __exit__(self, exc_type, exc_value, traceback):
        # Runs on the way out whether the block succeeded or raised.
        self.open = False
        print(f"[service closed] {self.name}")
        return False  # False = do not swallow the exception


def build_menus():
    """The three menus the demo and the tests both use."""
    lunch = Menu("Lunch", [Dish("Ramen", 12), Dish("Gyoza", 8), Dish("Salad", 4)])
    dinner = Menu("Dinner", [Dish("Ramen", 12), Dish("Duck", 40)])
    # An independent Menu holding equal dishes — a different object, equal value.
    copy = Menu("Lunch copy", [Dish("Ramen", 12), Dish("Gyoza", 8), Dish("Salad", 4)])
    return lunch, dinner, copy


def demo():
    """Prove that unmodified builtins work on a class written this afternoon."""
    lunch, dinner, copy = build_menus()

    print(f"len: {len(lunch)}")
    print(f"index: {lunch[0]!r} | slice: {lunch[1:3]!r}")
    print(f"iterate: {[dish.name for dish in lunch]}")
    print(f"contains: {'Ramen' in lunch} | {'Duck' in lunch}")
    print(f"equal: {lunch == copy} | {lunch == dinner}")
    print(f"eq other type: {lunch == 'Lunch'}")
    print(f"hash equal: {hash(lunch) == hash(copy)}")
    print(f"lt: {dinner < lunch} | ge (total_ordering): {dinner >= lunch}")
    print(f"sorted: {sorted([dinner, lunch])!r}")
    print(f"max: {max([dinner, lunch], key=len)!r}")
    print(f"longest dish: {max(lunch, key=lambda dish: dish.minutes)!r}")
    print(f"sum minutes via comprehension: {sum(dish.minutes for dish in lunch)}")
    print(f"set of menus: {len({lunch, copy, dinner})}")
    print(f"list(): {len(list(dinner))}")


if __name__ == "__main__":
    demo()

lesson_id: D068
day: 68
kind: python-program
languages: [python]
setup_commands:
  - cd labs/sections/programming-with-python/day-068-inheritance-composition-and-dunder-methods
  - python3 --version
run_commands:
  - python3 examples/01_inheritance_super.py
  - python3 examples/02_mro_diamond.py
  - python3 examples/03_composition.py
  - python3 starter/kitchen.py
  - python3 examples/kitchen.py
  - python3 examples/05_context_manager.py
  - python3 examples/06_abstract_base.py
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- starter/kitchen.py starter/comparison.md  # optional: reset your work'
requires_network: false
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-19'
executed_on: 'macOS (Apple Silicon), Python 3.14.0, bash tests/run_tests.sh -> 36 checks, 0 failure(s), exit 0'

# Requirements

## Software

| Requirement | Version | Why |
| --- | --- | --- |
| `python3` | 3.8 or newer (tested on 3.14.0) | Runs every script in this lab |
| `bash` | any modern version | Runs `tests/run_tests.sh` |

Nothing is installed. There is no `pip install` step, no virtual environment
to create, no `requirements.txt` to resolve, and no account to register.

## Python modules used

All four are part of the standard library and ship with Python itself:

| Module | Used for |
| --- | --- |
| `functools` | `@total_ordering`, which derives `<=`, `>` and `>=` from `__lt__` |
| `abc` | `ABC` and `@abstractmethod` in step 6 |
| `collections.abc` | `Iterable` and `Sized`, to show `isinstance` checking methods rather than ancestry |
| `traceback`, `importlib.util`, `os`, `sys` | Printing a stable short traceback, loading numbered example files by path in the tests, and letting step 5 import the reference `kitchen.py` beside it |

## Why 3.8 or newer

`typing.Protocol` arrived in Python 3.8 (PEP 544), and the lesson's
`Alternatives` section uses it. Everything else in this lab — the data model,
`abc`, `functools.total_ordering`, `collections.abc` — has been available far
longer.

One detail is version-dependent and worth knowing, because the exact text
appears in the expected output. The message for instantiating an incomplete
abstract subclass was reworded between the two versions checked here. On
3.14.0, which produced the captured output, you get:

```text
TypeError: Can't instantiate abstract class PastryStation without an implementation for abstract method 'prepare'
```

On 3.11.14 the same failure reads:

```text
TypeError: Can't instantiate abstract class PastryStation with abstract method prepare
```

Both are the same refusal at the same moment, naming the same class and the
same method; only the sentence changed. The tests match on the class and
method names rather than the full sentence, so they pass on either. If your
Python prints the shorter wording, nothing is wrong.

## Network, credentials, and privileges

- **Network:** not used. Every script runs entirely offline.
- **API keys:** none. Nothing here talks to a service.
- **Privileges:** none. Never run any part of this lab with `sudo`.
- **Files written:** none by the lab itself. The test suite creates one
  temporary directory with `mktemp -d` and removes it via an `EXIT` trap.

## Platform notes

macOS and Linux run every command exactly as written; the lab was authored
and executed on macOS with Apple Silicon.

On Windows, run the lab inside WSL. The Python scripts themselves are fully
portable and will run under native Windows Python unchanged, but
`tests/run_tests.sh` is a bash script and needs a POSIX shell. If you have no
WSL, you can still run each `python3 examples/...` command from PowerShell
and check the output against `expected-output/sample-run.txt` by eye — you
will simply lose the automated suite.

## Determinism

This lab has no timing measurements, no random numbers, no file sizes, and no
network calls. Every figure in `expected-output/` is reproducible byte for
byte on any machine running Python 3.12 or newer. Hash *values* are not
printed anywhere — only hash *equality* is compared — so Python's per-process
string hash randomisation does not affect any output.

# Worksheet — your written answers

Fill this in as you work. Steps 2 and 3 of the lab ask for written answers,
not code, and writing them down is the part that makes the distinction stick.
Replace each `Your answer:` line with what you actually observed.

## Step 2 — predict the MRO before you run it

`class ToasterOven(Heater, Timer)`, where `Heater` and `Timer` both inherit
from `Appliance`. Write your prediction here **before** running
`python3 examples/02_mro_diamond.py`.

- My predicted MRO: `Your answer:`
- What the program actually printed: `Your answer:`
- Did they match? `Your answer:`
- If not, which C3 rule did I miss — local precedence (a class comes before
  its own parents) or monotonicity (the order bases are listed is kept)?
  `Your answer:`

`Heater.power_on` calls `super().power_on()`. Which class does that call
reach, and does `Heater` inherit from it?

- `Your answer:`

Why does `Appliance` appear only once in the MRO, and what would go wrong if
it appeared twice?

- `Your answer:`

## Step 3 — the same domain, two ways

Run `python3 examples/03_composition.py` and then answer.

Which version would you keep for a kitchen-appliance product that ships for
years, and why?

- `Your answer:`

Name one change that would be **easier** in the inheritance version:

- `Your answer:`

Name one change that would be **easier** in the composition version:

- `Your answer:`

Describe one concrete edit to `Appliance` or `HeatingAppliance` that would
break `InheritedOven` but would leave `ComposedOven` untouched. (This is the
fragile base class problem, stated in your own words.)

- `Your answer:`

Say the relationship out loud in both directions. Which of these sounds true
and which makes you wince?

- "An `Oven` **is a** `HeatingAppliance`" — `Your answer:`
- "An `Oven` **is a** `Timer`" — `Your answer:`
- "An `Oven` **has a** `Timer`" — `Your answer:`

## Step 4 — what the protocols bought you

After completing `starter/kitchen.py`, list the builtins that now work on
your `Menu` class without any of them being modified:

- `Your answer:`

You wrote only `__lt__` for ordering. Which comparison operators did
`@total_ordering` derive for you, and what else did it need in order to do
that?

- `Your answer:`

`len({lunch, copy, dinner})` prints `2`, not `3`. Explain why in one
sentence, naming both dunder methods responsible.

- `Your answer:`

## Step 5 — the context manager guarantee

In the run whose body raises `ValueError`, does `[service closed]` print
before or after the `caught:` line, and what does that ordering prove about
when `__exit__` runs?

- `Your answer:`

What would change if `Menu.__exit__` returned `True` instead of `False`?

- `Your answer:`

## Step 6 — enforcement versus duck typing

`PastryStation` raised `TypeError` at construction. Why is failing there
better than failing later, inside a call to `announce`?

- `Your answer:`

`Ticket` inherits from nothing but `object`, yet `isinstance(t, Iterable)` is
`True`. What is `isinstance` actually checking in that case?

- `Your answer:`

When would you reach for `abc.ABC`, and when would you rely on duck typing
instead?

- `Your answer:`

"""YOUR COPY — complete the six numbered exercises.

This is a working skeleton. `Dish` is finished for you and the plumbing runs.
Six methods on `Menu` raise NotImplementedError on purpose; each one is a
numbered exercise telling you exactly what to write. Replace the `raise` with
your implementation, one at a time, running the file after each.

    python3 starter/kitchen.py

The demo at the bottom exercises `len()`, indexing, slicing, `for`, `in`,
`==`, `hash()`, `sorted()` and `max()`. None of those are modified in any
way — they are the builtins. When all six exercises are done, every one of
them will work on a class you wrote, and the output will match
`expected-output/sample-run.txt`.

Compare with `examples/kitchen.py` only after you have tried.
"""

from functools import total_ordering


class Dish:
    """Finished for you — study it, it is the pattern for exercise 5."""

    def __init__(self, name, minutes):
        self.name = name
        self.minutes = minutes

    def __repr__(self):
        return f"Dish({self.name!r}, {self.minutes})"

    def __eq__(self, other):
        # Note the NotImplemented return for unknown types: it tells Python
        # "ask the other operand", rather than answering False confidently.
        if not isinstance(other, Dish):
            return NotImplemented
        return (self.name, self.minutes) == (other.name, other.minutes)

    def __hash__(self):
        # Defining __eq__ sets __hash__ to None, so it must be restored here.
        return hash((self.name, self.minutes))


@total_ordering
class Menu:
    """A collection of dishes. Make plain Python accept it."""

    def __init__(self, name, dishes=None):
        self.name = name
        self.dishes = list(dishes or [])
        self.open = False

    def __repr__(self):
        return f"Menu({self.name!r}, {len(self.dishes)} dishes)"

    def total_minutes(self):
        """Finished for you — used by exercise 6."""
        return sum(dish.minutes for dish in self.dishes)

    # --- Exercise 1 --------------------------------------------------------
    # Make `len(menu)` work. Return how many dishes this menu holds.
    # Hint: `self.dishes` is a list; call the builtin `len()` on it.
    def __len__(self):
        raise NotImplementedError("Exercise 1: return len(self.dishes)")

    # --- Exercise 2 --------------------------------------------------------
    # Make `menu[0]` and `menu[1:3]` work. Return the item at `index`.
    # Hint: return `self.dishes[index]`. Because a list handles slice objects
    # itself, delegating like this makes slicing work with no extra code.
    def __getitem__(self, index):
        raise NotImplementedError("Exercise 2: return self.dishes[index]")

    # --- Exercise 3 --------------------------------------------------------
    # Make `for dish in menu:` work. Return an ITERATOR over the dishes.
    # Hint: `return iter(self.dishes)` — do not return the list itself, a
    # list is iterable but is not an iterator.
    def __iter__(self):
        raise NotImplementedError("Exercise 3: return iter(self.dishes)")

    # --- Exercise 4 --------------------------------------------------------
    # Make `"Ramen" in menu` work, accepting either a Dish or a plain name.
    # Hint: get the name with
    #   name = item.name if isinstance(item, Dish) else item
    # then return True if any dish in self.dishes has that name. A generator
    # expression inside the builtin `any()` reads well here.
    def __contains__(self, item):
        raise NotImplementedError("Exercise 4: any(dish.name == name for ...)")

    # --- Exercise 5 --------------------------------------------------------
    # Make `menu_a == menu_b` compare the dishes they hold. Two menus are
    # equal when their `dishes` lists are equal (Dish.__eq__ does the rest).
    # Return NotImplemented when `other` is not a Menu.
    #
    # THEN: because you defined __eq__, Python set __hash__ to None and your
    # menus became unhashable. Restore it below by hashing the same data
    # __eq__ compares — `hash(tuple(self.dishes))` works, because Dish is
    # hashable and a tuple of hashables is hashable.
    def __eq__(self, other):
        raise NotImplementedError("Exercise 5a: compare self.dishes")

    def __hash__(self):
        raise NotImplementedError("Exercise 5b: return hash(tuple(self.dishes))")

    # --- Exercise 6 --------------------------------------------------------
    # Make `sorted(menus)` work by defining ONE comparison. A menu sorts
    # before another when its total_minutes() is smaller. Return
    # NotImplemented when `other` is not a Menu.
    # The @total_ordering decorator above the class will then derive
    # <=, > and >= from this method plus __eq__ — so you write one, get four.
    def __lt__(self, other):
        raise NotImplementedError("Exercise 6: compare total_minutes()")

    # --- Finished for you: the context manager protocol (lab step 5) -------
    def __enter__(self):
        self.open = True
        print(f"[service open] {self.name}")
        return self

    def __exit__(self, exc_type, exc_value, traceback):
        self.open = False
        print(f"[service closed] {self.name}")
        return False  # False = do not swallow the exception


def build_menus():
    """The three menus the demo and the tests both use."""
    lunch = Menu("Lunch", [Dish("Ramen", 12), Dish("Gyoza", 8), Dish("Salad", 4)])
    dinner = Menu("Dinner", [Dish("Ramen", 12), Dish("Duck", 40)])
    copy = Menu("Lunch copy", [Dish("Ramen", 12), Dish("Gyoza", 8), Dish("Salad", 4)])
    return lunch, dinner, copy


def demo():
    """Every line below is an UNMODIFIED builtin working on your class."""
    lunch, dinner, copy = build_menus()

    print(f"len: {len(lunch)}")
    print(f"index: {lunch[0]!r} | slice: {lunch[1:3]!r}")
    print(f"iterate: {[dish.name for dish in lunch]}")
    print(f"contains: {'Ramen' in lunch} | {'Duck' in lunch}")
    print(f"equal: {lunch == copy} | {lunch == dinner}")
    print(f"eq other type: {lunch == 'Lunch'}")
    print(f"hash equal: {hash(lunch) == hash(copy)}")
    print(f"lt: {dinner < lunch} | ge (total_ordering): {dinner >= lunch}")
    print(f"sorted: {sorted([dinner, lunch])!r}")
    print(f"max: {max([dinner, lunch], key=len)!r}")
    print(f"longest dish: {max(lunch, key=lambda dish: dish.minutes)!r}")
    print(f"sum minutes via comprehension: {sum(dish.minutes for dish in lunch)}")
    print(f"set of menus: {len({lunch, copy, dinner})}")
    print(f"list(): {len(list(dinner))}")


if __name__ == "__main__":
    demo()

#!/usr/bin/env bash
# Tests for the Day 068 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# These checks exercise real behaviour, not file existence: a subclass that
# skips super().__init__() is constructed and the resulting AttributeError is
# caught in the method where it actually surfaces, a real diamond is built and
# its __mro__ compared against the C3 answer, an inconsistent hierarchy is
# rejected by the interpreter, a collaborator is swapped at runtime, and the
# container class is driven through len(), indexing, slicing, iteration,
# membership, equality, hashing and sorted() using nothing but builtins.
# Every check runs in a throwaway temporary directory that is removed
# afterwards. No network, no privileges, non-interactive. Exits 0 only if
# every check passes.
set -u

export PYTHONDONTWRITEBYTECODE=1

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
failures=0
checks=0

scratch="$(mktemp -d -t day068-tests.XXXXXX)"
cleanup() { rm -rf "${scratch}"; }
trap cleanup EXIT

check() {
  local label="$1" ok="$2"
  checks=$((checks + 1))
  if [ "${ok}" = "yes" ]; then
    echo "  ok: ${label}"
  else
    echo "  FAIL: ${label}"
    failures=$((failures + 1))
  fi
}

# check_kitchen <label> <kitchen_dir> <python-body>
# Runs an assertion body against the kitchen module imported from kitchen_dir.
# A clean exit (every assert passed) is a pass.
check_kitchen() {
  local label="$1" kitchen_dir="$2" body="$3"
  local out
  if out="$(PYTHONPATH="${kitchen_dir}" python3 -c "
from kitchen import Dish, Menu, build_menus
lunch, dinner, copy = build_menus()
${body}" 2>&1)"; then
    check "${label}" "yes"
  else
    check "${label}" "no"
    echo "    (${out##*$'\n'})"
  fi
}

# check_script <label> <script> <needle>
# Runs an example script and asserts it exits 0 and its output contains a
# literal string.
check_script() {
  local label="$1" script="$2" needle="$3"
  local out code
  out="$(cd "${lab_dir}" && python3 "${script}" 2>&1)"
  code=$?
  if [ "${code}" -eq 0 ] && printf '%s' "${out}" | grep -qF "${needle}"; then
    check "${label}" "yes"
  else
    check "${label}" "no"
    echo "    (exit ${code}; wanted \"${needle}\")"
  fi
}

# --- 1. Inheritance and super() -----------------------------------------
echo "Testing inheritance, super(), and what breaks without it ..."

check_script "1. broken subclass raises AttributeError for the parent's attribute" \
  "examples/01_inheritance_super.py" \
  "AttributeError: 'BrokenOven' object has no attribute 'name'"

check_script "1b. the fixed subclass produces the extended description" \
  "examples/01_inheritance_super.py" "Deck oven (3200W), 60L"

# The failure must appear in describe(), NOT in __init__ — that displacement
# is the actual lesson, so assert on the frame, not just the message.
if out="$(cd "${lab_dir}" && PYTHONPATH="examples" python3 -c "
import importlib.util, traceback
spec = importlib.util.spec_from_file_location('m', 'examples/01_inheritance_super.py')
m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
oven = m.BrokenOven('Deck oven', 3200, 60)
assert oven.capacity_litres == 60, 'construction itself must succeed'
try:
    oven.describe()
except AttributeError:
    tb = traceback.format_exc()
    assert 'in describe' in tb, 'failure must surface in describe()'
    assert 'in __init__' not in tb, 'the constructor must NOT be in the traceback'
else:
    raise SystemExit('describe() should have raised')
" 2>&1)"; then
  check "1c. construction succeeds; the failure surfaces in describe(), not __init__" "yes"
else
  check "1c. construction succeeds; the failure surfaces in describe(), not __init__" "no"
  echo "    (${out##*$'\n'})"
fi

if out="$(cd "${lab_dir}" && python3 -c "
import importlib.util
spec = importlib.util.spec_from_file_location('m', 'examples/01_inheritance_super.py')
m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
fixed = m.FixedOven('Deck oven', 3200, 60)
assert fixed.name == 'Deck oven' and fixed.watts == 3200, 'parent setup missing'
assert fixed.describe() == 'Deck oven (3200W), 60L', fixed.describe()
assert [c.__name__ for c in m.FixedOven.__mro__] == ['FixedOven', 'Appliance', 'object']
" 2>&1)"; then
  check "1d. super().__init__() restores name and watts and extends describe()" "yes"
else
  check "1d. super().__init__() restores name and watts and extends describe()" "no"
  echo "    (${out##*$'\n'})"
fi

# --- 2. The MRO and the diamond -----------------------------------------
echo "Testing the diamond hierarchy and C3 linearization ..."

check_script "2. the diamond MRO is ToasterOven -> Heater -> Timer -> Appliance -> object" \
  "examples/02_mro_diamond.py" \
  "ToasterOven -> Heater -> Timer -> Appliance -> object"

check_script "2b. cooperative super() chains through all four classes" \
  "examples/02_mro_diamond.py" \
  "ToasterOven: ready -> Heater: elements warming -> Timer: clock started -> Appliance: power on"

if out="$(cd "${lab_dir}" && python3 -c "
import importlib.util
spec = importlib.util.spec_from_file_location('m', 'examples/02_mro_diamond.py')
m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
mro = [c.__name__ for c in m.ToasterOven.__mro__]
assert mro == ['ToasterOven', 'Heater', 'Timer', 'Appliance', 'object'], mro
assert mro.count('Appliance') == 1, 'C3 must list the shared base exactly once'
# super() in Heater reaches Timer, which Heater does not inherit from.
assert m.Timer not in m.Heater.__bases__, 'Heater must NOT inherit from Timer'
assert mro[mro.index('Heater') + 1] == 'Timer', 'super() should land on Timer'
" 2>&1)"; then
  check "2c. the shared base appears once, and Heater's super() lands on a non-parent" "yes"
else
  check "2c. the shared base appears once, and Heater's super() lands on a non-parent" "no"
  echo "    (${out##*$'\n'})"
fi

if out="$(cd "${lab_dir}" && python3 -c "
import importlib.util
spec = importlib.util.spec_from_file_location('m', 'examples/02_mro_diamond.py')
m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
try:
    type('Impossible', (m.Appliance, m.Heater), {})
except TypeError as err:
    # Python wraps this message differently across versions, so normalise
    # whitespace before matching rather than depending on the line breaks.
    message = ' '.join(str(err).split())
    assert 'consistent method resolution order' in message, message
else:
    raise SystemExit('an inconsistent hierarchy should have been rejected')
" 2>&1)"; then
  check "2d. an inconsistent hierarchy is refused at class-definition time" "yes"
else
  check "2d. an inconsistent hierarchy is refused at class-definition time" "no"
  echo "    (${out##*$'\n'})"
fi

# --- 3. Composition -------------------------------------------------------
echo "Testing the composition rewrite of the same domain ..."

check_script "3. the composed oven delegates to its element and its timer" \
  "examples/03_composition.py" \
  "Deck oven: heating to 220C at 3200W; timer set to 35 min"

if out="$(cd "${lab_dir}" && python3 -c "
import importlib.util
spec = importlib.util.spec_from_file_location('m', 'examples/03_composition.py')
m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
# Both designs must produce the same heating string for the same inputs.
inherited = m.InheritedOven('Deck oven', 3200, 260, 60).heat(220)
composed = m.ComposedOven('Deck oven', 3200).element.heat(220)
assert inherited == composed == 'heating to 220C at 3200W', (inherited, composed)
# The composed classes must genuinely inherit nothing.
assert m.ComposedOven.__bases__ == (object,), m.ComposedOven.__bases__
assert m.ComposedToaster.__bases__ == (object,), m.ComposedToaster.__bases__
# has-a, not is-a: the collaborators are attributes.
oven = m.ComposedOven('Deck oven', 3200)
assert isinstance(oven.element, m.HeatingElement) and isinstance(oven.timer, m.Timer)
assert not isinstance(oven, m.HeatingElement), 'an Oven is not a HeatingElement'
" 2>&1)"; then
  check "3b. both designs behave identically, but the composed one inherits nothing" "yes"
else
  check "3b. both designs behave identically, but the composed one inherits nothing" "no"
  echo "    (${out##*$'\n'})"
fi

if out="$(cd "${lab_dir}" && python3 -c "
import importlib.util
spec = importlib.util.spec_from_file_location('m', 'examples/03_composition.py')
m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
oven = m.ComposedOven('Deck oven', 3200)
before = oven.bake(220, 35)
oven.element = m.FanAssistedElement(3200)   # swapped at RUNTIME
after = oven.bake(220, 35)
assert 'heating to' in before and 'fan-assisted to' in after, (before, after)
assert before != after, 'swapping the collaborator must change the behaviour'
" 2>&1)"; then
  check "3c. a collaborator can be swapped at runtime with no class edited" "yes"
else
  check "3c. a collaborator can be swapped at runtime with no class edited" "no"
  echo "    (${out##*$'\n'})"
fi

# --- 5. Context manager ---------------------------------------------------
echo "Testing the context manager's cleanup guarantee ..."

check_script "5. cleanup runs and the exception still reaches the caller" \
  "examples/05_context_manager.py" "caught: burnt the souffle | open = False"

# --- 6. Abstract base class -----------------------------------------------
echo "Testing the abstract base class and duck typing ..."

# Match on the class name only: the rest of this sentence was reworded
# between Python versions (see requirements/README.md). The method name is
# asserted separately in 6c via __abstractmethods__.
check_script "6. an incomplete subclass is refused at construction, by name" \
  "examples/06_abstract_base.py" \
  "TypeError: Can't instantiate abstract class PastryStation"

check_script "6b. the complete subclass works through the template method" \
  "examples/06_abstract_base.py" "Grill: grilling mackerel over charcoal"

if out="$(cd "${lab_dir}" && python3 -c "
import importlib.util
spec = importlib.util.spec_from_file_location('m', 'examples/06_abstract_base.py')
m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
assert m.PastryStation.__abstractmethods__ == frozenset({'prepare'}), \
    m.PastryStation.__abstractmethods__
try:
    m.Station('any')
except TypeError:
    pass
else:
    raise SystemExit('the ABC itself must not be instantiable')
" 2>&1)"; then
  check "6c. the ABC itself is not instantiable and names its outstanding method" "yes"
else
  check "6c. the ABC itself is not instantiable and names its outstanding method" "no"
  echo "    (${out##*$'\n'})"
fi

# --- 4. The container class: the protocol checks -------------------------
run_kitchen_checks() {
  local dir="$1"
  echo "Testing the container class in ${dir} (builtins only, nothing patched) ..."

  check_kitchen "4. len(menu) calls __len__" "${dir}" "
assert len(lunch) == 3, len(lunch)
assert len(dinner) == 2, len(dinner)
assert len(Menu('Empty')) == 0
"

  check_kitchen "4b. menu[i] and menu[i:j] call __getitem__ (slicing comes free)" "${dir}" "
assert lunch[0] == Dish('Ramen', 12), lunch[0]
assert lunch[-1] == Dish('Salad', 4), lunch[-1]
assert lunch[1:3] == [Dish('Gyoza', 8), Dish('Salad', 4)], lunch[1:3]
try:
    lunch[99]
except IndexError:
    pass
else:
    raise SystemExit('an out-of-range index should raise IndexError')
"

  check_kitchen "4c. a for loop calls __iter__, and two loops both start over" "${dir}" "
names = [d.name for d in lunch]
assert names == ['Ramen', 'Gyoza', 'Salad'], names
assert [d.name for d in lunch] == names, 'a second loop must restart, not exhaust'
assert list(lunch) == lunch.dishes, 'list() must consume __iter__'
"

  check_kitchen "4d. 'x in menu' calls __contains__ for both names and Dishes" "${dir}" "
assert ('Ramen' in lunch) is True
assert ('Duck' in lunch) is False
assert (Dish('Gyoza', 8) in lunch) is True
assert ('Duck' in dinner) is True
"

  check_kitchen "4e. __eq__ compares contents and defers on unknown types" "${dir}" "
assert (lunch == copy) is True, 'equal dishes must compare equal'
assert lunch is not copy, 'they must be distinct objects'
assert (lunch == dinner) is False
assert (lunch == 'Lunch') is False, 'comparing to a str must be False, not an error'
assert Menu.__eq__(lunch, 'Lunch') is NotImplemented, \
    '__eq__ must return NotImplemented for unknown types, not False'
"

  check_kitchen "4f. __hash__ survives __eq__, so menus work in sets and dicts" "${dir}" "
assert Menu.__hash__ is not None, 'defining __eq__ without __hash__ breaks sets'
assert hash(lunch) == hash(copy), 'equal objects must hash equal'
assert len({lunch, copy, dinner}) == 2, 'the set must collapse the two equal menus'
assert {lunch: 'x'}[copy] == 'x', 'an equal menu must find the same dict entry'
"

  check_kitchen "4g. sorted() and max() work using only __lt__ and @total_ordering" "${dir}" "
assert lunch.total_minutes() == 24 and dinner.total_minutes() == 52
assert sorted([dinner, lunch]) == [lunch, dinner], 'sorted must use __lt__'
assert (dinner < lunch) is False and (lunch < dinner) is True
# total_ordering derives these three from __lt__ plus __eq__:
assert (dinner >= lunch) is True
assert (dinner > lunch) is True
assert (lunch <= dinner) is True
assert max([dinner, lunch]) is dinner, 'max must use the ordering'
assert max([dinner, lunch], key=len) is lunch, 'key=len must use __len__'
"

  check_kitchen "4h. iteration protocol feeds max(), sum() and comprehensions" "${dir}" "
assert max(lunch, key=lambda d: d.minutes) == Dish('Ramen', 12)
assert sum(d.minutes for d in lunch) == 24
assert sorted(d.name for d in lunch) == ['Gyoza', 'Ramen', 'Salad']
"

  check_kitchen "4i. the context manager opens, closes, and closes again on failure" "${dir}" "
m = Menu('Service', [Dish('Waffles', 9)])
with m as service:
    assert service is m, '__enter__ must return the object bound by as'
    assert m.open is True
assert m.open is False, '__exit__ must run after a normal exit'
try:
    with m:
        raise ValueError('kitchen fire')
except ValueError as err:
    assert str(err) == 'kitchen fire', 'returning False must not swallow it'
else:
    raise SystemExit('__exit__ returned True and swallowed the exception')
assert m.open is False, '__exit__ must run after a raising exit too'
"

  check_kitchen "4j. Dish equality and hashing behave as the pattern for Menu" "${dir}" "
assert Dish('Ramen', 12) == Dish('Ramen', 12)
assert Dish('Ramen', 12) != Dish('Ramen', 13)
assert hash(Dish('Ramen', 12)) == hash(Dish('Ramen', 12))
assert Dish.__eq__(Dish('Ramen', 12), 'Ramen') is NotImplemented
assert len({Dish('Ramen', 12), Dish('Ramen', 12)}) == 1
"
}

# --- Reference: always tested strictly ---
run_kitchen_checks "${lab_dir}/examples"

echo "Testing examples/kitchen.py end to end ..."
check_script "4k. the reference demo reports the collapsed set of menus" \
  "examples/kitchen.py" "set of menus: 2"

# --- Learner starter ---
echo "Testing starter/kitchen.py ..."
starter_kitchen="${lab_dir}/starter/kitchen.py"
if python3 -c "compile(open('${starter_kitchen}').read(), '${starter_kitchen}', 'exec')" 2>/dev/null; then
  check "starter kitchen.py is valid Python" "yes"
else
  check "starter kitchen.py is valid Python" "no"
fi

if grep -q 'NotImplementedError' "${starter_kitchen}"; then
  echo "Note: starter/kitchen.py still has unfinished exercises — testing structure only."
  for name in __len__ __getitem__ __iter__ __contains__ __eq__ __hash__ __lt__ \
              __enter__ __exit__; do
    if grep -q "def ${name}" "${starter_kitchen}"; then
      check "starter defines ${name}" "yes"
    else
      check "starter defines ${name}" "no"
    fi
  done
else
  run_kitchen_checks "${lab_dir}/starter"
  check_script "starter demo reports the collapsed set of menus" \
    "starter/kitchen.py" "set of menus: 2"
  # A __contains__ that secretly rebuilds a list is not what was asked for,
  # but an __iter__ that returns the list itself is an outright bug: a list
  # is iterable, not an iterator, so nested loops would misbehave.
  if PYTHONPATH="${lab_dir}/starter" python3 -c "
from kitchen import Menu, Dish
m = Menu('x', [Dish('a', 1)])
it = iter(m)
assert iter(it) is it, '__iter__ must return an iterator, not the list'
" 2>/dev/null; then
    check "starter __iter__ returns a real iterator" "yes"
  else
    check "starter __iter__ returns a real iterator" "no"
  fi
fi

echo
echo "${checks} checks, ${failures} failure(s)."
[ "${failures}" -eq 0 ]