Building Utility Modules

Beyond small extracted functions, some logic is genuinely cross-cutting — useful to many different parts of the application without belonging to any single class.

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 — Utility Modules

Logic that belongs to no single class

Some logic is genuinely cross-cutting — useful in more than one place, but not naturally "owned" by any one class's data. This is exactly what a utility module is for.

# country_explorer/search.py
def matches_search_term(name, term):
    """Check whether a search term appears in a name, case-insensitively.

    Args:
        name: the string to search within.
        term: the search term.
    Returns:
        True if term appears anywhere in name, ignoring case.
    """
    return term.lower() in name.lower()

Method vs standalone utility function

A method (Session 14) is bound to a specific instance's data via self. A utility function takes everything it needs as plain, explicit arguments, with no ties to any one class — this makes it broadly reusable.

# Method — bound to a specific Country instance
class Country:
    def name_matches(self, term):
        return term.lower() in self.name.lower()

# Utility function — takes explicit arguments, usable anywhere a string is available
def matches_search_term(name, term):
    return term.lower() in name.lower()

# The utility version works even without a Country instance at all:
print(matches_search_term("Kenya", "ken"))   # True — no Country object needed

Using the utility from multiple places

Both CountryExplorer and CountryRepository can use the same search utility without either one owning it or duplicating the logic.

# models.py
from .search import matches_search_term

class CountryExplorer:
    def search(self, term):
        return [c for c in self.countries if matches_search_term(c.name, term)]

# repository.py
from .search import matches_search_term

class CountryRepository:
    def search(self, term):
        return [c for c in self.get_all() if matches_search_term(c.name, term)]

Thorough testing for widely-used utilities

Because this function will be relied upon from multiple places, it deserves especially thorough test coverage — a bug here has a wide blast radius.

# tests/test_search.py
from country_explorer.search import matches_search_term

def test_matches_exact():
    assert matches_search_term("Kenya", "Kenya") is True

def test_matches_partial():
    assert matches_search_term("Kenya", "ken") is True

def test_matches_case_insensitive():
    assert matches_search_term("KENYA", "kenya") is True

def test_no_match():
    assert matches_search_term("Kenya", "xyz") is False

def test_empty_term_matches_everything():
    assert matches_search_term("Kenya", "") is True  # an empty string is "in" every string

4. Lab

What you will build

A new module country_explorer/search.py plus tests/test_search.py.

Step-by-step instructions

# country_explorer/search.py
def matches_search_term(name, term):
    """Check whether a search term appears in a name, case-insensitively.

    Args:
        name: the string to search within.
        term: the search term.
    Returns:
        True if term appears anywhere in name, ignoring case.
    """
    return term.lower() in name.lower()

# country_explorer/models.py
from .search import matches_search_term

class CountryExplorer:
    # ... existing code ...
    def search(self, term):
        return [c for c in self.countries if matches_search_term(c.name, term)]

# country_explorer/repository.py
from .search import matches_search_term

class CountryRepository:
    # ... existing code ...
    def search(self, term):
        return [c for c in self.get_all() if matches_search_term(c.name, term)]

# tests/test_search.py
from country_explorer.search import matches_search_term

def test_matches_exact():
    assert matches_search_term("Kenya", "Kenya") is True

def test_matches_partial():
    assert matches_search_term("Kenya", "ken") is True

def test_matches_case_insensitive():
    assert matches_search_term("KENYA", "kenya") is True

def test_no_match():
    assert matches_search_term("Kenya", "xyz") is False

# tests/test_search_integration.py
from country_explorer import Country, CountryExplorer, CountryRepository

def test_explorer_search_uses_matches_search_term():
    explorer = CountryExplorer(countries=[Country(name="Kenya", region="Africa", population=1)])
    assert [c.name for c in explorer.search("ken")] == ["Kenya"]

def test_repository_search_uses_matches_search_term():
    repo = CountryRepository(raw_data=[{"name": "Kenya", "region": "Africa", "population": 1}])
    assert [c.name for c in repo.search("ken")] == ["Kenya"]

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/search.py country_explorer/models.py country_explorer/repository.py tests/test_search.py tests/test_search_integration.py docs/sessions/session-38/index.html
git commit -m "session-38: build a shared search utility used by both CountryExplorer and CountryRepository"

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