Tracing State Changes

Now that state can only change through controlled methods, we can add visibility into every change — turning "why is this value wrong" from a mystery into a readable trace.

1. Learning Objective

2. Pre-Coding Quiz

Answer these before reading the concept explanation or writing any code. It is fine to get these wrong — that is the point. You need 4/5 to proceed to the lab.

3. The Concept — Tracing State Changes

Why a controlled entry point makes tracing trivial

Because Session 21 forced every population change through set_population and grow_population, adding a trace to those two methods gives complete visibility into every change, anywhere in the program, with no missed call sites.

class Country:
    def __init__(self, name, region, population):
        self.name = name
        self.region = region
        self.population = population

    def set_population(self, value):
        if value < 0:
            raise ValueError(f"population must be non-negative, got {value}")
        old = self.population
        self.population = value
        print(f"[trace] {self.name}.population: {old} -> {value}")

A more structured trace with logging

print() works, but Python's built-in logging module gives you severity levels and a consistent format, letting you turn tracing verbosity up or down without touching the code that produces it.

import logging

logging.basicConfig(level=logging.DEBUG, format="%(levelname)s: %(message)s")

class Country:
    def __init__(self, name, region, population):
        self.name = name
        self.region = region
        self.population = population

    def set_population(self, value):
        if value < 0:
            logging.warning(f"rejected population {value} for {self.name}")
            raise ValueError(f"population must be non-negative, got {value}")
        old = self.population
        self.population = value
        logging.debug(f"{self.name}.population: {old} -> {value}")

debug vs warning severity

debug is for fine-grained detail you usually don't want cluttering normal output. warning flags something worth noticing — like a rejected change — without stopping the program the way an unhandled exception would.

logging.basicConfig(level=logging.WARNING)  # debug messages now silenced

# This debug call produces no visible output at WARNING level:
logging.debug("population changed")

# This warning still shows, because it meets the configured threshold:
logging.warning("rejected an invalid population value")

Counting calls as lightweight instrumentation

A simple counter attribute, incremented inside the controlled method, tells you how often a state change has actually occurred — useful for spotting unexpectedly frequent (or absent) updates while debugging.

class Country:
    def __init__(self, name, region, population):
        self.name = name
        self.region = region
        self.population = population
        self._update_count = 0

    def set_population(self, value):
        if value < 0:
            raise ValueError(f"population must be non-negative, got {value}")
        self.population = value
        self._update_count += 1

k = Country(name="Kenya", region="Africa", population=54000000)
k.set_population(55000000)
k.set_population(56000000)
print(k._update_count)  # 2

4. Lab

What you will build

A file called tracing_lab.py.

Step-by-step instructions

# tracing_lab.py
import logging

logging.basicConfig(level=logging.DEBUG, format="%(levelname)s: %(message)s")

class Country:
    def __init__(self, name, region, population):
        self.name = name
        self.region = region
        self.population = population
        self._update_count = 0

    def set_population(self, value):
        if value < 0:
            logging.warning(f"rejected population {value} for {self.name}")
            raise ValueError(f"population must be non-negative, got {value}")
        old = self.population
        self.population = value
        self._update_count += 1
        print(f"[trace] {self.name}.population: {old} -> {value}")
        logging.debug(f"{self.name} update #{self._update_count}")

k = Country(name="Kenya", region="Africa", population=54000000)
k.set_population(55000000)
k.set_population(56000000)
k.set_population(57000000)
print("Total updates:", k._update_count)

try:
    k.set_population(-1)
except ValueError as e:
    print("Caught:", e)
print("Total updates still:", k._update_count)  # unchanged — rejected update did not count

logging.getLogger().setLevel(logging.WARNING)
k.set_population(58000000)  # print trace still visible; debug log line is now silenced

5. Expected Files Changed

6. Commit Checkpoint

Once the lab is complete and you can explain every line, make this exact commit:

git add tracing_lab.py docs/sessions/session-23/index.html
git commit -m "session-23: trace state changes with print, logging, and a call counter"

7. Code Review Checklist

Go through your code line by line and check each item:

8. Post-Coding Quiz

Same 5 questions. Take it again now that you have written and run the code. You need 4/5 to mark this session complete.

9. Reflection Questions

Think through these after the post-quiz. No right answer — they are for discussion.

10. What Breaks If This Knowledge Is Missing?

11. What We Learned