File Handling Complete Guide

Complete Python File Handling & Data Persistence Guide

In previous modules, you learned how to process data in-memory using variables, collections, loops, and functions. However, all data created during program execution resides in random-access memory (RAM) and is lost as soon as the program terminates. To create useful, real-world applications, you must be able to persist data permanently.

This guide covers Python's built-in file handling capabilities, path manipulation, and structured data serialization using CSV and JSON formats. You will learn to read and write permanent files, manage directory structures, and handle input/output operations safely and efficiently using a strictly procedural, function-based design.

Table of Contents

1. Memory Persistence & File Systems
2. Text File Operations
3. Comma-Separated Values (CSV)
4. JavaScript Object Notation (JSON)
5. File System & Directory Manipulation
6. Data Validation & Safe Operations
7. Comprehensive Practice Project: Student Gradebook System

1. Memory Persistence & File Systems

Technical Hook & Concept

When you assign a value to a variable, it is stored in your computer's RAM. RAM is volatile, meaning it requires electricity to maintain its state. When your program finishes or your computer powers down, RAM is cleared.

Data persistence is the practice of saving in-memory data to non-volatile storage media (such as SSDs or HDDs). In modern computing, this storage is organized by the operating system into a hierarchy of directories (folders) and files.

Operating System File System Tree:
 Root Directory (/)
 ├── Users/
 │   └── student/
 │       └── projects/
 │           ├── main.py (Active Script)
 │           ├── data/
 │           │   ├── students.csv (Tabular data)
 │           │   └── config.json (Nested parameters)
 │           └── output/
 │               └── report.txt (Generated summary)

To interact with this hierarchy, you must understand file paths:

• Absolute Path: The complete, unambiguous address of a file starting from the root of the file system (e.g., /Users/student/projects/data/students.csv on Unix or C:\Users\student\projects\data\students.csv on Windows).
• Relative Path: A path defined relative to the script's current working directory (e.g., data/students.csv).
• Special Path Indicators:

  • . (Single dot): Represents the current working directory.
  • .. (Double dot): Represents the parent directory.

Modern Path Operations with Pathlib

Python historically used the os.path module for path manipulation, which relied on string concatenations and varied between operating systems (which use / vs \). Modern Python uses the object-oriented pathlib module, which abstract paths into robust, cross-platform components.

main.pyRunnable
EditCopyRun
import pathlib
import os

## Get the current working directory
current_dir = pathlib.Path(".")
print(f"Current Directory (Relative): {current_dir}")
print(f"Current Directory (Absolute): {current_dir.resolve()}")

## Define paths safely using the slash operator (/) which works on all OS platforms
data_folder = pathlib.Path("data")
file_path = data_folder / "students.csv"

print(f"Target File Path: {file_path}")
print(f"File Name: {file_path.name}")
print(f"File Suffix (Extension): {file_path.suffix}")
print(f"File Stem (Name without extension): {file_path.stem}")
print(f"Is Directory Parent Exists? {data_folder.exists()}")

Output:

Current Directory (Relative): .
Current Directory (Absolute): /workspace/projects
Target File Path: data/students.csv
File Name: students.csv
File Suffix (Extension): .csv
File Stem (Name without extension): students
Is Directory Parent Exists? False

Self-Check Checklist

• Self-Check: I understand the difference between volatile RAM and non-volatile disk storage. (Click to check)
• Self-Check: I can explain the difference between absolute and relative file paths. (Click to check)
• Self-Check: I can use pathlib.Path to construct cross-platform file paths using the / operator. (Click to check)

2. Text File Operations

Technical Hook & Concept

Files are broadly classified into two categories: Text Files (which contain human-readable characters encoded in formats like UTF-8) and Binary Files (which contain raw bytes representing compiled code, images, or proprietary formats). This module focuses primarily on text-based data persistence.

To read or write a file, you must:

1. Open the file and acquire a file handle.
2. Read data from or write data to the handle.
3. Close the file handle to flush buffers and release operating system resources.

File Modes

When opening a file, you must specify the operation mode:

• 'r' (Read Mode): Opens a file for reading. The file must exist, or a FileNotFoundError is raised. This is the default.
• 'w' (Write Mode): Opens a file for writing. If the file already exists, its contents are truncated (deleted). If the file does not exist, a new file is created.
• 'a' (Append Mode): Opens a file for writing, but preserves existing content. All new data is written to the end of the file.
• 'r+' (Read and Write Mode): Opens an existing file for editing. The file pointer starts at the beginning of the file.

Context Managers (with Statement)

Manually calling file.close() is highly discouraged in software engineering. If an error occurs between opening and closing a file, the file remains open in memory, causing potential resource leaks or file corruption.

Instead, Python provides Context Managers via the with statement. The context manager guarantees that the file handle is automatically and safely closed when the execution block is exited, even if an exception is raised inside the block.

main.pyRunnable
EditCopyRun
## procedural_text_operations.py

## 1. Writing to a file (Creates new or overwrites)
print("--- Writing Data ---")
with open("sample_log.txt", "w", encoding="utf-8") as file:
    file.write("First Log Entry\n")
    file.write("Second Log Entry: System normal\n")

print("File written successfully.")


with open("sample_log.txt", "a", encoding="utf-8") as file:
    file.write("Third Log Entry: Warning registered\n")

print("Data appended successfully.")

## 3. Reading entire file at once
print("\n--- Reading Entire Content ---")
with open("sample_log.txt", "r", encoding="utf-8") as file:
    content = file.read()
    print(content)

## 4. Reading line-by-line (Memory Efficient for large files)
print("--- Streaming Line by Line ---")
with open("sample_log.txt", "r", encoding="utf-8") as file:
    line_number = 1
    for line in file:
        print(f"Row {line_number}: {line.strip()}")
        line_number += 1

Output:

--- Writing Data ---
File written successfully.

--- Appending Data ---
Data appended successfully.

--- Reading Entire Content ---
First Log Entry
Second Log Entry: System normal
Third Log Entry: Warning registered


--- Streaming Line by Line ---
Row 1: First Log Entry
Row 2: Second Log Entry: System normal
Row 3: Third Log Entry: Warning registered

Self-Check Checklist

• Self-Check: I can explain why using a with context manager is safer than manually opening and closing files. (Click to check)
• Self-Check: I know the difference between 'w' (write/truncate) and 'a' (append) modes. (Click to check)
• Self-Check: I can read large files efficiently by iterating line-by-line rather than loading all text into RAM. (Click to check)

3. Comma-Separated Values (CSV)

Technical Hook & Concept

A comma-separated values (CSV) file is a plain text file that represents structured tabular data. Each line of the file represents a single row, and individual columns are separated by a delimiter, most commonly a comma (,) or tab (\t).

While you can parse CSV files manually using string splitting (line.split(",")), this approach fails when column values contain commas enclosed in quotes (e.g., "Denver, Colorado"). Python's built-in csv module provides robust parser components to handle these complexities.

CSV Raw Text Layout:
student_id,name,math_score,science_score
S101,Alice Johnson,95,92
S102,Bob Smith,88,85

Procedural CSV Operations

We perform CSV operations using two standard formats: lists of rows or dictionaries mapping keys to column headers.

main.pyRunnable
EditCopyRun
## procedural_csv_operations.py
import csv

## 1. Writing to a CSV file (List of Lists format)
data_to_write = [
    ["student_id", "name", "math_score", "science_score"],
    ["S101", "Alice Johnson", "95", "92"],
    ["S102", "Bob Smith", "88", "85"],
    ["S103", "Charlie Davis", "91", "90"]
]

print("--- Writing Tabular Data to CSV ---")
## Always set newline="" when opening CSV files to prevent blank row injection on Windows platforms
with open("students.csv", "w", newline="", encoding="utf-8") as csv_file:
    writer = csv.writer(csv_file)
    writer.writerows(data_to_write)

print("students.csv created successfully.")

## 2. Reading from CSV (Standard Reader)
print("\n--- Reading CSV Rows ---")
with open("students.csv", "r", encoding="utf-8") as csv_file:
    reader = csv.reader(csv_file)
    header = next(reader) # Extract the header row
    print(f"Header: {header}")
    for row in reader:
        print(f"Student: {row[1]} | Math: {row[2]} | Science: {row[3]}")

## 3. Parsing CSV using DictReader (Keys mapped to headers)
print("\n--- Parsing CSV using DictReader ---")
with open("students.csv", "r", encoding="utf-8") as csv_file:
    dict_reader = csv.DictReader(csv_file)
    for record in dict_reader:
        # Values are automatically mapped to header keys
        print(f"ID: {record['student_id']} - {record['name']} (Math: {record['math_score']})")

Output:

--- Writing Tabular Data to CSV ---
students.csv created successfully.

--- Reading CSV Rows ---
Header: ['student_id', 'name', 'math_score', 'science_score']
Student: Alice Johnson | Math: 95 | Science: 92
Student: Bob Smith | Math: 88 | Science: 85
Student: Charlie Davis | Math: 91 | Science: 90

--- Parsing CSV using DictReader ---
ID: S101 - Alice Johnson (Math: 95)
ID: S102 - Bob Smith (Math: 88)
ID: S103 - Charlie Davis (Math: 91)

Self-Check Checklist

• Self-Check: I understand that csv.DictReader maps each row to a dictionary using header names as keys. (Click to check)
• Self-Check: I understand the necessity of specifying newline="" when writing CSV files to avoid double-newline bugs. (Click to check)
• Self-Check: I can parse files with quoted field items containing commas without breaking column alignments. (Click to check)

4. JavaScript Object Notation (JSON)

Technical Hook & Concept

While CSV is excellent for flat, tabular spreadsheets, it cannot easily represent hierarchical or deeply nested data structures (such as a student record containing a list of class dictionaries, each containing test scores).

JavaScript Object Notation (JSON) is a lightweight, language-independent data exchange format. It mirrors Python's native dictionaries and lists perfectly, making it the industry standard for configuration settings and web data persistence.

JSON Hierarchical Layout:
{
  "class_name": "Python Foundations",
  "roster": [
    {
      "id": "S101",
      "name": "Alice",
      "hobbies": ["chess", "robotics"]
    }
  ]
}

Procedural JSON Serialization

Python's built-in json module provides four primary functions for serialization:

• json.dump(obj, fp): Serializes a Python object directly to an open file pointer.
• json.dumps(obj): Serializes a Python object to a string in memory.
• json.load(fp): Deserializes JSON data from an open file pointer to Python dictionaries/lists.
• json.loads(string): Deserializes JSON data from a string.

main.pyRunnable
EditCopyRun
## procedural_json_operations.py
import json

## Define a deeply nested data structure (impossible to store easily in flat CSV)
course_data = {
    "course_id": "CS-101",
    "name": "Python Foundations",
    "parameters": {
        "max_students": 30,
        "passing_threshold": 70.0
    },
    "enrolled_students": [
        {
            "id": "S101",
            "name": "Alice Johnson",
            "grades": {"quiz": 95.0, "exam": 92.5}
        },
        {
            "id": "S102",
            "name": "Bob Smith",
            "grades": {"quiz": 84.0, "exam": 89.0}
        }
    ]
}

## 1. Serializing and writing to JSON file
print("--- Serializing Python Object to JSON ---")
with open("course_details.json", "w", encoding="utf-8") as json_file:
    # Use indent parameter for human-readable layout
    json.dump(course_data, json_file, indent=4, ensure_ascii=False)

print("course_details.json created successfully.")

## 2. Reading and deserializing JSON back to Python structures
print("\n--- Deserializing JSON File ---")
with open("course_details.json", "r", encoding="utf-8") as json_file:
    loaded_data = json.load(json_file)

## The loaded data is a normal Python dictionary
print(f"Loaded Course: {loaded_data['name']}")
print(f"Max Students: {loaded_data['parameters']['max_students']}")

## Iterate through the nested list
print("\nRoster Status:")
for student in loaded_data["enrolled_students"]:
    average = (student["grades"]["quiz"] + student["grades"]["exam"]) / 2
    print(f" * {student['name']} - Cumulative Average: {average:.2f}%")

Output:

--- Serializing Python Object to JSON ---
course_details.json created successfully.

--- Deserializing JSON File ---
Loaded Course: Python Foundations
Max Students: 30

Roster Status:
 * Alice Johnson - Cumulative Average: 93.75%
 * Bob Smith - Cumulative Average: 86.50%

Self-Check Checklist

• Self-Check: I can explain the difference between json.dump() (files) and json.dumps() (in-memory strings). (Click to check)
• Self-Check: I can load nested JSON structures and parse them using nested list/dictionary loops. (Click to check)
• Self-Check: I know how to use indent formatting to write human-readable JSON configurations. (Click to check)

5. File System & Directory Manipulation

Technical Hook & Concept

Robust programs must frequently organize files, create directory structured workspaces, copy logs, or clean up outdated temporary files on disk. Python provides structural directory operations using pathlib and high-level file utilities using the standard shutil module.

main.pyRunnable
EditCopyRun
## procedural_fs_operations.py
import pathlib
import shutil

## 1. Set up absolute paths relative to current workspace
workspace_dir = pathlib.Path("./workspace")
archive_dir = workspace_dir / "archive"
source_file = workspace_dir / "active_report.txt"
destination_file = archive_dir / "report_backup.txt"

## Create directories recursively
print("--- Creating Directory Structures ---")
archive_dir.mkdir(parents=True, exist_ok=True)
print(f"Created: {archive_dir}")

## 2. Write a file to copy
source_file.write_text("Daily status update: Operation completed.", encoding="utf-8")
print(f"Created source file: {source_file}")

## 3. Copying a file (Preserving metadata using copy2)
print("\n--- Copying Files ---")
if source_file.exists():
    shutil.copy2(source_file, destination_file)
    print(f"Copied {source_file.name} to {destination_file}")


for path in workspace_dir.rglob("*"): # Recursive scan
    path_type = "Folder" if path.is_dir() else "File"
    print(f" * [{path_type}] {path.relative_to(workspace_dir)}")

## 5. Cleaning up files
print("\n--- Deleting File Operations ---")
if source_file.exists():
    source_file.unlink() # Delete single file
    print(f"Deleted source file: {source_file}")


shutil.rmtree(workspace_dir)
print("Workspace cleaned successfully.")

Output:

--- Creating Directory Structures ---
Created: workspace/archive
Created source file: workspace/active_report.txt

--- Copying Files ---
Copied active_report.txt to workspace/archive/report_backup.txt

--- Scanning Workspace Directory ---
 * [Folder] archive
 * [File] active_report.txt
 * [File] archive/report_backup.txt

--- Deleting File Operations ---
Deleted source file: workspace/active_report.txt
Cleaning workspace folder recursively...
Workspace cleaned successfully.

Self-Check Checklist

• Self-Check: I can use mkdir(parents=True, exist_ok=True) to safely construct directory branches without raising exceptions. (Click to check)
• Self-Check: I understand that shutil.copy2() copies both file content and metadata (like modification dates). (Click to check)
• Self-Check: I know how to use .unlink() to delete individual files, and shutil.rmtree() to delete entire folders recursively. (Click to check)

6. Data Validation & Safe Operations

Technical Hook & Concept

File operations are prone to run-time errors due to environmental factors out of the control of your code (e.g., missing files, locked permissions, exhausted disk space). If a program attempts to read a file that has been deleted, it will crash immediately unless it employs safe validation checks and defensive error handling.

To write stable code, you must:

1. Validate inputs pre-emptively (e.g., use path.exists() or type restrictions).
2. Employ defensive try-except blocks to capture potential exceptions (FileNotFoundError, PermissionError, json.JSONDecodeError).

main.pyRunnable
EditCopyRun
## procedural_error_handling.py
import pathlib
import json

def load_settings_file(path_string):
    """Procedurally loads a JSON configuration file with strict error shielding"""
    target_path = pathlib.Path(path_string)
    
    # Pre-emptive check: Verify existence
    if not target_path.exists():
        print(f"[-] Validation Error: The file '{path_string}' does not exist.")
        return {}
    
    # Pre-emptive check: Verify it is actually a file, not a directory
    if not target_path.is_file():
        print(f"[-] Validation Error: '{path_string}' is a directory, not a valid file.")
        return {}
    
    try:
        with open(target_path, "r", encoding="utf-8") as file:
            data = json.load(file)
            print(f"[+] Success: Settings loaded from '{path_string}'")
            return data
            
    except FileNotFoundError:
        print("[-] Error: Target file vanished during operations.")
        return {}
    except PermissionError:
        print("[-] Error: Insufficient read privileges to access settings.")
        return {}
    except json.JSONDecodeError as decode_error:
        print(f"[-] Error: File contains invalid JSON structure. Details: {decode_error}")
        return {}
    except Exception as unexpected_error:
        print(f"[-] Unexpected system failure: {unexpected_error}")
        return {}

## 1. Test missing file handling
print("Testing Missing File:")
data1 = load_settings_file("missing_config.json")

## 2. Test corrupted JSON format validation
print("\nTesting Corrupted JSON Content:")
corrupt_path = pathlib.Path("corrupt.json")
corrupt_path.write_text("{'invalid_quotes': True, missing_bracket", encoding="utf-8")

data2 = load_settings_file("corrupt.json")

## Clean up
corrupt_path.unlink()

Output:

Testing Missing File:
[-] Validation Error: The file 'missing_config.json' does not exist.

Testing Corrupted JSON Content:
[-] Error: File contains invalid JSON structure. Details: Expecting property name enclosed in double quotes: line 1 column 2 (char 1)

Self-Check Checklist

• Self-Check: I can use path.exists() and path.is_file() to pre-emptively validate paths before opening them. (Click to check)
• Self-Check: I can catch separate exceptions such as FileNotFoundError and PermissionError to handle different system states. (Click to check)
• Self-Check: I know how to check for json.JSONDecodeError to handle malformed data. (Click to check)

7. Comprehensive Practice Project: Student Gradebook System

This comprehensive project implements a procedural, fully persistent student information system. It utilizes standard functions to perform CRUD (Create, Read, Update, Delete) operations on nested lists and dictionaries, reading from and writing to both JSON and CSV files.

Structural Architecture

• students_db.json: Stores primary student profiles, nested contact details, and current enrollment parameters in a structured JSON database.
• grades.csv: Stores tabular grade assignments linked back to students by their unique student_id.

System Data Pipeline:
                   ┌───────────────────────┐
                   │  JSON DB (Profiles)   │ ◄─── Read/Write (Nested JSON)
                   └───────────┬───────────┘
                               │ (Key: student_id)
                   ┌───────────▼───────────┐
                   │   CSV DB (Grades)     │ ◄─── Read/Write (Tabular CSV)
                   └───────────┬───────────┘
                               ▼
                   ┌───────────────────────┐
                   │  Procedural Reporter  │ ───► Outputs formatted reports
                   └───────────────────────┘

Pure Procedural Implementation

main.pyRunnable
EditCopyRun
## student_gradebook_system.py
import json
import csv
import pathlib

## Define database file targets
DB_PROFILES = pathlib.Path("students_db.json")
DB_GRADES = pathlib.Path("grades.csv")

## ==========================================
## DATABASE UTILITY FUNCTIONS
## ==========================================

def initialize_database():
    """Initializes empty database files if they do not exist on disk"""
    if not DB_PROFILES.exists():
        initial_profiles = {
            "version": "1.0.0",
            "profiles": {}
        }
        with open(DB_PROFILES, "w", encoding="utf-8") as file:
            json.dump(initial_profiles, file, indent=4)
        print("[System] Profiles database initialized.")
        
    if not DB_GRADES.exists():
        with open(DB_GRADES, "w", newline="", encoding="utf-8") as file:
            writer = csv.writer(file)
            writer.writerow(["student_id", "subject", "assignment_name", "score"])
        print("[System] Grades database initialized.")


def load_profiles():
    """Loads student profiles from the JSON database"""
    try:
        with open(DB_PROFILES, "r", encoding="utf-8") as file:
            data = json.load(file)
            return data.get("profiles", {})
    except (FileNotFoundError, json.JSONDecodeError):
        print("[-] Error loading profiles; returning empty database.")
        return {}


def save_profiles(profiles):
    """Saves student profiles to the JSON database"""
    save_data = {
        "version": "1.0.0",
        "profiles": profiles
    }
    with open(DB_PROFILES, "w", encoding="utf-8") as file:
        json.dump(save_data, file, indent=4, ensure_ascii=False)


def load_all_grades():
    """Loads all student grades from the tabular CSV file"""
    grades_list = []
    if not DB_GRADES.exists():
        return grades_list
    
    with open(DB_GRADES, "r", encoding="utf-8") as file:
        reader = csv.DictReader(file)
        for row in reader:
            # Type cast the score from string to float for mathematical calculations
            row["score"] = float(row["score"])
            grades_list.append(row)
    return grades_list


def append_grade_to_csv(student_id, subject, assignment_name, score):
    """Appends a single grade record to the CSV file"""
    with open(DB_GRADES, "a", newline="", encoding="utf-8") as file:
        writer = csv.writer(file)
        writer.writerow([student_id, subject, assignment_name, score])

## ==========================================
## CORE SYSTEM LOGIC FUNCTIONS
## ==========================================

def register_student(student_id, name, age, contact_email):
    """Registers a new student profile in the JSON database"""
    profiles = load_profiles()
    
    if student_id in profiles:
        print(f"[-] Registration Failure: Student ID '{student_id}' already exists.")
        return False
    
    # Store profiles in a structured nested dictionary format
    profiles[student_id] = {
        "name": name,
        "age": int(age),
        "contact": contact_email,
        "status": "active"
    }
    
    save_profiles(profiles)
    print(f"[+] Student registered successfully: {name} ({student_id})")
    return True


def record_student_grade(student_id, subject, assignment_name, score):
    """Records a grade for a registered student in the CSV file"""
    profiles = load_profiles()
    
    # Validation: Ensure student exists in profiles database
    if student_id not in profiles:
        print(f"[-] Grade Recording Failure: Student ID '{student_id}' does not exist.")
        return False
    
    # Validation: Ensure scores are numeric bounds
    if not 0.0 <= score <= 100.0:
        print("[-] Grade Recording Failure: Scores must range between 0.0 and 100.0.")
        return False
    
    append_grade_to_csv(student_id, subject, assignment_name, score)
    print(f"[+] Grade logged: {student_id} - {assignment_name}: {score}%")
    return True


def generate_student_report(student_id):
    """Generates a complete report card for a single student by merging JSON and CSV data"""
    profiles = load_profiles()
    
    if student_id not in profiles:
        print(f"[-] Report Failure: Student ID '{student_id}' not registered.")
        return
    
    student_info = profiles[student_id]
    all_grades = load_all_grades()
    
    # Filter grades associated with this student
    student_grades = [g for g in all_grades if g["student_id"] == student_id]
    
    print("\n" + "=" * 50)
    print(f"STUDENT REPORT CARD: {student_info['name']}")
    print(f"Student ID: {student_id}")
    print(f"Age: {student_info['age']} | Contact: {student_info['contact']}")
    print(f"Enrollment Status: {student_info['status'].title()}")
    print("-" * 50)
    
    if not student_grades:
        print("No grades registered yet.")
    else:
        # Group grades by subject to calculate subject averages
        grades_by_subject = {}
        for grade in student_grades:
            subj = grade["subject"]
            if subj not in grades_by_subject:
                grades_by_subject[subj] = []
            grades_by_subject[subj].append(grade["score"])
            
        print("Grade Details:")
        for grade in student_grades:
            print(f" * [{grade['subject']}] {grade['assignment_name']}: {grade['score']}%")
            
        print("-" * 50)
        print("Subject Averages:")
        total_sum = 0
        total_count = 0
        for subj, scores in grades_by_subject.items():
            subject_average = sum(scores) / len(scores)
            total_sum += sum(scores)
            total_count += len(scores)
            print(f" * {subj}: {subject_average:.2f}%")
            
        cumulative_average = total_sum / total_count
        print("-" * 50)
        print(f"Cumulative GPA Average: {cumulative_average:.2f}%")
        
    print("=" * 50)

## ==========================================
## TEST EXECUTION
## ==========================================

if __name__ == "__main__":
    # Clean workspace test environment
    for f in [DB_PROFILES, DB_GRADES]:
        if f.exists():
            f.unlink()
            
    # Initialize the data files
    initialize_database()
    
    # Register students (JSON database writes)
    register_student("S101", "Alice Johnson", 16, "alice@school.edu")
    register_student("S102", "Bob Smith", 17, "bob@school.edu")
    
    # Record grades (CSV database writes)
    record_student_grade("S101", "Mathematics", "Midterm Exam", 95.0)
    record_student_grade("S101", "Mathematics", "Weekly Quiz 1", 90.0)
    record_student_grade("S101", "Science", "Lab Report 1", 92.5)
    
    record_student_grade("S102", "Mathematics", "Midterm Exam", 82.0)
    record_student_grade("S102", "Science", "Lab Report 1", 88.0)
    
    # Generate comprehensive report cards (JSON + CSV merges)
    generate_student_report("S101")
    generate_student_report("S102")
    
    # Clean up test files from disk
    for f in [DB_PROFILES, DB_GRADES]:
        if f.exists():
            f.unlink()

Output:

[System] Profiles database initialized.
[System] Grades database initialized.
[+] Student registered successfully: Alice Johnson (S101)
[+] Student registered successfully: Bob Smith (S102)
[+] Grade logged: S101 - Midterm Exam: 95.0%
[+] Grade logged: S101 - Weekly Quiz 1: 90.0%
[+] Grade logged: S101 - Lab Report 1: 92.5%
[+] Grade logged: S102 - Midterm Exam: 82.0%
[+] Grade logged: S102 - Lab Report 1: 88.0%

==================================================
STUDENT REPORT CARD: Alice Johnson
Student ID: S101
Age: 16 | Contact: alice@school.edu
Enrollment Status: Active
--------------------------------------------------
Grade Details:
 * [Mathematics] Midterm Exam: 95.0%
 * [Mathematics] Weekly Quiz 1: 90.0%
 * [Science] Lab Report 1: 92.5%
--------------------------------------------------
Subject Averages:
 * Mathematics: 92.50%
 * Science: 92.50%
--------------------------------------------------
Cumulative GPA Average: 92.50%
==================================================

==================================================
STUDENT REPORT CARD: Bob Smith
Student ID: S102
Age: 17 | Contact: bob@school.edu
Enrollment Status: Active
--------------------------------------------------
Grade Details:
 * [Mathematics] Midterm Exam: 82.0%
 * [Science] Lab Report 1: 88.0%
--------------------------------------------------
Subject Averages:
 * Mathematics: 82.00%
 * Science: 88.00%
--------------------------------------------------
Cumulative GPA Average: 85.00%
==================================================

Self-Check Checklist

• Self-Check: I can register new students and read existing student profiles through the JSON file layer. (Click to check)
• Self-Check: I understand how the unique student_id acts as a common relationship key connecting records in JSON to records in CSV. (Click to check)
• Self-Check: I can parse a CSV file, filter matching rows, type cast scores, and compute subject/cumulative averages. (Click to check)