Refactoring the Study Log with Classes

This is the project checkpoint for this part. It assumes that you have already walked through the migrations where you turned sessions into dictionaries and moved storage to JSON. This one introduces classes to the project: a Session for individual records and a StudyLog for the collection, with the summaries becoming methods on StudyLog.

You have already seen these classes in the previous chapters. The focus here is on putting the pieces together into a real program, and making design decisions about where classes belong and where they do not.

The Plan

The plan is to create two classes. The classes are:

A Session class for one record. A session has a fixed, known shape — always a subject, minutes, and a date. It also has natural behaviour: displaying itself, and judging whether it was long.

A StudyLog class for the collection. A study log holds a list of sessions, and it can answer questions about them — how many minutes in total, what are the per-subject summaries, which day was heaviest, what is the current streak.

What stays a plain shape: the results of the summaries. The per-subject summaries are a dictionary of small dictionaries; the heaviest day is a small record; the recent-days breakdown is a list. These are intermediate results computed on demand, throwaway code that should not be a class.

The Session Class

Pull together the Session from the classes chapters — fields, behaviour, and serialization:

class Session:
    def __init__(self, subject, minutes, date):
        self.subject = subject
        self.minutes = minutes
        self.date = date

    def is_long(self):
        return self.minutes >= 60

    def __str__(self):
        return f"{self.subject.title()}: {self.minutes} minutes on {self.date}"

    def to_dict(self):
        return {
            "subject": self.subject,
            "minutes": self.minutes,
            "date": self.date,
        }


def session_from_dict(data):
    return Session(data["subject"], data["minutes"], data["date"])

This is the whole record type: named fields from __init__, behaviour in is_long and __str__, the to_dict half of serialization, and the session_from_dict function for the rebuild direction.

Two Kinds of Summary Code

Before writing StudyLog, there is a need for a design decision. There are multiple types of summaries, and they do not all belong in the same place.

Some are questions you ask the log: how many minutes in total, what are the per-subject summaries, which day was heaviest, what is the current streak. These are behaviour about the whole collection, and they become methods on StudyLog.

Others are generic operations on any list of sessions: collecting the distinct days, totalling minutes per day, filtering to a date window. These do not need to be about a particular log — they would work on any list of sessions you handed them. They stay as free-standing helper functions, which the methods in StudyLog can use.

Forcing both questions and helpers onto StudyLog would bloat the class with general-purpose tools that are not really about one log. So: the helpers are functions; the questions about the log are methods.

The Helper Functions

These three are the helper functions, with field access changed from row positions to Session attributes. distinct_days reduces a list of sessions to the sorted, de-duplicated dates it covers:

from datetime import date, timedelta

def distinct_days(sessions):
    """Return the distinct session dates as date objects, sorted ascending."""
    day_strings = []
    for session in sessions:
        if session.date not in day_strings:
            day_strings.append(session.date)

    days = []
    for day_string in day_strings:
        days.append(date.fromisoformat(day_string))

    days.sort()
    return days

totals_by_day groups minutes by date, returning [date_string, total] rows in date order:

def totals_by_day(sessions):
    """Return [date_string, total_minutes] rows, sorted by date ascending."""
    days_seen = []
    for session in sessions:
        if session.date not in days_seen:
            days_seen.append(session.date)
    days_seen.sort()

    result = []
    for day in days_seen:
        total = 0
        for session in sessions:
            if session.date == day:
                total += session.minutes
        result.append([day, total])
    return result

sessions_between keeps the sessions whose dates fall in an inclusive window. In the previous part it rebuilt rows; now it simply keeps the Session objects that qualify:

def sessions_between(sessions, start, end):
    """Return the sessions whose dates fall between start and end (both inclusive)."""
    result = []
    for session in sessions:
        day = date.fromisoformat(session.date)
        if start <= day <= end:
            result.append(session)
    return result

Each reads session.date and session.minutes, where the earlier version unpacked positions or indexed a dictionary.

The StudyLog Class

The StudyLog class holds the sessions and answers questions about them. Its __init__ takes the list of sessions; the summary methods read self.sessions and, where useful, delegate to the helpers above.

class StudyLog:
    def __init__(self, sessions):
        self.sessions = sessions

    def total_minutes(self):
        total = 0
        for session in self.sessions:
            total += session.minutes
        return total

    def summaries_by_subject(self):
        counts = {}
        totals = {}
        for session in self.sessions:
            subject = session.subject
            counts[subject] = counts.get(subject, 0) + 1
            totals[subject] = totals.get(subject, 0) + session.minutes

        result = {}
        for subject in counts:
            result[subject] = {
                "count": counts[subject],
                "total": totals[subject],
                "average": totals[subject] / counts[subject],
            }
        return result

    def heaviest_day(self):
        totals = totals_by_day(self.sessions)
        if len(totals) == 0:
            return None
        best = totals[0]
        for row in totals[1:]:
            if row[1] > best[1]:
                best = row
        return best

    def recent_daily_totals(self, today=None):
        if today is None:
            today = date.today()
        start = today - timedelta(days=6)
        recent = sessions_between(self.sessions, start, today)
        return totals_by_day(recent)

    def current_streak(self, today=None):
        if today is None:
            today = date.today()
        days = distinct_days(self.sessions)
        if len(days) == 0:
            return 0
        if days[-1] > today:
            raise ValueError(
                f"Session date {days[-1]} is in the future relative to today {today}."
            )
        latest = days[-1]
        gap = (today - latest).days
        if gap > 1:
            return 0
        streak = 1
        for index in range(len(days) - 2, -1, -1):
            if (days[index + 1] - days[index]).days == 1:
                streak += 1
            else:
                break
        return streak

    def longest_streak(self):
        days = distinct_days(self.sessions)
        if len(days) == 0:
            return 0
        current = 1
        longest = 1
        for index in range(1, len(days)):
            if (days[index] - days[index - 1]).days == 1:
                current += 1
            else:
                current = 1
            if current > longest:
                longest = current
        return longest

The shape of each method is similar to the summary functions from the previous part with two changes. The sessions parameter is gone — a method reads self.sessions, because the log holds its own sessions. And field access is attribute access on a Session: session.minutes and session.subject, not session["minutes"] or row[1].

The algorithms are the ones you wrote in the previous part and ported again in the early chapters of this part; nothing about them is new.

A few things worth pointing out:

• The method summaries_by_subject returns a plain dictionary whose values are themselves plain dictionaries — {"math": {"count": 3, "total": 130, "average": 43.33}, ...}. Not a Summary class. The result is an intermediate value the dashboard will iterate over once and discard, so plain dictionaries are the right shape and a class would be unnecessary overhead.

• The methods heaviest_day and recent_daily_totals delegate to the helper functions rather than re-implementing them. The method heaviest_day calls totals_by_day(self.sessions) and then runs the “best so far” loop over the result. The method recent_daily_totals filters with sessions_between and totals the result with totals_by_day.

• The method current_streak keeps its today=None parameter, because that parameter was about testability, not about the collection — a test needs to pin down what “today” is, and the default of None falls back to the real date in normal use.

Because every method’s behaviour is unchanged, the tests still apply, once their fixtures build Session objects and wrap them in a StudyLog.

Saving and Loading

Loading a study log consists of reading JSON into dictionaries, then building a Session from each dictionary, and finally putting the list of sessions into a new StudyLog.

import json

def load_study_log(path):
    """Load a StudyLog from a JSON file. An empty log if the file is missing."""
    try:
        f = open(path, encoding="utf-8")
    except FileNotFoundError:
        return StudyLog([])
    with f:
        data = json.load(f)

    sessions = []
    for item in data:
        sessions.append(session_from_dict(item))
    return StudyLog(sessions)

Saving goes the other way: convert each Session to a dictionary, write the list as JSON:

    def save(self, path):
        data = []
        for session in self.sessions:
            data.append(session.to_dict())
        with open(path, "w", encoding="utf-8") as f:
            json.dump(data, f, indent=2)

The boundary is exactly where the serialization chapter put it — the file is JSON, the program is objects, and the conversion happens only in load_study_log and StudyLog.save.

Adding a session to a study log would be a small method too, which keeps the “create, then save” flow in one place:

    def add(self, session):
        self.sessions.append(session)

The Dashboard

The dashboard from the previous part was a free-standing print_summary(sessions, today=None). With a StudyLog, it becomes a method that reads the log’s own data and calls the log’s own summary methods:

    def print_dashboard(self, today=None):
        if today is None:
            today = date.today()

        if len(self.sessions) == 0:
            print("No sessions logged yet -- ready to start.")
            return

        total = self.total_minutes()
        hours, mins = divmod(total, 60)
        print(f"So far: {len(self.sessions)} sessions, {hours} hours {mins} minutes")
        print()

        print("By subject:")
        summaries = self.summaries_by_subject()
        for subject in sorted(summaries):
            info = summaries[subject]
            count = info["count"]
            word = "session" if count == 1 else "sessions"
            print(f"  {subject.title()}: {count} {word}, {info['total']} minutes, "
                  f"average {info['average']:.1f} minutes")
        print()

        recent = self.recent_daily_totals(today)
        if len(recent) > 0:
            print("Recent days:")
            for day, day_total in recent:
                print(f"  {day}: {day_total} minutes")
            print()

        heavy = self.heaviest_day()
        if heavy is not None:
            print(f"Heaviest day: {heavy[0]} ({heavy[1]} minutes)")

        print(f"Current streak: {self.current_streak(today)} days")
        print(f"Longest streak: {self.longest_streak()} days")

Every summary is now self.total_minutes(), self.summaries_by_subject(), and so on — a question asked of the log, rather than a free-standing call with sessions passed in. The dashboard reads as a description of what a study log shows about itself, which is what it is.

Two details carry forward from the previous part. The sorted(summaries) loop sorts the subjects before printing — a dictionary does not promise a useful order, so when display order matters you sort explicitly. And the "session" if count == 1 else "sessions" picks the right word so a single session does not read as “1 sessions”. For the usual five-session fixture, with today set to 2026-05-12, the method prints exactly the dashboard from the start of the part:

So far: 5 sessions, 4 hours 10 minutes

By subject:
  History: 1 session, 30 minutes, average 30.0 minutes
  Math: 3 sessions, 130 minutes, average 43.3 minutes
  Physics: 1 session, 90 minutes, average 90.0 minutes

Recent days:
  2026-05-10: 135 minutes
  2026-05-11: 90 minutes
  2026-05-12: 25 minutes

Heaviest day: 2026-05-10 (135 minutes)
Current streak: 3 days
Longest streak: 3 days

The Main Script

The top-level script gets noticeably simpler, because the StudyLog now carries the pieces that used to be loose:

from datetime import date

SESSIONS_FILE = "sessions.json"

print("=== Study Log ===")
print()

log = load_study_log(SESSIONS_FILE)
log.print_dashboard()
print()

while True:
    subject, minutes = get_session()
    if subject is None:
        break

    today_str = date.today().isoformat()
    log.add(Session(subject, minutes, today_str))
    log.save(SESSIONS_FILE)

    # ... per-session feedback as before ...

The function load_study_log returns a StudyLog; the dashboard is a method on it; adding a session creates a Session and hands it to log.add; saving is log.save. The script reads as a sequence of operations on a study log object, rather than a set of functions threaded together by a sessions list passed from one to the next.

[
  {"subject": "math", "minutes": 45, "date": "2026-05-10"},
  {"subject": "history", "minutes": 30, "date": "2026-05-11"}
]

StudyLog([
    Session("math", 45, "2026-05-10"),
    Session("history", 30, "2026-05-10"),
    Session("math", 60, "2026-05-11"),
    Session("physics", 90, "2026-05-12"),
])

So far: 4 sessions, 3 hours 45 minutes

By subject:
  History: 1 session, 30 minutes, average 30.0 minutes
  Math: 2 sessions, 105 minutes, average 52.5 minutes
  Physics: 1 session, 90 minutes, average 90.0 minutes

Recent days:
  2026-05-10: 75 minutes
  2026-05-11: 60 minutes
  2026-05-12: 90 minutes

Heaviest day: 2026-05-12 (90 minutes)
Current streak: 3 days
Longest streak: 3 days

No sessions logged yet -- ready to start.

  Short session on math -- every bit counts.
  Solid session on math.
  Long session on math -- remember to take breaks!

Using AI on This Migration

The migration is a natural place to think about combining the comparing-approaches skill with the data-design skill from the previous chapter. A workflow:

1. Decide the shapes first. Before writing methods, settle which things are classes (Session, StudyLog) and which stay plain (the summary results). This is the data-design judgment, and making it deliberately is the point — not defaulting to “everything is a class” because the part is about classes.
2. Move one method, then ask for a critique. Move summaries_by_subject onto StudyLog, then ask an assistant whether the per-subject result should stay plain dictionaries or become a class. Weigh the answer against how the dashboard actually uses it.
3. Verify against the tests. Each moved method from part 5 has a test. Adapt the fixture to objects and run it. A disagreement is a bug in the move.
4. Check the boundary explicitly. Save a log, load it back, and confirm the result is equal to what you saved. Serialization bugs hide here, and a round-trip test flushes them out.

The assistant is useful for the mechanical move and for proposing alternatives; the shape decisions and the verification are yours.

In the study log project, however, there are specific expectations for the shapes of the data and the behaviour. The assistant can suggest alternatives, but you need to check them against the assignment requirements.

What You Have Built

The study log is now an object with a clear structure: a StudyLog that holds Session objects, answers questions about them through methods, and persists itself to JSON through a thin serialization layer at the file boundary. The data is named all the way down — session.minutes, not row[1] — and the behaviour lives with the data it concerns.

Check Your Understanding

1. Why are Session and StudyLog classes, while the result of summaries_by_subject is left as plain dictionaries?
2. Why do the summary methods on StudyLog read self.sessions instead of taking a sessions parameter the way the Part 5 functions did?
3. Where in the program does conversion between objects and JSON happen, and where in the program does it deliberately not happen?
4. Why does current_streak keep its today=None parameter even after it becomes a method?
5. The migration is done one piece at a time, running the tests after each step. Why is that the safe way, and what does a newly failing test tell you?