rakrisi Daily

Daily Tech Brief

Top startup stories in your inbox

Subscribe Free

© 2026 rakrisi Daily

Python Import System - Mastering Imports

Python Import System: Mastering Imports

Welcome to Python’s Import System! Think of imports as bridges connecting different parts of your code. Understanding how imports work is crucial for writing maintainable, modular Python programs.

How Python Imports Work

When you import something, Python follows a systematic process:

  1. Check sys.modules - See if module is already loaded
  2. Find the module - Search through sys.path
  3. Load the code - Compile and execute the module
  4. Create namespace - Make the module object available
  5. Execute imports - Handle any imports in the module
import sys

# See current loaded modules
print(f"Loaded modules: {len(sys.modules)}")

# Check if a module is loaded
print(f"os loaded: {'os' in sys.modules}")
import os
print(f"os loaded: {'os' in sys.modules}")

Import Search Path

Python searches for modules in this order:

import sys
print("Python import search path:")
for i, path in enumerate(sys.path, 1):
    print(f"{i}. {path}")

Typical search order:

  1. Built-in modules (sys, os, math)
  2. Current working directory
  3. PYTHONPATH environment variable
  4. Site-packages (installed packages)
  5. Standard library

Import Statement Types

1. import Statement

import math
import os.path
import json as js

# Access with module prefix
result = math.sqrt(16)
files = os.path.listdir('.')
data = js.loads('{"key": "value"}')

2. from Statement

from math import sqrt, pi
from os.path import join, exists
from json import loads as parse_json

# Direct access (no prefix needed)
result = sqrt(16)
path = join('folder', 'file.txt')
data = parse_json('{"key": "value"}')

3. from module import *

from math import *

# Everything is imported
print(pi)      # 3.141592653589793
print(sqrt)    # <built-in function sqrt>
print(sin)     # <built-in function sin>

⚠️ Warning: Avoid import * in production code!

Relative vs Absolute Imports

Absolute Imports

# Always from project root
from mypackage.utils import helper
from ecommerce.products.models import Product
import myapp.database.connection as db

Relative Imports

# Within a package only
from . import sibling_module          # Same directory
from .sibling import function         # Specific function
from .. import parent_module          # Parent directory
from ..parent import function         # Parent function
from ...grandparent import function   # Grandparent

When to use relative imports:

  • Inside packages (not at top level)
  • When package structure might change
  • For internal package references

Import Execution and Caching

Module Execution

# test_module.py
print("Module is being executed!")

def test_function():
    print("Function called")

CONSTANT = 42

print("Module execution complete")
# main.py
print("Before import")
import test_module
print("After import")
print(f"Constant: {test_module.CONSTANT}")

print("Calling function:")
test_module.test_function()

Output:

Before import
Module is being executed!
Module execution complete
After import
Constant: 42
Calling function:
Function called

Import Caching

import sys

# First import
print("First import:")
import test_module

# Second import (cached)
print("Second import:")
import test_module

print(f"Module in cache: {'test_module' in sys.modules}")

Modules are only executed once, then cached in sys.modules.

Import Error Handling

Try/Except Imports

try:
    import optional_library
    HAS_OPTIONAL = True
except ImportError:
    HAS_OPTIONAL = False
    optional_library = None

# Use conditional code
if HAS_OPTIONAL:
    result = optional_library.do_something()
else:
    result = fallback_function()

Version Checking

import sys

if sys.version_info < (3, 6):
    raise ImportError("Python 3.6+ required")

try:
    import pandas as pd
    if pd.__version__ < '1.0.0':
        print("Warning: pandas version might be outdated")
except ImportError:
    print("pandas not available")

Circular Import Problems

What is Circular Import?

# module_a.py
import module_b

def function_a():
    module_b.function_b()

# module_b.py
import module_a

def function_b():
    module_a.function_a()

Result: ImportError: cannot import name 'function_a'

Solutions

1. Move Imports Inside Functions

# module_a.py
def function_a():
    import module_b  # Import inside function
    module_b.function_b()

# module_b.py
def function_b():
    import module_a  # Import inside function
    module_a.function_a()

2. Restructure Code

# shared.py
def shared_function():
    pass

# module_a.py
from shared import shared_function

def function_a():
    shared_function()

# module_b.py
from shared import shared_function

def function_b():
    shared_function()

3. Import at the End

# module_a.py
def function_a():
    module_b.function_b()

# Import at end to avoid circular dependency
import module_b

# module_b.py
def function_b():
    module_a.function_a()

# Import at end
import module_a

Advanced Import Techniques

Dynamic Imports

import importlib

# Import by string name
module_name = "math"
math_module = importlib.import_module(module_name)

# Use the imported module
result = math_module.sqrt(16)
print(result)  # 4.0

Plugin Loading

import importlib
import pkgutil

def load_plugins(package_name):
    """Load all plugins from a package."""
    plugins = {}
    package = importlib.import_module(package_name)

    for finder, name, ispkg in pkgutil.iter_modules(package.__path__):
        if name.startswith('plugin_'):
            module = importlib.import_module(f"{package_name}.{name}")
            plugins[name] = module

    return plugins

# Usage
plugins = load_plugins('myapp.plugins')
for name, plugin in plugins.items():
    plugin.initialize()

Conditional Imports

# Choose implementation based on availability
try:
    from cmath import sqrt as complex_sqrt
    COMPLEX_SUPPORT = True
except ImportError:
    from math import sqrt as complex_sqrt
    COMPLEX_SUPPORT = False

def calculate_sqrt(number):
    if COMPLEX_SUPPORT and isinstance(number, complex):
        return complex_sqrt(number)
    elif number >= 0:
        return complex_sqrt(number)
    else:
        raise ValueError("Cannot take square root of negative real number")

Import Performance

Import Time Optimization

# Slow: Import everything at top
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt

def process_data():
    # Use libraries
    pass

# Fast: Import inside function when needed
def process_data():
    import pandas as pd
    import numpy as np
    # Use libraries
    pass

Lazy Loading

class LazyLoader:
    def __init__(self, module_name):
        self.module_name = module_name
        self._module = None

    def __getattr__(self, name):
        if self._module is None:
            self._module = importlib.import_module(self.module_name)
        return getattr(self._module, name)

# Usage
pd = LazyLoader('pandas')
np = LazyLoader('numpy')

# First access loads the module
df = pd.DataFrame()  # pandas loads here

Import Best Practices

1. Use Absolute Imports

# Good
from mypackage.utils import helper_function
import myproject.models.user as user_model

# Avoid (except in packages)
from .utils import helper_function  # Only in packages

2. Group Imports

# Standard library imports
import os
import sys
from pathlib import Path

# Third-party imports
import requests
import pandas as pd

# Local imports
from mypackage.utils import helper
from .models import User

3. Use Import Aliases Wisely

# Good: Common abbreviations
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt

# Bad: Unclear abbreviations
import pandas as p
import mylongmodulename as m

4. Avoid Wildcard Imports

# Bad
from math import *

# Good
from math import sqrt, pi, sin, cos

5. Handle Optional Dependencies

try:
    import optional_package
    HAS_OPTIONAL = True
except ImportError:
    HAS_OPTIONAL = False

def optional_function():
    if not HAS_OPTIONAL:
        raise ImportError("optional_package is required")
    return optional_package.do_something()

Common Import Patterns

Factory Pattern with Imports

# database/factory.py
def create_database(db_type):
    if db_type == 'sqlite':
        from .sqlite_db import SQLiteDatabase
        return SQLiteDatabase()
    elif db_type == 'postgres':
        from .postgres_db import PostgresDatabase
        return PostgresDatabase()
    else:
        raise ValueError(f"Unsupported database type: {db_type}")

Strategy Pattern with Imports

# payment/strategies.py
def get_payment_strategy(provider):
    if provider == 'stripe':
        from .stripe_payment import StripePayment
        return StripePayment()
    elif provider == 'paypal':
        from .paypal_payment import PayPalPayment
        return PayPalPayment()
    else:
        raise ValueError(f"Unsupported payment provider: {provider}")

Plugin Architecture

# plugins/__init__.py
import importlib
import os

def load_all_plugins():
    """Load all plugins from plugins directory."""
    plugins = {}
    plugin_dir = os.path.dirname(__file__)

    for filename in os.listdir(plugin_dir):
        if filename.startswith('plugin_') and filename.endswith('.py'):
            module_name = filename[:-3]  # Remove .py
            module = importlib.import_module(f'plugins.{module_name}')
            plugins[module_name] = module

    return plugins

Debugging Import Issues

Check Module Path

import mymodule
print(f"Module file: {mymodule.__file__}")
print(f"Module path: {mymodule.__path__ if hasattr(mymodule, '__path__') else 'Not a package'}")

Inspect Search Path

import sys
print("Current Python path:")
for path in sys.path:
    print(f"  {path}")

# Add to path if needed
sys.path.insert(0, '/path/to/my/modules')

Check Loaded Modules

import sys
print("Modules containing 'math':")
for name in sorted(sys.modules.keys()):
    if 'math' in name:
        print(f"  {name}")

Import Trace

import sys

# Enable import tracing
sys.settrace(lambda frame, event, arg: print(f"{event}: {frame.f_code.co_name}") if event == 'call' else None)

import mymodule

Practice Exercises

Exercise 1: Import Performance

Create a script that measures import time for different import methods:

  • import math
  • from math import sqrt
  • from math import *
  • Lazy loading with __getattr__

Exercise 2: Plugin System

Build a plugin system that:

  • Automatically discovers plugins in a plugins/ directory
  • Loads plugins dynamically
  • Calls plugin hooks
  • Handles missing plugins gracefully

Exercise 3: Conditional Dependencies

Create a package that:

  • Works with or without optional dependencies (pandas, numpy, etc.)
  • Provides fallback implementations
  • Warns users about missing features
  • Has a check_dependencies() function

Exercise 4: Circular Import Fix

Take code with circular imports and refactor it to eliminate the circular dependencies using different techniques.

Summary

Python’s import system is powerful but requires understanding:

Import Types:

import module                    # Full module
from module import function      # Specific items
from module import *             # Everything (avoid!)

Import Search:

  1. Built-in modules
  2. Current directory
  3. PYTHONPATH
  4. Site-packages
  5. Standard library

Key Concepts:

  • Modules execute once, then cache in sys.modules
  • Absolute imports: from package.module import function
  • Relative imports: from .module import function (packages only)
  • Avoid circular imports with lazy loading or restructuring

Best Practices:

  • Use absolute imports when possible
  • Group imports by type (standard, third-party, local)
  • Handle optional dependencies gracefully
  • Avoid wildcard imports
  • Use clear, descriptive import aliases

Next: Project Structure - organizing complete Python projects! 🏗️

Previous Python Packages - Directory Organization
Next Python Project Structure - Best Practices