Reusable Functions and Modules

With a clean package structure in place, we identify genuinely reusable logic scattered across the project and extract it into shared, well-tested functions.

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 — Extracting Reusable Logic

Spotting duplicated logic

As a project grows, similar formatting or calculation logic tends to appear in more than one place. The first step is noticing it — comparing what several pieces of code are actually doing, not just how they look on the surface.

# Duplication scattered across the project:

# models.py
def summary(self):
    return f"{self.name} ({self.region}): pop. {self.population:,}"

# some future report-generation code, formatting the same kind of number again
def population_report_line(name, population):
    return f"{name}: {population:,} people"

Extracting one shared function

Once genuine, ongoing duplication is identified, extract it into one well-named function, and update every call site to use it — exactly the "one place to change" principle from Session 10.

# country_explorer/formatting.py
def format_population(value):
    """Format a population count with comma separators.

    Args:
        value: the population as an int.
    Returns:
        A string like "54,000,000".
    """
    return f"{value:,}"

# models.py
from .formatting import format_population

def summary(self):
    return f"{self.name} ({self.region}): pop. {format_population(self.population)}"

Documenting the extracted function with a docstring

A function meant to be reused across the project deserves clear documentation of what it takes and what it returns, directly alongside the code — readable via help() and by anyone reading the source.

Testing the extracted function directly

A focused test of the standalone function is simpler than relying on it being indirectly exercised through summary() or other larger tests.

# tests/test_formatting.py
from country_explorer.formatting import format_population

def test_format_population_adds_commas():
    assert format_population(54000000) == "54,000,000"

def test_format_population_small_number():
    assert format_population(5) == "5"

When NOT to extract — premature abstraction

If two pieces of code happen to look similar right now, but represent genuinely different concepts likely to change independently, forcing them into a shared function adds coupling without a real benefit. Extraction should follow real, ongoing duplication of one actual idea — not surface-level resemblance.

4. Lab

What you will build

A new module country_explorer/formatting.py plus tests/test_formatting.py.

Step-by-step instructions

# country_explorer/formatting.py
def format_population(value):
    """Format a population count with comma separators.

    Args:
        value: the population as an int.
    Returns:
        A string like "54,000,000".
    """
    return f"{value:,}"

# country_explorer/models.py
from .formatting import format_population

class Country:
    # ... existing code ...
    def summary(self):
        return f"{self.name} ({self.region}): pop. {format_population(self.population)}"

# tests/test_formatting.py
from country_explorer.formatting import format_population

def test_format_population_adds_commas():
    assert format_population(54000000) == "54,000,000"

def test_format_population_small_number():
    assert format_population(0) == "0"

# pytest -v

5. Expected Files Changed

6. Commit Checkpoint

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

git add country_explorer/formatting.py country_explorer/models.py tests/test_formatting.py docs/sessions/session-37/index.html
git commit -m "session-37: extract and test a reusable format_population function"

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