Project: A Results Analysis Tool

from dataclasses import dataclass

GRADE_BANDS = ((75, "A"), (65, "B"), (45, "C"), (30, "D"), (0, "F"))


@dataclass(frozen=True)
class Result:
    student: str
    form: int
    subject: str
    score: int

    @property
    def grade(self) -> str:
        return next(letter for minimum, letter in GRADE_BANDS if self.score >= minimum)

import csv
from io import StringIO

from models import Result


def load_results(text: str) -> tuple[list[Result], list[str]]:
    """Parse CSV text; return the valid results and a list of readable errors."""
    results: list[Result] = []
    errors: list[str] = []
    for line_no, row in enumerate(csv.DictReader(StringIO(text)), start=2):
        try:
            score = int(row["score"])
            form = int(row["form"])
            if not 0 <= score <= 100:
                raise ValueError(f"score {score} is outside 0-100")
            if not row["student"].strip():
                raise ValueError("student name is empty")
            results.append(Result(row["student"].strip(), form, row["subject"].strip(), score))
        except (ValueError, KeyError, TypeError) as err:
            errors.append(f"line {line_no}: {err}")
    return results, errors

import statistics
from collections import Counter, defaultdict

from models import Result


def subject_stats(results: list[Result]) -> dict[str, dict[str, float]]:
    by_subject: dict[str, list[int]] = defaultdict(list)
    for r in results:
        by_subject[r.subject].append(r.score)
    return {
        subject: {
            "mean": round(statistics.mean(scores), 1),
            "median": statistics.median(scores),
            "pass_rate": round(100 * sum(s >= 30 for s in scores) / len(scores), 1),
        }
        for subject, scores in sorted(by_subject.items())
    }


def student_averages(results: list[Result]) -> dict[str, float]:
    by_student: dict[str, list[int]] = defaultdict(list)
    for r in results:
        by_student[r.student].append(r.score)
    return {name: round(statistics.mean(s), 1) for name, s in by_student.items()}


def rank(averages: dict[str, float]) -> list[tuple[int, str, float]]:
    """Competition ranking: ties share a position, the next one is skipped (1, 2, 2, 4)."""
    ordered = sorted(averages.items(), key=lambda item: (-item[1], item[0]))
    ranked: list[tuple[int, str, float]] = []
    for i, (name, avg) in enumerate(ordered):
        position = ranked[-1][0] if ranked and ranked[-1][2] == avg else i + 1
        ranked.append((position, name, avg))
    return ranked


def grade_distribution(results: list[Result]) -> dict[str, int]:
    counts = Counter(r.grade for r in results)
    return {grade: counts.get(grade, 0) for grade in "ABCDF"}

from analysis import grade_distribution, rank, student_averages, subject_stats
from loading import load_results

DATA = """student,form,subject,score
Amina Hassan,4,Maths,88
Amina Hassan,4,Biology,79
Juma Said,4,Maths,29
Juma Said,4,Biology,48
Neema Kimaro,4,Maths,71
Neema Kimaro,4,Biology,84
Ali Mohamed,4,Maths,95
Ali Mohamed,4,Biology,60
Rehema Mollel,4,Maths,abc
Zawadi Njau,4,Biology,120
"""


def main() -> None:
    results, errors = load_results(DATA)
    print(f"Loaded {len(results)} results, skipped {len(errors)}:")
    for e in errors:
        print("  -", e)

    print("\nSubject   Mean  Median  Pass%")
    for subject, s in subject_stats(results).items():
        print(f"{subject:<9}{s['mean']:>5}{s['median']:>8}{s['pass_rate']:>7}")

    print("\nPos  Student          Average")
    for position, name, avg in rank(student_averages(results)):
        print(f"{position:>3}  {name:<16}{avg:>7}")

    print("\nGrades:", grade_distribution(results))


if __name__ == "__main__":
    main()