SOLID Principles: Practice Workbook

Prerequisite: 02_solid_principles.md. This workbook assumes the five principles have already been defined and demonstrated. It contains no new theory. Its purpose is to convert conceptual knowledge into diagnostic skill.

Table of Contents

1. How to Use This Workbook
2. Vocabulary and the Diagnostic Method
3. Section A: Recognition Drills
4. Section B: Single Responsibility Principle
5. Section C: Open/Closed Principle
6. Section D: Liskov Substitution Principle
7. Section E: Interface Segregation Principle
8. Section F: Dependency Inversion Principle
9. Section G: Combined Violations
10. Section H: Capstone Refactor
11. Self-Review Checklist
12. Summary and Key Takeaways
13. Appendix: Violation Signature Reference

1. How to Use This Workbook

1.1 What this document is for

Knowing the definition of the Single Responsibility Principle and being able to detect a Single Responsibility violation in unfamiliar code are two different competencies. The first is declarative knowledge and can be acquired by reading. The second is a diagnostic skill and can only be acquired by repeated exposure to examples, followed by correction.

This workbook supplies that exposure. It contains 24 problems arranged so that each principle is encountered three times at increasing levels of difficulty, then encountered again in combination with other principles, and finally encountered inside a single large class that violates all five at once. The last arrangement is the one that occurs in production code and in design interviews.

The objective is stated precisely as follows. On completing this workbook, a learner presented with an unfamiliar class of 40 to 60 lines should be able to state which principles are under strain, justify each claim by pointing to specific lines, and describe the direction of the correction without needing to consult reference material.

1.2 The three difficulty levels

Every section progresses through three levels. The levels are not merely longer problems; they exercise different cognitive operations.

Level 1 tests whether the violation signature is recognised. Level 2 tests whether the correction is known. Level 3 tests whether the principle has been internalised well enough to prevent the violation from occurring in the first place, which is the only level that transfers directly to real work.

Learners who find Level 2 comfortable should not treat Level 3 as optional. Correcting supplied code is a substantially easier task than designing structure from a requirement, because the supplied code already contains the domain vocabulary, the method names, and the data shapes. At Level 3 none of that is given.

1.3 Working method

Each problem states its requirements completely before the solution appears. The solution is preceded by a horizontal rule and a ### Solution heading so that it can be scrolled past. The recommended procedure is:

1. Read the problem statement and the code, if code is supplied.
2. Write the diagnosis in your own words before writing any code. A diagnosis that cannot be written in two sentences is usually incomplete.
3. Produce the correction or the design.
4. Read the solution and compare, paying attention to the reasoning rather than to superficial differences in naming.

Differences in class names, in the choice between abc.ABC and typing.Protocol, and in the placement of small helper methods are not errors. Differences in where the dependencies are created, in which class owns which decision, and in whether new behaviour requires editing existing code are errors, and they are the differences worth studying.

1.4 Recommended schedule

The workbook is designed for two passes separated by at least one week.

The difference between the two passes is the useful measurement. A principle that is diagnosed correctly in the first pass and incorrectly in the second was never learned; it was recalled.

2. Vocabulary and the Diagnostic Method

2.1 Terms used throughout the solutions

Precise vocabulary is what allows a diagnosis to be stated in two sentences instead of two paragraphs. The following terms appear repeatedly in the solutions and are defined here for reference.

2.2 A repeatable scan

Diagnosis is faster and more reliable when it follows a fixed order rather than an intuition. The following five questions, asked in this sequence, will locate the majority of violations in a class of moderate size. The ordering matters: responsibility defects are addressed first because they frequently cause the others, and a class that has been correctly split often turns out to have no remaining extensibility or dependency problem.

1. Enumerate the reasons this class would be edited. List them as concrete requirement changes, not as abstract categories. If the list has more than one entry, the Single Responsibility Principle is under strain.
2. Search for conditional chains keyed on a type, a mode, or a string constant. Each such chain is a location that must be edited when a new variant appears, which is an Open/Closed defect.
3. Inspect every override for narrowed behaviour. An override that raises an exception the base does not declare, that rejects inputs the base accepts, or that guarantees less than the base promises is a Liskov violation.
4. Inspect every implementer for unused inherited obligations. A method implemented as pass, as return None, or as raise NotImplementedError indicates that the interface obliges the implementer to declare capability it does not have, which is an Interface Segregation defect.
5. Locate every point at which the class obtains a collaborator. A collaborator constructed inside the class, imported as a module-level singleton, or read from global configuration is a Dependency Inversion defect, because it removes the seam at which substitution would occur.

2.3 The relationship between the answers

The five questions are not independent, and the solutions in this workbook repeatedly rely on the following relationships.

The practical consequence is that a diagnosis naming one violation is usually incomplete. Section G and Section H are built specifically to train the habit of enumerating all of them.

3. Section A: Recognition Drills

Five short fragments follow. For each one, name the principle under strain and state the reason in a single sentence. No code is to be written. The intended time is two to four minutes per fragment, which is short enough to force pattern recognition rather than deliberation.

The fragments are drawn from five different domains deliberately. A learner who practises on a single domain begins to recognise the domain rather than the defect.

Drill A.1

class PatientRecord:
    def __init__(self, patient_id: str, name: str, contact: str):
        self.patient_id = patient_id
        self.name = name
        self.contact = contact
        self.visits = []

    def update_contact(self, new_contact: str) -> None:
        self.contact = new_contact

    def add_visit(self, visit) -> None:
        self.visits.append(visit)

    def send_discharge_email(self, smtp_host: str, smtp_user: str) -> None:
        import smtplib
        server = smtplib.SMTP(smtp_host)
        server.login(smtp_user, "hunter2")
        server.sendmail(smtp_user, self.contact, f"Discharge summary for {self.name}")
        server.quit()

    def generate_pdf_summary(self, output_path: str) -> None:
        with open(output_path, "wb") as handle:
            handle.write(b"%PDF-1.4 ... rendered visit history ...")

    def save_to_database(self, connection) -> None:
        connection.execute(
            "INSERT INTO patients (id, name, contact) VALUES (?, ?, ?)",
            (self.patient_id, self.name, self.contact),
        )

Question: Which principle is violated, and why?

Solution A.1

Single Responsibility Principle.

The class holds four independent reasons to change: the structure of patient data, the mail transport mechanism, the layout of the printed discharge summary, and the relational schema used for persistence. A migration from SMTP to a transactional email API, a change to the PDF layout, and a change to the database schema are three unrelated requirements originating from three different stakeholder roles, yet all three arrive at this one file.

The direction of correction is to reduce PatientRecord to the data and the rules that govern that data, and to relocate mail transport, document rendering, and persistence into separate collaborators. Note that the mail and persistence methods also constitute a Dependency Inversion defect, because smtplib is imported and used directly rather than being reached through an abstraction. The responsibility defect is the primary one, because correcting it is what creates the classes in which the dependency can then be injected.

Drill A.2

class ShippingCostCalculator:
    def calculate(self, order, courier: str) -> float:
        weight = order.total_weight_kg
        if courier == "bluedart":
            return 40.0 + (12.0 * weight)
        elif courier == "delhivery":
            return 35.0 + (10.5 * weight) + (20.0 if order.is_cod else 0.0)
        elif courier == "indiapost":
            base = 25.0 + (8.0 * weight)
            return base * 0.5 if order.is_book_media else base
        elif courier == "fedex":
            return 150.0 + (30.0 * weight) if order.is_international else 90.0 + (18.0 * weight)
        else:
            raise ValueError(f"Unsupported courier: {courier}")

Question: Which principle is violated, and why?

Solution A.2

Open/Closed Principle.

Every additional courier requires an edit inside calculate, which means the class is not closed against a change that is certain to recur. The specific cost of this arrangement is that adding a courier requires re-testing the rate logic of every existing courier, because all of it lives in one method that has just been modified.

The direction of correction is to define an abstraction representing a courier rate card with a single method that returns a cost for an order, to implement one class per courier, and to reduce the calculator to a lookup and a delegation. Adding a courier then consists of adding a class and registering it, with no edit to any existing rate logic.

A secondary observation worth making at this stage is that the four branches contain genuinely different business rules: a cash-on-delivery surcharge, a media discount, and an international multiplier. These are separate policies that have been co-located purely because they share a method, which is also a responsibility defect.

Drill A.3

class SavingsAccount:
    def __init__(self, account_no: str, balance: float):
        self.account_no = account_no
        self.balance = balance

    def deposit(self, amount: float) -> None:
        self.balance += amount

    def withdraw(self, amount: float) -> float:
        if amount > self.balance:
            raise ValueError("Insufficient funds")
        self.balance -= amount
        return amount


class FixedDepositAccount(SavingsAccount):
    def withdraw(self, amount: float) -> float:
        raise PermissionError("Fixed deposits cannot be withdrawn before maturity")


def sweep_idle_funds(account: SavingsAccount, target) -> None:
    if account.balance > 100_000:
        surplus = account.balance - 100_000
        account.withdraw(surplus)
        target.deposit(surplus)

Question: Which principle is violated, and why?

Solution A.3

Liskov Substitution Principle.

sweep_idle_funds is written against the contract of SavingsAccount, which promises that withdraw succeeds whenever the requested amount does not exceed the balance. FixedDepositAccount is a declared subtype and is therefore accepted by the parameter, but it violates that promise unconditionally by raising PermissionError, an exception type the base contract never declares. The caller has no way to anticipate the failure short of testing the concrete type, which is precisely what subtype polymorphism is supposed to eliminate.

The direction of correction is to reject the inheritance relationship rather than to defend against it at the call site. A fixed deposit is not a savings account with one method disabled; it is a distinct product whose funds are not withdrawable on demand. Section D develops the two acceptable corrections in detail: separating the withdrawable capability into its own abstraction, or widening the base contract so that a refusal to withdraw is a declared and expected outcome rather than a surprise.

Drill A.4

from abc import ABC, abstractmethod


class RideVehicle(ABC):
    @abstractmethod
    def start_ride(self, rider_id: str) -> None: ...

    @abstractmethod
    def end_ride(self, rider_id: str) -> float: ...

    @abstractmethod
    def load_luggage(self, pieces: int) -> None: ...

    @abstractmethod
    def install_child_seat(self) -> None: ...

    @abstractmethod
    def enable_air_conditioning(self) -> None: ...


class Motorbike(RideVehicle):
    def start_ride(self, rider_id: str) -> None:
        print(f"Bike ride started for {rider_id}")

    def end_ride(self, rider_id: str) -> float:
        return 48.0

    def load_luggage(self, pieces: int) -> None:
        pass

    def install_child_seat(self) -> None:
        pass

    def enable_air_conditioning(self) -> None:
        pass

Question: Which principle is violated, and why?

Solution A.4

Interface Segregation Principle.

RideVehicle obliges every implementer to declare five capabilities, but a motorbike possesses only two of them. The three empty implementations are not harmless boilerplate; each one is a false statement about the object’s capability, and it is a statement that client code is entitled to rely on. A booking flow holding a RideVehicle reference will call install_child_seat and receive silent success, which is worse than an error because the failure surfaces later, at the kerb, rather than at the point of the mistaken call.

The direction of correction is to decompose the interface along the lines of client need: a Rideable abstraction carrying the two lifecycle methods, and separate LuggageCapable, ChildSeatCapable, and ClimateControlled abstractions. Motorbike then implements only Rideable, and its declared type contains no untrue promises.

Note the coupling to the Liskov Substitution Principle. Had the three unsupported methods raised NotImplementedError instead of silently passing, the same fragment would additionally be a Liskov violation. The underlying defect is identical in both variants: the interface promises more than the implementer can deliver, and the implementer is forced to choose between lying quietly and failing loudly.

Drill A.5

class InventoryService:
    def __init__(self):
        self.repository = MySQLInventoryRepository(
            host="prod-inventory.internal", user="svc_inv", password="s3cr3t"
        )
        self.notifier = FirebasePushSender(project_id="retail-prod-4417")

    def reserve(self, sku: str, quantity: int, customer_id: str) -> bool:
        available = self.repository.available_quantity(sku)
        if available < quantity:
            self.notifier.send(customer_id, f"{sku} is out of stock")
            return False
        self.repository.decrement(sku, quantity)
        self.notifier.send(customer_id, f"Reserved {quantity} units of {sku}")
        return True

Question: Which principle is violated, and why?

Solution A.5

Dependency Inversion Principle.

The reservation policy, which is the high-level concern of this class, is expressed in terms of two concrete low-level implementations that it constructs for itself. Two consequences follow directly. The reservation rule cannot be exercised in a test without a reachable MySQL instance and a valid Firebase project, because both objects are created during __init__ and the failure occurs before any policy code runs. Substituting a different data store or a different notification channel requires editing this class, even though the reservation rule itself is unchanged.

The direction of correction is to define InventoryRepository and Notifier abstractions expressing only what the reservation policy requires, to accept both through the constructor, and to move the selection of MySQL and Firebase to the composition root. The credentials embedded in the constructor are a separate defect of a different kind and should also be relocated to configuration, but the structural problem is the absence of a seam.

Section A review

The rightmost column is the operative part of this table. Each signature is a syntactic pattern that can be spotted without understanding the domain, which is what makes rapid diagnosis possible in unfamiliar code.

4. Section B: Single Responsibility Principle

The principle under examination states that a module should have exactly one reason to change. The formal statement given by Robert C. Martin is that a module should be responsible to one, and only one, actor. The practical test used throughout this section is the enumeration described in Section 2.2: list the concrete requirement changes that would force an edit to the class, and count the distinct stakeholder roles those changes originate from.

Problem B.1 (Level 1)

A content platform contains the following class.

class BlogPost:
    def __init__(self, author_id: str):
        self.author_id = author_id
        self.title = ""
        self.body = ""
        self.tags: list[str] = []
        self.published = False

    def set_title(self, title: str) -> None:
        if len(title) > 120:
            raise ValueError("Title exceeds 120 characters")
        self.title = title

    def set_body(self, body: str) -> None:
        self.body = body

    def format_as_html(self) -> str:
        tag_markup = "".join(f"<span class='tag'>{t}</span>" for t in self.tags)
        return f"<article><h1>{self.title}</h1>{tag_markup}<div>{self.body}</div></article>"

    def format_as_markdown(self) -> str:
        tag_line = " ".join(f"#{t}" for t in self.tags)
        return f"# {self.title}\n\n{tag_line}\n\n{self.body}"

    def save_to_db(self, conn) -> None:
        conn.execute(
            "REPLACE INTO posts (author, title, body) VALUES (?, ?, ?)",
            (self.author_id, self.title, self.body),
        )

    def email_to_subscribers(self, subscriber_emails: list[str]) -> None:
        for address in subscriber_emails:
            print(f"POST /sendgrid/v3/mail/send to {address}: {self.title}")

Questions:

1. How many responsibilities does this class hold? Name each one and identify the stakeholder role it belongs to.
2. Which requirement changes would force an edit to this class despite having nothing to do with the data or rules of a blog post?

Solution B.1

Four responsibilities, belonging to four stakeholder roles.

Answer to question 2. A redesign of the article markup, a change to the storage schema, and a change of email vendor are three requirement changes that arrive from three different teams and none of which concerns what a blog post is or what makes one valid. Each of them nevertheless forces an edit to BlogPost. The direct operational consequence is that these four teams contend for the same file, so their changes must be sequenced, reviewed together, and released together, and a defect introduced by any one of them is attributed to a class the other three also depend on.

A useful supplementary observation concerns the naming test. The class is called BlogPost, which correctly describes only the first responsibility. A name that described the class as it currently stands would be something on the order of BlogPostWithRenderingAndStorageAndNotification, and the awkwardness of that name is a reliable signal. When an honest name for a class requires a conjunction, the class holds more than one responsibility.

Problem B.2 (Level 2)

The following class belongs to a human resources reporting tool. It works correctly. Diagnose its structural defects and produce a corrected version that preserves the existing behaviour.

class EmployeeReport:
    def __init__(self, employees):
        self.employees = employees

    def get_top_performers(self):
        return [e for e in self.employees if e.performance_score > 8.0]

    def format_as_table(self):
        header = f"{'Name':<20} {'Score':<10} {'Department':<15}\n"
        rows = "\n".join(
            f"{e.name:<20} {e.performance_score:<10} {e.department:<15}"
            for e in self.employees
        )
        return header + rows

    def save_to_csv(self, filepath):
        import csv
        with open(filepath, "w") as f:
            writer = csv.DictWriter(f, fieldnames=["name", "score", "department"])
            writer.writeheader()
            for e in self.employees:
                writer.writerow({
                    "name": e.name,
                    "score": e.performance_score,
                    "department": e.department,
                })

    def send_to_hr(self, email_address):
        print(f"Emailing report to {email_address}")

Required:

1. Enumerate the responsibilities.
2. Refactor into separate classes, each with one reason to change.
3. State what each split makes possible that was not possible before.

Solution B.2

Diagnosis.

The class holds three responsibilities, and the fourth method reveals a dependency defect that becomes visible only after the split.

The first responsibility is analysis: deciding which employees qualify as top performers. The threshold of 8.0 is a business rule owned by the human resources policy team, and it is hard-coded into a method that cannot be reused with a different threshold.

The second responsibility is presentation: converting employee records into fixed-width text. Column widths, column order, and the choice of which fields appear are owned by whoever consumes the report.

The third responsibility is transport and serialisation: writing CSV to a filesystem path and sending mail. These are infrastructure concerns owned by the platform team, and they carry the additional problem that save_to_csv reaches directly for the filesystem and send_to_hr reaches directly for a mail mechanism, so neither can be exercised without side effects.

There is a fourth defect that is a consequence of the first three. format_as_table ignores the result of get_top_performers and formats self.employees in its entirety, while the class name promises a report about top performers. When several responsibilities share mutable state, inconsistencies of this kind become easy to introduce and hard to notice, which is one of the concrete costs of the violation rather than an accident of this particular example.

Corrected version.

from __future__ import annotations

import csv
from dataclasses import dataclass
from typing import Iterable, Protocol, Sequence


@dataclass(frozen=True)
class Employee:
    name: str
    performance_score: float
    department: str


# Responsibility 1: analysis. Owns the question of who qualifies.
class PerformanceAnalyser:
    def __init__(self, threshold: float = 8.0):
        self._threshold = threshold

    def top_performers(self, employees: Iterable[Employee]) -> list[Employee]:
        return [e for e in employees if e.performance_score > self._threshold]


# Responsibility 2: presentation. Owns layout only, and returns text
# rather than writing it anywhere.
class TableFormatter:
    COLUMNS = ("Name", "Score", "Department")

    def render(self, employees: Sequence[Employee]) -> str:
        header = f"{self.COLUMNS[0]:<20} {self.COLUMNS[1]:<10} {self.COLUMNS[2]:<15}"
        rows = [
            f"{e.name:<20} {e.performance_score:<10} {e.department:<15}"
            for e in employees
        ]
        return "\n".join([header, *rows])


# Responsibility 3: serialisation to a tabular file format.
class CsvExporter:
    FIELDS = ("name", "score", "department")

    def export(self, employees: Sequence[Employee], filepath: str) -> None:
        with open(filepath, "w", newline="") as handle:
            writer = csv.DictWriter(handle, fieldnames=self.FIELDS)
            writer.writeheader()
            for e in employees:
                writer.writerow({
                    "name": e.name,
                    "score": e.performance_score,
                    "department": e.department,
                })


# Responsibility 4: delivery, expressed as an abstraction so that the
# coordinator does not depend on any particular mail vendor.
class ReportDelivery(Protocol):
    def deliver(self, recipient: str, subject: str, body: str) -> None: ...


class ConsoleDelivery:
    def __init__(self) -> None:
        self.delivered: list[tuple[str, str, str]] = []

    def deliver(self, recipient: str, subject: str, body: str) -> None:
        self.delivered.append((recipient, subject, body))
        print(f"To {recipient}: {subject}")


# Coordination. Owns the sequence of steps, none of the steps themselves.
class TopPerformerReport:
    def __init__(
        self,
        analyser: PerformanceAnalyser,
        formatter: TableFormatter,
        delivery: ReportDelivery,
    ):
        self._analyser = analyser
        self._formatter = formatter
        self._delivery = delivery

    def send(self, employees: Sequence[Employee], recipient: str) -> str:
        qualifying = self._analyser.top_performers(employees)
        body = self._formatter.render(qualifying)
        self._delivery.deliver(recipient, "Top performers", body)
        return body

What each split makes possible.

The last row is the most important, because it is the one that changes daily working conditions. The qualification rule is the part of this code most likely to contain a business defect, and after the split it is testable in three lines with no filesystem and no mail transport.

Two points of technique deserve comment. First, TableFormatter.render returns a string and writes nothing, which is what allows the same output to be delivered by mail, written to a file, or asserted in a test. A formatter that performs its own output has silently absorbed a second responsibility. Second, ReportDelivery is declared as a Protocol rather than an abstract base class, which means ConsoleDelivery satisfies it structurally without inheriting from it. This matters when the implementer is a third-party object that cannot be made to inherit from an abstraction defined in this codebase.

Problem B.3 (Level 3)

Scenario. A restaurant management system must support the following order lifecycle.

A waiter creates an order against a table and adds items to it. Items may be added or removed while the order is open. When the waiter places the order, the kitchen must be notified of the items to prepare. The kitchen marks items ready, and when all items are ready the order is served. When the order is closed, the billing system must compute the payable amount including a service charge and applicable tax, an invoice must be produced in a printable form, and the customer must receive a receipt by either SMS or email according to the contact details held for the table’s guest.

Orders may be cancelled while open, in which case no notification, no bill, and no receipt are produced. Cancellation after placement requires a manager override and must be recorded for audit.

Required:

1. Identify the responsibilities present in this scenario and assign each to a class.
2. Present the design as a table of classes, responsibilities, and key method signatures.
3. Write the code for the coordinating class and the signatures of the collaborators. Full implementations of the collaborators are not required.
4. Write a short justification of the design decisions, stating in each case which future change the decision protects against.

Solution B.3

Step 1: separating the responsibilities in the requirement text.

The requirement contains six distinct concerns, and identifying them from prose is the skill this problem exercises. A reliable technique is to underline each noun phrase that names an artefact or a rule, then group the verbs that act on it.

Step 2: the design.

Step 3: the code.

from __future__ import annotations

from dataclasses import dataclass, field
from enum import Enum
from typing import Protocol


class OrderStatus(Enum):
    OPEN = "open"
    PLACED = "placed"
    SERVED = "served"
    CLOSED = "closed"
    CANCELLED = "cancelled"


@dataclass(frozen=True)
class OrderItem:
    menu_item_id: str
    name: str
    unit_price: float
    quantity: int

    @property
    def line_total(self) -> float:
        return self.unit_price * self.quantity


@dataclass(frozen=True)
class Bill:
    subtotal: float
    service_charge: float
    tax: float

    @property
    def total(self) -> float:
        return self.subtotal + self.service_charge + self.tax


class IllegalTransition(Exception):
    """Raised when a lifecycle operation is invalid for the current status."""


class Order:
    """Holds order state and guards its own invariants. Knows nothing about
    kitchens, money, documents, messaging, or audit."""

    def __init__(self, order_id: str, table_no: int):
        self.order_id = order_id
        self.table_no = table_no
        self._items: list[OrderItem] = []
        self._ready: set[str] = set()
        self._status = OrderStatus.OPEN

    @property
    def status(self) -> OrderStatus:
        return self._status

    @property
    def items(self) -> tuple[OrderItem, ...]:
        return tuple(self._items)

    def add_item(self, item: OrderItem) -> None:
        self._require(OrderStatus.OPEN, "add items")
        self._items.append(item)

    def remove_item(self, menu_item_id: str) -> None:
        self._require(OrderStatus.OPEN, "remove items")
        self._items = [i for i in self._items if i.menu_item_id != menu_item_id]

    def place(self) -> None:
        self._require(OrderStatus.OPEN, "place")
        if not self._items:
            raise IllegalTransition("Cannot place an order with no items")
        self._status = OrderStatus.PLACED

    def mark_item_ready(self, menu_item_id: str) -> None:
        self._require(OrderStatus.PLACED, "mark items ready")
        self._ready.add(menu_item_id)

    def all_items_ready(self) -> bool:
        return {i.menu_item_id for i in self._items} <= self._ready

    def serve(self) -> None:
        self._require(OrderStatus.PLACED, "serve")
        if not self.all_items_ready():
            raise IllegalTransition("Cannot serve before all items are ready")
        self._status = OrderStatus.SERVED

    def close(self) -> None:
        self._require(OrderStatus.SERVED, "close")
        self._status = OrderStatus.CLOSED

    def cancel(self) -> None:
        if self._status in (OrderStatus.CLOSED, OrderStatus.CANCELLED):
            raise IllegalTransition(f"Cannot cancel an order that is {self._status.value}")
        self._status = OrderStatus.CANCELLED

    def _require(self, expected: OrderStatus, action: str) -> None:
        if self._status is not expected:
            raise IllegalTransition(
                f"Cannot {action} while order is {self._status.value}"
            )


# ---------- Collaborator contracts, signatures only ----------

class KitchenNotifier(Protocol):
    def notify(self, order: Order) -> None: ...


class BillCalculator(Protocol):
    def calculate(self, order: Order) -> Bill: ...


class InvoiceRenderer(Protocol):
    def render(self, order: Order, bill: Bill) -> str: ...


class ReceiptSender(Protocol):
    def send(self, contact: str, document: str) -> None: ...


class AuditLog(Protocol):
    def record(self, event_type: str, payload: dict) -> None: ...


# ---------- Coordination ----------

class OrderService:
    """Owns the sequence in which collaborators are invoked. Contains no
    kitchen logic, no arithmetic, no formatting, and no transport."""

    def __init__(
        self,
        kitchen: KitchenNotifier,
        calculator: BillCalculator,
        renderer: InvoiceRenderer,
        receipts: ReceiptSender,
        audit: AuditLog,
    ):
        self._kitchen = kitchen
        self._calculator = calculator
        self._renderer = renderer
        self._receipts = receipts
        self._audit = audit

    def place_order(self, order: Order) -> None:
        order.place()
        self._kitchen.notify(order)

    def close_order(self, order: Order, guest_contact: str) -> str:
        order.close()
        bill = self._calculator.calculate(order)
        invoice = self._renderer.render(order, bill)
        self._receipts.send(guest_contact, invoice)
        return invoice

    def cancel_order(self, order: Order, manager_id: str | None = None) -> None:
        requires_override = order.status is not OrderStatus.OPEN
        if requires_override and manager_id is None:
            raise PermissionError("Manager override required after placement")

        previous = order.status
        order.cancel()

        if requires_override:
            self._audit.record(
                "order_cancelled_after_placement",
                {
                    "order_id": order.order_id,
                    "previous_status": previous.value,
                    "manager_id": manager_id,
                },
            )

Step 4: design decisions and the changes they protect against.

The lifecycle rules live in Order, not in OrderService. The condition that an order cannot be served before all its items are ready is an invariant of an order, and placing it in the object that owns the state means no code path can bypass it. Had the check lived in OrderService.serve_order, a second caller added later, for example a bulk-close routine at end of shift, would be able to reach an inconsistent state. This decision protects against invariant violations introduced by new callers.

OrderService contains sequencing and nothing else. Every method in it reads as a short list of steps delegated elsewhere. This is the correct shape for a coordinator, and it provides a test that can be applied to any coordinator: if arithmetic, string formatting, or if statements about business values appear in it, a responsibility has leaked in.

Bill calculation is separated from invoice rendering. These are frequently combined because both concern the printed bill, and the separation is the single decision in this design most likely to be omitted. They change for unrelated reasons. A change in the tax rate is imposed externally, must be applied on a specific date, and must be verifiable by finance. A change in the printed layout comes from operations and has no financial consequence. Keeping them separate means the tax change is a two-line edit to a class whose entire content is arithmetic and is therefore straightforward to test exhaustively.

Receipt dispatch is one abstraction, not two. The requirement mentions SMS and email, which suggests two classes. The correct reading is that both are instances of the same role, delivering a document to a contact address, so both implement ReceiptSender. The decision of which to use for a given guest is a selection among implementations and belongs either at the composition root or in a small dispatching implementation of the same interface. This protects against the arrival of a third channel, which then requires no change to OrderService.

Audit recording is invoked by the coordinator rather than by Order. Auditing is an obligation of the enclosing process, not a property of an order. If Order.cancel wrote audit records, then constructing an order in a test would require an audit sink, and the domain object would depend on infrastructure.

Cancellation before placement produces no bill, no receipt, and no audit record. This is visible in the code as the absence of calls rather than as a conditional, because the requirement was read carefully: the manager override and the audit record are both consequences of the same condition, that the order has already been placed. Deriving requires_override once and using it twice keeps the two consequences in agreement, which is preferable to writing two independent status checks that a later edit could allow to diverge.

Section B review

5. Section C: Open/Closed Principle

The principle under examination states that a module should be open for extension and closed for modification. New behaviour should be addable by writing new code rather than by editing code that already works and is already tested.

The practical significance is a matter of risk rather than of elegance. Code that has been in production for a year has been validated by that year of operation. Editing it discards part of that validation, because the tests that pass now were written against the previous behaviour. Adding a new class alongside it discards none of it. The Open/Closed Principle is therefore best understood as a technique for confining the blast radius of a change.

Problem C.1 (Level 1)

A payments service contains the following method.

class PaymentProcessor:
    def process(self, payment) -> dict:
        if payment.method == "card":
            self._validate_card(payment.card_number, payment.cvv)
            fee = payment.amount * 0.02
            return {"status": "captured", "fee": fee, "gateway": "razorpay"}
        elif payment.method == "upi":
            if not payment.vpa.endswith(("@okhdfcbank", "@ybl", "@paytm")):
                return {"status": "rejected", "reason": "unsupported VPA"}
            return {"status": "captured", "fee": 0.0, "gateway": "npci"}
        elif payment.method == "netbanking":
            fee = 15.0
            return {"status": "pending", "fee": fee, "gateway": payment.bank_code}
        elif payment.method == "wallet":
            if payment.wallet_balance < payment.amount:
                return {"status": "rejected", "reason": "insufficient balance"}
            return {"status": "captured", "fee": 0.0, "gateway": "internal"}
        else:
            raise ValueError(f"Unknown payment method: {payment.method}")

    def _validate_card(self, number: str, cvv: str) -> None:
        if len(number) != 16 or len(cvv) != 3:
            raise ValueError("Invalid card")

Questions:

1. Which principle is violated?
2. Describe precisely what must happen when a cryptocurrency method is added, and state the risk that arises.
3. What is the direction of the correction?

Solution C.1

Answer to question 1. The Open/Closed Principle. process must be modified for every new payment method, so the class is not closed against the change that the business is most certain to request.

Answer to question 2. Adding a cryptocurrency method requires inserting a branch into process, which means editing a method that currently handles four working payment flows. Three risks follow, and they should be stated in this order of severity.

The first is regression risk. Card, UPI, netbanking, and wallet payments all flow through the modified method, so a mistake made while adding the new branch can break a payment method that is currently taking live money. The change cannot be reviewed in isolation, because the reviewer must reason about the whole method.

The second is test invalidation. The existing tests for process were written against a method that no longer exists in the same form. They may still pass, but they no longer constitute complete coverage of the method as modified, and determining what additional coverage is required is manual work that grows with each branch.

The third is deployment coupling. The cryptocurrency feature cannot be released independently of the existing payment methods, because it ships inside the same class. If the new method must be disabled after release, the rollback affects code paths that were working.

Answer to question 3. Each payment method becomes a class implementing a common abstraction with a single method that accepts a payment and returns a result. PaymentProcessor holds a mapping from method identifier to handler and delegates to the selected handler. The conditional chain disappears entirely, because the mapping lookup performs the selection that the chain was performing. Adding cryptocurrency then consists of writing one new class and adding one entry to the registry, and the existing four classes are neither edited nor recompiled nor re-reviewed.

Two further observations are worth recording. First, the four branches contain markedly different logic: card validation, VPA suffix checking, a flat fee, and a balance comparison. These are four independent policies, which is why the method also violates the Single Responsibility Principle. The two violations have the same correction, which is common. Second, the final else clause that raises ValueError is the only part of the chain that survives the refactor, appearing as the failure branch of the registry lookup.

Problem C.2 (Level 2)

An observability library contains the following class. Refactor it so that adding an XML format or an HTML format requires no modification to any existing class.

class LogFormatter:
    def format(self, log_entry, output_format: str) -> str:
        if output_format == "plain":
            return f"[{log_entry.level}] {log_entry.timestamp}: {log_entry.message}"
        elif output_format == "json":
            import json
            return json.dumps({
                "level": log_entry.level,
                "timestamp": str(log_entry.timestamp),
                "message": log_entry.message,
            })
        elif output_format == "csv":
            return f"{log_entry.level},{log_entry.timestamp},{log_entry.message}"
        else:
            raise ValueError(f"Unknown format: {output_format}")

Required:

1. State the defect and the specific cost it imposes.
2. Produce the refactored design.
3. Show how a caller selects a format, and show what the addition of an XML formatter looks like.
4. Explain why the output_format string parameter disappears from the formatting call.

Solution C.2

Diagnosis.

The class conflates two decisions that occur at different times. The decision of which format to use is made once, at configuration time, by whoever operates the application. The decision of how to render a single entry is made on every log line. By taking output_format as a parameter of format, the class re-evaluates a configuration-time decision on every invocation, and it must contain every possible answer to that decision in order to do so.

The cost is that the class accumulates one branch per format and becomes a change magnet for a concern that is not shared between formats. The CSV rendering and the JSON rendering have nothing in common beyond their input type, so a defect fixed in one has no relationship to the other, yet both are edited in the same file and shipped together. A secondary cost is that the class cannot be extended by a consumer of the library at all. A user of this logging package who requires a proprietary format has no option but to modify the package source, which is the clearest possible demonstration that the class is not closed for modification.

Refactored design.

from __future__ import annotations

import json
from abc import ABC, abstractmethod
from dataclasses import dataclass
from datetime import datetime
from xml.sax.saxutils import escape


@dataclass(frozen=True)
class LogEntry:
    level: str
    timestamp: datetime
    message: str


class LogFormatter(ABC):
    """The abstraction. One responsibility: render a single entry as text."""

    @abstractmethod
    def format(self, entry: LogEntry) -> str: ...


class PlainFormatter(LogFormatter):
    def format(self, entry: LogEntry) -> str:
        return f"[{entry.level}] {entry.timestamp}: {entry.message}"


class JsonFormatter(LogFormatter):
    def format(self, entry: LogEntry) -> str:
        return json.dumps({
            "level": entry.level,
            "timestamp": entry.timestamp.isoformat(),
            "message": entry.message,
        })


class CsvFormatter(LogFormatter):
    def format(self, entry: LogEntry) -> str:
        message = entry.message.replace('"', '""')
        return f'{entry.level},{entry.timestamp.isoformat()},"{message}"'

The consumer of a formatter holds the abstraction and never learns which implementation it received.

class Logger:
    def __init__(self, formatter: LogFormatter, sink):
        self._formatter = formatter
        self._sink = sink

    def log(self, level: str, message: str) -> None:
        entry = LogEntry(level=level, timestamp=datetime.now(), message=message)
        self._sink.write(self._formatter.format(entry) + "\n")

Adding a format is now an addition of a file, with no edit anywhere else.

class XmlFormatter(LogFormatter):
    def format(self, entry: LogEntry) -> str:
        return (
            "<log>"
            f"<level>{escape(entry.level)}</level>"
            f"<timestamp>{entry.timestamp.isoformat()}</timestamp>"
            f"<message>{escape(entry.message)}</message>"
            "</log>"
        )

Where configuration supplies a format as a string, the mapping from string to implementation belongs in one place at the edge of the system rather than inside the formatting call path.

_FORMATTERS: dict[str, type[LogFormatter]] = {
    "plain": PlainFormatter,
    "json": JsonFormatter,
    "csv": CsvFormatter,
    "xml": XmlFormatter,
}


def formatter_from_config(name: str) -> LogFormatter:
    try:
        return _FORMATTERS[name]()
    except KeyError:
        raise ValueError(f"Unknown log format: {name}") from None

Answer to question 4. The output_format parameter disappears because the selection has been moved from call time to construction time, where it belongs. A Logger is constructed once with a JsonFormatter and thereafter produces JSON; there is no per-call decision to make. This relocation is the substance of the refactor, and the elimination of the conditional chain is its consequence rather than its goal. A refactor that kept the parameter and merely replaced the chain with a dictionary lookup inside format would remove the branches without removing the coupling, since the class would still need to know every available format.

Two points of technique appear in the code above and are worth noting because they are frequently missed. The registry maps names to classes rather than to instances, so a formatter that holds per-logger state remains safe to use. The CsvFormatter quotes and escapes the message field, and the XmlFormatter escapes its text nodes; these correctness details were absent from the original and become straightforward to add once each format occupies its own class, which is a practical benefit of the separation beyond extensibility.

Problem C.3 (Level 3)

Scenario. An e-commerce platform applies promotions to orders at checkout. Three promotion types exist today.

A flat discount reduces the order total by a fixed amount, for example 200 rupees off. A percentage discount reduces the total by a proportion, for example 10 percent, and is subject to a maximum discount cap. A buy-one-get-one promotion applies to a specified product and gives 50 percent off the second and subsequent qualifying units.

The marketing team introduces new promotion types every quarter and has already asked about free shipping above a threshold, a first-order discount, and a bundle price for a fixed set of products. Promotions may be combined on a single order, in which case they apply in a defined sequence, and the platform must be able to display a line-by-line breakdown of which promotion contributed which reduction.

Required:

1. Design a promotions system that is open to new promotion types without modification of the pricing engine.
2. Implement the abstraction, the three existing promotion types, and the pricing engine.
3. Support the line-by-line breakdown requirement.
4. Demonstrate the addition of a free-shipping promotion, and state precisely which existing files are edited.
5. Write the design decisions, including the reason for the chosen return type of the promotion method.

Solution C.3

Step 1: locating the axis of variation.

The requirement contains one axis that varies without limit, which is the set of promotion types, and one axis that is stable, which is the process of applying a list of promotions to an order and reporting the result. The Open/Closed Principle is applied by expressing the varying axis as implementations of an abstraction and the stable axis as a single class that depends only on that abstraction.

The breakdown requirement determines the shape of the abstraction and is the part of this problem most often designed incorrectly. If a promotion returns a number, the engine can compute a total but cannot report which promotion produced which reduction, and the natural repair is for the engine to inspect the promotion type in order to label the line, which reintroduces exactly the conditional chain that the design exists to eliminate. The abstraction must therefore return a value that carries its own description.

Step 2 and 3: implementation.

from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Sequence


@dataclass(frozen=True)
class OrderLine:
    product_id: str
    unit_price: float
    quantity: int

    @property
    def line_total(self) -> float:
        return self.unit_price * self.quantity


@dataclass(frozen=True)
class Order:
    order_id: str
    customer_id: str
    lines: tuple[OrderLine, ...]
    shipping_cost: float
    is_first_order: bool = False

    @property
    def item_subtotal(self) -> float:
        return sum(line.line_total for line in self.lines)


@dataclass(frozen=True)
class Discount:
    """The result of one promotion. Carries its own label so that the engine
    never needs to inspect the promotion type to describe the reduction."""

    label: str
    amount: float
    applies_to: str = "items"   # "items" or "shipping"

    @staticmethod
    def none(label: str) -> "Discount":
        return Discount(label=label, amount=0.0)

    @property
    def is_zero(self) -> bool:
        return self.amount <= 0.0


class Promotion(ABC):
    """The abstraction. A promotion decides whether it applies to an order and
    how large a reduction it produces. It never mutates the order and never
    knows about other promotions."""

    @property
    @abstractmethod
    def code(self) -> str: ...

    @abstractmethod
    def apply(self, order: Order, running_total: float) -> Discount: ...


class FlatDiscount(Promotion):
    def __init__(self, amount: float, minimum_order_value: float = 0.0):
        self._amount = amount
        self._minimum = minimum_order_value

    @property
    def code(self) -> str:
        return f"FLAT{int(self._amount)}"

    def apply(self, order: Order, running_total: float) -> Discount:
        if running_total < self._minimum:
            return Discount.none(self.code)
        return Discount(self.code, min(self._amount, running_total))


class PercentageDiscount(Promotion):
    def __init__(self, percent: float, maximum_discount: float | None = None):
        self._percent = percent
        self._cap = maximum_discount

    @property
    def code(self) -> str:
        return f"PCT{int(self._percent)}"

    def apply(self, order: Order, running_total: float) -> Discount:
        raw = running_total * (self._percent / 100.0)
        amount = min(raw, self._cap) if self._cap is not None else raw
        return Discount(self.code, amount)


class BuyOneGetHalfOff(Promotion):
    def __init__(self, product_id: str):
        self._product_id = product_id

    @property
    def code(self) -> str:
        return f"BOGO50:{self._product_id}"

    def apply(self, order: Order, running_total: float) -> Discount:
        qualifying = [l for l in order.lines if l.product_id == self._product_id]
        reduction = sum(
            line.unit_price * 0.5 * (line.quantity - 1)
            for line in qualifying
            if line.quantity > 1
        )
        return Discount(self.code, reduction)

The engine holds a sequence of promotions and knows nothing about any of them beyond the abstraction.

@dataclass(frozen=True)
class PricedOrder:
    item_subtotal: float
    shipping_cost: float
    breakdown: tuple[Discount, ...]

    @property
    def total_discount(self) -> float:
        return sum(d.amount for d in self.breakdown)

    @property
    def payable(self) -> float:
        return round(
            self.item_subtotal + self.shipping_cost - self.total_discount, 2
        )


class PricingEngine:
    """Stable. Applies promotions in the configured sequence and reports the
    result. Contains no promotion-specific logic and no conditional chain."""

    def __init__(self, promotions: Sequence[Promotion]):
        self._promotions = tuple(promotions)

    def price(self, order: Order) -> PricedOrder:
        running_total = order.item_subtotal
        shipping_remaining = order.shipping_cost
        applied: list[Discount] = []

        for promotion in self._promotions:
            discount = promotion.apply(order, running_total)
            if discount.is_zero:
                continue
            if discount.applies_to == "shipping":
                capped = Discount(
                    discount.label, min(discount.amount, shipping_remaining), "shipping"
                )
                shipping_remaining -= capped.amount
                applied.append(capped)
            else:
                capped = Discount(
                    discount.label, min(discount.amount, running_total), "items"
                )
                running_total -= capped.amount
                applied.append(capped)

        return PricedOrder(
            item_subtotal=order.item_subtotal,
            shipping_cost=order.shipping_cost,
            breakdown=tuple(applied),
        )

Step 4: adding a promotion type.

class FreeShippingAbove(Promotion):
    def __init__(self, threshold: float):
        self._threshold = threshold

    @property
    def code(self) -> str:
        return f"FREESHIP{int(self._threshold)}"

    def apply(self, order: Order, running_total: float) -> Discount:
        if running_total < self._threshold:
            return Discount.none(self.code)
        return Discount(self.code, order.shipping_cost, applies_to="shipping")

The files edited in order to introduce free shipping are: one new file containing FreeShippingAbove, and the composition root or campaign configuration where the active promotions for a campaign are listed. PricingEngine, FlatDiscount, PercentageDiscount, BuyOneGetHalfOff, Discount, and PricedOrder are all unmodified. No existing test requires revision, and the existing promotions require no re-review.

A worked example of the composition and the resulting breakdown:

order = Order(
    order_id="ORD-9001",
    customer_id="CUST-22",
    lines=(
        OrderLine("BOOK-1", 499.0, 3),
        OrderLine("MUG-7", 250.0, 1),
    ),
    shipping_cost=60.0,
    is_first_order=True,
)

engine = PricingEngine([
    BuyOneGetHalfOff("BOOK-1"),
    PercentageDiscount(percent=10, maximum_discount=150.0),
    FlatDiscount(amount=200.0, minimum_order_value=1000.0),
    FreeShippingAbove(threshold=750.0),
])

priced = engine.price(order)
for line in priced.breakdown:
    print(f"{line.label:<20} -{line.amount:>8.2f}  ({line.applies_to})")
print(f"{'Payable':<20}  {priced.payable:>8.2f}")

Step 5: design decisions.

The promotion method returns a Discount rather than a float or a modified order. Three candidate return types were available and the choice determines whether the design holds. Returning a float satisfies the arithmetic but destroys the breakdown, and it forces the engine to label lines by inspecting types. Returning a modified Order gives each promotion the power to alter any part of the order, which makes the effect of a promotion sequence unpredictable and makes each promotion far harder to test. Returning a descriptive value object gives the engine everything it needs to both compute and report while confining each promotion to producing a single number and a label. This decision protects against the breakdown requirement being satisfied by a type check, which is the failure mode this design exists to prevent.

Promotions receive the running total as an explicit parameter. The requirement states that promotions apply in a defined sequence, which means a percentage promotion applied after a flat discount must compute its percentage on the reduced amount. Passing running_total makes the ordering semantics explicit at the call site and keeps promotions free of mutable state. The alternative, in which each promotion reads a mutable amount from the order, produces promotions whose results depend on invocation history in ways that are not visible in their signatures.

Capping is enforced by the engine, not trusted to each promotion. A promotion that returns a reduction larger than the amount remaining would drive the payable total negative. Because promotions are written by many people over many quarters, the engine treats their output as untrusted and clamps it. This is a deliberate placement of a system-wide invariant in the one class that cannot be bypassed, and it is the same reasoning applied to Order in Problem B.3.

A promotion decides for itself whether it applies. The zero-valued Discount returned when a condition is unmet allows eligibility rules to live inside the promotion that owns them. The alternative of a separate is_applicable predicate on the abstraction requires the engine to call two methods in the correct order and permits an inconsistent implementation in which the predicate and the calculation disagree.

Shipping is modelled as a separate target rather than folded into the item total. Free shipping is already on the roadmap, and a promotion reducing shipping must not be permitted to reduce the item subtotal. Introducing the applies_to field costs one attribute and one branch in the engine, and it prevents an entire class of pricing defect. This is a case where a small anticipatory generalisation is justified, because the requirement explicitly names free shipping as forthcoming rather than merely conceivable.

Section C review

6. Section D: Liskov Substitution Principle

The principle under examination states that if S is a subtype of T, then objects of type T may be replaced with objects of type S without altering the correctness of the program. Barbara Liskov’s original formulation concerns the properties provable about supertype objects remaining provable about subtype objects.

The operational content of the principle is a set of rules governing what an override is permitted to do. An override may accept the same inputs or a wider range of inputs, but it may not narrow the accepted range, which is stated as the rule that preconditions may not be strengthened in a subtype. An override may guarantee the same outcome or a stronger outcome, but it may not guarantee less, which is stated as the rule that postconditions may not be weakened. An override may raise the exception types declared by the supertype or their subtypes, but it may not introduce new categories of failure. An override may not invalidate any invariant the supertype maintains.

Violations are diagnosed by reading the override against the base contract rather than by reading the override alone. This is what makes Liskov violations harder to spot than the other four: the defect is a mismatch between two locations, and neither location is wrong in isolation.

Problem D.1 (Level 1)

class Rectangle:
    def __init__(self, width: float, height: float):
        self._width = width
        self._height = height

    def set_width(self, width: float) -> None:
        self._width = width

    def set_height(self, height: float) -> None:
        self._height = height

    def area(self) -> float:
        return self._width * self._height


class Square(Rectangle):
    def __init__(self, side: float):
        super().__init__(side, side)

    def set_width(self, width: float) -> None:
        self._width = width
        self._height = width

    def set_height(self, height: float) -> None:
        self._width = height
        self._height = height


def resize_and_verify(shape: Rectangle) -> None:
    shape.set_width(5)
    shape.set_height(10)
    assert shape.area() == 50, f"Expected 50, got {shape.area()}"

Questions:

1. What happens when resize_and_verify receives a Square?
2. Which rule of the principle is broken, stated precisely?
3. Why is adding an isinstance check inside resize_and_verify not a correction?

Solution D.1

Answer to question 1. Setting the width to 5 also sets the height to 5. Setting the height to 10 also sets the width to 10. The area is 100 rather than 50, and the assertion fails. The function is correct with respect to the contract it was written against, and it fails only because it was handed an object whose declared type promises behaviour the object does not exhibit.

Answer to question 2. The rule broken is that invariants of the supertype must be preserved. Rectangle maintains the invariant that width and height are independent, which is observable through its public interface: after set_width(w) followed by set_height(h), the area is w * h for any w and h. Square cannot preserve this invariant, because its own invariant requires the two dimensions to be equal. Stated more sharply, Square weakens the postcondition of set_width from “the width is w and the height is unchanged” to “the width is w”, and every caller relying on the discarded clause is broken.

Answer to question 3. A type check inside the consumer is not a correction for three reasons, and the third is the decisive one.

It does not remove the defect; it documents it at every call site. The next function written against Rectangle will need the same guard, and the guard will be omitted somewhere.

It violates the Open/Closed Principle in the consumer. Each new shape subtype requires a new branch in every guard, so the number of edits grows as the product of subtypes and consumers.

It contradicts the purpose of subtype polymorphism. The reason to declare a parameter as Rectangle is to avoid knowing which concrete shape arrived. If the function must know, the type declaration is not providing the abstraction it appears to provide, and the inheritance relationship is providing no benefit while imposing a cost.

The correction is to recognise that the inheritance relationship is unsound as modelled. A square is a rectangle in geometry, where shapes are immutable values, and is not a rectangle in this design, where shapes have independently mutable dimensions. Two sound alternatives exist. Immutable shapes with a read-only area can be related by inheritance without difficulty, because there are no setters whose postconditions can be weakened. Alternatively, Square and Rectangle can be siblings implementing a common Shape abstraction that declares area and no dimension setters. The general lesson is that whether inheritance is valid depends on the mutability and the contract of the base, not on the taxonomy of the concepts.

Problem D.2 (Level 2)

A storage library contains the following hierarchy.

class FileStorage:
    def read(self, path: str) -> bytes:
        raise NotImplementedError

    def write(self, path: str, data: bytes) -> None:
        raise NotImplementedError

    def delete(self, path: str) -> None:
        raise NotImplementedError


class LocalFileStorage(FileStorage):
    def __init__(self, root: str):
        self._root = root

    def read(self, path: str) -> bytes:
        with open(f"{self._root}/{path}", "rb") as handle:
            return handle.read()

    def write(self, path: str, data: bytes) -> None:
        with open(f"{self._root}/{path}", "wb") as handle:
            handle.write(data)

    def delete(self, path: str) -> None:
        import os
        os.remove(f"{self._root}/{path}")


class ReadOnlyArchiveStorage(FileStorage):
    def __init__(self, bucket: str):
        self._bucket = bucket

    def read(self, path: str) -> bytes:
        return b"...object bytes from immutable archive..."

    def write(self, path: str, data: bytes) -> None:
        raise PermissionError("Archive storage is immutable")

    def delete(self, path: str) -> None:
        raise PermissionError("Archive storage is immutable")


def archive_and_purge(storage: FileStorage, path: str, destination: str) -> None:
    payload = storage.read(path)
    storage.write(destination, payload)
    storage.delete(path)

Required:

1. State the violation precisely and identify which caller is broken.
2. Explain why catching PermissionError in archive_and_purge is not the correction.
3. Redesign the hierarchy so that the defect is unrepresentable, and show the corrected signature of archive_and_purge.
4. Identify which additional principle the original code violates.

Solution D.2

Diagnosis.

FileStorage declares three capabilities, and its contract therefore promises that any instance can read, write, and delete. ReadOnlyArchiveStorage is a declared subtype and satisfies the interface syntactically while contradicting it semantically: two of its three methods fail unconditionally with an exception type the base contract never mentions. archive_and_purge is written against the base contract, is correct with respect to that contract, and fails at the second statement when handed an archive instance. The failure occurs after the read has succeeded, which means the function fails partway through a multi-step operation, and this is the practical reason the defect is expensive rather than merely inelegant.

Answer to question 2. Catching the exception addresses the symptom at one call site and leaves the defect in place. Three specific objections apply.

The handler has no correct action available. If the write fails because the target is immutable, the archiving operation cannot be completed, so the handler can only re-raise a different exception or silently abandon the work. Neither outcome is better than the original failure, and the second is worse.

The knowledge is in the wrong place. The call site learns, by experiment at runtime, a fact that was known statically at construction time, namely that this particular storage cannot be written to. Discovering statically available information through exception handling is a design defect independent of the principle being discussed.

It does not generalise. Every function in the library that writes or deletes requires the same handler, and each is an opportunity to omit it. The compiler and the type checker provide no assistance, because the declared type continues to promise the capability.

Corrected hierarchy.

The correction separates the capabilities into distinct abstractions, so that a function requiring write access cannot be handed an object that lacks it.

from abc import ABC, abstractmethod


class ReadableStorage(ABC):
    """Contract: read returns the bytes at path, or raises FileNotFoundError
    if no object exists at that path."""

    @abstractmethod
    def read(self, path: str) -> bytes: ...


class WritableStorage(ReadableStorage):
    """Contract: everything ReadableStorage promises, and in addition write
    stores data at path and delete removes it. Neither refuses on grounds of
    the store being immutable."""

    @abstractmethod
    def write(self, path: str, data: bytes) -> None: ...

    @abstractmethod
    def delete(self, path: str) -> None: ...


class LocalFileStorage(WritableStorage):
    def __init__(self, root: str):
        self._root = root

    def read(self, path: str) -> bytes:
        with open(f"{self._root}/{path}", "rb") as handle:
            return handle.read()

    def write(self, path: str, data: bytes) -> None:
        with open(f"{self._root}/{path}", "wb") as handle:
            handle.write(data)

    def delete(self, path: str) -> None:
        import os
        os.remove(f"{self._root}/{path}")


class ReadOnlyArchiveStorage(ReadableStorage):
    """Implements only what it can honour. There is no write method to break."""

    def __init__(self, bucket: str):
        self._bucket = bucket

    def read(self, path: str) -> bytes:
        return b"...object bytes from immutable archive..."

The consumers now declare the narrowest capability they require, which is what converts the runtime failure into a static error.

def archive_and_purge(
    source: ReadableStorage, sink: WritableStorage, path: str, destination: str
) -> None:
    """Reads from any readable store and writes to any writable store. The
    parameter types make it impossible to pass an immutable store as the sink."""
    payload = source.read(path)
    sink.write(destination, payload)


def load_manifest(storage: ReadableStorage) -> bytes:
    """Accepts both implementations, because both can genuinely read."""
    return storage.read("manifest.json")

Passing ReadOnlyArchiveStorage as the sink argument is now reported by a static type checker before the program runs, and no exception handler is required anywhere.

Note that the original single-parameter signature was itself part of the problem. A function that reads from and writes to the same storage object had conflated two roles, source and destination, that the corrected signature separates. Liskov violations frequently expose modelling errors of this kind in the consumers as well as in the hierarchy.

Answer to question 4. The original code also violates the Interface Segregation Principle, because FileStorage obliges every implementer to declare mutation capability regardless of whether it possesses any. This pairing is characteristic. An over-broad interface forces implementers to supply methods they cannot honour, and whichever way they discharge the obligation, by raising or by silently doing nothing, the result is a Liskov violation for the callers. Correcting the interface breadth is therefore usually the mechanism by which the substitution defect is removed, which is why the two principles are treated together in Section G.

Problem D.3 (Level 3)

Scenario. A retail bank offers three account products.

A savings account permits deposits and withdrawals at any time, provided the resulting balance does not fall below zero.

A current account permits deposits and withdrawals at any time and additionally permits the balance to fall to a negative overdraft limit agreed per customer.

A recurring deposit account accepts a fixed monthly deposit and permits no withdrawal at all until a maturity date, after which the entire balance may be withdrawn once and the account is closed.

The bank runs an end-of-day sweep process that moves any balance above a configured ceiling from a customer’s operating accounts into a nominated investment account. It also runs a monthly interest posting process that applies to all three products, and a statement generation process that applies to all three products.

Required:

1. Design a hierarchy in which no operation raises an exception that its declared type does not anticipate.
2. Present and justify a choice between the two available correction strategies.
3. Implement the design and show the sweep process, which is the consumer whose correctness is most at risk.
4. State the design decisions, including how the overdraft limit and the maturity rule are prevented from becoming special cases in the consumers.

Solution D.3

Step 1: identifying what varies and what does not.

The requirement describes three consumers and three products. The consumers divide cleanly on the basis of which capability they require. Interest posting and statement generation require only that an account has a balance, an identifier, and a method of crediting interest, and all three products support all of these. The sweep process requires withdrawal, and only two of the three products support it at any given time.

This division is the substance of the design. The naive hierarchy, in which a single Account base declares withdraw and the recurring deposit refuses it, produces exactly the defect of Problem D.2: the sweep process is written against a contract the recurring deposit cannot honour, and it fails at runtime when the account mix changes.

Step 2: choosing between the two correction strategies.

Two strategies are available whenever a subtype cannot honour a base operation, and selecting between them is a design judgement rather than a rule.

The first strategy is capability separation, in which the operation is moved to a narrower abstraction that only capable types implement. This is the strategy applied in Problem D.2. Its advantage is that misuse becomes a static error. Its cost is that the capability must be determinable from the type, because a static type cannot express a condition that changes at runtime.

The second strategy is contract widening, in which the base contract is changed so that refusal is a declared and expected outcome rather than a surprise. The operation returns a result value indicating success or refusal, or raises a documented domain exception that the base contract names, and every caller is then obliged to handle refusal because the signature says so. Its advantage is that it accommodates conditions evaluated at runtime. Its cost is that every caller must handle the refusal path, including callers dealing with types that never refuse.

The choice for this requirement is capability separation for the recurring deposit and contract widening for the withdrawal limit. The justification rests on when each condition is known.

Whether a product supports withdrawal at all is a property of the product, fixed when the account is opened, and therefore expressible in the type. A recurring deposit account is not withdrawable, and this never changes during the period in which it is a recurring deposit account. Capability separation applies.

Whether a specific withdrawal succeeds depends on the amount requested and the current balance, which are runtime values. No type system can prevent a request for more than the available balance, so refusal must be a declared outcome of the operation for every withdrawable account. Contract widening applies, and crucially it applies uniformly: the savings account and the current account both refuse under some conditions, they differ only in where the boundary lies, and therefore no caller needs to distinguish between them.

Treating maturity as a runtime condition rather than a type property would be the common error here. It appears attractive because maturity does change over time. It is rejected because the transition at maturity is not a change in the account’s capability but the end of the account’s life: the requirement states that the entire balance is withdrawn once and the account closes. Modelling maturity as a withdraw that begins succeeding would oblige every caller of withdraw, including the sweep process, to reason about a case that occurs once per account and is handled by a dedicated closure process.

Step 3: implementation.

from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass
from datetime import date
from typing import Sequence


@dataclass(frozen=True)
class WithdrawalResult:
    """The declared outcome of a withdrawal attempt. Refusal is part of the
    contract, so no caller is surprised by it."""

    succeeded: bool
    amount: float
    reason: str = ""

    @staticmethod
    def refused(reason: str) -> "WithdrawalResult":
        return WithdrawalResult(succeeded=False, amount=0.0, reason=reason)


class Account(ABC):
    """The widest abstraction. Everything every product can honour, and
    nothing else. Interest posting and statements depend only on this."""

    def __init__(self, account_no: str, balance: float = 0.0):
        self._account_no = account_no
        self._balance = balance

    @property
    def account_no(self) -> str:
        return self._account_no

    @property
    def balance(self) -> float:
        return self._balance

    def deposit(self, amount: float) -> None:
        if amount <= 0:
            raise ValueError("Deposit amount must be positive")
        self._balance += amount

    def credit_interest(self, amount: float) -> None:
        self._balance += amount

    @property
    @abstractmethod
    def annual_interest_rate(self) -> float: ...


class WithdrawableAccount(Account):
    """Adds the withdrawal capability. Contract: withdraw never raises on
    grounds of insufficient funds or policy. It returns a WithdrawalResult
    whose succeeded flag reports the outcome."""

    @abstractmethod
    def withdraw(self, amount: float) -> WithdrawalResult: ...

    @property
    @abstractmethod
    def withdrawable_balance(self) -> float:
        """The largest amount a withdrawal would currently succeed with.
        Zero is a valid answer and is not an error."""


class SavingsAccount(WithdrawableAccount):
    @property
    def annual_interest_rate(self) -> float:
        return 3.5

    @property
    def withdrawable_balance(self) -> float:
        return max(self._balance, 0.0)

    def withdraw(self, amount: float) -> WithdrawalResult:
        if amount <= 0:
            raise ValueError("Withdrawal amount must be positive")
        if amount > self.withdrawable_balance:
            return WithdrawalResult.refused("Insufficient funds")
        self._balance -= amount
        return WithdrawalResult(succeeded=True, amount=amount)


class CurrentAccount(WithdrawableAccount):
    def __init__(self, account_no: str, balance: float = 0.0, overdraft_limit: float = 0.0):
        super().__init__(account_no, balance)
        self._overdraft_limit = overdraft_limit

    @property
    def annual_interest_rate(self) -> float:
        return 0.0

    @property
    def withdrawable_balance(self) -> float:
        return max(self._balance + self._overdraft_limit, 0.0)

    def withdraw(self, amount: float) -> WithdrawalResult:
        if amount <= 0:
            raise ValueError("Withdrawal amount must be positive")
        if amount > self.withdrawable_balance:
            return WithdrawalResult.refused("Overdraft limit exceeded")
        self._balance -= amount
        return WithdrawalResult(succeeded=True, amount=amount)


class RecurringDepositAccount(Account):
    """Not withdrawable. There is no withdraw method to break, and the type
    system prevents this account from reaching the sweep process."""

    def __init__(
        self,
        account_no: str,
        monthly_instalment: float,
        maturity_date: date,
        balance: float = 0.0,
    ):
        super().__init__(account_no, balance)
        self._monthly_instalment = monthly_instalment
        self._maturity_date = maturity_date
        self._closed = False

    @property
    def annual_interest_rate(self) -> float:
        return 6.75

    def pay_instalment(self) -> None:
        self.deposit(self._monthly_instalment)

    def is_matured(self, as_of: date) -> bool:
        return as_of >= self._maturity_date

    def close_on_maturity(self, as_of: date) -> float:
        """The single withdrawal permitted by the product, modelled as closure
        rather than as a withdrawal, because that is what it is."""
        if not self.is_matured(as_of):
            raise ValueError("Recurring deposit has not matured")
        if self._closed:
            raise ValueError("Account already closed")
        proceeds, self._balance, self._closed = self._balance, 0.0, True
        return proceeds