Python Modules & Packages

1. Modules

Purpose: A module is simply a Python file (with .py extension) containing functions, classes, and variables that you can reuse.

Creating Your Own Module:

python

# Save this as 'calculator.py'
"""A simple calculator module - calculator.py"""

def add(a, b):
    """Return the sum of two numbers."""
    return a + b

def subtract(a, b):
    """Return the difference of two numbers."""
    return a - b

def multiply(a, b):
    """Return the product of two numbers."""
    return a * b

def divide(a, b):
    """Return the quotient of two numbers."""
    if b == 0:
        return "Error: Division by zero"
    return a / b

# Module-level variable
PI = 3.14159

# This code runs only when the module is executed directly
if __name__ == "__main__":
    print("Calculator module test:")
    print(f"5 + 3 = {add(5, 3)}")
    print(f"PI = {PI}")

2. Importing Modules

Different Ways to Import:

python

# Method 1: Import entire module
import calculator

result = calculator.add(10, 5)
print(f"10 + 5 = {result}")
print(f"PI value: {calculator.PI}")

# Method 2: Import specific functions/classes
from calculator import add, multiply

result = add(15, 3)  # No need for module prefix
print(f"15 + 3 = {result}")

# Method 3: Import with alias
import calculator as calc
from calculator import divide as div

result = calc.multiply(4, 7)
division_result = div(20, 4)

# Method 4: Import everything (generally not recommended)
from calculator import *

result = subtract(10, 3)

The __name__ Variable:

python

# Understanding __name__
if __name__ == "__main__":
    # This code runs only when the file is executed directly
    print("This script is running directly")
else:
    # This code runs when the file is imported as a module
    print(f"This module was imported. Name: {__name__}")

3. Packages

Purpose: A package is a collection of modules organized in directories. It must contain a special __init__.py file.

Package Structure:

text

my_package/
│
├── __init__.py          # Package initialization
├── math_utils.py        # Module 1
├── string_utils.py      # Module 2
└── data/
    ├── __init__.py      # Sub-package initialization
    └── file_handlers.py # Sub-module

Creating a Package:

python

# my_package/__init__.py
"""My custom utility package."""

__version__ = "1.0.0"
__author__ = "Your Name"

# Import key functions to make them easily accessible
from .math_utils import add, multiply
from .string_utils import reverse_string

print("My package initialized!")

# my_package/math_utils.py
"""Math utilities module."""

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

def multiply(a, b):
    return a * b

def factorial(n):
    if n == 0:
        return 1
    return n * factorial(n - 1)

# my_package/string_utils.py
"""String utilities module."""

def reverse_string(text):
    return text[::-1]

def count_vowels(text):
    vowels = "aeiouAEIOU"
    return sum(1 for char in text if char in vowels)

Using Packages:

python

# Import from package
import my_package.math_utils as math_utils
from my_package.string_utils import reverse_string, count_vowels

result1 = math_utils.factorial(5)
result2 = reverse_string("Hello")
result3 = count_vowels("Python Programming")

print(f"5! = {result1}")           # 5! = 120
print(f"Reversed: {result2}")      # Reversed: olleH
print(f"Vowels: {result3}")        # Vowels: 4

# Using imports from __init__.py
from my_package import add, multiply
print(f"Add: {add(10, 5)}")        # Add: 15

4. Python Standard Library Overview

Python comes with a rich set of built-in modules - "batteries included"!

Essential Standard Library Modules:

1. math - Mathematical Functions

python

import math

print(f"Square root: {math.sqrt(25)}")        # 5.0
print(f"Pi: {math.pi}")                       # 3.141592653589793
print(f"Cosine: {math.cos(math.pi)}")         # -1.0
print(f"Factorial: {math.factorial(5)}")      # 120
print(f"Logarithm: {math.log(100, 10)}")      # 2.0

2. random - Random Number Generation

python

x

import math

print(f"Square root: {math.sqrt(25)}")        # 5.0
print(f"Pi: {math.pi}")                       # 3.141592653589793
print(f"Cosine: {math.cos(math.pi)}")         # -1.0
print(f"Factorial: {math.factorial(5)}")      # 120
print(f"Logarithm: {math.log(100, 10)}")      # 2.0

3. datetime - Date and Time Operations

python

from datetime import datetime, date, timedelta

# Current time
now = datetime.now()
print(f"Current: {now}")
print(f"Formatted: {now.strftime('%Y-%m-%d %H:%M:%S')}")

# Specific date
birthday = date(1990, 5, 15)
print(f"Birthday: {birthday}")

# Date arithmetic
tomorrow = date.today() + timedelta(days=1)
print(f"Tomorrow: {tomorrow}")

# Parsing dates
date_string = "2024-12-25"
christmas = datetime.strptime(date_string, "%Y-%m-%d")
print(f"Christmas: {christmas}")

4. os - Operating System Interface

python

import os

# File and directory operations
print(f"Current directory: {os.getcwd()}")
print(f"Files in directory: {os.listdir('.')}")

# Environment variables
print(f"Home directory: {os.getenv('HOME')}")

# Path operations
file_path = os.path.join("folder", "subfolder", "file.txt")
print(f"Full path: {file_path}")  # folder/subfolder/file.txt

# Check if file/directory exists
print(f"Exists: {os.path.exists('myfile.txt')}")

5. sys - System-specific Parameters

python

import sys

# Command line arguments
print(f"Script name: {sys.argv[0]}")
print(f"Arguments: {sys.argv[1:]}")

# Python path
print(f"Python path: {sys.path}")

# System information
print(f"Python version: {sys.version}")
print(f"Platform: {sys.platform}")

# Exit the program
# sys.exit(0)  # Exit with success status

6. json - JSON Data Handling

python

import json

# Python object to JSON string
data = {
    "name": "Alice",
    "age": 30,
    "hobbies": ["reading", "hiking"],
    "is_student": False
}

json_string = json.dumps(data, indent=2)
print("JSON string:")
print(json_string)

# JSON string to Python object
parsed_data = json.loads(json_string)
print(f"Name: {parsed_data['name']}")

# Working with files
with open("data.json", "w") as file:
    json.dump(data, file, indent=2)

with open("data.json", "r") as file:
    loaded_data = json.load(file)

5. Practical Examples

Example 1: Custom Utility Package

python

# File: text_analyzer/__init__.py
"""Text analysis utilities."""

from .analyzer import count_words, count_characters, most_common_words

# File: text_analyzer/analyzer.py
"""Text analysis functions."""

from collections import Counter
import string

def count_words(text):
    """Count words in text."""
    words = text.split()
    return len(words)

def count_characters(text, include_spaces=True):
    """Count characters in text."""
    if not include_spaces:
        text = text.replace(" ", "")
    return len(text)

def most_common_words(text, n=5):
    """Find n most common words."""
    # Remove punctuation and convert to lowercase
    text = text.translate(str.maketrans('', '', string.punctuation)).lower()
    words = text.split()
    return Counter(words).most_common(n)

# File: main.py
from text_analyzer import count_words, most_common_words

sample_text = "Hello world! This is a test. Hello again world."
print(f"Word count: {count_words(sample_text)}")
print(f"Common words: {most_common_words(sample_text, 3)}")

Example 2: Configuration Manager Using Multiple Modules

python

# File: config/__init__.py
"""Configuration management package."""

from .file_loader import load_config, save_config
from .validator import validate_config

# File: config/file_loader.py
"""Configuration file handling."""

import json
import yaml  # You might need to pip install PyYAML

def load_config(filename):
    """Load configuration from JSON or YAML file."""
    with open(filename, 'r') as file:
        if filename.endswith('.json'):
            return json.load(file)
        elif filename.endswith('.yaml') or filename.endswith('.yml'):
            return yaml.safe_load(file)
        else:
            raise ValueError("Unsupported file format")

def save_config(config, filename):
    """Save configuration to file."""
    with open(filename, 'w') as file:
        if filename.endswith('.json'):
            json.dump(config, file, indent=2)
        elif filename.endswith('.yaml') or filename.endswith('.yml'):
            yaml.dump(config, file, default_flow_style=False)

# File: config/validator.py
"""Configuration validation."""

def validate_config(config):
    """Validate configuration dictionary."""
    required_fields = ['database', 'host', 'port']
    
    for field in required_fields:
        if field not in config:
            raise ValueError(f"Missing required field: {field}")
    
    if not isinstance(config['port'], int):
        raise ValueError("Port must be an integer")
    
    return True

# File: main_app.py
from config import load_config, save_config, validate_config

# Load and validate configuration
try:
    config = load_config("app_config.json")
    validate_config(config)
    print("Configuration loaded successfully!")
    
    # Use the configuration
    print(f"Database: {config.get('database')}")
    print(f"Host: {config.get('host')}")
    
except Exception as e:
    print(f"Configuration error: {e}")

Example 3: Using Multiple Standard Library Modules

python

import os
import sys
import json
from datetime import datetime
import random

def create_project_structure(project_name):
    """Create a standard Python project structure."""
    
    # Create directories
    directories = [
        project_name,
        f"{project_name}/src",
        f"{project_name}/tests",
        f"{project_name}/docs",
        f"{project_name}/data"
    ]
    
    for directory in directories:
        os.makedirs(directory, exist_ok=True)
        print(f"Created directory: {directory}")
    
    # Create basic files
    files = {
        f"{project_name}/README.md": f"# {project_name}\n\nProject description",
        f"{project_name}/requirements.txt": "# Project dependencies",
        f"{project_name}/src/__init__.py": "# Package initialization",
        f"{project_name}/src/main.py": "# Main application file",
        f"{project_name}/tests/__init__.py": "# Tests package",
        f"{project_name}/tests/test_basic.py": "# Test cases"
    }
    
    for filename, content in files.items():
        with open(filename, 'w') as file:
            file.write(content)
        print(f"Created file: {filename}")
    
    # Create project metadata
    metadata = {
        "project_name": project_name,
        "created": datetime.now().isoformat(),
        "version": "1.0.0",
        "python_version": sys.version.split()[0]
    }
    
    with open(f"{project_name}/project_info.json", 'w') as file:
        json.dump(metadata, file, indent=2)
    
    print(f"Project '{project_name}' created successfully!")
    return metadata

# Usage
if __name__ == "__main__":
    project_name = "my_awesome_project"
    info = create_project_structure(project_name)
    print(f"Project info: {json.dumps(info, indent=2)}")

6. Best Practices

1. Organizing Imports:

python

# Standard library imports
import os
import sys
from datetime import datetime, timedelta

# Third-party imports
import requests
import numpy as np

# Local application imports
from my_package import utils
from .helpers import validate_data

2. Avoiding Circular Imports:

python

# Bad: module_a.py imports module_b.py, and module_b.py imports module_a.py

# Good: Move common imports to a third module
# common.py
def shared_function():
    pass

# module_a.py
from common import shared_function

# module_b.py  
from common import shared_function

3. Using if __name__ == "__main__":

python

x

# Bad: module_a.py imports module_b.py, and module_b.py imports module_a.py

# Good: Move common imports to a third module
# common.py
def shared_function():
    pass

# module_a.py
from common import shared_function

# module_b.py  
from common import shared_function

Key Takeaways:

1. Modules are single Python files, packages are directories with __init__.py

2. Use import to access functionality from other modules

3. The __name__ variable helps determine if a module is run directly or imported

4. Python Standard Library has hundreds of useful modules for common tasks

5. Organize large projects into logical packages and modules

6. Follow import conventions for clean, readable code

Use virtual environments (venv) to manage dependencies for your projects, and create requirements.txt files to document them!

Mastering modules and packages is essential for building maintainable, scalable Python applications and leveraging the rich Python ecosystem.