Python Modules & Import System

In Python, a module is a file with a .py extension containing executable Python statements, function definitions, classes, and global variables. Modules are the fundamental architectural building block for code organization, reusability, and namespace encapsulation.

When Python encounters an import statement for the first time, it performs three operations behind the scenes:

1. Locates the file: Searches through the directories configured in sys.path.
2. Compiles to Bytecode: Parses source code into bytecode (.pyc) and caches it inside the __pycache__/ directory to accelerate future startups.
3. Executes and Caches in Memory: Executes the top-level statements from top to bottom, creates a new module type object, and stores a reference to it in the global sys.modules dictionary table.

Because Python caches imported modules in sys.modules, importing the same module 100 times across 100 different files executes the module's initialization code only once!

# Inspecting module metadata and the sys.modules cache:
import math
import sys

print("Module Object:", math)
print("Module Name (__name__):", math.__name__)
print("Module Docstring:", math.__doc__[:60], "...")
print("Is 'math' cached in sys.modules?", 'math' in sys.modules)

Python provides three flexible syntax patterns to bring module members into your current namespace:

1. Standard import module_name:

Brings the entire module into your namespace as a qualified prefix (e.g. math.sqrt(16)). This is the safest approach because it avoids any risk of naming collisions with your local variables.

2. Specific from module_name import item1, item2:

Brings specific functions or classes directly into your local scope so you can call sqrt(16) without prefixing math..

3. Renaming Aliases with as:

Provides a concise or disambiguated shorthand name for lengthy module names (e.g. import datetime as dt or import numpy as np).

# Method 1: Standard import with full qualification
import math
res1 = math.pow(2, 3)

# Method 2: Importing specific members directly
from math import sqrt, pi
res2 = sqrt(144)

# Method 3: Importing with clean alias
import datetime as dt
current_year = dt.datetime.now().year

print(f"2 ** 3 = {res1}")
print(f"Square root of 144 = {res2}")
print(f"Value of Pi = {pi:.4f}")
print(f"Current Year via 'dt' alias: {current_year}")

When you execute import my_module, Python does not search your entire hard drive. Instead, it searches a precise, ordered list of directory path strings stored in sys.path:

1. Current Directory: The directory containing the script that was executed from the terminal (or current working directory in interactive shells).
2. PYTHONPATH Environment Variable: Any custom directory paths configured by the developer in the operating system environment.
3. Standard Library Directories: The directory where official Python modules (like math, json, os) are installed.
4. Site-Packages (Third-Party Packages): The directory where packages installed via pip (like requests, fastapi, pandas) live.

If Python searches all directories in sys.path without finding a matching .py file or compiled C extension, it halts and raises a ModuleNotFoundError: No module named '...' exception.

import sys

print("--- 🔍 Python Module Search Paths (sys.path) ---")
for index, directory_path in enumerate(sys.path, start=1):
    print(f"{index}. {directory_path}")

Every Python module has a built-in special variable named __name__ automatically set by the CPython interpreter:

• When you execute a file directly from the terminal (e.g. python app.py), Python sets __name__ = "__main__".
• When a file is imported into another script (e.g. import app), Python sets __name__ = "app" (the actual module name).

This allows a Python file to act as both a reusable library of functions AND an executable standalone script with unit tests or CLI demos!

# geometry_helper.py
def calculate_circle_area(radius):
    """Reusable function for calculating circle area."""
    import math
    return math.pi * (radius ** 2)

def calculate_perimeter(radius):
    """Reusable function for calculating circumference."""
    import math
    return 2 * math.pi * radius

# The __name__ check ensures this test block only runs when executed directly:
if __name__ == "__main__":
    print("--- 🧪 Running geometry_helper.py Standalone Tests ---")
    test_r = 5
    print(f"Test Radius: {test_r}")
    print(f"Calculated Area: {calculate_circle_area(test_r):.2f}")
    print(f"Calculated Perimeter: {calculate_perimeter(test_r):.2f}")