Building a Data Access Layer

Application logic should not know or care where its data comes from. We build a CountryRepository that hides that detail behind a clean, swappable interface.

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 — A Data Access Layer

Wrapping a data source behind an interface

A repository is a small class whose only job is providing access to data — hiding exactly where and how that data is stored behind a clean set of methods.

from mock_countries import MOCK_COUNTRIES

class CountryRepository:
    def __init__(self, raw_data):
        self._raw_data = raw_data

    def get_all(self):
        return [Country.from_dict(r) for r in self._raw_data]

    def find_by_region(self, region):
        return [Country.from_dict(r) for r in self._raw_data if r["region"] == region]

repo = CountryRepository(raw_data=MOCK_COUNTRIES)
all_countries = repo.get_all()
print(len(all_countries))

Swapping the source without touching callers

As long as get_all() keeps returning the same shape (a list of Country instances), the repository's internals can change completely, and nothing that calls repo.get_all() needs to know or care.

class CountryRepository:
    def __init__(self, raw_data):
        self._raw_data = raw_data

    def get_all(self):
        return [Country.from_dict(r) for r in self._raw_data]

# Today: built around mock data
repo = CountryRepository(raw_data=MOCK_COUNTRIES)

# Later (Session 29/42): built around a completely different source —
# but repo.get_all() everywhere else in the app doesn't change at all
# repo = CountryRepository(raw_data=load_from_json_file("countries.json"))
# repo = CountryRepository(raw_data=fetch_from_real_api())

Repository vs Explorer — two different responsibilities

CountryRepository fetches raw data and hands back Country instances. CountryExplorer (Session 16) takes an already-fetched working set and offers operations over it. Keeping these responsibilities separate mirrors Session 16's "small, focused classes" principle.

repo = CountryRepository(raw_data=MOCK_COUNTRIES)
explorer = CountryExplorer(countries=repo.get_all())  # repository FETCHES, explorer OPERATES

print(explorer.total_population)         # explorer's job
print(repo.find_by_region("Africa"))     # repository's job — a different kind of query

4. Lab

What you will build

A file called repository_lab.py.

Step-by-step instructions

# repository_lab.py
from mock_countries import MOCK_COUNTRIES

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

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

    @classmethod
    def from_dict(cls, data):
        return cls(**data)

class CountryRepository:
    def __init__(self, raw_data):
        self._raw_data = raw_data

    def get_all(self):
        return [Country.from_dict(r) for r in self._raw_data]

    def find_by_region(self, region):
        return [Country.from_dict(r) for r in self._raw_data if r["region"] == region]

repo = CountryRepository(raw_data=MOCK_COUNTRIES)
print(len(repo.get_all()))
print([c.name for c in repo.find_by_region("Africa")])

class CountryExplorer:
    def __init__(self, countries):
        self.countries = countries

    @property
    def total_population(self):
        return sum(c.population for c in self.countries)

explorer = CountryExplorer(countries=repo.get_all())
print(explorer.total_population)

tiny_data = [{"name": "Fiji", "region": "Oceania", "population": 900000}]
tiny_repo = CountryRepository(raw_data=tiny_data)
tiny_explorer = CountryExplorer(countries=tiny_repo.get_all())
print(tiny_explorer.total_population)  # 900000 — same CountryExplorer class, different source

5. Expected Files Changed

6. Commit Checkpoint

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

git add repository_lab.py docs/sessions/session-28/index.html
git commit -m "session-28: build a CountryRepository data-access layer around the mock data"

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