Python Intermediate Python Projects

Split the program by responsibility, so each part can be understood, tested and changed on its own:

equipment_report/
    loans/
        __init__.py
        parsing.py      # read CSV files -> lists of dicts (no calculations)
        stock.py        # pure calculations on Python data (no files)
        report.py       # format results as text (no files, no calculations)
        cli.py          # glue: read arguments, call the others, write output
    tests/
        test_stock.py
        test_parsing.py
    pyproject.toml
    README.md

The calculation module, stock.py, takes plain dictionaries and returns plain dictionaries: it doesn't know whether data came from a CSV file, a database or a test. That makes it trivial to test and reuse. Parsing deals with messy input; reporting deals with presentation; the command-line module wires them together.

One large function that reads a file, calculates, formats and prints is hard to debug: when a total is wrong, you can't tell whether parsing, arithmetic or formatting is at fault. Separate modules localise failures.

Files outlive the program, so decide their format, encoding and failure policy up front:

• Format: CSV for tables people open in spreadsheets; JSON for nested settings and state; SQLite (sqlite3) when you need queries or several record types.
• Encoding: always encoding="utf-8", with newline="" for CSV.
• Failure policy: what happens with a missing file, a malformed row or a crash halfway through writing?

Never write directly over your only copy of important data. Write to a temporary file and replace the original only when writing succeeded:

import json, os
from pathlib import Path

def save_json(path, data):
    path = Path(path)
    tmp = path.with_suffix(".tmp")
    tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")
    os.replace(tmp, path)       # atomic on the same file system

If the program crashes while writing, the original file is untouched. Keep a sample data file in the repository, with fake data, so others can run the project immediately.

Test pure logic directly with ordinary values, and test file-handling code with temporary files that the test creates and cleans up:

# tests/test_stock.py
from loans.stock import remaining_stock

def test_items_not_checked_out_keep_full_stock():
    assert remaining_stock({"lamps": 6}, {}) == {"lamps": 6}

def test_parse_skips_bad_rows(tmp_path):
    file = tmp_path / "loans.csv"
    file.write_text("item,qty\ntripods,3\nlamps,many\n", encoding="utf-8")
    rows, errors = parse_loans(file)
    assert rows == [{"item": "tripods", "qty": 3}] and len(errors) == 1

pytest's tmp_path fixture provides a fresh folder for each test. Tests must never depend on files in your home folder or on data only you have; another developer, or continuous integration, must be able to run them on a clean machine.

Focus tests on the risky cases: missing equipment, items returned twice, empty files, malformed rows and quantities that would go negative. The mocking and fixtures lesson covers replacing network calls in the API client project.

A project is only finished when someone else can run it. Document and automate the set-up:

## Setup
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
python -m pip install -e ".[dev]"

## Run
python -m loans.cli data/sample_loans.csv

## Test
python -m pytest

Declare dependencies in pyproject.toml (see dependency management), add a .gitignore for .venv and generated output, and include sample data.

The real test is a clean checkout: clone the repository into a new folder, follow the README exactly, and check that tests pass and the report matches the documented example. Anything you had to do that isn't written down, such as installing a package by hand or creating a folder, is a missing step. A project that only works in your personal environment isn't finished.

Task: build an equipment report, a validated donation importer or a logged API client with modules, persistence and tests. Suggested milestones for the donation importer:

1. parsing.py: read a CSV of donations, returning valid rows and a list of errors with line numbers.
2. summary.py: total donations per month from clean rows (pure function).
3. storage.py: save the summary to JSON with the temporary-file pattern.
4. tests/: test parsing with tmp_path, the summary with plain data, and saving with a temporary folder.
5. README.md: set-up, run and test commands, verified from a fresh clone.

def monthly_totals(rows):
    totals = {}
    for row in rows:
        month = row["date"][:7]                 # "2026-03-14" -> "2026-03"
        totals[month] = totals.get(month, 0) + row["amount"]
    return totals

print(monthly_totals([{"date": "2026-03-14", "amount": 20}, {"date": "2026-03-20", "amount": 15},
                      {"date": "2026-04-02", "amount": 40}]))   # {'2026-03': 35, '2026-04': 40}

For the worked check, the responsibility that should be separated from stock arithmetic is external file parsing.

The Python Packaging User Guide's packaging tutorial explains project layout and pyproject.toml. Continue with advanced projects and revisit pytest in depth. Practise with the Python exercises and Python quiz.