The Project: the Booknook Shelf

Every lesson in this course is set in one place, on one project. Booknook is made up. The café, its owner, its volunteer, its members and every loan are fictional and simulated. The books are real public-domain titles. The real cases that open each lesson are separate, cited, and clearly marked as real.

The place

Kettle and Page is a small café with a lending shelf in the corner, called Booknook. Customers donated twenty-four books. Anyone who signs up as a member can borrow a book for two weeks for free. Bring it back late and you pay a small fee, which goes in the café's charity jar.

The shelf opened on Tuesday 1 September 2026. For two weeks the loans were written in a paper notebook. Since Monday 14 September they have been kept in a spreadsheet. Neither is working well: nobody can say quickly which books are out, who is late, or how much should be in the jar.

The problem

Amira, who owns the café, wants the shelf's records kept by a small program she can trust:

1. Which books are on the shelf, and which are out, and with whom?
2. Who is overdue, by how many days, and what do they owe?
3. Lend a book and take it back, refusing a fourth book to anyone who already has three.
4. Read Tom's old notebook and say which lines are wrong, instead of guessing.
5. Give the same answer every time it is asked the same question.
6. One command each morning that prints the day's report.

You are the person building it. You start knowing no Python at all; by the end you have a tested package with classes, files and a command-line tool.

What this course uses the project for

This course is about Python itself: values, text, decisions, loops, collections, functions, modules, files, errors, classes and tests. The shelf is the instrument. It is small enough to hold in your head (24 books, 6 members, 40 loans) and real enough to need every one of those tools. Each module answers a harder question from Amira, because each module gives you a better tool.

It has nothing to do with the companies in the other courses in this series. No language models are used anywhere.

The people

The six members:

Minor characters (another café customer, a new volunteer) may appear in one lesson. Do not add main characters.

The rules

The rules and data as code are in 06-shared-data.md.

The data

Modules 1 to 4 use smaller slices written straight into the lesson: one book and one loan in Module 1, then six books and twelve loans with dates as "shelf days" (14 September is day 14, 14 October is day 44) until the datetime module arrives in Module 7. The exact slices are in 06-shared-data.md.

The answers on 14 October

These come from running the code in 06-shared-data.md. Every lesson that reaches one of them must get the same number.

Dates

• Tuesday 1 September 2026: the shelf opens. Tom records loans in his paper notebook.
• Monday 14 September: Amira starts the loans spreadsheet, loans.csv. Tom's notebook is never typed in properly.
• Monday 21 September: Sofia joins.
• Tuesday 13 October: the last loan in the data (Kwame takes Wuthering Heights).
• Wednesday 14 October 2026: the course's fixed "today", and the date facts in the course were checked. Every module is set on this day. Lessons are told in the present tense.

What Amira asks, module by module

Fixed names

Lessons may add names; they do not rename these.

The function names keep the same meaning when the dates change from shelf days to real dates in Module 7: only what goes in changes.

One repository: which module adds which file

Modules 1 to 6 work inside notebook cells. Small practice scripts such as hello.py are made along the way, but they are not part of the project. From Module 7 everything you keep goes in one folder, booknook, in your Google Drive in Colab (02-setup-colab.md, section 7) or on your own computer (07-run-locally.md). Inside it is the Python package, also called booknook. Every lab from Module 7 on starts with the %%ensure cell, which restores any earlier file that is missing and keeps the ones you already have.

The finished repository:

booknook/
  booknook/
    __init__.py  __main__.py  dates.py  fees.py  catalogue.py
    storage.py   models.py    tools.py  report.py
  data/
    books.csv  members.json  loans.csv  tom_notebook.txt  notebook_loans.csv
  tests/
    test_fees.py  test_dates.py  test_storage.py  test_models.py  test_cli.py
  requirements.txt
  requirements-dev.txt
  README.md

The file is called storage.py, not io.py, because io is already the name of a module that comes with Python, and a file with the same name hides it. Module 7 Lesson 1 uses this as its example of why not to name a file random.py.

The finished shelf

• A catalogue, members and loans read from plain files, and saved back safely
• Tom's notebook parsed, with every faulty line reported instead of guessed at
• Lending and returning that refuse a fourth book and a book with no copy left
• Due dates, days late and fees worked out the same way every time, from a date you pass in
• A morning report and an overdue list from one command
• Tests that fail the moment a change breaks a rule

The one idea

A program is a set of rules written so exactly that a computer can follow them. Amira's shelf has only four rules, and each module makes them more exact: first as numbers in variables, then as functions, then as classes, then as tests that prove the rules still hold. The course's job is to make you the person who can write them down that exactly.