Exercise: Running Club Log

Write the five functions behind a running club's weekly log, reading its runs from a CSV file, totaling each runner's miles, writing a summary CSV and saving and loading goals as JSON, and let pytest's tests check each one in folders of their own.

Journeyman · Python · Updated

By

The Riverbend Running Club keeps its week in two files: a spreadsheet of runs saved as runs.csv, and each member's weekly goal in goals.json. You'll write the five functions that turn those files into a weekly report: one reads the runs, one totals each runner's miles, one writes a summary the club can open in a spreadsheet, and two save and load the goals. The tests check each function on small files of their own, so your files are never touched.

Get the exercise code

Open this lesson's GitHub repository, github.com/ask-codey/exercise-python-running-club-log, also linked from the Exercise box beside the lesson. Clone it into your python-course folder. In VS Code's terminal:

cd ~/python-course
git clone https://github.com/ask-codey/exercise-python-running-club-log.git

Git makes a folder, exercise-python-running-club-log, with the exercise code inside. Open that folder in VS Code (File > Open Folder), open its terminal with Terminal > New Terminal, and make the exercise's virtual environment, as Virtual Environments and pip explains. On Windows (PowerShell):

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

On a Mac (zsh):

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

The prompt starts with (.venv) once the virtual environment is on.

The folder holds:

  • club.py: the five functions, for you to finish.
  • report.py: prints the club's week with your functions and writes summary.csv, so you can see them at work. Ready to use.
  • runs.csv and goals.json: the club's runs for the week and each member's goal. report.py reads them.
  • tests/test_club.py: the tests, which call each function and check what comes back or what it wrote. You don't need to change it.
  • requirements.txt and pytest.ini: the package the tests need, and where pytest finds the tests and your code.

What to do

Every function in club.py is already declared with its name and parameters, and for now it stops with a NotImplementedError that says Not built yet. The docstring under each one says what it should do, with examples:

def read_runs(path):
    """Return the runs in the CSV file at path, as a list of dictionaries.

    The file's header is date,runner,miles,minutes. Each run becomes one
    dictionary with those four keys, in the file's order. Convert the miles
    to a float and the minutes to an int; the date and the runner stay text.

    A file with this header and the line 2026-11-02,Priya,3.1,29 gives
    [{"date": "2026-11-02", "runner": "Priya", "miles": 3.1, "minutes": 29}]
    A file with only the header gives [].
    """
    raise NotImplementedError("Not built yet.")

In each function, replace the raise NotImplementedError("Not built yet.") line with your own code. Open every file with encoding="utf-8", and every CSV file with newline="" as well:

  1. read_runs(path) reads the CSV file at path and returns its runs as a list of dictionaries, with the miles as a float and the minutes as an int.
  2. miles_by_runner(runs) takes that list and returns a dictionary of each runner's total miles, such as {"Priya": 5.6, "Marcus": 4.0}, each total rounded to 1 decimal place. The runners are in the order each one first appears.
  3. write_summary(path, totals) writes those totals to a new CSV file at path: the header runner,miles, then one line for each runner.
  4. save_goals(path, goals) saves the goals dictionary to a JSON file at path, laid out with indent=2.
  5. load_goals(path) returns the goals saved in the JSON file at path, or an empty dictionary, {}, when there's no file there yet.

Each path the tests give your functions is a path pytest makes, not text, and open() takes it as it is: pass path straight to open().

Check your work

Run the tests from the exercise folder, with the virtual environment on:

pytest

At first all 15 tests fail. That's expected: each function you finish turns its tests green. A failing test's message says what it called, what it expected and what came back, for example read_runs on a runs.csv holding only the header should return [], but it returned None.

The tests never touch your own files. Each one writes the small files it needs into tmp_path, an empty folder pytest makes for that test alone; Fixtures and Temporary Files, in Module 4, shows how that works.

To see your functions at work on the club's real files, run python report.py from the exercise folder.

Hints

  • Start with read_runs. report.py needs it first, and csv.DictReader does most of the work: each row comes back as a dictionary of text, so convert the two numbers as you build each run. CSV Files: Tables in Plain Text shows the pieces.
  • Total with a dictionary. totals.get(runner, 0) gives a runner's total so far, or 0 the first time you meet them. Round once, after every run is added up, not after each one.
  • Write with csv.DictWriter. Give it fieldnames=["runner", "miles"], call writeheader() once, then writerow() for each runner and their miles.
  • JSON is two lines each way. json.dump(goals, file, indent=2) saves and json.load(file) loads, as JSON Files: Saving Your Data shows.
  • A missing file is an exception you can expect. open() stops with a FileNotFoundError when the file isn't there, and Handling Errors with try and except shows how to catch it and return {} instead.

When you're done

Every test is green: pytest's last line says 15 passed. And python report.py prints:

Riverbend Running Club: this week
8 runs logged
Priya: 10.0 of 12 miles, 2.0 to go
Marcus: 10.2 of 10 miles, goal met!
Zoë: 8.2 of 15 miles, 6.8 to go
Luis: 2.6 of 5 miles, 2.4 to go
Saved summary.csv
Goals in the backup: 4
Goals in a file that isn't there yet: {}

Open summary.csv in VS Code, or in a spreadsheet app: it's the club's week as a table, one runner to a row. Now look back at miles_by_runner: it never opens a file. Why does that make it the easiest of the five to test?

Submit your exercise

The exercise is how you finish this lesson. When your work is done, put it on GitHub in a repo of your own, then submit that repo's address here. Hand In Your Work with Git walks through each step.

  1. On GitHub, click +, then New repository. Name it (for example exercise-python-running-club-log), choose Public, and click Create repository. Leave out the README: your folder already has one.

  2. In VS Code's terminal, in your exercise folder, send your work to your new repo. Point your copy at your own repo, then commit and push:

    git remote set-url origin https://github.com/your-name/exercise-python-running-club-log.git
    git add .
    git commit -m "My solution"
    git push -u origin main
    
  3. Paste your repo's address, such as https://github.com/your-name/exercise-python-running-club-log, into Submit your exercise on this page. The site checks that the repo is public and holds your commits, and then the lesson is complete.

Changed something after you submitted? Push it, and submit again: your latest submission is the one that counts.

So what

Reading data in, working it out, and writing the results back out is the shape of most programs you'll write, and keeping the file work apart from the math is what makes each piece quick to test.

Key terms

Related