Organizing Your Python Code into Modules and Packages

Every Python project starts as a single file. That is completely normal. But as your script grows past a few dozen lines, a single file becomes hard to read, impossible to test, and painful to reuse. The fix is straightforward: identify the natural groups of responsibility in your code and move each group into its own file. This page shows you exactly how to do that, step by step.

Why split your code?

A well-organised codebase gives you three concrete advantages:

Readability — each file has one clear job, so a new reader (including future-you) can find relevant code instantly
Reusability — a calculate_totals function in its own module can be imported by multiple scripts without copy-pasting
Testability — small, focused functions with no side effects are trivial to unit-test; one giant script is nearly impossible to test reliably

Before: a single tangled script

Here is a realistic sales analysis script that does everything in one file. It works, but it is hard to maintain.

# analyzer.py  — 80 lines, does everything

import csv
import json
from datetime import datetime

# ── Load data ────────────────────────────────────────────────────────────────
rows = []
with open("data/sales.csv", "r") as f:
    reader = csv.DictReader(f)
    for row in reader:
        rows.append({
            "date": datetime.strptime(row["date"], "%Y-%m-%d"),
            "product": row["product"],
            "quantity": int(row["quantity"]),
            "price": float(row["price"]),
        })

# ── Process data ─────────────────────────────────────────────────────────────
for row in rows:
    row["total"] = row["quantity"] * row["price"]

grand_total = sum(r["total"] for r in rows)
by_product = {}
for row in rows:
    p = row["product"]
    by_product[p] = by_product.get(p, 0) + row["total"]
best_seller = max(by_product, key=by_product.get)

# ── Format and print ─────────────────────────────────────────────────────────
print("=" * 40)
print(f"Grand total: ${grand_total:,.2f}")
print(f"Best seller: {best_seller} (${by_product[best_seller]:,.2f})")
for product, total in sorted(by_product.items(), key=lambda x: -x[1]):
    print(f"  {product:<12} ${total:>10,.2f}")

# ── Save report ──────────────────────────────────────────────────────────────
report = {
    "generated": datetime.now().isoformat(),
    "grand_total": grand_total,
    "by_product": by_product,
    "best_seller": best_seller,
}
with open("output/report.json", "w") as f:
    json.dump(report, f, indent=2)
print("Report saved to output/report.json")

The problem: if you want to reuse the loading logic in a second script, you have to copy it. If a test fails, you have to wade through 80 lines to find the bug. If a colleague needs to change the output format, they risk breaking the data-processing logic by accident.

Identify the logical groups

Read through your script and label every line with its responsibility. In the example above, four groups emerge naturally:

Group	Responsibility	File name
Data loading	Read CSV, parse types	`data_loader.py`
Data processing	Calculate totals and summaries	`data_processor.py`
Reporting	Format and print results	`reporter.py`
Entry point	Orchestrate everything	`main.py`

After: four focused modules

Here is the project layout after refactoring:

sales-analysis/
├── data/
│   └── sales.csv
├── output/
├── sales_analysis/
│   ├── __init__.py
│   ├── data_loader.py
│   ├── data_processor.py
│   ├── reporter.py
│   └── main.py
└── pyproject.toml

`data_loader.py` — reads and parses raw data

# sales_analysis/data_loader.py

import csv
from datetime import datetime
from pathlib import Path


def load_sales(filepath: str | Path) -> list[dict]:
    """
    Read a sales CSV and return a list of dicts with typed values.

    Each dict has keys: date (datetime), product (str),
    quantity (int), price (float).
    """
    rows = []
    with open(filepath, "r", newline="") as f:
        reader = csv.DictReader(f)
        for row in reader:
            rows.append({
                "date": datetime.strptime(row["date"], "%Y-%m-%d"),
                "product": row["product"],
                "quantity": int(row["quantity"]),
                "price": float(row["price"]),
            })
    return rows

`data_processor.py` — all calculation logic

# sales_analysis/data_processor.py


def add_totals(rows: list[dict]) -> list[dict]:
    """Add a 'total' key (quantity × price) to each row."""
    for row in rows:
        row["total"] = row["quantity"] * row["price"]
    return rows


def summarise_by_product(rows: list[dict]) -> dict[str, float]:
    """Return a dict mapping each product name to its total revenue."""
    summary: dict[str, float] = {}
    for row in rows:
        product = row["product"]
        summary[product] = summary.get(product, 0.0) + row["total"]
    return summary


def grand_total(rows: list[dict]) -> float:
    """Sum all row totals."""
    return sum(row["total"] for row in rows)


def best_seller(summary: dict[str, float]) -> str:
    """Return the product with the highest total revenue."""
    return max(summary, key=summary.get)

`reporter.py` — formatting and output

# sales_analysis/reporter.py

import json
from datetime import datetime
from pathlib import Path


def print_summary(grand: float, summary: dict[str, float], top: str) -> None:
    """Print a formatted sales summary to the terminal."""
    print("=" * 40)
    print(f"Grand total:  ${grand:,.2f}")
    print(f"Best seller:  {top} (${summary[top]:,.2f})")
    print()
    print("Revenue by product:")
    for product, total in sorted(summary.items(), key=lambda x: -x[1]):
        print(f"  {product:<14} ${total:>10,.2f}")


def save_report(
    grand: float,
    summary: dict[str, float],
    top: str,
    output_path: str | Path,
) -> None:
    """Save a JSON report to disk, creating the output directory if needed."""
    output_path = Path(output_path)
    output_path.parent.mkdir(parents=True, exist_ok=True)

    report = {
        "generated": datetime.now().isoformat(),
        "grand_total": grand,
        "by_product": summary,
        "best_seller": top,
    }
    with open(output_path, "w") as f:
        json.dump(report, f, indent=2)

    print(f"Report saved → {output_path}")

`main.py` — the orchestrator

# sales_analysis/main.py

from pathlib import Path

from sales_analysis.data_loader import load_sales
from sales_analysis.data_processor import add_totals, summarise_by_product, grand_total, best_seller
from sales_analysis.reporter import print_summary, save_report


def run(data_path: str | Path = "data/sales.csv") -> None:
    """Full analysis pipeline: load → process → report → save."""
    rows = load_sales(data_path)
    rows = add_totals(rows)

    summary = summarise_by_product(rows)
    total = grand_total(rows)
    top = best_seller(summary)

    print_summary(total, summary, top)
    save_report(total, summary, top, "output/report.json")


if __name__ == "__main__":
    run()

Notice how main.py reads like plain English — it tells you what happens without burying you in how. The implementation details live in the appropriate modules.

Making your folder a package with `init.py`

Add an __init__.py to sales_analysis/ to make it a proper Python package. You can leave it empty, or use it to expose a clean public API:

# sales_analysis/__init__.py

from .data_loader import load_sales
from .data_processor import add_totals, summarise_by_product, grand_total, best_seller
from .reporter import print_summary, save_report

__all__ = [
    "load_sales",
    "add_totals",
    "summarise_by_product",
    "grand_total",
    "best_seller",
    "print_summary",
    "save_report",
]

With this in place, other scripts can import directly from the package:

from sales_analysis import load_sales, grand_total

Importing between modules

Use absolute imports within your package. They always resolve correctly, regardless of where you run the code from.

# Always write this:
from sales_analysis.data_processor import add_totals

# Not this (breaks when you run the file directly):
from .data_processor import add_totals

Run the project from its root directory using the -m flag:

cd sales-analysis
python -m sales_analysis.main

Writing a simple test after refactoring

Once your logic lives in focused functions, writing tests becomes trivial. Create tests/test_data_processor.py:

# tests/test_data_processor.py

from sales_analysis.data_processor import grand_total, summarise_by_product, best_seller

SAMPLE_ROWS = [
    {"product": "Laptop",   "quantity": 2, "price": 999.99, "total": 1999.98},
    {"product": "Mouse",    "quantity": 5, "price":  29.99, "total":  149.95},
    {"product": "Keyboard", "quantity": 3, "price":  79.99, "total":  239.97},
]

def test_grand_total():
    assert round(grand_total(SAMPLE_ROWS), 2) == 2389.90

def test_best_seller():
    summary = summarise_by_product(SAMPLE_ROWS)
    assert best_seller(summary) == "Laptop"

def test_summarise_by_product_keys():
    summary = summarise_by_product(SAMPLE_ROWS)
    assert set(summary.keys()) == {"Laptop", "Mouse", "Keyboard"}

Run the tests:

pytest tests/

Try testing the monolithic analyzer.py and you will immediately understand why modular code is worth the refactoring effort.

When you are not sure how to split a script, start with a single rule: one function does one thing, and one module groups related functions. If you cannot summarise a module’s job in one short sentence, it probably needs to be split further.

Project Workflow

Learn the day-to-day workflow for managing Python projects end to end

Project Development

SQL & Databases

Data Analysis

Organizing Your Python Code into Modules and Packages

Why split your code?

Before: a single tangled script

Identify the logical groups

After: four focused modules

`data_loader.py` — reads and parses raw data

`data_processor.py` — all calculation logic

`reporter.py` — formatting and output

`main.py` — the orchestrator

Making your folder a package with `init.py`

Importing between modules

Writing a simple test after refactoring

Project Workflow

​Why split your code?

​Before: a single tangled script

​Identify the logical groups

​After: four focused modules

​data_loader.py — reads and parses raw data

​data_processor.py — all calculation logic

​reporter.py — formatting and output

​main.py — the orchestrator

​Making your folder a package with __init__.py

​Importing between modules

​Writing a simple test after refactoring

Project Workflow

Why split your code?

Before: a single tangled script

Identify the logical groups

After: four focused modules

`data_loader.py` — reads and parses raw data

`data_processor.py` — all calculation logic

`reporter.py` — formatting and output

`main.py` — the orchestrator

Making your folder a package with `init.py`

Importing between modules

Writing a simple test after refactoring