Python — modules, packages and virtual environments

A module is a .py file. A package is a directory of modules. As soon as a program is more than a couple of hundred lines it should be split up.

project/
├── src/myapp/
│   ├── __init__.py
│   ├── data.py          # reading and cleaning
│   ├── model.py         # training and prediction
│   └── cli.py           # the command-line interface
├── tests/
├── requirements.txt
└── README.md

from myapp.data import read_csv — the import mirrors the directory structure.

The rule: a module should have one clear responsibility and be importable without side effects. Code that is meant to run goes under if __name__ == "__main__":.

# A virtual environment: an isolated Python per project
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install numpy pandas scikit-learn
pip freeze > requirements.txt      # pins the exact versions
deactivate

# On another machine (or in CI):
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Why a venv? Project A needs numpy 1.26, project B needs 2.1. Without isolation one of them breaks. With a venv each project has its own package tree.

A requirements.txt with exact versions (numpy==2.1.3) is the difference between «it worked last summer» and «it works». Always put .venv/ in .gitignore — the environment is recreated from the file, it does not belong in git.