🎯 Advanced Relative Import Patterns

Solve complex import scenarios in deeply nested packages and multi-level hierarchies.

🎯 Deep Package Hierarchies

Navigate complex multi-level package structures.

company/
├── __init__.py
├── core/
│   ├── __init__.py
│   └── models.py
├── services/
│   ├── __init__.py
│   ├── user/
│   │   ├── __init__.py
│   │   ├── models.py
│   │   └── handlers.py
│   └── order/
│       ├── __init__.py
│       ├── models.py
│       └── handlers.py
└── utils/
    ├── __init__.py
    └── validators.py

In company/services/user/handlers.py:

# Import from sibling module (same level)
from .models import User

# Import from parent package's sibling
from ..order.models import Order

# Import from grandparent package's child
from ...core.models import BaseModel

# Import from utils (multiple levels up)
from ...utils.validators import validate_email

class UserHandler:
    def handle_user_order(self, user: User, order: Order):
        """Handler combining models from different packages."""
        if not validate_email(user.email):
            raise ValueError("Invalid email")
        return {"user": user, "order": order}

💡 Circular Import Prevention in Deep Hierarchies

Solve circular imports across multiple levels.

# Problem: circular import across levels
# company/services/user/models.py
from ...core.models import BaseModel
from .handlers import UserHandler  # Circular if handlers imports this

# company/services/user/handlers.py
from .models import User  # Circular!

Solution 1: Structural reorganization:

# Separate models and handlers
company/
├── models/
│   ├── __init__.py
│   ├── user.py
│   └── order.py
└── handlers/
    ├── __init__.py
    ├── user.py
    └── order.py

# company/models/user.py
from ...core.models import BaseModel

class User(BaseModel):
    pass

# company/handlers/user.py (no circular dependency)
from ..models.user import User

class UserHandler:
    pass

Solution 2: TYPE_CHECKING imports:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from .handlers import UserHandler

class User:
    def render(self) -> "UserHandler":
        # Only imports at type-check time, not runtime
        from .handlers import UserHandler
        return UserHandler().render(self)

🏗️ Package __init__.py Architecture

Design __init__.py for complex hierarchies.

# company/__init__.py - Root package initialization

from . import core
from . import services
from . import utils

__version__ = "1.0.0"
__all__ = ["core", "services", "utils"]

# company/services/__init__.py - Services subpackage
from . import user
from . import order

__all__ = ["user", "order"]

# company/services/user/__init__.py - User service package
from .models import User, UserProfile
from .handlers import UserHandler

__all__ = ["User", "UserProfile", "UserHandler"]

# Now users can do:
from company.services.user import User
from company.services import order

📦 Relative Import Type Compatibility

Handle different relative import scenarios.

# company/services/user/models.py

# ✅ Valid: Same package, same level
from . import handlers

# ✅ Valid: Sibling subpackage
from ..order import models as order_models

# ✅ Valid: Parent package
from .. import validators

# ✅ Valid: Grandparent
from ... import core

# ✅ Valid: Grandparent's child
from ...core.models import BaseModel

# ❌ Invalid: Can't go above top level
from .... import something  # Would try to go above company

# ❌ Invalid: Can't use relative with absolute in same statement
from ..order import Order
import external_package  # Fine separately, but mixing is confusing

🔄 Multi-Package Systems

Organize multiple interdependent packages.

project/
├── package_a/
│   ├── __init__.py
│   ├── module_a.py
│   └── subpkg/
│       ├── __init__.py
│       └── module_a_sub.py
└── package_b/
    ├── __init__.py
    ├── module_b.py
    └── subpkg/
        ├── __init__.py
        └── module_b_sub.py

In package_b/module_b.py:

# Can import from package_a (different top-level package)
# But only with absolute imports (no relative imports across packages)
import package_a
from package_a.module_a import ClassA

# Within package_b, use relative imports
from . import subpkg
from .subpkg.module_b_sub import ClassBSub

💻 Export Aggregation Pattern

Use relative imports to aggregate and expose package APIs.

# company/services/__init__.py - Aggregate service APIs

# Import all public items from subpackages
from .user import User, UserHandler
from .user import UserService
from .order import Order, OrderHandler
from .order import OrderService

# Re-export as package API
__all__ = [
    "User",
    "UserHandler",
    "UserService",
    "Order",
    "OrderHandler",
    "OrderService"
]

# Users can now do:
from company.services import User, Order
# Instead of:
# from company.services.user import User
# from company.services.order import Order

Lazy re-export:

# company/services/__init__.py - Lazy export

def __getattr__(name):
    """Lazy import for performance."""
    if name == "User":
        from .user import User
        return User
    elif name == "Order":
        from .order import Order
        return Order
    raise AttributeError(f"module {__name__} has no attribute {name}")

def __dir__():
    return ["User", "Order"]

🎨 Template Pattern for Package Layout

Best practices template:

myproject/
├── setup.py
├── setup.cfg
└── src/
    └── myproject/           # Top-level package
        ├── __init__.py      # Version, exports
        ├── core/            # Core functionality
        │   ├── __init__.py
        │   ├── models.py
        │   └── utils.py
        ├── services/        # Business logic
        │   ├── __init__.py
        │   ├── user/
        │   │   ├── __init__.py
        │   │   ├── models.py
        │   │   └── handlers.py
        │   └── order/
        │       ├── __init__.py
        │       ├── models.py
        │       └── handlers.py
        └── api/             # API layer
            ├── __init__.py
            ├── v1/
            │   ├── __init__.py
            │   ├── users.py
            │   └── orders.py
            └── v2/
                ├── __init__.py
                ├── users.py
                └── orders.py

myproject/__init__.py:

__version__ = "1.0.0"

from . import core
from . import services
from . import api

__all__ = ["core", "services", "api"]

myproject/services/__init__.py:

# Use relative imports
from . import user
from . import order

__all__ = ["user", "order"]

myproject/services/user/__init__.py:

from .models import User
from .handlers import UserHandler

__all__ = ["User", "UserHandler"]

🔑 Import Strategy Guide

When to use relative imports:

# ✅ Within same package/subpackage
from .models import User

# ✅ Accessing parent package siblings
from ..order import Order

# ✅ Accessing utilities from parent
from ...utils import validators

When to use absolute imports:

# ✅ Different top-level packages
from package_a import something

# ✅ External libraries
import numpy as np

# ✅ From installed packages
from requests import get

🔑 Key Takeaways

• ✅ Use relative imports only within packages

• ✅ One dot (.) = current package

• ✅ Two dots (..) = parent package

• ✅ Solve circular imports with late imports or restructuring

• ✅ Use TYPE_CHECKING for type hints without circular imports

• ✅ Aggregate exports in __init__.py for clean APIs

• ✅ Use __getattr__ for lazy package loading

Ready to practice? Challenges | Quiz