Creating Packages

A Python package is a way to organize related modules into a directory hierarchy. Think of it as a folder that Python recognizes as containing importable code. Packages help you structure large projects and make your code reusable across different projects.

Why Use Packages?

A package is simply a directory containing an __init__.py file and one or more module files. The __init__.py file can be empty or contain initialization code. Let's see how to create a basic package structure.

myproject/                    # Project root
    main.py                   # Entry point (uses the package)
    mypackage/                # Package directory
        __init__.py           # Makes it a package (can be empty)
        module1.py            # First module
        module2.py            # Second module
        utils/                # Subpackage
            __init__.py       # Subpackage init
            helpers.py        # Subpackage module

# Importing from this structure:
from mypackage import module1
from mypackage.module2 import some_function
from mypackage.utils.helpers import helper_func

Creating a Simple Package

# File: mypackage/__init__.py
# Can be empty, or define what to export:
from .module1 import greet
from .module2 import calculate

# File: mypackage/module1.py
def greet(name):
    return f"Hello, {name}!"

# File: mypackage/module2.py
def calculate(a, b):
    return a + b

Using the Package

# File: main.py (in project root)
# Method 1: Import from __init__.py exports
from mypackage import greet, calculate

print(greet("Alice"))       # Hello, Alice!
print(calculate(5, 3))      # 8

# Method 2: Import specific modules
from mypackage.module1 import greet
from mypackage.module2 import calculate

# Method 3: Import entire package
import mypackage
print(mypackage.greet("Bob"))  # Hello, Bob!

# math_tools/__init__.py
from .add import add
from .multiply import multiply

# math_tools/add.py
def add(a, b):
    return a + b

# math_tools/multiply.py
def multiply(a, b):
    return a * b

# main.py
from math_tools import add, multiply
print(add(2, 3))       # 5
print(multiply(4, 5))  # 20

# myutils/__init__.py
# (empty file)

# myutils/strings.py
def capitalize_all(words):
    return [w.upper() for w in words]

# main.py - must import from module directly
from myutils.strings import capitalize_all
print(capitalize_all(["hello", "world"]))  # ['HELLO', 'WORLD']

# shapes/__init__.py
from .two_d import circle, rectangle

# shapes/two_d/__init__.py
from .circle import area as circle_area
from .rectangle import area as rect_area

# shapes/two_d/circle.py
import math
def area(radius):
    return math.pi * radius ** 2

# shapes/two_d/rectangle.py
def area(width, height):
    return width * height

# main.py
from shapes.two_d import circle_area, rect_area
print(circle_area(5))      # 78.54...
print(rect_area(4, 6))     # 24

The __init__.py file serves multiple purposes. It marks a directory as a Python package, runs initialization code when the package is imported, and controls what gets exported when someone imports from your package.

Empty vs Non-Empty __init__.py

# Empty __init__.py
# Just marks the directory as a package
# Users must import from specific modules:
from mypackage.module1 import func1

# Non-empty __init__.py with exports
# File: mypackage/__init__.py
from .module1 import func1
from .module2 import func2, MyClass

# Now users can import directly:
from mypackage import func1, func2, MyClass

Controlling Exports with __all__

# mypackage/__init__.py
from .module1 import func1, func2, helper
from .module2 import ClassA, ClassB

# Only export these when using "from mypackage import *"
__all__ = ["func1", "ClassA"]

# Now:
# from mypackage import *
# Only imports func1 and ClassA, not func2, helper, or ClassB

Package Initialization Code

# mypackage/__init__.py
print("Initializing mypackage...")  # Runs when imported

# Set package-level variables
VERSION = "1.0.0"
AUTHOR = "Your Name"

# Import and expose functions
from .core import main_function
from .utils import helper

# Run setup code
_setup_logging()  # Internal function

Python offers several ways to import from packages. Each style has its use case. Understanding when to use each makes your code cleaner and more readable.

Best Practices

# Good: Explicit imports
from mypackage.utils import format_date
from mypackage.models import User, Product

# Good: Short alias for long names
import matplotlib.pyplot as plt
import pandas as pd

# Avoid: Star imports (pollutes namespace)
from mypackage import *  # What did we import?

# Avoid: Too many levels
import a.b.c.d.e.f.module  # Hard to read

# Style 1: Import module
import data.loader
data.loader.load_csv("file.csv")

# Style 2: From import
from data import loader
loader.load_csv("file.csv")

# Style 3: Import function directly
from data.loader import load_csv
load_csv("file.csv")

# mymodule.py
__all__ = ["public_func1", "public_func2"]

def public_func1():
    return "I am public"

def public_func2():
    return "I am also public"

def _private_helper():
    return "I am private by convention"

def internal_func():
    return "Not in __all__, not exported with *"

# mylib/__init__.py
"""My Library - Clean API example."""

from .config import Config, load_config
from .client import Client, connect
from .utils import format_response

__all__ = [
    "Config",
    "load_config",
    "Client", 
    "connect",
    "format_response"
]

__version__ = "1.0.0"

Relative imports use dots to refer to modules within the same package. A single dot means "current package" and two dots mean "parent package". They make your package more portable and avoid hardcoding package names.

Single Dot - Current Package

# Package structure:
# mypackage/
#     __init__.py
#     main.py
#     utils.py

# In main.py - import from same package
from . import utils           # Import utils module
from .utils import helper     # Import helper from utils

# These are equivalent to:
from mypackage import utils
from mypackage.utils import helper

Double Dot - Parent Package

# Package structure:
# mypackage/
#     __init__.py
#     core/
#         __init__.py
#         engine.py
#     utils/
#         __init__.py
#         helpers.py

# In helpers.py - import from parent package
from .. import core           # Go up, import core
from ..core import engine     # Go up, into core, import engine
from ..core.engine import run # Go up, into core.engine, get run

When to Use Relative Imports

# Absolute import (original)
from mypackage.utils import helper

# Relative import (converted)
from .utils import helper

# Both work the same when inside mypackage/

# File: mypackage/sub/module.py

# Import from parent package
from ..config import settings
from .. import config  # Or import the whole module

# The .. goes up from "sub" to "mypackage"

# File: mypackage/api/endpoints.py
# Structure:
# mypackage/
#     api/endpoints.py  <- we are here
#     db/connection.py  <- we want Database from here

# Go up to mypackage, then down to db.connection
from ..db.connection import Database

# Or import the module
from ..db import connection
db = connection.Database()