LLD: Vending Machine¶

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from enum import Enum
from threading import Lock


class Denomination(Enum):
    NICKEL = 0.05
    DIME = 0.10
    QUARTER = 0.25
    ONE_DOLLAR = 1.00


@dataclass(frozen=True)
class Product:
    sku: str
    name: str


class Slot:
    def __init__(self, code: str, product: Product, price: float, quantity: int):
        self.code = code
        self.product = product
        self.price = price
        self.quantity = quantity

    def is_available(self) -> bool:
        return self.quantity > 0

    def decrement(self) -> None:
        if self.quantity <= 0:
            raise RuntimeError(f"slot {self.code!r} is already empty — should never be reached")
        self.quantity -= 1


class Inventory:
    def __init__(self, slots: dict[str, Slot]):
        self.slots = slots

    def get_slot(self, code: str) -> Slot | None:
        return self.slots.get(code)


class InsufficientChangeError(Exception):
    """Raised when the reserve cannot make exact change for an amount it does have covered in total value."""


class CoinReserve:
    def __init__(self, counts: dict[Denomination, int]):
        self.counts = counts

    def total_value(self) -> float:
        return round(sum(d.value * c for d, c in self.counts.items()), 2)

    def make_change(self, amount: float, extra_coins: list[Denomination] | None = None) -> list[Denomination]:
        """Greedy: largest denomination first. See Patterns Applied for why this
        is a Strategy seam and where greedy stops being optimal in general."""
        remaining = round(amount, 2)
        result: list[Denomination] = []
        working_counts = dict(self.counts)          # don't mutate reserve until commit
        for coin in extra_coins or []:
            working_counts[coin] = working_counts.get(coin, 0) + 1
        for denom in sorted(Denomination, key=lambda d: -d.value):
            while remaining >= denom.value - 1e-9 and working_counts.get(denom, 0) > 0:
                result.append(denom)
                working_counts[denom] -= 1
                remaining = round(remaining - denom.value, 2)
        if remaining > 1e-9:
            raise InsufficientChangeError(
                f"cannot make exact change for {amount:.2f} from current reserve"
            )
        return result

    def commit_change(self, denominations: list[Denomination]) -> None:
        for d in denominations:
            self.counts[d] -= 1

    def add(self, denomination: Denomination) -> None:
        self.counts[denomination] = self.counts.get(denomination, 0) + 1


class VendingState(ABC):
    @abstractmethod
    def select_item(self, machine: "VendingMachine", code: str) -> None: ...

    @abstractmethod
    def insert_coin(self, machine: "VendingMachine", denomination: Denomination) -> None: ...

    @abstractmethod
    def dispense(self, machine: "VendingMachine") -> None: ...

    @abstractmethod
    def cancel(self, machine: "VendingMachine") -> None: ...


class IdleState(VendingState):
    def select_item(self, machine: "VendingMachine", code: str) -> None:
        slot = machine.inventory.get_slot(code)
        if slot is None:
            raise ValueError(f"no such slot {code!r}")
        if not slot.is_available():
            machine.selected_slot = slot
            machine.set_state(OutOfStockState())
            return
        machine.selected_slot = slot
        machine.inserted_amount = 0.0
        machine.set_state(ItemSelectedState())

    def insert_coin(self, machine: "VendingMachine", denomination: Denomination) -> None:
        raise RuntimeError("select an item before inserting money")

    def dispense(self, machine: "VendingMachine") -> None:
        raise RuntimeError("no item selected")

    def cancel(self, machine: "VendingMachine") -> None:
        pass  # nothing to cancel


class OutOfStockState(VendingState):
    def select_item(self, machine: "VendingMachine", code: str) -> None:
        IdleState().select_item(machine, code)  # re-route through idle's logic

    def insert_coin(self, machine: "VendingMachine", denomination: Denomination) -> None:
        raise RuntimeError("selected item is out of stock — choose another")

    def dispense(self, machine: "VendingMachine") -> None:
        raise RuntimeError("selected item is out of stock")

    def cancel(self, machine: "VendingMachine") -> None:
        machine.selected_slot = None
        machine.set_state(IdleState())


class ItemSelectedState(VendingState):
    def select_item(self, machine: "VendingMachine", code: str) -> None:
        IdleState().select_item(machine, code)  # allow changing selection before paying

    def insert_coin(self, machine: "VendingMachine", denomination: Denomination) -> None:
        machine.inserted_amount = round(machine.inserted_amount + denomination.value, 2)
        machine.inserted_coins.append(denomination)  # escrow until the sale succeeds
        if machine.inserted_amount >= machine.selected_slot.price - 1e-9:
            machine.set_state(DispensingState())
            machine.state.dispense(machine)
        else:
            machine.set_state(PaymentInProgressState())

    def dispense(self, machine: "VendingMachine") -> None:
        raise RuntimeError("insert payment before dispensing")

    def cancel(self, machine: "VendingMachine") -> None:
        machine.selected_slot = None
        machine.set_state(IdleState())


class PaymentInProgressState(VendingState):
    def select_item(self, machine: "VendingMachine", code: str) -> None:
        raise RuntimeError("cancel the current transaction before selecting a different item")

    def insert_coin(self, machine: "VendingMachine", denomination: Denomination) -> None:
        machine.inserted_amount = round(machine.inserted_amount + denomination.value, 2)
        machine.inserted_coins.append(denomination)
        if machine.inserted_amount >= machine.selected_slot.price - 1e-9:
            machine.set_state(DispensingState())
            machine.state.dispense(machine)

    def dispense(self, machine: "VendingMachine") -> None:
        raise RuntimeError("insufficient funds inserted")

    def cancel(self, machine: "VendingMachine") -> None:
        machine.refund()
        machine.selected_slot = None
        machine.set_state(IdleState())


class DispensingState(VendingState):
    def select_item(self, machine: "VendingMachine", code: str) -> None:
        raise RuntimeError("dispense in progress")

    def insert_coin(self, machine: "VendingMachine", denomination: Denomination) -> None:
        raise RuntimeError("dispense in progress")

    def dispense(self, machine: "VendingMachine") -> None:
        slot = machine.selected_slot
        change_owed = round(machine.inserted_amount - slot.price, 2)
        try:
            change = machine.reserve.make_change(change_owed, machine.inserted_coins) if change_owed > 0 else []
        except InsufficientChangeError:
            # Cannot make correct change: refuse the sale entirely and refund
            # everything inserted, rather than dispensing without giving change back.
            machine.refund()
            machine.selected_slot = None
            machine.set_state(IdleState())
            return

        slot.decrement()
        for coin in machine.inserted_coins:          # sale committed: escrow joins the reserve
            machine.reserve.add(coin)
        machine.reserve.commit_change(change)
        machine.dispensed_product = slot.product
        machine.returned_change = change
        machine.inserted_amount = 0.0
        machine.inserted_coins = []
        machine.selected_slot = None
        machine.set_state(IdleState())

    def cancel(self, machine: "VendingMachine") -> None:
        raise RuntimeError("cannot cancel mid-dispense")


class VendingMachine:
    def __init__(self, inventory: Inventory, reserve: CoinReserve):
        self.inventory = inventory
        self.reserve = reserve
        self.state: VendingState = IdleState()
        self.selected_slot: Slot | None = None
        self.inserted_amount: float = 0.0
        self.inserted_coins: list[Denomination] = []  # exact coins held in transaction escrow
        self.dispensed_product: Product | None = None
        self.returned_change: list[Denomination] = []
        self._lock = Lock()

    def set_state(self, state: VendingState) -> None:
        self.state = state

    def select_item(self, code: str) -> None:
        with self._lock:
            self.state.select_item(self, code)

    def insert_coin(self, denomination: Denomination) -> None:
        with self._lock:
            self.state.insert_coin(self, denomination)

    def dispense(self) -> None:
        with self._lock:
            self.state.dispense(self)

    def cancel(self) -> None:
        with self._lock:
            self.state.cancel(self)

    def refund(self) -> list[Denomination]:
        """Return the exact escrowed coins; cancellation never depends on making change."""
        change = list(self.inserted_coins)
        self.inserted_coins = []
        self.inserted_amount = 0.0
        self.returned_change = change
        return change