Handling follow-up questions and extensions

followups/parking_followups.py

"""Three follow-ups to the parking lot, each applied to the base design on its own."""

import os

from seams import FollowUp, report

RATE = {"bike": 1000, "car": 4000, "ev": 5000}  # paise per started hour, by kind
CARS = ["C1", "C2"]


def lot(m, spots=None, **options):
    spots = spots or {m.Kind.CAR: CARS, m.Kind.BIKE: ["B1"]}
    fee = m.HourlyFee({kind: RATE[kind.value] for kind in m.Kind})
    return m.ParkingLot(spots, fee, printer=options.pop("printer", lambda line: None), **options)


# ---- the tests the base design already passes ------------------------------------------------------------------------
def check_first_free_spot_of_its_kind(m):
    p = lot(m)
    assert [p.park(plate, m.Kind.CAR, 0).spot for plate in ("KA01", "KA02")] == CARS
    assert p.park("KA03", m.Kind.BIKE, 0).spot == "B1"


def check_full_kind_is_refused(m):
    p = lot(m)
    p.park("KA01", m.Kind.BIKE, 0)
    try:
        p.park("KA02", m.Kind.BIKE, 0)
    except m.LotFull:
        return
    raise AssertionError("a second bike got a spot")


def check_leaving_frees_the_spot(m):
    p = lot(m)
    ticket = p.park("KA01", m.Kind.CAR, 0)
    p.leave(ticket.id, 30)
    assert p.free_spots(m.Kind.CAR) == 2 and p.park("KA02", m.Kind.CAR, 40).spot == "C1"


def check_fee_counts_started_hours(m):
    p = lot(m)
    fees = [p.leave(p.park(f"KA0{i}", m.Kind.CAR, 0).id, left) for i, left in enumerate((60, 61))]
    assert fees == [4000, 8000], fees


BASE_TESTS = [check_first_free_spot_of_its_kind, check_full_kind_is_refused, check_leaving_frees_the_spot,
              check_fee_counts_started_hours]


# ---- A1: a new variant -----------------------------------------------------------------------------------------------
def check_ev_falls_back_to_a_car_spot(m):
    p = lot(m, {m.Kind.CAR: CARS, m.Kind.EV: ["E1"]})
    assert [p.park(plate, m.Kind.EV, 0).spot for plate in ("EV01", "EV02")] == ["E1", "C1"]


def check_car_never_takes_a_charging_spot(m):
    p = lot(m, {m.Kind.CAR: CARS, m.Kind.EV: ["E1"]})
    assert [p.park(plate, m.Kind.CAR, 0).spot for plate in ("KA01", "KA02")] == CARS
    try:
        p.park("KA03", m.Kind.CAR, 0)
    except m.LotFull:
        return
    raise AssertionError("a car took the charging spot")


A1 = FollowUp(
    "A1", "Add charging spots: only electric cars use them, and one takes a car spot when they are full.",
    kind="variant", seam="Kind, which the lot already allocates by, and the order of spot kinds to try",
    edits=[
        ('    CAR = "car"\n', '    CAR = "car"\n    EV = "ev"\n'),
        ("class LotFull(", "FALLBACK = {Kind.EV: (Kind.EV, Kind.CAR)}  # spot kinds to try, in order\n\n\nclass LotFull("),
        ("""        for spot in self._spots.get(kind, []):
            if spot not in self._holder:
                return spot
""", """        for spot_kind in FALLBACK.get(kind, (kind,)):
            for spot in self._spots.get(spot_kind, []):
                if spot not in self._holder:
                    return spot
"""),
    ],
    tests=[check_ev_falls_back_to_a_car_spot, check_car_never_takes_a_charging_spot],
)


# ---- A2: concurrency -------------------------------------------------------------------------------------------------
def check_two_gates_get_two_spots(m):
    """Gate B's driver arrives while gate A prints its ticket, the widest gap between finding a spot and taking it."""
    printed, second = [], []

    def printer(line):
        printed.append(line)
        if len(printed) == 1:
            second.append(p.park("KA02", m.Kind.CAR, 0))

    p = lot(m, printer=printer)
    first = p.park("KA01", m.Kind.CAR, 0)
    assert first.spot != second[0].spot, f"both drivers were sent to {first.spot}"
    assert p.free_spots(m.Kind.CAR) == 0


A2 = FollowUp(
    "A2", "A second entry gate opens, so two drivers can arrive at the same moment.",
    kind="concurrency", seam="ParkingLot.park: find a spot and take it in one step, with no slow call inside",
    edits=[
        ("from dataclasses import dataclass\n", "import threading\nfrom dataclasses import dataclass\n"),
        ("        self._holder = {}  # spot -> id of the ticket parked there\n",
         "        self._holder = {}  # spot -> id of the ticket parked there\n        self._lock = threading.Lock()\n"),
        ("""        spot = self._free_spot(kind)
        self._printer(f"ticket for {plate}: go to {spot}")
        return self._occupy(spot, plate, kind, at)
""", """        with self._lock:
            spot = self._free_spot(kind)
            ticket = self._occupy(spot, plate, kind, at)
        self._printer(f"ticket for {plate}: go to {spot}")
        return ticket
"""),
        ("""        ticket = self._tickets.remove(ticket_id)
        del self._holder[ticket.spot]
""", """        with self._lock:
            ticket = self._tickets.remove(ticket_id)
            del self._holder[ticket.spot]
"""),
    ],
    tests=[check_two_gates_get_two_spots],
)


# ---- A3: persistence -------------------------------------------------------------------------------------------------
def check_restart_keeps_open_tickets(m):
    path = "tickets.json"
    try:
        before = lot(m, tickets=m.JsonTickets(path))
        stays = before.park("KA01", m.Kind.CAR, 0)
        before.leave(before.park("KA02", m.Kind.CAR, 5).id, 30)
        after = lot(m, tickets=m.JsonTickets(path))  # the program restarted
        assert after.free_spots(m.Kind.CAR) == 1
        assert after.park("KA03", m.Kind.CAR, 60).id == 3, "a ticket number was given out twice"
        assert after.leave(stays.id, 125) == 12000
    finally:
        if os.path.exists(path):
            os.remove(path)


A3 = FollowUp(
    "A3", "The program restarts every night; cars parked before the restart must still leave and pay.",
    kind="persistence", seam="the ticket store: a second class behind the methods the lot already calls",
    edits=[
        ("from dataclasses import dataclass\n", "import json\nimport os\nfrom dataclasses import dataclass\n"),
        ("class ParkingLot:\n", '''class JsonTickets(InMemoryTickets):
    """The same tickets, written to a file after every change and read back when the program starts."""

    def __init__(self, path):
        super().__init__()
        self._path = path
        if os.path.exists(path):
            with open(path, encoding="utf-8") as file:
                saved = json.load(file)
            self._last_id = saved["last_id"]
            for t in saved["tickets"]:
                self._by_id[t["id"]] = Ticket(t["id"], t["plate"], Kind(t["kind"]), t["spot"], t["entered"])

    def save(self, ticket):
        super().save(ticket)
        self._write()

    def remove(self, ticket_id):
        ticket = super().remove(ticket_id)
        self._write()
        return ticket

    def _write(self):
        tickets = [{**vars(t), "kind": t.kind.value} for t in self.all()]
        with open(self._path + ".tmp", "w", encoding="utf-8") as file:
            json.dump({"last_id": self._last_id, "tickets": tickets}, file)
        os.replace(self._path + ".tmp", self._path)  # a crash mid-write leaves the old file whole


class ParkingLot:
'''),
        ("        self._holder = {}  # spot -> id of the ticket parked there\n",
         "        self._holder = {t.spot: t.id for t in self._tickets.all()}  # rebuilt from the saved tickets\n"),
    ],
    tests=[check_restart_keeps_open_tickets],
)


if __name__ == "__main__":
    report("parking.py", BASE_TESTS, [A1, A2, A3])

parking.py: 4 of 4 tests pass on the base design

A1 [variant] Add charging spots: only electric cars use them, and one takes a car spot when they are full.
  seam: Kind, which the lot already allocates by, and the order of spot kinds to try
  changed: +6 -3 lines; untouched: LotFull, Ticket, HourlyFee, InMemoryTickets
  Kind
    + EV = "ev"
  top level
    + FALLBACK = {Kind.EV: (Kind.EV, Kind.CAR)}  # spot kinds to try, in order
  ParkingLot._free_spot
    - for spot in self._spots.get(kind, []):
    -     if spot not in self._holder:
    -         return spot
    + for spot_kind in FALLBACK.get(kind, (kind,)):
    +     for spot in self._spots.get(spot_kind, []):
    +         if spot not in self._holder:
    +             return spot
  tests: old 4/4 pass on the new code; new 0/2 on the old code, 2/2 on the new
    on the old code: check_ev_falls_back_to_a_car_spot: AttributeError: type object 'Kind' has no attribute 'EV'

A2 [concurrency] A second entry gate opens, so two drivers can arrive at the same moment.
  seam: ParkingLot.park: find a spot and take it in one step, with no slow call inside
  changed: +9 -4 lines; untouched: Kind, LotFull, Ticket, HourlyFee, InMemoryTickets
  top level
    + import threading
  ParkingLot.__init__
    + self._lock = threading.Lock()
  ParkingLot.park
    - spot = self._free_spot(kind)
    + with self._lock:
    +     spot = self._free_spot(kind)
    +     ticket = self._occupy(spot, plate, kind, at)
      self._printer(f"ticket for {plate}: go to {spot}")
    - return self._occupy(spot, plate, kind, at)
    + return ticket
  ParkingLot.leave
    - ticket = self._tickets.remove(ticket_id)
    - del self._holder[ticket.spot]
    + with self._lock:
    +     ticket = self._tickets.remove(ticket_id)
    +     del self._holder[ticket.spot]
  tests: old 4/4 pass on the new code; new 0/1 on the old code, 1/1 on the new
    on the old code: check_two_gates_get_two_spots: AssertionError: both drivers were sent to C1

A3 [persistence] The program restarts every night; cars parked before the restart must still leave and pay.
  seam: the ticket store: a second class behind the methods the lot already calls
  changed: +26 -1 lines; untouched: Kind, LotFull, Ticket, HourlyFee, InMemoryTickets
  top level
    + import json
    + import os
  JsonTickets: new, 23 lines
  ParkingLot.__init__
    - self._holder = {}  # spot -> id of the ticket parked there
    + self._holder = {t.spot: t.id for t in self._tickets.all()}  # rebuilt from the saved tickets
  tests: old 4/4 pass on the new code; new 0/1 on the old code, 1/1 on the new
    on the old code: check_restart_keeps_open_tickets: AttributeError: module 'parking_base' has no attribute 'JsonTickets'

followups/parking.py

"""A parking lot as it stands after a timed round: spots by vehicle kind, tickets and an hourly fee in paise."""

from dataclasses import dataclass
from enum import Enum


class Kind(Enum):
    BIKE = "bike"
    CAR = "car"


class LotFull(Exception):
    """No free spot for the vehicle's kind."""


@dataclass(frozen=True)
class Ticket:
    id: int
    plate: str
    kind: Kind
    spot: str
    entered: int  # minutes after the lot opened


class HourlyFee:
    """Every started hour costs the kind's rate; the first hour is always charged."""

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

    def fee(self, ticket, left):
        hours = max(1, -(-(left - ticket.entered) // 60))
        return hours * self.rates[ticket.kind]


class InMemoryTickets:
    """The open tickets, and the counter that numbers them."""

    def __init__(self):
        self._by_id = {}
        self._last_id = 0

    def new_id(self):
        self._last_id += 1
        return self._last_id

    def save(self, ticket):
        self._by_id[ticket.id] = ticket

    def remove(self, ticket_id):
        return self._by_id.pop(ticket_id)

    def all(self):
        return list(self._by_id.values())


class ParkingLot:
    def __init__(self, spots, fee, tickets=None, printer=print):
        self._spots = spots  # {Kind.CAR: ["C1", "C2"], ...}, in the order they are given out
        self._fee = fee
        self._tickets = tickets if tickets is not None else InMemoryTickets()
        self._printer = printer  # the gate's ticket printer
        self._holder = {}  # spot -> id of the ticket parked there

    def park(self, plate, kind, at):
        spot = self._free_spot(kind)
        self._printer(f"ticket for {plate}: go to {spot}")
        return self._occupy(spot, plate, kind, at)

    def leave(self, ticket_id, at):
        ticket = self._tickets.remove(ticket_id)
        del self._holder[ticket.spot]
        return self._fee.fee(ticket, at)

    def free_spots(self, kind):
        return sum(spot not in self._holder for spot in self._spots.get(kind, []))

    def _free_spot(self, kind):
        for spot in self._spots.get(kind, []):
            if spot not in self._holder:
                return spot
        raise LotFull(kind.value)

    def _occupy(self, spot, plate, kind, at):
        ticket = Ticket(self._tickets.new_id(), plate, kind, spot, at)
        self._holder[spot] = ticket.id
        self._tickets.save(ticket)
        return ticket

followups/seams.py

"""Measures a follow-up the way an interviewer judges it: where the change goes, what stays untouched, and what the
tests say. Each follow-up is a list of edits to a design's source. The edits are applied to the base design on their
own, the two versions are compared line by line, and the old and the new tests run against both versions."""

import ast
import difflib
import sys
import types


class FollowUp:
    def __init__(self, tag, ask, kind, seam, edits, tests, replaces=()):
        self.tag, self.ask, self.kind, self.seam = tag, ask, kind, seam
        self.edits = edits  # (old text, new text) pairs; each old text occurs exactly once in the base
        self.tests = tests  # functions that take the design's module and raise when a rule is broken
        self.replaces = set(replaces)  # names of old tests whose rule the follow-up changes on purpose


def apply(source, edits):
    for old, new in edits:
        found = source.count(old)
        if found != 1:
            raise ValueError(f"an edit must match exactly once; this one matches {found} times: {old.strip()[:60]!r}")
        source = source.replace(old, new)
    return source


def owners(source):
    """The definition that holds each line, such as "ParkingLot.park", by line number."""
    owner = {}

    def visit(node, prefix):
        for child in ast.iter_child_nodes(node):
            if isinstance(child, (ast.ClassDef, ast.FunctionDef)):
                name = f"{prefix}.{child.name}" if prefix else child.name
                first = min([child.lineno] + [d.lineno for d in child.decorator_list])
                for line in range(first, child.end_lineno + 1):
                    owner[line] = name
                visit(child, name)

    visit(ast.parse(source), "")
    return owner


def changes(before, after):
    """The changed lines that are not blank, grouped by owner: {owner: ["- old", "+ new", ...]}, in file order. One or
    two unchanged lines between two changes of the same owner are kept as context ("  ")."""
    a, b = before.splitlines(), after.splitlines()
    own_a, own_b = owners(before), owners(after)
    out = {}
    blocks = difflib.SequenceMatcher(None, a, b, autojunk=False).get_opcodes()
    for n, (tag, i1, i2, j1, j2) in enumerate(blocks):
        if tag == "equal":
            same = 0 < n < len(blocks) - 1 and own_b.get(j1) == own_b.get(j2 + 1) == own_b.get(j1 + 1)
            if same and own_b.get(j1 + 1) in out:  # unchanged lines inside a definition that changes around them
                kept = [f"  {line.rstrip()}" for line in b[j1:j2] if line.strip()] if j2 - j1 <= 2 else ["  ..."]
                out[own_b[j1 + 1]] += kept
            continue
        for sign, lines, own, start, end in (("-", a, own_a, i1, i2), ("+", b, own_b, j1, j2)):
            for i in range(start, end):
                if lines[i].strip():
                    out.setdefault(own.get(i + 1, "top level"), []).append(f"{sign} {lines[i].rstrip()}")
    return out


def show(changed, before, after):
    """Prints the changed lines without their common indent; a definition that is new or gone as a whole is one line."""
    names_before, names_after = set(owners(before).values()), set(owners(after).values())
    done = set()
    for owner, lines in changed.items():
        top = owner.split(".")[0]
        if top in done:
            continue
        whole = top if top != "top level" and (top not in names_before or top not in names_after) else None
        if whole or (owner != "top level" and (owner not in names_before or owner not in names_after)):
            name = whole or owner
            group = [line for o, ls in changed.items() if o == name or o.startswith(name + ".") for line in ls]
            print(f"  {name}: {'new' if name not in names_before else 'removed'}, {len(group)} lines")
            done.add(whole)
            continue
        print(f"  {owner}")
        indent = min(len(line[2:]) - len(line[2:].lstrip()) for line in lines if line != "  ...")
        for line in lines:
            print(f"    {line}" if line == "  ..." else f"    {line[:2]}{line[2 + indent:]}")


def load(name, source):
    module = types.ModuleType(name)
    sys.modules[name] = module
    exec(compile(source, f"{name}.py", "exec"), module.__dict__)
    return module


def failures(tests, module):
    """The tests that fail on this module, each with the first line of its error."""
    failed = []
    for test in tests:
        try:
            test(module)
        except Exception as error:  # an assertion, or an error raised because the version lacks the feature
            failed.append(f"{test.__name__}: {type(error).__name__}: {(str(error).splitlines() or [''])[0]}")
    return failed


def report(file, base_tests, follow_ups):
    base = open(file, encoding="utf-8").read()
    name = file.removesuffix(".py")
    old = load(f"{name}_base", base)
    print(f"{file}: {len(base_tests) - len(failures(base_tests, old))} of {len(base_tests)} tests pass on the base design")
    for f in follow_ups:
        after = apply(base, f.edits)
        new = load(f"{name}_{f.tag.lower()}", after)
        changed = changes(base, after)
        added = sum(line.startswith("+") for lines in changed.values() for line in lines)
        removed = sum(line.startswith("-") for lines in changed.values() for line in lines)
        tops = {owner.split(".")[0] for owner in changed}
        untouched = [node.name for node in ast.parse(after).body if isinstance(node, ast.ClassDef) and node.name not in tops]
        print(f"\n{f.tag} [{f.kind}] {f.ask}")
        print(f"  seam: {f.seam}")
        print(f"  changed: +{added} -{removed} lines; untouched: {', '.join(untouched) or 'nothing'}")
        show(changed, base, after)
        kept = [t for t in base_tests if t.__name__ not in f.replaces]
        old_on_new = failures(kept, new)
        new_on_old, new_on_new = failures(f.tests, old), failures(f.tests, new)
        print(f"  tests: old {len(kept) - len(old_on_new)}/{len(kept)} pass on the new code;"
              f" new {len(f.tests) - len(new_on_old)}/{len(f.tests)} on the old code, {len(f.tests) - len(new_on_new)}/{len(f.tests)} on the new")
        for test in sorted(f.replaces):
            print(f"    replaced: {test} pinned the rule this follow-up changes")
        for failure in old_on_new + new_on_new:
            print(f"    still failing: {failure}")
        if not old_on_new + new_on_new and new_on_old:
            print(f"    on the old code: {new_on_old[0]}")

followups/booking_followups.py

"""Three follow-ups to the room booker, each applied to the base design on its own."""

from seams import FollowUp, report

RATE = {"Lotus": 20000, "Banyan": 50000}  # paise per half hour


def at(day, hhmm):
    hours, minutes = map(int, hhmm.split(":"))
    return day * 24 * 60 + hours * 60 + minutes


def slot(m, day, start, end):
    return m.Slot(at(day, start), at(day, end))


def rooms(m):
    return m.RoomBook(RATE, m.Tariff(RATE))


def refused(m, call):
    try:
        call()
    except m.Refused as error:
        return str(error)
    raise AssertionError("the request was accepted")


# ---- the tests the base design already passes ------------------------------------------------------------------------
def check_books_a_free_room(m):
    b = rooms(m).book("Lotus", slot(m, 1, "10:00", "11:00"), "asha")
    assert (b.id, b.price) == ("B1", 40000)


def check_overlap_is_refused(m):
    r = rooms(m)
    r.book("Lotus", slot(m, 1, "10:00", "11:00"), "asha")
    assert refused(m, lambda: r.book("Lotus", slot(m, 1, "10:30", "11:30"), "ravi")) == "Lotus is taken by B1"
    assert r.book("Banyan", slot(m, 1, "10:30", "11:30"), "ravi").id == "B2"


def check_back_to_back_is_allowed(m):
    r = rooms(m)
    r.book("Lotus", slot(m, 1, "10:00", "11:00"), "asha")
    assert r.book("Lotus", slot(m, 1, "11:00", "12:00"), "ravi").id == "B2"


def check_cancel_refunds_and_frees(m):
    r = rooms(m)
    b = r.book("Lotus", slot(m, 2, "10:00", "11:00"), "asha")
    assert r.cancel(b.id, now=at(0, "09:00")) == 40000
    assert r.book("Lotus", slot(m, 2, "10:00", "11:00"), "ravi").id == "B2"


def check_started_booking_stays(m):
    r = rooms(m)
    b = r.book("Lotus", slot(m, 1, "10:00", "11:00"), "asha")
    assert refused(m, lambda: r.cancel(b.id, now=at(1, "10:00"))) == "B1 has already started"


BASE_TESTS = [check_books_a_free_room, check_overlap_is_refused, check_back_to_back_is_allowed,
              check_cancel_refunds_and_frees, check_started_booking_stays]


# ---- B1: a new rule --------------------------------------------------------------------------------------------------
def check_late_cancellation_refunds_half(m):
    r = rooms(m)
    b = r.book("Lotus", slot(m, 2, "10:00", "11:00"), "asha")
    assert r.cancel(b.id, now=at(1, "10:01")) == 20000, "23 hours 59 minutes ahead is late"


def check_a_day_ahead_refunds_everything(m):
    r = rooms(m)
    b = r.book("Lotus", slot(m, 2, "10:00", "11:00"), "asha")
    assert r.cancel(b.id, now=at(1, "10:00")) == 40000, "exactly 24 hours ahead is in time"


B1 = FollowUp(
    "B1", "Cancelling less than 24 hours before the start refunds only half the price.",
    kind="rule", seam="Tariff, which already owns what a booking costs",
    edits=[
        ("""        return (slot.end - slot.start) // 30 * self.per_half_hour[room]
""", """        return (slot.end - slot.start) // 30 * self.per_half_hour[room]

    def refund(self, booking, now):
        \"\"\"All of the price up to 24 hours before the start, half of it after that.\"\"\"
        if booking.slot.start - now >= 24 * 60:
            return booking.price
        return booking.price // 2
"""),
        ("        return booking.price  # the refund\n", "        return self._tariff.refund(booking, now)\n"),
    ],
    tests=[check_late_cancellation_refunds_half, check_a_day_ahead_refunds_everything],
)


# ---- B2: a rule that changes an old one ----------------------------------------------------------------------------
def check_cleaning_time_between_bookings(m):
    r = rooms(m)
    r.book("Lotus", slot(m, 1, "10:00", "11:00"), "asha")
    for start, end in (("11:00", "12:00"), ("09:00", "09:50")):
        assert refused(m, lambda: r.book("Lotus", slot(m, 1, start, end), "ravi")) == "Lotus is taken by B1"
    booked = [r.book("Lotus", slot(m, 1, s, e), "ravi").id for s, e in (("11:15", "12:00"), ("09:00", "09:45"))]
    assert booked == ["B2", "B3"]


B2 = FollowUp(
    "B2", "Keep 15 minutes free between two bookings of a room, for cleaning.",
    kind="rule", seam="Slot.overlaps, the one place that decides whether two slots clash",
    edits=[
        ("class Refused(", "CLEANING = 15  # minutes kept free between two bookings of a room\n\n\nclass Refused("),
        ("""    def overlaps(self, other):
        return self.start < other.end and other.start < self.end
""", """    def overlaps(self, other, gap=0):
        return self.start < other.end + gap and other.start < self.end + gap
"""),
        ("other.slot.overlaps(slot):", "other.slot.overlaps(slot, gap=CLEANING):"),
    ],
    tests=[check_cleaning_time_between_bookings],
    replaces=["check_back_to_back_is_allowed"],
)


# ---- B3: a failure: the same request twice -----------------------------------------------------------------------------
def check_a_retry_gets_the_first_answer(m):
    r = rooms(m)
    first = r.book("Lotus", slot(m, 1, "10:00", "11:00"), "asha", request_id="asha-phone-41")
    again = r.book("Lotus", slot(m, 1, "10:00", "11:00"), "asha", request_id="asha-phone-41")  # the answer was lost
    assert again == first
    assert r.book("Banyan", slot(m, 1, "10:00", "11:00"), "asha", request_id="asha-phone-42").id == "B2"


def check_another_request_for_the_slot_is_refused(m):
    r = rooms(m)
    r.book("Lotus", slot(m, 1, "10:00", "11:00"), "asha", request_id="asha-phone-41")
    assert refused(m, lambda: r.book("Lotus", slot(m, 1, "10:00", "11:00"), "ravi", request_id="ravi-7")) == "Lotus is taken by B1"


B3 = FollowUp(
    "B3", "Bookings now come from a phone app. When an answer is lost, the app sends the same request again.",
    kind="failure", seam="RoomBook.book, which remembers each request id and answers a repeat with the first result",
    edits=[
        ("        self._count = 0\n", "        self._count = 0\n        self._answers = {}  # request id -> the booking it made\n"),
        ("    def book(self, room, slot, who):\n", """    def book(self, room, slot, who, request_id=None):
        if request_id in self._answers:
            return self._answers[request_id]  # a repeat: the first answer again, nothing booked twice
"""),
        ("        self._bookings[booking.id] = booking\n", """        self._bookings[booking.id] = booking
        if request_id is not None:
            self._answers[request_id] = booking
"""),
    ],
    tests=[check_a_retry_gets_the_first_answer, check_another_request_for_the_slot_is_refused],
)

report("booking.py", BASE_TESTS, [B1, B2, B3])

booking.py: 5 of 5 tests pass on the base design

B1 [rule] Cancelling less than 24 hours before the start refunds only half the price.
  seam: Tariff, which already owns what a booking costs
  changed: +6 -1 lines; untouched: Refused, Slot, Booking
  Tariff.refund: new, 5 lines
  RoomBook.cancel
    - return booking.price  # the refund
    + return self._tariff.refund(booking, now)
  tests: old 5/5 pass on the new code; new 1/2 on the old code, 2/2 on the new
    on the old code: check_late_cancellation_refunds_half: AssertionError: 23 hours 59 minutes ahead is late

B2 [rule] Keep 15 minutes free between two bookings of a room, for cleaning.
  seam: Slot.overlaps, the one place that decides whether two slots clash
  changed: +4 -3 lines; untouched: Refused, Booking, Tariff
  top level
    + CLEANING = 15  # minutes kept free between two bookings of a room
  Slot.overlaps
    - def overlaps(self, other):
    -     return self.start < other.end and other.start < self.end
    + def overlaps(self, other, gap=0):
    +     return self.start < other.end + gap and other.start < self.end + gap
  RoomBook.book
    - if other.room == room and other.slot.overlaps(slot):
    + if other.room == room and other.slot.overlaps(slot, gap=CLEANING):
  tests: old 4/4 pass on the new code; new 0/1 on the old code, 1/1 on the new
    replaced: check_back_to_back_is_allowed pinned the rule this follow-up changes
    on the old code: check_cleaning_time_between_bookings: AssertionError: the request was accepted

B3 [failure] Bookings now come from a phone app. When an answer is lost, the app sends the same request again.
  seam: RoomBook.book, which remembers each request id and answers a repeat with the first result
  changed: +6 -1 lines; untouched: Refused, Slot, Booking, Tariff
  RoomBook.__init__
    + self._answers = {}  # request id -> the booking it made
  RoomBook.book
    - def book(self, room, slot, who):
    + def book(self, room, slot, who, request_id=None):
    +     if request_id in self._answers:
    +         return self._answers[request_id]  # a repeat: the first answer again, nothing booked twice
      ...
    +     if request_id is not None:
    +         self._answers[request_id] = booking
  tests: old 5/5 pass on the new code; new 0/2 on the old code, 2/2 on the new
    on the old code: check_a_retry_gets_the_first_answer: TypeError: RoomBook.book() got an unexpected keyword argument 'request_id'

followups/booking.py

"""Meeting rooms booked by the half hour, as they stand after a timed round. Times are minutes on the building's
clock, counted from 00:00 on day 0; prices are in paise."""

from dataclasses import dataclass


class Refused(Exception):
    """A booking or a cancellation the rules do not allow."""


@dataclass(frozen=True)
class Slot:
    start: int
    end: int

    def overlaps(self, other):
        return self.start < other.end and other.start < self.end


@dataclass(frozen=True)
class Booking:
    id: str
    room: str
    slot: Slot
    who: str
    price: int


class Tariff:
    """What a booking costs: a rate for every half hour, by room."""

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

    def price(self, room, slot):
        return (slot.end - slot.start) // 30 * self.per_half_hour[room]


class RoomBook:
    def __init__(self, rooms, tariff):
        self._rooms = set(rooms)
        self._tariff = tariff
        self._bookings = {}
        self._count = 0

    def book(self, room, slot, who):
        if room not in self._rooms:
            raise Refused(f"no room {room}")
        for other in self._bookings.values():
            if other.room == room and other.slot.overlaps(slot):
                raise Refused(f"{room} is taken by {other.id}")
        self._count += 1
        booking = Booking(f"B{self._count}", room, slot, who, self._tariff.price(room, slot))
        self._bookings[booking.id] = booking
        return booking

    def cancel(self, booking_id, now):
        booking = self._bookings.get(booking_id)
        if booking is None:
            raise Refused(f"no booking {booking_id}")
        if now >= booking.slot.start:
            raise Refused(f"{booking_id} has already started")
        del self._bookings[booking_id]
        return booking.price  # the refund

followups/library_followups.py

"""Three follow-ups to the library, each applied to the base design on its own."""

from seams import FollowUp, report

BOOKS = [("p-1", "Clean Rivers"), ("p-2", "Monsoon Maths"), ("p-3", "Tiny Engines"),
         ("p-4", "Night Trains"), ("p-5", "Salt and Stone"), ("p-6", "The Quiet Lab")]
PEOPLE = {"asha": "Asha", "ravi": "Ravi", "meera": "Meera"}


def library(m, extra=(), copies=2):
    titles = [m.Title(isbn, name, copies) for isbn, name in BOOKS] + list(extra)
    return m.Library(titles, [m.Member(key, name) for key, name in PEOPLE.items()])


def refused(m, call):
    try:
        call()
    except m.Refused as error:
        return str(error)
    raise AssertionError("the loan was allowed")


# ---- the tests the base design already passes ------------------------------------------------------------------------
def check_lends_a_free_copy(m):
    lib = library(m)
    lib.lend("asha", "p-2")
    assert lib.holds("asha") == ["p-2"]


def check_no_free_copy_is_refused(m):
    lib = library(m, copies=1)
    lib.lend("asha", "p-1")
    assert refused(m, lambda: lib.lend("ravi", "p-1")) == "no copy of Clean Rivers is free"


def check_fourth_book_is_refused(m):
    lib = library(m)
    for isbn in ("p-1", "p-2", "p-3"):
        lib.lend("asha", isbn)
    assert refused(m, lambda: lib.lend("asha", "p-4")) == "Asha already holds 3 books"


def check_giving_back_frees_the_copy(m):
    lib = library(m, copies=1)
    lib.lend("asha", "p-1")
    lib.give_back("asha", "p-1")
    lib.lend("ravi", "p-1")
    assert (lib.holds("asha"), lib.holds("ravi")) == ([], ["p-1"])


BASE_TESTS = [check_lends_a_free_copy, check_no_free_copy_is_refused, check_fourth_book_is_refused,
              check_giving_back_frees_the_copy]


# ---- C1: a new variant ------------------------------------------------------------------------------------------------
def check_an_ebook_lends_to_everyone(m):
    lib = library(m, extra=[m.EBook("e-1", "Kite Science")])
    for key in PEOPLE:
        lib.lend(key, "e-1")
    assert all(lib.holds(key) == ["e-1"] for key in PEOPLE)


def check_an_ebook_counts_towards_the_limit(m):
    lib = library(m, extra=[m.EBook("e-1", "Kite Science")])
    for isbn in ("p-1", "p-2", "p-3"):
        lib.lend("asha", isbn)
    assert refused(m, lambda: lib.lend("asha", "e-1")) == "Asha already holds 3 books"


C1 = FollowUp(
    "C1", "Add e-books: any number of members may borrow the same e-book at once.",
    kind="variant", seam="Title.can_lend, which Library.lend already asks instead of counting copies itself",
    edits=[
        ("@dataclass\nclass Member:", '''class EBook(Title):
    """A licence the library may lend to any number of members at once."""

    def __init__(self, isbn, name):
        super().__init__(isbn, name, copies=0)

    def can_lend(self):
        return True


@dataclass
class Member:'''),
    ],
    tests=[check_an_ebook_lends_to_everyone, check_an_ebook_counts_towards_the_limit],
)


# ---- C2: a new rule ---------------------------------------------------------------------------------------------------
def check_a_student_holds_five(m):
    lib = m.Library([m.Title(isbn, name, 2) for isbn, name in BOOKS], [m.Member("sam", "Sam", kind="student")])
    for isbn, _ in BOOKS[:5]:
        lib.lend("sam", isbn)
    assert refused(m, lambda: lib.lend("sam", "p-6")) == "Sam already holds 5 books"


C2 = FollowUp(
    "C2", "Students may hold five books; everyone else still holds three.",
    kind="rule", seam="the limit, a constant that becomes a table by membership type",
    edits=[
        ("MAX_LOANS = 3\n", 'MAX_LOANS = {"adult": 3, "student": 5}  # books a member may hold, by membership\n'),
        ("    loans: list = field(default_factory=list)  # ISBNs of the books the member holds\n",
         '    loans: list = field(default_factory=list)  # ISBNs of the books the member holds\n    kind: str = "adult"\n'),
        ("""        if len(member.loans) >= MAX_LOANS:
            raise Refused(f"{member.name} already holds {MAX_LOANS} books")
""", """        limit = MAX_LOANS[member.kind]
        if len(member.loans) >= limit:
            raise Refused(f"{member.name} already holds {limit} books")
"""),
    ],
    tests=[check_a_student_holds_five],
)


# ---- C3: a rule with nowhere to live -----------------------------------------------------------------------------------
def check_overdue_loans_are_listed(m):
    lib = library(m)
    lib.lend("asha", "p-1", today=1)  # due back on day 15
    lib.lend("ravi", "p-2", today=10)  # due back on day 24
    assert lib.overdue(today=15) == []
    assert lib.overdue(today=17) == [("Asha", "Clean Rivers", 2)]
    lib.give_back("asha", "p-1")
    assert lib.overdue(today=30) == [("Ravi", "Monsoon Maths", 6)]


C3 = FollowUp(
    "C3", "Loans are due back after 14 days, and the desk wants the list of overdue books each morning.",
    kind="rule", seam="none yet: a loan is only an ISBN in a list, so its due day has nowhere to live",
    edits=[
        ("MAX_LOANS = 3\n", "MAX_LOANS = 3\nLOAN_DAYS = 14\n"),
        ("@dataclass\nclass Member:", '''@dataclass(frozen=True)
class Loan:
    isbn: str
    due: int  # the library's day number


@dataclass
class Member:'''),
        ("# ISBNs of the books the member holds", "# Loan records"),
        ("    def lend(self, member_id, isbn):\n", "    def lend(self, member_id, isbn, today=0):\n"),
        ("        member.loans.append(isbn)\n", "        member.loans.append(Loan(isbn, today + LOAN_DAYS))\n"),
        ("        member.loans.remove(isbn)\n", "        member.loans.remove(next(loan for loan in member.loans if loan.isbn == isbn))\n"),
        ("        return sorted(self._members[member_id].loans)\n", '''        return sorted(loan.isbn for loan in self._members[member_id].loans)

    def overdue(self, today):
        """(member, title, days late) for every loan past its due day."""
        return sorted((m.name, self._titles[loan.isbn].name, today - loan.due)
                      for m in self._members.values() for loan in m.loans if loan.due < today)
'''),
    ],
    tests=[check_overdue_loans_are_listed],
)

report("library.py", BASE_TESTS, [C1, C2, C3])

library.py: 4 of 4 tests pass on the base design

C1 [variant] Add e-books: any number of members may borrow the same e-book at once.
  seam: Title.can_lend, which Library.lend already asks instead of counting copies itself
  changed: +6 -0 lines; untouched: Refused, Title, Member, Library
  EBook: new, 6 lines
  tests: old 4/4 pass on the new code; new 0/2 on the old code, 2/2 on the new
    on the old code: check_an_ebook_lends_to_everyone: AttributeError: module 'library_base' has no attribute 'EBook'

C2 [rule] Students may hold five books; everyone else still holds three.
  seam: the limit, a constant that becomes a table by membership type
  changed: +5 -3 lines; untouched: Refused, Title
  top level
    - MAX_LOANS = 3
    + MAX_LOANS = {"adult": 3, "student": 5}  # books a member may hold, by membership
  Member
    + kind: str = "adult"
  Library.lend
    - if len(member.loans) >= MAX_LOANS:
    -     raise Refused(f"{member.name} already holds {MAX_LOANS} books")
    + limit = MAX_LOANS[member.kind]
    + if len(member.loans) >= limit:
    +     raise Refused(f"{member.name} already holds {limit} books")
  tests: old 4/4 pass on the new code; new 0/1 on the old code, 1/1 on the new
    on the old code: check_a_student_holds_five: TypeError: Member.__init__() got an unexpected keyword argument 'kind'

C3 [rule] Loans are due back after 14 days, and the desk wants the list of overdue books each morning.
  seam: none yet: a loan is only an ISBN in a list, so its due day has nowhere to live
  changed: +14 -5 lines; untouched: Refused, Title
  top level
    + LOAN_DAYS = 14
  Loan: new, 4 lines
  Member
    - loans: list = field(default_factory=list)  # ISBNs of the books the member holds
    + loans: list = field(default_factory=list)  # Loan records
  Library.lend
    - def lend(self, member_id, isbn):
    + def lend(self, member_id, isbn, today=0):
      ...
    -     member.loans.append(isbn)
    +     member.loans.append(Loan(isbn, today + LOAN_DAYS))
  Library.give_back
    - member.loans.remove(isbn)
    + member.loans.remove(next(loan for loan in member.loans if loan.isbn == isbn))
  Library.holds
    - return sorted(self._members[member_id].loans)
    + return sorted(loan.isbn for loan in self._members[member_id].loans)
  Library.overdue: new, 4 lines
  tests: old 4/4 pass on the new code; new 0/1 on the old code, 1/1 on the new
    on the old code: check_overdue_loans_are_listed: TypeError: Library.lend() got an unexpected keyword argument 'today'

followups/library.py

"""A small lending library as it stands after a timed round: titles with copies, members who hold a few books."""

from dataclasses import dataclass, field

MAX_LOANS = 3


class Refused(Exception):
    """A loan the rules do not allow."""


class Title:
    def __init__(self, isbn, name, copies):
        self.isbn, self.name, self.copies = isbn, name, copies
        self.lent = 0

    def can_lend(self):
        return self.lent < self.copies

    def lend(self):
        self.lent += 1

    def give_back(self):
        self.lent -= 1


@dataclass
class Member:
    id: str
    name: str
    loans: list = field(default_factory=list)  # ISBNs of the books the member holds


class Library:
    def __init__(self, titles, members):
        self._titles = {t.isbn: t for t in titles}
        self._members = {m.id: m for m in members}

    def lend(self, member_id, isbn):
        member, title = self._members[member_id], self._titles[isbn]
        if len(member.loans) >= MAX_LOANS:
            raise Refused(f"{member.name} already holds {MAX_LOANS} books")
        if not title.can_lend():
            raise Refused(f"no copy of {title.name} is free")
        title.lend()
        member.loans.append(isbn)

    def give_back(self, member_id, isbn):
        member = self._members[member_id]
        member.loans.remove(isbn)
        self._titles[isbn].give_back()

    def holds(self, member_id):
        return sorted(self._members[member_id].loans)