Key vocabulary

Combining records and real file handling — a second rehearsal project

Why this lesson builds on SDD19, not replaces it

SDD19 deliberately kept its scenario narrow — one array, no records, no files — so the five assessed solution-development activities could be practised without extra complexity. This lesson adds arrays of records (SDD6, SDD15) and genuine sequential file handling (SDD11, SDD12): opening a file, reading its text, closing it, processing records, then opening a file for writing, writing the updated text, and closing it. SQA sets the real assignment task annually. This library task is therefore transferable rehearsal in applying analysis, design, implementation, testing, and evaluation to stored structured data; it is not a promise that every annual assignment uses records, CSV data, or this read-search-update-write pattern. The complete seven-stage iterative software lifecycle remains a separate concept and also includes documentation and maintenance.

The problem for this lesson

A school library wants a small program to manage its book records: each book has a title, an author, and a number of copies available. The records are stored in a CSV file so they persist between runs. The program should read the records, find a specific book by title using a standard algorithm, issue a loan by reducing that book's copies by one (only if a copy is actually available), and then write the updated records back to the file so the change is saved.

Stage 1 — Analysis

The functional requirements are: open and read a CSV file into an array of book records; find a specific book by title; report "Book not found" and make no change when the search returns -1; reduce a found book's copy count by one only when a copy is available; and write any successful update back to the real file. Each is independently testable. The explicit not-found requirement matters because Python accepts books[-1] as the last record: passing an unchecked search sentinel into the update would silently alter the wrong book.

Stage 2 — Design

The recognised structure diagram must be hierarchical: the top-level processLoan program module controls subordinate modules for loading, searching, safely issuing, and saving. Connector labels show data passed IN and returned OUT. loadBooksFromFile performs the real open/read/close operation before calling the pure readBooks parser; saveBooksToFile calls the pure writeBooks serialiser before the real open/write/close operation. The issueLoan selection checks if index == -1 before any books[index] access, and the top module saves only when the subprogram reports that a record was actually updated.

Stage 3 — Implementation

Implementation separates file access from text processing so each part can be tested clearly. readBooks(fileContents) parses CSV text with manual newline/comma splitting; writeBooks(books) serialises records with manual joining. Their thin wrappers use with open(filename, "r") as file: and file.read(), or with open(filename, "w") as file: and file.write(...). Leaving a with block closes the handle automatically. The record remains an @dataclass, the search remains the standard linear search algorithm, and issueLoan guards the -1 sentinel before indexing. This creates a genuine persistent round trip rather than merely passing an already-supplied string between helper functions.

Stage 4 — Testing

Testing is a construction task, not a supplied completed table. Starting only from FR1–FR5, pupils must devise a comprehensive set of normal, extreme, and exceptional cases; state exact expected results; and link every case to one or more requirements. The plan must include an integrated missing-title attempt that continues as far as the update decision, proving that the -1 result does not change the last record or write a corrupted file. Pupils then compare their expectations with the separately supplied execution evidence and record actual results and pass/fail. This makes requirement traceability visible instead of asking pupils merely to read somebody else's plan.

Stage 5 — Evaluation

Evaluation applies SDD18's five criteria to the combined program: fitness for purpose (does it genuinely load and save the file while meeting FR1–FR5); efficient use of coding constructs (is linear search appropriate); usability (are issued, unavailable, and not-found messages clear); maintainability (does each wrapper or helper have one named job); and robustness. The corrected flow handles a missing title safely and treats an empty file as an empty array, but malformed CSV fields can still raise an error, so robustness remains only partially met. Claims about persistence are supported by reopening the saved file and checking the changed value, not by inspecting a returned string alone.

Worked examples

Mystery of the Blue Loch,A. Ferguson,3
Highland Adventures,R. Bell,5
The Coding Puzzle,S. Mackay,0
Edinburgh Nights,L. Grant,2
The Silent Algorithm,K. Reid,4

from dataclasses import dataclass

@dataclass
class Book:
    title: str
    author: str
    copies: int

def readBooks(fileContents):
    books = []
    fileContents = fileContents.strip()
    if fileContents == "":
        return books
    lines = fileContents.split("\n")
    for line in lines:
        fields = line.split(",")
        title = fields[0]
        author = fields[1]
        copies = int(fields[2])
        books.append(Book(title, author, copies))
    return books

def loadBooksFromFile(filename):
    with open(filename, "r") as file:
        fileContents = file.read()
    return readBooks(fileContents)

def findBookByTitle(books, target):
    index = 0
    found = False
    while index < len(books) and not found:
        if books[index].title == target:
            found = True
        else:
            index = index + 1
    if found:
        return index
    else:
        return -1

def issueLoan(books, index):
    if index == -1:
        print("Book not found")
        return False
    if books[index].copies > 0:
        books[index].copies = books[index].copies - 1
        print("Loan issued for", books[index].title,
              "- copies remaining:", books[index].copies)
        return True
    else:
        print("Cannot issue loan -", books[index].title,
              "has no copies available")
        return False

def writeBooks(books):
    lines = []
    for book in books:
        line = book.title + "," + book.author + "," + str(book.copies)
        lines.append(line)
    return "\n".join(lines)

def saveBooksToFile(filename, books):
    fileContents = writeBooks(books)
    with open(filename, "w") as file:
        file.write(fileContents)

def processLoan(filename, target):
    books = loadBooksFromFile(filename)
    index = findBookByTitle(books, target)
    loanIssued = issueLoan(books, index)
    if loanIssued:
        saveBooksToFile(filename, books)
    return loanIssued

Task Set A — Core questions

def countAvailableBooks(books):
    count = 0
    for position in range(len(books)):
        if books[position].copies > 0:
            count = count + 1
    return count

# countAvailableBooks(libraryBooks) returns 4
# (all books except "The Coding Puzzle", which has 0 copies)

Task Set B — Extension