In [ ]:
# Initialize Otter
import otter
grader = otter.Notebook("07_lecture_file_io_exception_handling.ipynb")

File I/O and Exception Handling

Theme: UM Semester at Sea -- Cetacean Research Expedition

Goal: Learn to read, write, and process files in Python. We will open text files for reading, writing, and appending, use with statements for safe file handling, process files line-by-line with for loops, read and write CSV data with csv.reader and csv.writer, fetch real whale data from the internet with urllib, and build fault-tolerant programs with try/except blocks.

Scenario: You've joined the crew of the research vessel R/V Coral Gables on a University of Miami marine biology expedition through the Florida Straits and Bahamas. The chief scientist, Dr. Maria Torres, has been recording whale and dolphin sightings in text logs and CSV spreadsheets. Your job: read the expedition data, analyze it, fetch additional data from online databases, and write research reports -- all using Python.

What you already know: Functions (Week 7), for loops (Weeks 5-6), tuples with index constants (Weeks 6-7), import (Week 7). Today we add file I/O and error handling to your toolkit.

In [ ]:
# Validation: Check Python version and file location
import os
import sys

# Supported Python versions for this course
SUPPORTED_VERSIONS = ["3.12", "3.13"]
current_version = f"{sys.version_info.major}.{sys.version_info.minor}"

if current_version not in SUPPORTED_VERSIONS:
    raise EnvironmentError(
        f"Python version mismatch!\n"
        f"Supported: {', '.join(SUPPORTED_VERSIONS)}\n"
        f"Found: {current_version}\n"
        f"Please use Python 3.12 or 3.13 for this course."
    )
print(f"Python version: {current_version}")

# Expected filename for this assignment
EXPECTED_FILE = "07_lecture_file_io_exception_handling.ipynb"

# Check file is in the correct directory
current_path = os.path.abspath("")
required_path_segment = os.path.join("Documents", "CSC115", "lecture_notebooks")
allowed_envs = ["submission", "dist", "live", "source"]
in_allowed_env = any(env in current_path for env in allowed_envs)

if required_path_segment not in current_path and not in_allowed_env:
    raise EnvironmentError(
        f"File location error!\n"
        f"This notebook should be in: ~/Documents/CSC115/lecture_notebooks/\n"
        f"Current location: {current_path}\n"
        f"Please move this file to the correct directory."
    )

# Verify filename (skip in grading/development environments)
if not in_allowed_env:
    if not os.path.exists(EXPECTED_FILE):
        notebooks = [f for f in os.listdir(".") if f.endswith(".ipynb")]
        raise EnvironmentError(
            f"Filename mismatch!\n"
            f"Expected: {EXPECTED_FILE}\n"
            f"Found notebooks: {notebooks}\n"
            f"Please rename your notebook to '{EXPECTED_FILE}'."
        )

print(f"File location: {os.path.join(current_path, EXPECTED_FILE)}")

Setup: Imports, Data Constants, and Visualization Helpers

Run this cell to load everything we need. It imports the libraries, defines index constants for our CSV data (same pattern as section[SECTION_PRICE] from the functions lecture), and provides visualization helper functions you can call after reading data.

In [ ]:
import csv
import os
import urllib.request

import matplotlib.pyplot as plt

# --- Index constants for local whale sighting CSV ---
# Each row: (date, species, count, length_m, latitude, longitude, behavior)
SIGHTING_DATE = 0
SPECIES = 1
COUNT = 2
LENGTH_M = 3
LATITUDE = 4
LONGITUDE = 5
BEHAVIOR = 6

# --- Index constants for remote South African whale data ---
# Each row: (Species, Platform, Year, Month, Day, Latitude, Longitude, Season)
REMOTE_SPECIES = 0
REMOTE_PLATFORM = 1
REMOTE_YEAR = 2
REMOTE_MONTH = 3
REMOTE_DAY = 4
REMOTE_LAT = 5
REMOTE_LON = 6
REMOTE_SEASON = 7

# Remote data URL (South African whale sightings, 6000+ records)
WHALE_DATA_URL = "https://ndownloader.figshare.com/files/23756840"


# --- Visualization Helper Functions ---
# These are provided for you! Call them after reading data to see charts.
# You'll learn to write matplotlib code yourself in Week 15.


def plot_species_bar_chart(species_counts):
    """Create a bar chart of species sighting counts.

    species_counts: list of (species_name, count) tuples
    """
    names = [s[0] for s in species_counts]
    counts = [s[1] for s in species_counts]
    plt.figure(figsize=(10, 5))
    bars = plt.bar(names, counts, color="steelblue")
    plt.xlabel("Species")
    plt.ylabel("Number of Sightings")
    plt.title("Semester at Sea - Sightings by Species")
    plt.xticks(rotation=45, ha="right")
    for bar, count in zip(bars, counts):
        plt.text(
            bar.get_x() + bar.get_width() / 2,
            bar.get_height() + 0.3,
            str(count),
            ha="center",
            va="bottom",
            fontweight="bold",
        )
    plt.tight_layout()
    plt.show()


def plot_sightings_timeline(yearly_counts):
    """Create a line chart of sightings over time.

    yearly_counts: list of (year, count) tuples, sorted by year
    """
    years = [y[0] for y in yearly_counts]
    counts = [y[1] for y in yearly_counts]
    plt.figure(figsize=(10, 5))
    plt.plot(years, counts, marker="o", color="teal", linewidth=2, markersize=6)
    plt.fill_between(years, counts, alpha=0.15, color="teal")
    plt.xlabel("Year")
    plt.ylabel("Number of Sightings")
    plt.title("Whale Sightings Over Time")
    plt.grid(True, alpha=0.3)
    plt.tight_layout()
    plt.show()


def plot_sighting_map(locations):
    """Create a scatter plot of sighting locations.

    locations: list of (latitude, longitude, species) tuples
    """
    species_set = sorted(set(loc[2] for loc in locations))
    colors = plt.colormaps["Set2"](range(len(species_set)))
    plt.figure(figsize=(10, 7))
    for i, species in enumerate(species_set):
        lats = [loc[0] for loc in locations if loc[2] == species]
        lons = [loc[1] for loc in locations if loc[2] == species]
        plt.scatter(
            lons,
            lats,
            label=species,
            color=colors[i],
            alpha=0.7,
            s=50,
            edgecolors="white",
            linewidth=0.5,
        )
    plt.xlabel("Longitude")
    plt.ylabel("Latitude")
    plt.title("Semester at Sea - Sighting Locations")
    plt.legend(loc="best", fontsize=8)
    plt.grid(True, alpha=0.3)
    plt.tight_layout()
    plt.show()


# Verify data files exist
if os.path.exists("captains_log.txt"):
    print("captains_log.txt found!")
else:
    print("WARNING: captains_log.txt not found - some demos won't work")

if os.path.exists("whale_sightings.csv"):
    print("whale_sightings.csv found!")
else:
    print("WARNING: whale_sightings.csv not found - some demos won't work")

print("\nVisualization helpers loaded: plot_species_bar_chart, plot_sightings_timeline, plot_sighting_map")
print("Index constants defined for local CSV (7) and remote CSV (8)")

Two data sources for this notebook:

  1. Local files (already on your computer):

    • captains_log.txt -- Dr. Torres's daily expedition log (plain text)
    • whale_sightings.csv -- structured sighting records (CSV with 18 rows, 7 columns)
  2. Remote data (downloaded from the internet):

    • South African whale sightings -- 6,000+ real research records from Figshare

The CSV data uses the same tuple with index constants pattern from the functions lecture. Instead of section[SECTION_PRICE], we use row[SPECIES] or row[LATITUDE]. Same idea, different data.


1. The Big Picture

Before we learn each piece, let's see the end goal. This function does everything: downloads whale data from the internet, reads a CSV, counts species, creates a bar chart, writes a summary report, and handles errors. Run it and see the result!

Don't worry if you don't understand every line yet. By the end of this notebook, you'll be able to build each piece yourself.

In [ ]:
def expedition_summary(data_url, report_path, min_count=5):
    """Download cetacean data, analyze species, plot results, and write a report.

    Demonstrates: open, with, csv.reader, for loops, write, try/except, urllib, matplotlib
    """
    try:
        # Step 1: Download data from the internet
        urllib.request.urlretrieve(data_url, "temp_expedition.csv")
        print("Data downloaded successfully!")

        # Step 2: Read and tally species (using a dict -- you'll learn these in Week 12!)
        tally = {}
        with open("temp_expedition.csv", "r") as src:
            reader = csv.reader(src)
            next(reader)  # skip header
            for rec in reader:
                whale_type = rec[0]
                tally[whale_type] = tally.get(whale_type, 0) + 1

        # Step 3: Visualize the results
        sorted_tally = sorted(tally.items(), key=lambda x: -x[1])
        plot_species_bar_chart(sorted_tally)

        # Step 4: Write the report
        with open(report_path, "w") as rpt:
            rpt.write("SEMESTER AT SEA - CETACEAN EXPEDITION REPORT\n")
            rpt.write("=" * 48 + "\n")
            rpt.write(f"Data source: {data_url}\n\n")
            for whale_type, num in sorted_tally:
                if num >= min_count:
                    rpt.write(f"  {whale_type}: {num} sightings\n")
            rpt.write(f"\nTotal species: {len(tally)}\n")

        print(f"\nReport saved to {report_path}")

        # Step 5: Show the report we just wrote
        print("\n--- Report Preview ---")
        with open(report_path, "r") as preview:
            print(preview.read())

    except Exception as err:
        print(f"Something went wrong: {err}")


# Run it!
expedition_summary(WHALE_DATA_URL, "expedition_report.txt")

This one function does everything -- downloads data from the internet, reads a CSV, counts species, creates a bar chart, writes a report, and handles errors.

But what if we want to just read a file without downloading? Or count species without writing a report? Or handle a missing file without crashing? We need to learn each piece individually. That's what this notebook teaches.

Some of the code above uses concepts we haven't covered yet (like dict and lambda -- those are Week 12). By the end of today, you'll know how to build every file I/O and error handling piece yourself.


Day 1: Reading and Writing Files

2. What Are Files?

So far, every piece of data we've worked with disappears when the notebook restarts. Variables, lists, tuples -- all gone. Files let us save data permanently and load data that already exists.

There are two types of files:

  • Text files (.txt, .csv, .py) -- Human-readable characters. You can open them in Notepad or TextEdit and read them. This is what we'll work with.
  • Binary files (.jpg, .pdf, .xlsx, .mp3) -- Encoded data that requires special software to interpret. We won't cover these.

On our research expedition, Dr. Torres keeps a text log of daily observations, and the science team records structured sighting data in CSV files. Let's learn to read and write both.


3. Reading Text Files

In [ ]:
# open() creates a connection to a file
# "r" means "read mode" -- the default
file = open("captains_log.txt", "r")
content = file.read()  # Read the ENTIRE file into one big string
file.close()  # ALWAYS close when done!

print(content)
print(f"\nTotal characters: {len(content)}")
In [ ]:
# .readlines() gives you a LIST where each element is one line
file = open("captains_log.txt", "r")
lines = file.readlines()
file.close()

print(f"Number of lines: {len(lines)}")
print(f"First line: {repr(lines[0])}")  # repr() shows the \n at the end!
print(f"Fifth line: {repr(lines[4])}")

Notice the \n at the end of each line? That's the newline character -- it's what creates line breaks in the file. When we process lines, we'll need to remove it with .strip().

Also notice we called file.close() both times -- forgetting this can cause data loss. There's a better way...


4. The with Statement

In [ ]:
# 'with' automatically closes the file when the block ends
# This is the RECOMMENDED way to work with files in Python

with open("captains_log.txt", "r") as file:
    content = file.read()

# File is automatically closed here -- even if an error occurs!
print(content[:100])  # First 100 characters
print(f"\nFile closed? {file.closed}")  # True!
In [ ]:
# with also works for reading just one line at a time
# Think of 'with' like a self-closing door --
# you walk in, do your work, and the door closes behind you automatically

with open("captains_log.txt", "r") as file:
    first_line = file.readline()  # Read just ONE line

print(f"First line: {first_line.strip()}")

From now on, we will always use with to open files. It's safer, cleaner, and prevents bugs. Think of open() without with like leaving the fridge door open -- it works, but bad things happen if you forget to close it.


5. Writing and Appending to Files

In [ ]:
# "w" = write mode -- creates a new file (or OVERWRITES an existing one!)
with open("test_output.txt", "w") as file:
    file.write("Research Vessel Coral Gables\n")
    file.write("Expedition Log Entry\n")
    file.write("All systems operational.\n")

# Read it back to verify
with open("test_output.txt", "r") as file:
    print(file.read())
In [ ]:
# CAREFUL: "w" mode DESTROYS existing content!
with open("test_output.txt", "w") as file:
    file.write("This replaces EVERYTHING that was in the file.\n")

with open("test_output.txt", "r") as file:
    print(file.read())
# The three lines from the previous cell are GONE
In [ ]:
# "a" = append mode -- adds to the END of an existing file
# If the file doesn't exist, it creates a new one (just like "w")

with open("test_output.txt", "a") as file:
    file.write("This line is ADDED to the end.\n")
    file.write("So is this one.\n")

with open("test_output.txt", "r") as file:
    print(file.read())
# Both the original line AND the new lines are there!

Three file modes to remember:

  • 'r' = read (default) -- opens an existing file for reading
  • 'w' = write -- creates a new file or overwrites an existing one
  • 'a' = append -- adds to the end of an existing file (never destroys data)

When in doubt, use 'a' -- it never destroys existing data.


6. Processing Files with For Loops

In [ ]:
# You can loop directly over a file object -- each iteration gives you one line
# This is MEMORY EFFICIENT -- only one line is in memory at a time

with open("captains_log.txt", "r") as file:
    for line in file:
        print(repr(line))  # repr() shows the hidden \n characters
In [ ]:
# .strip() removes whitespace (including \n) from both ends of a string

with open("captains_log.txt", "r") as file:
    for line in file:
        clean_line = line.strip()
        if clean_line:  # Skip empty lines
            print(clean_line)
In [ ]:
# Let's find all the sighting entries from the captain's log
# Same counter pattern from the for loops and functions lectures!

sighting_entries = []
with open("captains_log.txt", "r") as file:
    for line in file:
        clean_line = line.strip()
        if clean_line.startswith("Sightings:"):
            sighting_entries.append(clean_line)

print(f"Found {len(sighting_entries)} sighting entries:")
for entry in sighting_entries:
    print(f"  {entry}")

This is the same pattern you've been using since Week 5 -- loop through items, check a condition, collect or count matches. The only difference is that now the items come from a file instead of a list. The thinking is identical: for line in file works just like for item in my_list.


Question 1: Count Sighting Days (1 point)

Read the captain's log and figure out how many expedition days included at least one marine wildlife observation. The log contains daily entries, and each day has a line reporting what was seen. Days with no observations are explicitly noted. Store the count in successful_observation_days.

Hint: Open captains_log.txt with a with statement and loop through the lines. Look for the pattern that tells you what was spotted each day. Check whether the line indicates actual animals were seen or not. Use the counter pattern from previous lectures.

In [ ]:
successful_observation_days = ...
...
    ...
        clean = ...
        ...

print(f"Days with wildlife observations: {successful_observation_days}")
In [ ]:
grader.check("q1_sighting_days")

Question 2: Write a Field Report (1 point)

Write a brief field report to a file called field_report.txt. Your report should follow this format exactly:

  • Line 1: FIELD REPORT - R/V Coral Gables
  • Line 2: A separator of 40 equals signs
  • Line 3: A line reporting the number of observation days you counted in Q1 (using successful_observation_days)
  • Line 4: Status: Expedition complete

Use a with statement in write mode. After writing, read the file back into field_report_content so we can verify it.

Hint: Use open() with 'w' mode inside a with block. Call .write() for each line -- remember to add \n at the end of each line. Use an f-string for the line that includes your count.

In [ ]:
...
    ...
    ...
    ...
    ...

# Read it back to verify
with open("field_report.txt", "r") as check:
    field_report_content = check.read()
print(field_report_content)
In [ ]:
grader.check("q2_field_report")

Day 2: CSV, Internet Data, and Exception Handling

Quick recap from Day 1:

  • open("filename", mode) opens a file -- modes: "r" (read), "w" (write/overwrite), "a" (append)
  • with open(...) as file: automatically closes the file when the block ends -- always use this
  • .read() gets the whole file as one string; for line in file: processes one line at a time
  • .strip() removes whitespace and \n from line endings
  • .write(string) writes text -- you must add \n yourself for line breaks

Now let's learn about CSV files, fetching data from the internet, and handling errors gracefully.


7. Reading CSV Files

CSV stands for Comma-Separated Values. It's a text file where each line is a row, and commas separate the columns. This is the most common format for data exchange -- spreadsheets, databases, and scientific instruments all export CSV.

In [ ]:
# Let's peek at our whale sightings file as raw text first

with open("whale_sightings.csv", "r") as file:
    for i, line in enumerate(file):
        print(line.strip())
        if i >= 4:  # Just show the first 5 lines
            print("...")
            break
In [ ]:
# csv.reader handles the comma-splitting for you
# Each row becomes a LIST of strings

with open("whale_sightings.csv", "r") as file:
    reader = csv.reader(file)
    header = next(reader)  # First row is the column names
    print(f"Columns: {header}")
    print()

    for row in reader:
        print(row)  # Each row is a list like ['2026-01-15', 'Humpback Whale', '2', ...]
In [ ]:
# Same pattern as the ticketing data! Use index constants to access fields.
# This makes your code readable: row[SPECIES] instead of row[1]

sightings = []
with open("whale_sightings.csv", "r") as file:
    reader = csv.reader(file)
    next(reader)  # skip header
    for row in reader:
        # Convert numeric fields from strings to numbers
        row[COUNT] = int(row[COUNT])
        row[LENGTH_M] = float(row[LENGTH_M])
        row[LATITUDE] = float(row[LATITUDE])
        row[LONGITUDE] = float(row[LONGITUDE])
        sightings.append(row)

print(f"Loaded {len(sightings)} sighting records")
print(f"First sighting: {sightings[0][SPECIES]} - {sightings[0][COUNT]} animals, {sightings[0][BEHAVIOR]}")

IMPORTANT: csv.reader gives you strings for every field, even numbers! The count "2" is the string "2", not the number 2. You need to convert with int() or float() when you want to do math. Forgetting this conversion is one of the most common CSV bugs.

About next(reader): This reads and discards the first row (the header). Without it, your data loop would treat the header as a sighting record -- 'species' is not a whale!


Visualization Demo

Now that we've loaded the data, let's visualize it using the helper functions from setup!

In [ ]:
# Count sightings per species using the accumulator pattern
species_count_list = []
seen_species = []
for sighting in sightings:
    name = sighting[SPECIES]
    if name not in seen_species:
        seen_species.append(name)

for name in seen_species:
    total = 0
    for sighting in sightings:
        if sighting[SPECIES] == name:
            total += 1
    species_count_list.append((name, total))

# Call the helper function -- instant bar chart!
plot_species_bar_chart(species_count_list)
In [ ]:
# Plot sighting locations on a scatter plot
location_data = []
for sighting in sightings:
    location_data.append((sighting[LATITUDE], sighting[LONGITUDE], sighting[SPECIES]))

plot_sighting_map(location_data)

See how reading the CSV correctly unlocked these visualizations? The helper functions just needed the right data in the right format -- lists of tuples. You did the hard part by reading the file!


8. Writing CSV Files

In [ ]:
# csv.writer handles adding commas and proper formatting
# Let's write just the whale sightings (no dolphins or turtles)

whale_only = [s for s in sightings if "Whale" in s[SPECIES]]

with open("whales_only.csv", "w", newline="") as file:
    writer = csv.writer(file)
    # Write the header row
    writer.writerow(["date", "species", "count", "length_m", "latitude", "longitude", "behavior"])
    # Write each data row
    for sighting in whale_only:
        writer.writerow(sighting)

print(f"Wrote {len(whale_only)} whale records to whales_only.csv")

# Verify by reading it back
with open("whales_only.csv", "r") as file:
    print(file.read())

Notice newline="" in the open() call when writing CSV. This prevents extra blank lines on Windows. Always include it when writing CSV files. You don't need it when reading.

  • writer.writerow(row) writes one row
  • writer.writerows(list_of_rows) writes many rows at once

9. Fetching Data from the Internet

In [ ]:
# urllib is a standard library module -- same import pattern as csv, random, math
# urlretrieve() downloads a file from a URL and saves it locally

urllib.request.urlretrieve(WHALE_DATA_URL, "south_african_whales.csv")
print("Download complete!")

# Now read it like any other CSV file
record_count = 0
with open("south_african_whales.csv", "r") as file:
    reader = csv.reader(file)
    header = next(reader)
    for row in reader:
        record_count += 1

print(f"Downloaded {record_count} records from South Africa!")
print(f"Columns: {header}")
In [ ]:
# Let's count species in the South African dataset
# and visualize with our helper function

sa_species_counts = []
sa_seen = []
sa_sightings = []

with open("south_african_whales.csv", "r") as file:
    reader = csv.reader(file)
    next(reader)
    for row in reader:
        sa_sightings.append(row)
        name = row[REMOTE_SPECIES]
        if name not in sa_seen:
            sa_seen.append(name)

for name in sa_seen:
    total = 0
    for row in sa_sightings:
        if row[REMOTE_SPECIES] == name:
            total += 1
    sa_species_counts.append((name, total))

plot_species_bar_chart(sa_species_counts)
print("\nSpecies breakdown:")
for name, num in sa_species_counts:
    print(f"  {name}: {num} sightings")

We just downloaded over 6,000 real whale sighting records from the internet and visualized them -- in about 15 lines of code! This is the power of combining file I/O with Python's standard library. The data was collected by marine researchers in South Africa from 1913 to 2016.


10. Exception Handling

What happens when something goes wrong? A file doesn't exist, or CSV data has a bad number? Without error handling, your program crashes. Let's learn to handle these situations gracefully.

In [ ]:
# What if the file doesn't exist?
# Uncomment to see the error:
# with open("nonexistent_file.txt", "r") as file:
#     content = file.read()
# FileNotFoundError: [Errno 2] No such file or directory

# What if CSV data has a bad number?
# int("not_a_number")  # ValueError: invalid literal for int()

# These errors CRASH your program! Let's learn to handle them gracefully.
print("Run this cell, then try uncommenting the lines above one at a time.")
In [ ]:
# try/except lets you ATTEMPT something and CATCH errors if they happen
# Instead of crashing, your program can respond gracefully

try:
    with open("nonexistent_file.txt", "r") as file:
        content = file.read()
    print(content)
except FileNotFoundError:
    print("That file doesn't exist! Please check the filename.")

print("Program keeps running -- no crash!")
In [ ]:
# Different errors need different responses
# FileNotFoundError: file doesn't exist
# ValueError: can't convert a string to a number

def read_whale_length(length_str):
    """Convert a length string to a float, handling bad data."""
    try:
        length = float(length_str)
        print(f"Whale length: {length}m")
        return length
    except ValueError:
        print(f"Bad data: '{length_str}' is not a valid number")
        return 0.0


read_whale_length("14.5")  # Works fine
read_whale_length("unknown")  # Handles the error
read_whale_length("")  # Handles empty data too
In [ ]:
# You can capture the error object to see what went wrong

try:
    with open("missing_data.csv", "r") as file:
        content = file.read()
except FileNotFoundError as error:
    print(f"Error details: {error}")

try:
    value = int("abc")
except ValueError as error:
    print(f"Error details: {error}")
In [ ]:
# You can handle different error types with separate except blocks

def safe_read_sighting(filename, row_index):
    """Safely read a specific row from a CSV file."""
    try:
        with open(filename, "r") as file:
            reader = csv.reader(file)
            next(reader)  # skip header
            rows = list(reader)
            sighting = rows[row_index]
            count = int(sighting[COUNT])
            print(f"{sighting[SPECIES]}: {count} animals")
    except FileNotFoundError:
        print(f"File '{filename}' not found")
    except IndexError:
        print(f"Row {row_index} doesn't exist in the file")
    except ValueError:
        print("Could not convert count to a number")


safe_read_sighting("whale_sightings.csv", 0)  # Works
safe_read_sighting("fake_file.csv", 0)  # FileNotFoundError
safe_read_sighting("whale_sightings.csv", 999)  # IndexError

Think of try/except like a safety net. The code inside try is the tightrope walk -- it might succeed or it might fail. The code inside except is the net that catches you if you fall. Without it, your program crashes to the ground.

Rule of thumb: Use try/except at the boundaries of your program -- where you interact with things outside your control: files (might not exist), user input (might be garbage), network requests (might fail). You don't need it for regular math or string operations within your code.


Question 3: Count Species Sightings (1 point)

Write a function called count_species that takes a CSV filename as a parameter and returns a list of tuples. Each tuple should contain a species name and how many sighting records exist for that species in the file. The function should read the CSV, skip the header row, and tally up the records for each unique species.

After calling your function, pass the result to plot_species_bar_chart() to visualize it!

Hint: Use csv.reader inside a with block, skip the header with next(), and loop through rows. For counting, use two lists: one to track which species you've seen, and another to accumulate the (species, count) tuples. This is the same accumulator pattern from previous lectures.

In [ ]:
def count_species(csv_filename):
    """Read a CSV file and return a list of (species, count) tuples."""
    seen = ...
    sighting_rows = ...
    ...
        reader = ...
        ...
        ...
    ...
        ...
    result = ...
    ...
        total = ...
        ...
            ...
        ...
    ...


# Test it and visualize!
local_species_counts = count_species("whale_sightings.csv")
print(local_species_counts)
plot_species_bar_chart(local_species_counts)
In [ ]:
grader.check("q3_species_counts")

Question 4: Build a Safe File Reader (1 point)

Write a function called safe_line_count that takes a filename as a parameter and returns the number of lines in that file. If the file does not exist, the function should NOT crash -- instead, it should print an informative message and return -1. Use a try/except block to handle the error.

Hint: Wrap your file-reading code in a try block. The except block should catch the specific type of error that occurs when a file is missing. Return the line count on success, or -1 on failure.

In [ ]:
def safe_line_count(filename):
    """Count lines in a file, returning -1 if the file doesn't exist."""
    ...
        count = ...
        ...
            ...
        ...
    ...
        ...
        ...


# Test it
print(f"captains_log.txt: {safe_line_count('captains_log.txt')} lines")
print(f"whale_sightings.csv: {safe_line_count('whale_sightings.csv')} lines")
print(f"missing_file.txt: {safe_line_count('missing_file.txt')} lines")
In [ ]:
grader.check("q4_safe_reader")

Question 5: Fetch and Analyze Remote Data (1 point)

Write a function called count_remote_species that takes a URL and a local filename as parameters. The function should download the remote CSV file to the local filename, read it, and return a list of (species, count) tuples -- just like count_species from Q3, but for remote data. Use urllib.request.urlretrieve() for downloading. Wrap the whole operation in a try/except block so a network error doesn't crash the program -- return an empty list if anything goes wrong.

Hint: Start with urllib.request.urlretrieve(url, local_filename) to download. Then open the local file with csv.reader, skip the header, and count species. Use the REMOTE_SPECIES index constant for the remote data. Wrap everything in try/except.

In [ ]:
# YOUR CODE HERE
...
    ...
    ...
        ...
        seen = ...
        all_rows = ...
        ...
            reader = ...
            ...
            ...
        ...
            ...
        result = ...
        ...
            total = ...
            ...
                ...
            ...
        ...
    ...
        ...
        ...


# Test it
remote_species_counts = count_remote_species(WHALE_DATA_URL, "south_african_whales.csv")
print(f"Found {len(remote_species_counts)} species in remote dataset")
for name, num in remote_species_counts:
    print(f"  {name}: {num}")
if remote_species_counts:
    plot_species_bar_chart(remote_species_counts)
In [ ]:
grader.check("q5_remote_analysis")

Question 6 (Stretch): Generate Research Report (1 point)

Combine your skills! Write a function called generate_research_summary that takes a local CSV filename and an output report filename. Instead of recalculating everything from scratch, reuse your count_species function from Q3 to get the species counts. Then write a formatted report to the output file with:

  • A title line: SEMESTER AT SEA - SPECIES SUMMARY
  • A separator line of 40 equals signs
  • One line per species showing its name and sighting count
  • A final line with the total number of unique species

Return the total number of unique species found. This is function composition -- building complex behavior from simple building blocks.

Hint: Call count_species(csv_filename) to get the species data -- don't re-read the CSV yourself. Loop through the returned tuples to write each species line. Think about what each function gives back and how to chain them together.

In [ ]:
# YOUR CODE HERE
...
    ...
    species_data = ...
    ...
        ...
        ...
        ...
            ...
        ...
    ...


# Test: generate a report from our expedition data
species_total = generate_research_summary("whale_sightings.csv", "research_summary.txt")
print(f"Report generated! {species_total} species documented.\n")

# Read and display the report
with open("research_summary.txt", "r") as f:
    print(f.read())

# Bonus: visualize the data too!
plot_species_bar_chart(count_species("whale_sightings.csv"))
In [ ]:
grader.check("q6_stretch_report")

Summary

Concept Syntax Expedition Example
Read a file open("file", "r") open("captains_log.txt", "r")
Write a file open("file", "w") open("field_report.txt", "w")
Append to a file open("file", "a") open("captains_log.txt", "a")
Safe file handling with open(...) as f: Auto-closes the file
Read all content f.read() Get entire log as one string
Process line by line for line in f: Loop through log entries
Clean line endings line.strip() Remove \n whitespace
Read CSV csv.reader(file) Parse whale sighting records
Skip CSV header next(reader) Skip column names row
Write CSV csv.writer(file) Save filtered sighting data
Download from internet urllib.request.urlretrieve() Fetch South African whale data
Handle errors try: ... except: Catch missing files, bad data
Function composition Call functions inside functions generate_research_summary() calls count_species()

Key Takeaways

  1. Files persist data -- variables disappear when Python stops, but files stay on disk
  2. Always use with -- it guarantees the file closes, even if errors occur
  3. csv.reader gives you strings -- convert numeric fields with int() or float()
  4. Process files with for loops -- same counter/accumulator patterns you already know
  5. try/except prevents crashes -- use it at boundaries (files, network, user input)
  6. Function composition scales -- small functions that each do one thing combine into powerful pipelines

What's Next?

  • Lab: Grade book manager -- practice reading/writing CSV grade data with error handling
  • Next Week: Lists and list operations

Submitting to Gradescope

This file is saved on your computer -- you do not need to download it from Jupyter.

  1. Find the file on your computer:

    • Mac: Open Finder -> Documents/CSC115/lecture_notebooks/07_lecture_file_io_exception_handling/07_lecture_file_io_exception_handling.ipynb
    • Windows: Open File Explorer -> Documents\CSC115\lecture_notebooks\07_lecture_file_io_exception_handling\07_lecture_file_io_exception_handling.ipynb
  2. Upload to Gradescope:

    • Go to gradescope.com and open this assignment
    • Click "Submit" and upload the .ipynb file
    • The filename must be exactly 07_lecture_file_io_exception_handling.ipynb

Do NOT use File > Download in Jupyter -- this can rename the file and cause submission errors.


You have completed the File I/O and Exception Handling notebook.


To double-check your work, the cell below will rerun all of the autograder tests.

In [ ]:
grader.check_all()