Modules, Packages, and an Isolated Environment

By the end of this lesson you can split a project across several importable files and say exactly what an import runs, and you can create an environment that pins the project's dependencies so it behaves the same on any machine.

The review assistant is now more code than fits comfortably in one file, and it is about to acquire dependencies. Both bring the same class of problem: something that works here and not there.

An import that runs code as a side effect turns "I imported a helper" into "I made a network call". A dependency installed globally means the project works on your machine, breaks on a colleague's, and breaks on yours the day another project needs a different version of the same library. Neither is difficult to prevent and both are unpleasant to diagnose afterwards.

A module is one .py file. A package is a directory of modules. import matching runs matching.py top to bottom, once per process, and binds the module object to the name.

That word "runs" is the important one. Anything at the top level of a module executes on import: a print, a file read, a database connection, a network call. Only definitions, def and class, and cheap constants belong at the top level. Work belongs inside a function that something calls deliberately.

The guard for a file that is both importable and runnable:

def main():
    ...


if __name__ == "__main__":
    main()

__name__ is "__main__" when the file was run directly and the module's own name when it was imported. Without the guard, importing a script to reuse one function also runs the whole script.

Prefer absolute imports from the project root, from opportunity.matching import qualifies, over relative ones. They read the same wherever they appear and do not change meaning when a file moves.

A virtual environment is a directory with its own Python executable (copied or linked, depending on the platform), configuration, and package directory. Create it with python -m venv .venv, activate it, and commands such as python -m pip install ... then target that environment rather than the system Python.

python -m venv .venv
source .venv/bin/activate          # macOS and Linux
.venv\Scripts\activate             # Windows
pip install requests
pip freeze > requirements.txt

Two habits improve repeatability. Verify activation before installing anything, because installing into the system interpreter succeeds and looks identical until the project moves. And pin versions: requirements.txt produced by pip freeze records exact installed versions. Pins do not by themselves guarantee identical builds across operating systems or package-index changes; stronger reproducibility can also require environment markers, hashes, and testing the rebuild on each supported platform.

Add .venv/ to .gitignore before the first commit. It is large, entirely reconstructible from requirements.txt, and specific to one machine and operating system. Getting it out of a repository afterwards is far more work than keeping it out.

This lesson's task runs on your own machine. Pyodide has a temporary virtual filesystem and can install some compatible packages with micropip, but it has no conventional operating-system shell, cannot create a normal platform virtual environment, and cannot directly manage the host machine's project files. Simulating venv and pip here would therefore teach the wrong workflow.

Two files. First matching.py:

"""Matching rules for opportunity records."""

MINIMUM_VALUE = 100000

print("matching module loaded")


def qualifies(record, minimum=MINIMUM_VALUE):
    return record.get("amount", 0) >= minimum

Then report.py:

from matching import qualifies

BATCH = [{"notice_id": "A-1", "amount": 300000}, {"notice_id": "A-2", "amount": 40000}]


def main():
    selected = [record for record in BATCH if qualifies(record)]
    print(f"{len(selected)} of {len(BATCH)} qualify")


if __name__ == "__main__":
    main()

matching.py has one line of real work at the top level, the print, and it is there to be noticed. It runs when the module is imported, not when qualifies is called, which is why a top-level side effect is a design decision rather than an implementation detail.

report.py defines main and calls it only under the guard, so importing report from a test gets the function without running the report.

Predict what python report.py prints, and in what order.

matching module loaded
1 of 2 qualify

Remove the if __name__ == "__main__": guard from report.py and call main() directly at the top level. Predict what a test file containing from report import main now prints when it is collected.

A colleague reports that the project works for them and fails for you with ModuleNotFoundError: No module named 'requests'. They send this setup transcript.

python -m venv .venv
pip install requests
pip freeze > requirements.txt
python report.py

python -m venv .venv
source .venv/bin/activate
python -c "import sys; print(sys.prefix)"
pip install requests
pip freeze > requirements.txt

This task runs on your own machine, because a conventional virtual environment needs the host Python installation, project filesystem, and shell that this browser runner deliberately does not expose.

1. In a new empty directory, run python -m venv .venv.
2. Activate it: source .venv/bin/activate on macOS or Linux, .venv\Scripts\activate on Windows.
3. Verify it: python -c "import sys; print(sys.prefix)" must print a path inside .venv.
4. Install one package you are curious about with python -m pip install <name>.
5. Run python -m pip freeze > requirements.txt and read the file.
6. Create a .gitignore containing .venv/, run git init and git status, and confirm .venv is not listed.

Record your attempt below once you have completed step 6, or if you got stuck; both are useful.

Sign in to track your progress on this exercise.

Optional: delete .venv entirely, recreate it, activate it, and run python -m pip install -r requirements.txt. Confirm the project runs again. This is the rebuild a colleague, a build server, or you-in-six-months will perform, and it is the only way to find out whether requirements.txt is actually complete. A file that has never been used to rebuild an environment is a file nobody has tested.

Sign in to track your progress on this exercise.

1. What actually happens when Python executes import matching?
2. What does the if __name__ == "__main__": guard prevent?
3. Why verify sys.prefix before installing anything?
4. Why does .venv/ belong in .gitignore?

Sign in to track your progress on this exercise.

Importing runs a module, so keep work out of the top level and behind the __main__ guard; create an environment, verify it before installing, pin what you install, and keep it out of version control. Next: giving the script arguments, configuration, and logs that say what happened without saying what your credentials are.