Python Modules, Packages, pip and Virtual Environments

A 50-line script fits in one file. A real project doesn't. In this lesson you'll organize code the way professional teams do and learn to manage external libraries, which are Python's real superpower: there are hundreds of thousands of them, for almost any task you can imagine. These are also the skills that separate "I wrote a script once" from "I can work on a team's codebase."

Modules: your code in several files

A module is simply a .py file. Anything you define in it can be imported from another file in the same folder.

# file: finance.py
SALES_TAX = 0.0825

def price_with_tax(price):
    return round(price * (1 + SALES_TAX), 2)

def loan_payment(amount, apr, months):
    r = apr / 12
    return round(amount * r / (1 - (1 + r) ** -months), 2)

# file: main.py
import finance
from finance import loan_payment

print(finance.price_with_tax(100))       # 108.25
print(loan_payment(25_000, 0.069, 60))   # 493.85

There are three ways to import:

Avoid from module import *: it pulls in everything without telling you what, and it can overwrite your own names.

What if __name__ == "__main__" really means

When you import a module, Python runs all of its code. If finance.py had a stray test print, it would show up every time you imported it. That's why "run this" code is guarded like this (you saw it in lesson 7):

if __name__ == "__main__":
    print(loan_payment(5_000, 0.2, 12))   # only runs when this file is launched directly

Packages: folders of modules

When you have many modules, group them in folders. A folder with an __init__.py file (it can be empty) is a package:

expense_tracker/
├── main.py
├── requirements.txt
├── expenses/
│   ├── __init__.py
│   ├── models.py        ← classes (lesson 9)
│   ├── storage.py       ← read and save the CSV
│   └── reports.py       ← summaries
└── tests/
    └── test_reports.py

# in main.py
from expenses.models import Expense
from expenses import reports

pip: installing libraries

pip is Python's package installer. It downloads libraries from the official Python Package Index, PyPI:

pip install requests          # install
pip install pandas==3.0.0     # a specific version (example)
pip install --upgrade pandas  # upgrade
pip list                      # see what's installed
pip uninstall requests        # uninstall

If pip isn't recognized as a command, use python -m pip install … (or python3 -m pip on macOS and Linux). This form guarantees you install for the same Python you run.

Virtual environments: one Python per project

If you install everything "globally," sooner or later two projects will need different versions of the same library and one of them will break. A virtual environment is a folder with its own Python and its own libraries, isolated from everything else.

# 1. Create the environment (once per project, inside its folder)
python -m venv .venv

# 2. Activate it (every time you open a new terminal)
.venv\Scripts\activate          # Windows
source .venv/bin/activate       # macOS and Linux

# 3. Install what you need: it stays inside .venv
pip install pandas requests

# 4. Leave the environment
deactivate

While the environment is active, the terminal shows (.venv) at the start of the line. VS Code detects the .venv folder and offers to use it automatically.

requirements.txt: make your project run on another computer

pip freeze > requirements.txt       # save the exact list of installed libraries
pip install -r requirements.txt     # on another computer, install everything at once

Share your code and requirements.txt, never the .venv folder (it's heavy and tied to your operating system). If you use Git, add .venv/ to your .gitignore file.

Automated tests with pytest

A test is code that checks that other code works. With tests you can change your program without fear: if you break something, you'll know in seconds.

# file: test_finance.py
import pytest
from finance import price_with_tax, loan_payment


def test_price_with_tax():
    assert price_with_tax(100) == 108.25


def test_loan_payment():
    assert loan_payment(25_000, 0.069, 60) == 493.85


def test_zero_rate_fails():
    with pytest.raises(ZeroDivisionError):
        loan_payment(25_000, 0, 60)

pip install pytest
pytest            # finds test_*.py files and runs every test_* function

assert checks that something is true; if it isn't, the test fails and pytest shows you what it expected and what it got. The third test documents a real edge case: a 0% APR makes the formula divide by zero, which is exactly the kind of thing tests help you notice before a customer does.

Real case: a print shop's quote calculator, with tests

Lone Star Print Co. in Austin, Texas, bills per full thousand and charges a 25% rush fee. Here's the whole project, end to end:

1. Step 1Folder and environmentmkdir printshop, cd printshop, python -m venv .venv and activate it.
2. Step 2Dependenciespip install pytest, then pip freeze > requirements.txt.
3. Step 3A module with the logicquotes.py: functions only, no input(), easy to test.
4. Step 4Teststest_quotes.py with the cases that matter to the business, run with pytest.

# file: quotes.py - Lone Star Print Co. (Austin, Texas), prices in USD
import math

PRICE_PER_THOUSAND = {"business_cards": 45.0, "flyers": 120.0, "stickers": 210.0}
RUSH_FEE = 0.25


def quote(product, quantity, rush=False):
    """Price in dollars. Billed per full thousand."""
    if product not in PRICE_PER_THOUSAND:
        raise ValueError(f"Unknown product: {product}")
    thousands = math.ceil(quantity / 1000)
    price = thousands * PRICE_PER_THOUSAND[product]
    if rush:
        price *= 1 + RUSH_FEE
    return round(price, 2)


if __name__ == "__main__":
    print(quote("business_cards", 2500))       # 135.0
    print(quote("flyers", 1000, rush=True))    # 150.0

# file: test_quotes.py
import pytest
from quotes import quote


def test_bills_full_thousands():
    assert quote("business_cards", 2500) == 135.0


def test_rush_fee():
    assert quote("flyers", 1000, rush=True) == 150.0


def test_unknown_product():
    with pytest.raises(ValueError):
        quote("banners", 10)

2,500 business cards are 3 thousands (math.ceil(2.5) = 3) × $45 = $135. Running pytest -q prints 3 passed. Now imagine a coworker changes the rush fee to 0.20 without telling anyone. The next time someone runs the tests, pytest catches it:

    def test_rush_fee():
>       assert quote("flyers", 1000, rush=True) == 150.0
E       AssertionError: assert 144.0 == 150.0
E        +  where 144.0 = quote('flyers', 1000, rush=True)

test_quotes.py:11: AssertionError
=========================== short test summary info ============================
FAILED test_quotes.py::test_rush_fee - AssertionError: assert 144.0 == 150.0
1 failed, 2 passed in 0.01s

How to read it: the line marked > is the one that failed; the E lines show what it got (144.0) versus what was expected (150.0) and which call produced it. The bug surfaced in seconds, before a customer got a wrong quote.

Common mistakes with modules and libraries

The most frequent one: you installed a library, but Python says it doesn't exist.

ModuleNotFoundError: No module named 'requests'

It almost always means you installed it into one Python and you're running another. For example, you installed it with the virtual environment active, and today you opened a new terminal without activating it. Activate the environment (you should see (.venv)) or install with python -m pip install requests using the same python you run your program with.

Professional style

• PEP 8 is Python's official style guide: 4-space indentation, snake_case for functions and variables, CamelCase for classes, lines that aren't too long.
• Tools like ruff and black check and format your code automatically.
• Use type hints (lesson 7) and docstrings on public functions.

# expenses/reports.py
def total_by_category(expenses):
    totals = {}
    for e in expenses:
        totals[e["category"]] = totals.get(e["category"], 0) + e["amount"]
    return totals


# tests/test_reports.py
from expenses.reports import total_by_category


def test_total_by_category():
    expenses = [{"category": "food", "amount": 10.0},
                {"category": "food", "amount": 5.0},
                {"category": "entertainment", "amount": 20.0}]
    assert total_by_category(expenses) == {"food": 15.0, "entertainment": 20.0}


def test_empty_list():
    assert total_by_category([]) == {}

Summary

• A module is a .py file; a package is a folder with __init__.py.
• Install libraries with pip inside one virtual environment per project.
• Share requirements.txt, never the .venv folder.
• Tests with pytest let you change code with confidence and catch silent rule changes.
• Most ModuleNotFoundError messages mean the wrong Python or an inactive environment.

Next lesson: Data Analysis with pandas: From Excel to Python. You'll use your first big external library, the standard tool for analyzing data in Python.