Project 2: Library Management System

The scenario

The Millbrook Public Library serves a town of 12,000 people. It owns about 4,000 titles, keeps several copies of the popular ones, and has 900 card holders. Loans are still written on index cards, and the head librarian, Rosa, has three problems she wants solved:

1. Typos in ISBNs. Volunteers type ISBNs by hand. A single wrong digit puts the wrong book in the catalog. ISBNs carry a check digit designed to catch exactly this kind of mistake, and the software should use it.
2. Fair waiting lists. When the new thriller comes in, twenty people want it. Whoever asked first should get it first, and they should be told when it is waiting for them at the desk.
3. Fines that are actually charged. Late fines are 25 cents per day, capped at $10 per loan. A member who owes $5 or more cannot borrow until they pay something down.

Members have one of three tiers. Children may borrow 3 items for 14 days, standard members 5 items for 21 days, and premium (donor) members 10 items for 28 days.

Learning goals

Feature specification

The package is library. Its public API is re-exported from library/__init__.py, so tests can write from library import Library, Book, Member.

Business rules

• Copy ids are C00001, C00002, …; loan ids are L00001, …
• checkout checks, in order: unpaid fines (≥ 500 cents blocks), the tier's loan limit, then a copy for this member: one reserved for them on the hold shelf first, otherwise any available copy.
• The due date is the checkout date plus the tier's loan period. "Today" always comes from the injected clock.
• return_copy closes the loan, adds any fine to the member (and notifies them), then shelves the copy: if someone is waiting, the copy goes onto the hold shelf reserved for the first person in line and they get a "Hold ready" notification; otherwise it becomes available.
• A hold can be placed only when no copy is available, not twice by the same member, and not by a member who already has the title on loan. New copies added with add_copies serve the waiting list first.

Architecture

The Library is a service object: it owns the records and enforces the rules. Everything it needs from the outside world (today's date, a way to send messages) comes in through its constructor as an object that satisfies a Protocol. That is dependency injection: production code passes SystemClock(); tests pass FixedClock(date(2026, 3, 1)) and an InMemoryNotifier() they can inspect.

flowchart LR
  subgraph models[models.py]
    Book
    Copy
    Member
    Loan
    MemberTier
  end
  Library -->|validates with| ISBN[isbn.py]
  Library --> models
  Library -->|indexes| SearchIndex[search.py SearchIndex]
  Library -->|today| Clock[[Clock Protocol]]
  Library -->|send| Notifier[[Notifier Protocol]]
  Clock -.-> SystemClock
  Clock -.-> FixedClock
  Notifier -.-> InMemoryNotifier
  Storage[storage.py] -->|to_dict / from_records| Library
  Storage --> JSON[(library.json)]
    

Inside the Library, each kind of record lives in a dict keyed by its id, so every lookup is O(1). Each title with a waiting list has a deque of member ids: append joins the back of the line and popleft serves the front, both O(1). A plain list would make pop(0) O(n).

The search index is an inverted index: instead of storing "book → words", it stores "word → set of ISBNs". A query for tolkien hobbit intersects two small sets instead of scanning every title.

Getting started

pixi run projects            # list every project and its status
pixi run start p02           # copy the starter into work/p02_library_system/
pixi run grade p02           # run all 67 tests against your work/ copy
pixi run grade p02 -- -k isbn   # only tests whose names contain "isbn"
pixi run mypy --strict work/p02_library_system/library

Open work/p02_library_system/library/. Every function has its final signature, a Google-style docstring, and a TODO comment telling you what to do. Replace each raise NotImplementedError. errors.py and __init__.py are complete. The constructors of Library, SearchIndex, FixedClock, and InMemoryNotifier are given so you can see the internal data structures.

Milestones

Work in order: each milestone's tests only need the earlier ones. Run pixi run grade p02 -- -k <keyword> after each step.

try:
    return self._members[member_id]
except KeyError:
    raise NotFoundError(f"no member {member_id}") from None

Rubric

Stretch goals

• CLI. A main() with argparse subcommands (add, lend, return, search, overdue) that loads and saves library.json; register it as a Pixi task.
• Outbox notifier. An OutboxNotifier that writes each message to a file. Because it satisfies the Notifier Protocol, the Library needs no changes.
• Ranked search. Score by the number of matching words and allow prefix matches (tolk finds Tolkien). A trie (M27) makes prefix lookup fast.
• Renewals. renew(loan_id) extends a loan once, unless someone is waiting.
• Property-based tests. With Hypothesis (pixi add hypothesis), generate random nine-digit bodies, compute the ISBN-10 check digit, and assert the ISBN-13 conversion always validates.

Reflection quiz