Python Modules and Packages Tutorial | Code Organization

Python Modules and Packages

Modules and packages help organize Python code into reusable components. Learn how to create, import, and manage Python modules and packages.

What are Modules and Packages?

Modules are Python files containing code (functions, classes, variables). Packages are directories containing multiple modules and an __init__.py file. They enable code organization and reusability.

"Modules and packages make Python code modular, reusable, and maintainable."

Creating and Using Modules

Any Python file can be used as a module:

# mymodule.py
def greet(name):
    return f"Hello, {name}!"

def add(a, b):
    return a + b

PI = 3.14159

class Calculator:
    def multiply(self, x, y):
        return x * y

# main.py
import mymodule

print(mymodule.greet("Alice"))  # Hello, Alice!
print(mymodule.add(5, 3))       # 8
print(mymodule.PI)              # 3.14159

calc = mymodule.Calculator()
print(calc.multiply(4, 5))      # 20

Import Statements

Different ways to import modules:

# Import entire module
import math
print(math.sqrt(16))  # 4.0

# Import specific items
from math import sqrt, pi
print(sqrt(25))  # 5.0
print(pi)        # 3.141592653589793

# Import with alias
import math as m
print(m.cos(0))  # 1.0

# Import specific items with aliases
from math import factorial as fact
print(fact(5))  # 120

# Import all (not recommended)
from math import *
print(sin(0))  # 0.0

The Module Search Path

Python searches for modules in specific locations:

import sys

# Current directory
print(sys.path[0])

# Python installation directory
# Site-packages directory
# PYTHONPATH environment variable

# Add custom path
sys.path.append('/path/to/my/modules')

# Check module location
import math
print(math.__file__)

Creating Packages

Packages are directories with __init__.py:

# mypackage/
#   __init__.py
#   module1.py
#   module2.py
#   subpackage/
#       __init__.py
#       submodule.py

# __init__.py (can be empty or contain initialization code)
print("mypackage initialized")

# module1.py
def function1():
    return "Function 1"

# module2.py
def function2():
    return "Function 2"

# subpackage/__init__.py
print("subpackage initialized")

# subpackage/submodule.py
def sub_function():
    return "Sub function"

# Using the package
import mypackage.module1
print(mypackage.module1.function1())

from mypackage import module2
print(module2.function2())

from mypackage.subpackage import submodule
print(submodule.sub_function())

Relative Imports

Use relative imports within packages:

# In mypackage/subpackage/submodule.py
from ..module1 import function1  # Parent directory
from . import something         # Current directory
from .. import module2          # Parent package

# Absolute imports (preferred)
from mypackage.module1 import function1
from mypackage.subpackage import something

Module Execution

Modules can check if they're run directly:

# mymodule.py
def main():
    print("Running as main module")

if __name__ == "__main__":
    main()

# When imported, __name__ is "mymodule"
# When run directly, __name__ is "__main__"

Built-in Modules

Python comes with many built-in modules:

# os module - Operating system interface
import os
print(os.getcwd())          # Current working directory
print(os.listdir('.'))      # List directory contents

# sys module - System-specific parameters
import sys
print(sys.version)          # Python version
print(sys.platform)         # Platform

# datetime module - Date and time
from datetime import datetime
now = datetime.now()
print(now.strftime("%Y-%m-%d %H:%M:%S"))

# json module - JSON encoding/decoding
import json
data = {"name": "Alice", "age": 25}
json_str = json.dumps(data)
print(json_str)

parsed = json.loads(json_str)
print(parsed["name"])

# random module - Random number generation
import random
print(random.randint(1, 10))    # Random integer
print(random.choice(['a', 'b', 'c']))  # Random choice

Installing Third-Party Packages

Use pip to install packages:

# Install package
pip install requests

# Install specific version
pip install requests==2.25.1

# Install from requirements file
pip install -r requirements.txt

# List installed packages
pip list

# Show package information
pip show requests

# Using installed package
import requests

response = requests.get('https://api.github.com/user', auth=('user', 'pass'))
print(response.status_code)
print(response.json())

Virtual Environments

Isolate project dependencies:

# Create virtual environment
python -m venv myenv

# Activate (Windows)
myenv\Scripts\activate

# Activate (Unix/Mac)
source myenv/bin/activate

# Install packages in virtual environment
pip install requests flask

# Deactivate
deactivate

# Create requirements file
pip freeze > requirements.txt

Package Management Best Practices

Use virtual environments: Isolate project dependencies
Create requirements.txt: Document dependencies
Use relative imports: Within packages
Organize by functionality: Group related modules
Use __init__.py: Make directories packages
Avoid circular imports: Plan import structure carefully
Use descriptive names: For modules and packages
Document with docstrings: Explain module purpose

Common Module Patterns

# Configuration module
# config.py
DATABASE_URL = "sqlite:///app.db"
DEBUG = True
SECRET_KEY = "your-secret-key"

# Main application
import config
print(config.DATABASE_URL)

# Utility functions module
# utils.py
def format_currency(amount):
    return f"${amount:.2f}"

def calculate_tax(amount, rate=0.08):
    return amount * rate

# Plugin system
# plugins/__init__.py
import importlib
import os

def load_plugins():
    plugins = []
    plugin_dir = os.path.dirname(__file__)
    
    for filename in os.listdir(plugin_dir):
        if filename.endswith('.py') and filename != '__init__.py':
            module_name = filename[:-3]
            module = importlib.import_module(f'plugins.{module_name}')
            plugins.append(module)
    
    return plugins

Modules and packages are essential for organizing Python code. They enable code reuse, improve maintainability, and help manage dependencies effectively.