MiniGrades

A lightweight CLI tool for managing student records and grades, built with Python.

Changelog

v4.0 (from v3.0)

• Lesson-based grading — grades are now associated with specific lessons (e.g., Math, Science); each lesson stores its own grade list
• Updated data format — student lines now use id | name | Lesson1: g1,g2 | Lesson2: g3 format with per-lesson segments
• add-grade updated — now requires a lesson name: add-grade <id> <lesson> <grade>; appends to existing lesson or creates a new segment
• delete-grade updated — now requires a lesson name: delete-grade <id> <lesson> <grade>; removes the lesson segment if no grades remain
• change-grade updated — now requires a lesson name: change-grade <id> <lesson> <old> <new>
• list updated — displays per-lesson grades and averages for each student
• student-info updated — shows per-lesson breakdown with grades and averages
• report updated — markdown report table now includes a LESSON column with per-lesson rows
• Lesson validation — lesson names must contain only alphabetic characters
• Test suite expanded — from 42 to 49 tests covering lesson-based operations and edge cases
• clear-data command — bulk deletion of all student records with Y/N confirmation prompt
• clear-log command — ability to clear the activity log
• Activity logging — all operations are automatically recorded to log.txt with timestamps and status (SUCCESS, ERROR, INFO)
• help system — built-in command reference with per-command detailed usage (help <command>)
• Colored output — integrated colorama for color-coded terminal messages (green/red/cyan/yellow/magenta)
• Descriptive error messages — all errors now use an operation-prefixed format (e.g., Adding student failed: ...)
• DRY refactoring — codebase-wide restructuring with shared helpers, constants, and dispatch tables across utils.py, main.py, and test.py

Quick Start

# Initialize the system
python main.py init

# Add a student
python main.py add-student 101 Berke

# Add grades under specific lessons
python main.py add-grade 101 Math 85
python main.py add-grade 101 Math 90
python main.py add-grade 101 Science 75

# View records
python main.py list
python main.py student-info 101

# Generate a markdown report
python main.py report

Run python main.py help to see all available commands.

Commands

Command	Usage	Description
init	python main.py init	Initializes the system and creates storage
add-student	python main.py add-student <id> <name>	Registers a new student
add-grade	python main.py add-grade <id> <lesson> <grade>	Adds a grade (0–100) under a lesson
delete-student	python main.py delete-student <id>	Removes a student and all associated data
delete-grade	python main.py delete-grade <id> <lesson> <grade>	Removes a specific grade from a lesson
change-grade	python main.py change-grade <id> <lesson> <old> <new>	Replaces an existing grade in a lesson
list	python main.py list	Lists all students with per-lesson grades and averages
student-info	python main.py student-info <id>	Displays detailed per-lesson info for a student
report	python main.py report	Generates a formatted Markdown report with lesson columns
clear-data	python main.py clear-data	Deletes all student records (requires confirmation)
clear-log	python main.py clear-log	Clears the activity log
help	python main.py help [command]	Displays usage instructions

Project Structure

minigrades/
├── main.py             # CLI entry point
├── utils.py            # Core functions and helpers
├── test.py             # Pytest test suite (49 tests)
├── SPEC.txt            # Formal specification
├── README.md
└── .minigrades/        # Runtime storage (generated by init)
    ├── data.txt        # Student records
    ├── report.md       # Generated report
    └── log.txt         # Activity log

Testing

python -m pytest test.py -v

All operations are covered with 49 tests, including edge cases for input validation, lesson validation, duplicate detection, and error handling.

Dependencies

• Python 3.13+
• colorama — colored terminal output

pip install colorama

How It Works

Student data is stored in .minigrades/data.txt as pipe-delimited records (ID | Name | Lesson1: g1,g2 | Lesson2: g3). Each lesson has its own segment with a colon-separated grade list. Every operation is logged to log.txt with a timestamp and status. The report command generates a Markdown table at .minigrades/report.md with per-lesson rows.

All averages are displayed with 2 decimal precision. Grades are maintained in insertion order.