Modules & Packages

Folder Structure

Here is the package we will build. Two things make it work: the mypackage/ folder holds the modules, and __init__.py marks that folder as a package rather than an ordinary directory. The script that uses it, main.py, sits beside the folder, not inside it, which is what lets import mypackage find it.

project/
├── main.py
└── mypackage/
    ├── __init__.py
    ├── helpers.py
    └── math_utils.py

The dotted path in an import mirrors this tree one segment at a time: mypackage.math_utils means the math_utils module inside the mypackage folder.

Create the whole thing from an empty directory:

# Terminal

mkdir project
cd project

mkdir mypackage
touch main.py
touch mypackage/__init__.py mypackage/helpers.py mypackage/math_utils.py

That leaves you with five empty files. The next sections fill in three of them, one at a time.

The helpers Module

Two small string utilities. Nothing about this file is special: it is an ordinary module that happens to live inside a package folder.

# mypackage/helpers.py

def format_name(name):
    return name.strip().title()

def clean_text(text):
    return " ".join(text.split())

The math_utils Module

A second module in the same package. Grouping related modules under one folder is the entire point of packages: helpers and math_utils stay separate files, but ship and import as one unit.

# mypackage/math_utils.py

def square(n):
    return n * n

def cube(n):
    return n * n * n

Using the Package

Now main.py can reach both modules. The two import forms below are worth contrasting: the first pulls in the whole helpers module, so its functions stay behind the helpers. prefix; the second reaches into math_utils and pulls out a single name, so square() is used bare.

# main.py

from mypackage import helpers
from mypackage.math_utils import square

print(helpers.format_name("  ada lovelace  "))
print(helpers.clean_text("too    many   spaces"))
print(square(7))

Ada Lovelace
too many spaces
49

What Goes in __init__.py?

The __init__.py file can be empty (it just marks the directory as a package), or it can contain initialization code and convenient imports.

# mypackage/__init__.py

"""
This file makes the directory a Python package.
Can be empty, or can contain initialization code.
"""

# Import commonly used items for convenience
from .helpers import format_name, clean_text
from .math_utils import square, cube

# Package-level variables
__version__ = "1.0.0"
__author__ = "Your Name"

Those re-exports change how callers reach the same functions. Instead of naming the module inside the package (from mypackage.math_utils import square), they can import straight from the package:

# main.py

import mypackage
from mypackage import square, format_name

print(square(9))
print(format_name("grace hopper"))
print(mypackage.__version__)

81
Grace Hopper
1.0.0

How It Works

# calculator.py

def add(a, b):
    """Add two numbers"""
    return a + b

def subtract(a, b):
    """Subtract b from a"""
    return a - b

def multiply(a, b):
    """Multiply two numbers"""
    return a * b

# This code only runs when script is executed directly
if __name__ == "__main__":
    # Test/demo code
    print("Testing calculator module...")
    print(f"5 + 3 = {add(5, 3)}")
    print(f"10 - 4 = {subtract(10, 4)}")
    print(f"7 * 6 = {multiply(7, 6)}")
    print("All tests passed!")

Testing calculator module...
5 + 3 = 8
10 - 4 = 6
7 * 6 = 42
All tests passed!

That output is what python calculator.py prints. Running the file directly sets__name__ to "__main__", so the test code executes. Importing it (import calculator) sets __name__ to "calculator" instead, so the same block is skipped and nothing is printed: the caller gets the three functions and none of the demo noise.

Practical Example

# data_processor.py

def clean_data(data):
    """Remove empty strings and strip whitespace"""
    return [item.strip() for item in data if item.strip()]

def calculate_average(numbers):
    """Calculate average of numbers"""
    if not numbers:
        return 0
    return sum(numbers) / len(numbers)

if __name__ == "__main__":
    # Demo: shows how to use the module
    sample_data = ["  hello  ", "", "  world  ", "   "]
    cleaned = clean_data(sample_data)
    print(f"Cleaned data: {cleaned}")

    scores = [85, 92, 78, 95, 88]
    avg = calculate_average(scores)
    print(f"Average score: {avg}")

Cleaned data: ['hello', 'world']
Average score: 87.6