Modules, Imports & Packages

Python organizes code into modules (files) and packages (directories). The import system loads code once per process, caches it in sys.modules, and exposes names through the importing namespace.

Recipe

# myapp/services/users.py
from myapp.models.user import User
from myapp.utils.text import slugify
 
def list_active() -> list[User]:
    return [u for u in User.all() if u.active]

When to reach for this:

• Splitting a growing script into maintainable packages
• Publishing reusable libraries on PyPI
• Running CLI entry points via python -m
• Lazy-loading heavy optional dependencies

Working Example

# myapp/__init__.py
__version__ = "1.0.0"
 
# myapp/config.py
from dataclasses import dataclass
import os
 
@dataclass(frozen=True)
class Settings:
    debug: bool
    database_url: str
 
def load_settings() -> Settings:
    return Settings(
        debug=os.getenv("DEBUG", "0") == "1",
        database_url=os.getenv("DATABASE_URL", "sqlite:///local.db"),
    )
 
# myapp/main.py
from myapp.config import load_settings
 
def main() -> None:
    settings = load_settings()
    print(f"debug={settings.debug} db={settings.database_url}")
 
if __name__ == "__main__":
    main()

Run with: python -m myapp.main from the parent directory on PYTHONPATH.

What this demonstrates:

• Package __init__.py can expose version metadata
• Absolute imports (from myapp.config import ...) stay clear when package grows
• if __name__ == "__main__" entry guard for runnable modules
• -m switch sets __package__ correctly for relative imports inside the package

Deep Dive

How It Works

• Import search path - sys.path lists directories; PYTHONPATH and venv site-packages extend it.
• Module cache - First import executes module body; later imports reuse sys.modules.
• Relative imports - from .config import load_settings require package context (-m or package import).
• Namespace packages - PEP 420 directories without __init__.py can participate in a split namespace.
• __all__ - Documents public names for from module import * (rare in app code).

Layout Recommendation

project/
  src/
    myapp/
      __init__.py
      main.py
      config.py
  pyproject.toml

Install editable (uv pip install -e .) so import myapp resolves during development.

Python Notes

import importlib
 
def lazy_import(module: str):
    return importlib.import_module(module)
 
# TYPE_CHECKING block avoids runtime circular import
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from myapp.models import User

Gotchas

• Circular imports - a imports b while b imports a. Fix: Move shared types to a third module or lazy-import inside functions.
• Running file directly - python myapp/main.py breaks relative imports. Fix: python -m myapp.main.
• Shadowing stdlib - Naming a file json.py breaks import json. Fix: Avoid stdlib names for modules.
• Side effects at import - DB connections at module level slow tests. Fix: Factory functions called from main.
• Star imports - from utils import * pollutes namespace. Fix: Import explicit symbols.

Alternatives

FAQs

Related

• Virtual Environments Quickstart - isolated dependencies
• src layout - production package layout
• pyproject.toml explained - package metadata
• Files & I/O - reading config files

External Related Links

• Python Tutorial (Official) - Official beginner-to-intermediate tutorial.
• Python Packaging User Guide - Official guide for installing, building, and distributing packages.
• Python Package Index (PyPI) - Official repository of Python packages.
• The Quick Python Book (4th Edition) - Concise Python overview (Naomi Ceder).
• Automate the Boring Stuff with Python (Penguin Random House) - Same title via publisher.

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.

NzA2MjAyfDMxN29pZ2N8b2kuc2VkaXVnZWRvYw==