Mini Python Project — Student Grade Tracker

grade_tracker/
├── grade_tracker.py   # main application — all classes and logic
└── students.csv        # auto-created on first save

import csv
import os
import numpy as np
from datetime import datetime
from functools import wraps

# ──────────────────────────────────────────────
# Custom exception
# ──────────────────────────────────────────────
class DuplicateStudentError(Exception):
    """Raised when a student ID already exists in the tracker."""
    pass

# ──────────────────────────────────────────────
# Logging decorator
# ──────────────────────────────────────────────
def log_action(func):
    """Decorator — prints a timestamped log line for every significant action."""
    @wraps(func)
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        timestamp = datetime.now().strftime("%H:%M:%S")
        print(f"  [{timestamp}] ✓ {func.__name__} completed")
        return result
    return wrapper

class Student:
    """
    Represents one student and their subject scores.

    Attributes:
        student_id (str): Unique identifier (e.g. "S001")
        name       (str): Full name
        scores     (dict): {subject: score} — scores are 0–100 floats
    """

    GRADE_BOUNDARIES = [
        (90, "A+"), (80, "A"), (70, "B"), (60, "C"), (50, "D"), (0, "F")
    ]

    def __init__(self, student_id: str, name: str):
        if not student_id.strip():
            raise ValueError("Student ID cannot be empty.")
        if not name.strip():
            raise ValueError("Student name cannot be empty.")
        self._id    = student_id.strip().upper()
        self._name  = name.strip().title()
        self._scores: dict[str, float] = {}

    # ── Read-only properties ──────────────────
    @property
    def student_id(self) -> str:
        return self._id

    @property
    def name(self) -> str:
        return self._name

    @property
    def scores(self) -> dict:
        return dict(self._scores)   # return a copy — protects internal state

    # ── Computed properties ───────────────────
    @property
    def average(self) -> float:
        """Mean score across all subjects. Returns 0.0 if no scores recorded."""
        if not self._scores:
            return 0.0
        return float(np.mean(list(self._scores.values())))

    @property
    def grade(self) -> str:
        """Letter grade derived from the average score."""
        avg = self.average
        for threshold, letter in self.GRADE_BOUNDARIES:
            if avg >= threshold:
                return letter
        return "F"

    @property
    def highest_score(self) -> tuple[str, float]:
        """Returns (subject, score) for the best subject."""
        if not self._scores:
            return ("None", 0.0)
        best = max(self._scores, key=self._scores.get)
        return (best, self._scores[best])

    @property
    def lowest_score(self) -> tuple[str, float]:
        """Returns (subject, score) for the weakest subject."""
        if not self._scores:
            return ("None", 0.0)
        worst = min(self._scores, key=self._scores.get)
        return (worst, self._scores[worst])

    # ── Methods ───────────────────────────────
    def add_score(self, subject: str, score: float) -> None:
        """Record a score for a subject. Score must be between 0 and 100."""
        subject = subject.strip().title()
        if not (0 <= score <= 100):
            raise ValueError(f"Score {score} is out of range (0–100).")
        self._scores[subject] = round(float(score), 2)

    def to_dict(self) -> dict:
        """Serialise to a flat dict suitable for CSV writing."""
        return {
            "student_id": self._id,
            "name":       self._name,
            "scores":     str(self._scores),   # store as string repr
        }

    def __repr__(self) -> str:
        return (f"Student(id={self._id!r}, name={self._name!r}, "
                f"avg={self.average:.1f}, grade={self.grade!r})")

class GradeTracker:
    """
    Manages a collection of Student objects.

    Responsibilities:
      - Add / look up students
      - Record scores
      - Persist to / load from CSV
      - Generate class report
    """

    CSV_FILE = "students.csv"
    SUBJECTS  = ["Maths", "English", "Science", "History", "Art"]

    def __init__(self):
        self._students: dict[str, Student] = {}   # {student_id: Student}
        self._load()   # restore previous session on startup

    # ── Internal helpers ──────────────────────
    def _get(self, student_id: str) -> Student:
        """Retrieve a student by ID or raise KeyError with a helpful message."""
        sid = student_id.strip().upper()
        if sid not in self._students:
            raise KeyError(f"No student found with ID '{sid}'.")
        return self._students[sid]

    # ── CSV Persistence ───────────────────────
    def _load(self) -> None:
        """Load students from CSV on startup. Silently skips if file missing."""
        if not os.path.exists(self.CSV_FILE):
            return
        with open(self.CSV_FILE, newline="", encoding="utf-8") as f:
            for row in csv.DictReader(f):
                s = Student(row["student_id"], row["name"])
                # ast.literal_eval safely parses the stored dict string
                import ast
                scores = ast.literal_eval(row["scores"]) if row["scores"] != "{}" else {}
                for subject, score in scores.items():
                    s.add_score(subject, score)
                self._students[s.student_id] = s
        print(f"  Loaded {len(self._students)} student(s) from {self.CSV_FILE}")

    @log_action
    def save(self) -> None:
        """Write all students to CSV."""
        with open(self.CSV_FILE, "w", newline="", encoding="utf-8") as f:
            writer = csv.DictWriter(f, fieldnames=["student_id", "name", "scores"])
            writer.writeheader()
            for s in self._students.values():
                writer.writerow(s.to_dict())

    # ── Student management ────────────────────
    @log_action
    def add_student(self, student_id: str, name: str) -> Student:
        """Add a new student. Raises DuplicateStudentError if ID already exists."""
        sid = student_id.strip().upper()
        if sid in self._students:
            raise DuplicateStudentError(
                f"Student ID '{sid}' already exists. Use a unique ID."
            )
        student = Student(student_id, name)
        self._students[sid] = student
        return student

    @log_action
    def record_score(self, student_id: str, subject: str, score: float) -> None:
        """Record a subject score for a student."""
        student = self._get(student_id)
        student.add_score(subject, score)

    def get_student(self, student_id: str) -> Student:
        return self._get(student_id)

    def all_students(self) -> list[Student]:
        return list(self._students.values())

    # ── Class-level statistics ─────────────────
    def class_average(self) -> float:
        """Mean of all student averages. Returns 0.0 for empty tracker."""
        students = self.all_students()
        if not students:
            return 0.0
        return float(np.mean([s.average for s in students]))

    def top_students(self, n: int = 3) -> list[Student]:
        """Return the top N students by average score."""
        return sorted(self.all_students(),
                      key=lambda s: s.average, reverse=True)[:n]

    def at_risk_students(self, threshold: float = 50.0) -> list[Student]:
        """Return students whose average is below the threshold."""
        return [s for s in self.all_students() if s.average < threshold]

    def subject_averages(self) -> dict[str, float]:
        """Compute the class average for each subject."""
        subject_scores: dict[str, list] = {}
        for s in self.all_students():
            for subj, score in s.scores.items():
                subject_scores.setdefault(subj, []).append(score)
        return {subj: round(float(np.mean(scores)), 2)
                for subj, scores in subject_scores.items()}

def print_report(tracker: GradeTracker) -> None:
    """Print a full formatted class report to the terminal."""
    students = tracker.all_students()
    if not students:
        print("  No students recorded yet.")
        return

    # Sort by average descending for the ranking
    ranked = sorted(students, key=lambda s: s.average, reverse=True)

    # ── Header ──────────────────────────────────────────────────────────
    width = 72
    print("\n" + "=" * width)
    print(" STUDENT GRADE TRACKER — CLASS REPORT ".center(width))
    print(f" Generated: {datetime.now().strftime('%Y-%m-%d %H:%M')} ".center(width))
    print("=" * width)

    # ── Class summary ────────────────────────────────────────────────────
    class_avg  = tracker.class_average()
    top        = ranked[0]
    bottom     = ranked[-1]
    at_risk    = tracker.at_risk_students()
    subj_avgs  = tracker.subject_averages()

    print(f"\n  Total students  : {len(students)}")
    print(f"  Class average   : {class_avg:.1f}  ({_grade_from_avg(class_avg)})")
    print(f"  Top performer   : {top.name} ({top.average:.1f})")
    print(f"  Needs support   : {bottom.name} ({bottom.average:.1f})")
    print(f"  At-risk (<50)   : {len(at_risk)} student(s)")

    if subj_avgs:
        best_subj  = max(subj_avgs, key=subj_avgs.get)
        worst_subj = min(subj_avgs, key=subj_avgs.get)
        print(f"  Strongest subj  : {best_subj} ({subj_avgs[best_subj]:.1f})")
        print(f"  Weakest subj    : {worst_subj} ({subj_avgs[worst_subj]:.1f})")

    # ── Per-student table ────────────────────────────────────────────────
    print("\n" + "-" * width)
    print(f"  {'Rank':<5} {'ID':<8} {'Name':<20} {'Avg':>6} {'Grade':>6}  Scores")
    print("-" * width)

    for rank, s in enumerate(ranked, start=1):
        score_str = "  ".join(f"{subj}:{score:.0f}"
                              for subj, score in sorted(s.scores.items()))
        medal = {1: "🏉", 2: "🥈", 3: "🥉"}.get(rank, "  ")
        print(f"  {medal}{rank:<4} {s.student_id:<8} {s.name:<20} "
              f"{s.average:>6.1f} {s.grade:>6}  {score_str}")

    # ── Subject averages ─────────────────────────────────────────────────
    if subj_avgs:
        print("\n" + "-" * width)
        print("  Subject Averages:")
        for subj, avg in sorted(subj_avgs.items()):
            bar   = "█" * int(avg / 5)   # max 20 blocks at score=100
            grade = _grade_from_avg(avg)
            print(f"    {subj:<12} {avg:>5.1f}  {grade}  {bar}")

    # ── At-risk students ─────────────────────────────────────────────────
    if at_risk:
        print("\n" + "-" * width)
        print("  ⚠  At-Risk Students (average < 50):")
        for s in at_risk:
            print(f"    {s.name} ({s.student_id}) — avg {s.average:.1f}")

    print("\n" + "=" * width + "\n")


def _grade_from_avg(avg: float) -> str:
    """Helper — letter grade from a numeric average."""
    for threshold, letter in Student.GRADE_BOUNDARIES:
        if avg >= threshold:
            return letter
    return "F"

def main():
    print("\n" + "=" * 50)
    print("   STUDENT GRADE TRACKER".center(50))
    print("=" * 50)

    tracker = GradeTracker()   # loads from CSV automatically

    # ── Add students ──────────────────────────────────
    print("\n--- Adding Students ---")
    try:
        tracker.add_student("S001", "alice smith")
        tracker.add_student("S002", "diana osei")
        tracker.add_student("S003", "charlie brown")
        tracker.add_student("S004", "bob jones")
        tracker.add_student("S001", "duplicate")   # will raise error
    except DuplicateStudentError as e:
        print(f"  Caught: {e}")
    except ValueError as e:
        print(f"  Validation error: {e}")

    # ── Record scores ─────────────────────────────────
    print("\n--- Recording Scores ---")
    score_data = [
        ("S001", "Maths",   90), ("S001", "English", 88), ("S001", "Art",     95),
        ("S002", "Maths",   84), ("S002", "English", 80),
        ("S003", "Maths",   72), ("S003", "Science", 72),
        ("S004", "Maths",   60), ("S004", "English", 45),
    ]
    for sid, subj, score in score_data:
        try:
            tracker.record_score(sid, subj, score)
        except (KeyError, ValueError) as e:
            print(f"  Error: {e}")

    # ── Individual lookups ────────────────────────────
    print("\n--- Individual Student Info ---")
    alice = tracker.get_student("S001")
    print(f"  {alice}")
    best_subj, best_score = alice.highest_score
    worst_subj, worst_score = alice.lowest_score
    print(f"  Best subject : {best_subj} ({best_score})")
    print(f"  Weak subject : {worst_subj} ({worst_score})")

    # ── Save ──────────────────────────────────────────
    print("\n--- Saving Data ---")
    tracker.save()

    # ── Full report ───────────────────────────────────
    print_report(tracker)


if __name__ == "__main__":
    main()