Python Modules

Python Modules & Packages: Imports, Namespace, & __all__

Modules are .py files containing code definitions and executable statements. Packages are directories containing modules and a package initialization file (__init__.py).

Package Directory Structure & Import Search Path

flowchart TD
    Root["Project Root/"] --> Pkg["my_package/"]
    Pkg --> Init["__init__.py (Package initialization)"]
    Pkg --> Mod1["auth.py (Module)"]
    Pkg --> Mod2["database.py (Module)"]
    Init --> Path["Import Search: 1. Current Dir -> 2. PYTHONPATH -> 3. Standard Library"]

Import Styles

• import math: Imports module into its own namespace (math.sqrt(16)).
• from math import sqrt: Imports target function directly into local namespace (sqrt(16)).
• from math import *: Anti-pattern (pollutes local namespace).

Practical Code Example

import sys
from pathlib import Path
from typing import List

def inspect_import_system() -> None:
    print(f"Current Executable: {sys.executable}")
    print("
--- Python Module Search Paths (sys.path) ---")
    for idx, path_str in enumerate(sys.path[:3], start=1):
        print(f" Path {idx}: {path_str}")

    # Inspecting Module Attributes
    print(f"
Module Name: {__name__}")
    print(f"File Path: {Path(__file__).resolve() if '__file__' in globals() else 'Interactive'}")

if __name__ == "__main__":
    inspect_import_system()

Best Practices & Gotchas

• Avoid Wildcard Imports (from module import *): Wildcard imports hide variable provenance and cause namespace pollution.
• Use __all__ in Package Modules: Explicitly declare __all__ = ["PublicClass", "public_func"] to define exported public APIs.
• Prevent Circular Imports: If Module A imports Module B while Module B imports Module A, structure imports inside function bodies or refactor shared dependencies into a separate module.

Self-Check Challenge

Create a module file math_utils.py containing a function add(a, b), import it into a main script using from math_utils import add, and print the calculation result.