Packages & init.py

A package is a directory containing Python modules. The __init__.py file marks the directory as a package and controls its public interface.

Package Structure

myapp/
    __init__.py
    models/
        __init__.py
        user.py
        product.py
    utils/
        __init__.py
        validation.py
        formatting.py
    main.py

init.py Basics

# myapp/__init__.py
__version__ = "1.0.0"
__author__  = "Alice"

# Expose key classes at the package level
from .models.user    import User
from .models.product import Product

Importing from Packages

from myapp.models.user import User
from myapp.utils.validation import validate_email
import myapp.utils.formatting as fmt

# After exposing in __init__.py:
from myapp import User, Product

Relative Imports

# Inside myapp/models/product.py
from .user import User          # same package
from ..utils import formatting  # parent package

Namespace Packages (Python 3.3+)

# __init__.py is optional in Python 3.3+
# Directory without __init__.py is a namespace package
# Useful for splitting a package across multiple directories

Example

# Simulate a mini-package in memory
import types, sys

pkg = types.ModuleType("geometry")
pkg.__path__ = []
sys.modules["geometry"] = pkg

circles = types.ModuleType("geometry.circles")
circles.area = lambda r: 3.14159 * r**2
circles.perimeter = lambda r: 2 * 3.14159 * r
sys.modules["geometry.circles"] = circles
pkg.circles = circles

from geometry.circles import area, perimeter
print(f"Area: {area(5):.2f}")
print(f"Perimeter: {perimeter(5):.2f}")

PYTHON

Full Editor

Pro Tip

Keep __init__.py lean. Avoid heavy imports there — they run every time any sub-module is imported, which slows startup.