Package and Folder Organization

Layer 6 begins. Our project has grown past what flat files can comfortably hold. We reorganize into a proper Python package structure.

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 — Modules vs Packages

From one growing file to a package

country.py has grown to contain Country, CountryExplorer, CountryRepository, and validate_country_record — several distinct responsibilities crammed into one file. A package lets us split these while keeping them organized under one importable unit.

# Before — everything in one growing file
# country.py
class Country: ...
class CountryExplorer: ...
class CountryRepository: ...
def validate_country_record(data): ...

Creating a package with __init__.py

A directory becomes a package once it contains an __init__.py file. The file can be empty, or it can re-export names to make imports more convenient for users of the package.

# country_explorer/__init__.py
from .models import Country, CountryExplorer
from .repository import CountryRepository
from .validators import validate_country_record

# This lets other code do: from country_explorer import Country
# instead of the more verbose: from country_explorer.models import Country

Splitting by responsibility

Following the conceptual boundaries already established in the project — Session 28's repository/explorer split, Session 24's separate validators — gives a natural, sensible package layout.

# country_explorer/models.py
class Country:
    ...

class CountryExplorer:
    ...

# country_explorer/repository.py
from .models import Country

class CountryRepository:
    ...

# country_explorer/validators.py
def validate_country_record(data):
    ...

Updating imports and re-running the test suite

Every file that imported from country now needs to import from country_explorer (or a specific submodule). Running the full test suite immediately afterward confirms the reorganization did not silently break anything — the payoff of Layer 5's investment.

# tests/test_country.py — before
# from country import Country

# tests/test_country.py — after
from country_explorer import Country

# Then: pytest -v
# If every test still passes, the reorganization was behavior-preserving, as intended

4. Lab

What you will build

A new package directory country_explorer/ replacing the flat country.py.

Step-by-step instructions

# country_explorer/__init__.py
from .models import Country, CountryExplorer
from .repository import CountryRepository
from .validators import validate_country_record

# country_explorer/models.py
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:,}"

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

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

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


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

    def add_country(self, country):
        if not isinstance(country, Country):
            raise TypeError(f"expected a Country instance, got {type(country).__name__}")
        self.countries.append(country)

    @property
    def country_count(self):
        return len(self.countries)

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

# country_explorer/repository.py
from .models import Country

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]

# country_explorer/validators.py
def validate_country_record(data):
    required = {"name": str, "region": str, "population": int}
    for key, expected_type in required.items():
        if key not in data:
            raise ValueError(f"missing required field: {key}")
        if not isinstance(data[key], expected_type):
            raise TypeError(f"{key} must be {expected_type.__name__}, got {type(data[key]).__name__}")
    return data

# tests/test_country.py, test_return_values.py, test_state_changes.py, test_repository.py
# change: from country import Country, CountryExplorer, CountryRepository, validate_country_record
# to:     from country_explorer import Country, CountryExplorer, CountryRepository, validate_country_record

# 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/ tests/ docs/sessions/session-36/index.html
git rm country.py
git commit -m "session-36: reorganize into a country_explorer package with focused submodules"

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