Python: Need For User-Defined Functions

# Python has many built-in functions, but they have limitations

# 1. Built-in functions are generic
# They are designed to work for many use cases, but not specific ones

# Example: Calculating the area of a circle
radius = 5
# Python doesn't have a built-in function for circle area
# We'd have to write:
import math
area = math.pi * radius ** 2
print(area)  # 78.53981633974483

# 2. Built-in functions can't handle custom business logic
# Example: Employee bonus calculation
salary = 50000
performance_rating = "Excellent"
# No built-in function exists for this

# 3. Built-in functions are limited in number
# While Python has ~70 built-in functions, you may need hundreds

# 4. Built-in functions can't be customized
# You can't modify how sum() works without creating your own

# 5. Code duplication without user-defined functions
# Without functions, you'd repeat code many times
# Calculate area of a circle multiple times
r1 = 5
area1 = math.pi * r1 ** 2

r2 = 7
area2 = math.pi * r2 ** 2

r3 = 10
area3 = math.pi * r3 ** 2

# This is repetitive and error-prone!
# With a user-defined function, you'd write this once

# User-defined functions address all the limitations of built-in functions

# Example 1: Custom business logic
def calculate_bonus(salary, performance_rating):
    """Calculate employee bonus based on salary and rating"""
    if performance_rating == "Excellent":
        bonus = salary * 0.20
    elif performance_rating == "Good":
        bonus = salary * 0.10
    elif performance_rating == "Average":
        bonus = salary * 0.05
    else:
        bonus = 0
    return bonus

# Now we can calculate bonuses easily
print(calculate_bonus(50000, "Excellent"))  # 10000.0
print(calculate_bonus(60000, "Good"))       # 6000.0

# Example 2: Domain-specific calculations
def calculate_circle_area(radius):
    """Calculate the area of a circle"""
    import math
    return math.pi * radius ** 2

print(calculate_circle_area(5))   # 78.53981633974483
print(calculate_circle_area(7))   # 153.93804002589985

# Example 3: Data validation
def validate_email(email):
    """Validate an email address format"""
    if "@" in email and "." in email:
        return True
    return False

print(validate_email("user@example.com"))   # True
print(validate_email("invalid-email"))      # False

# Example 4: Data processing
def process_user_data(users):
    """Process user data and extract statistics"""
    total = len(users)
    ages = [user["age"] for user in users]
    avg_age = sum(ages) / total if total > 0 else 0
    return {
        "total": total,
        "average_age": avg_age,
        "youngest": min(ages) if ages else None,
        "oldest": max(ages) if ages else None
    }

users = [
    {"name": "Alice", "age": 25},
    {"name": "Bob", "age": 30},
    {"name": "Charlie", "age": 35}
]
print(process_user_data(users))
# {'total': 3, 'average_age': 30.0, 'youngest': 25, 'oldest': 35}

# Without user-defined functions (Monolithic code)
# A complex program with repeated code

# With user-defined functions (Modular code)
def greet_user(name):
    """Greet a user by name"""
    return f"Hello, {name}! Welcome to our system."

def validate_age(age):
    """Validate that age is reasonable"""
    if not isinstance(age, int) or age < 0 or age > 120:
        return False
    return True

def calculate_discount(price, membership_level):
    """Calculate discount based on membership level"""
    discounts = {
        "gold": 0.20,
        "silver": 0.10,
        "bronze": 0.05,
        "none": 0
    }
    discount = discounts.get(membership_level.lower(), 0)
    return price * (1 - discount)

def process_order(customer_name, age, items, membership_level):
    """Process a customer order"""
    # Validate age
    if not validate_age(age):
        return "Invalid age provided"
    
    # Calculate total
    total = sum(item["price"] * item["quantity"] for item in items)
    
    # Apply discount
    final_total = calculate_discount(total, membership_level)
    
    # Generate greeting
    greeting = greet_user(customer_name)
    
    return {
        "greeting": greeting,
        "total": total,
        "discount": total - final_total,
        "final_total": final_total,
        "membership": membership_level
    }

# Benefits of this approach:
# 1. Each function has a single responsibility
# 2. Functions are reusable across the program
# 3. Code is readable and self-documenting
# 4. Easy to test each function independently
# 5. Easy to modify or extend

# Example 1: E-commerce System
def calculate_shipping_cost(total_weight, shipping_method):
    """Calculate shipping cost based on weight and method"""
    rates = {
        "standard": 5.00,
        "express": 15.00,
        "overnight": 25.00
    }
    base_rate = rates.get(shipping_method, 5.00)
    return base_rate + (total_weight * 0.50)

# Example 2: Data Analysis
def calculate_statistics(data):
    """Calculate basic statistics for a dataset"""
    if not data:
        return None
    
    total = sum(data)
    count = len(data)
    mean = total / count
    sorted_data = sorted(data)
    median = sorted_data[count // 2] if count % 2 == 1 else (sorted_data[count // 2 - 1] + sorted_data[count // 2]) / 2
    min_val = min(data)
    max_val = max(data)
    
    return {
        "mean": mean,
        "median": median,
        "min": min_val,
        "max": max_val,
        "count": count,
        "sum": total
    }

# Example 3: File Processing
def read_csv_safely(filename):
    """Safely read CSV file with error handling"""
    import csv
    try:
        with open(filename, 'r') as file:
            reader = csv.reader(file)
            return list(reader)
    except FileNotFoundError:
        print(f"File '{filename}' not found")
        return None
    except Exception as e:
        print(f"Error reading file: {e}")
        return None

# Example 4: API Integration
def format_api_response(data, status_code):
    """Format API response consistently"""
    return {
        "status": "success" if 200 <= status_code < 300 else "error",
        "status_code": status_code,
        "data": data,
        "timestamp": "2026-07-26T12:00:00Z"
    }

# Example 5: Logging
def log_activity(user_id, action, details):
    """Log user activity in the system"""
    import datetime
    timestamp = datetime.datetime.now()
    log_entry = f"{timestamp} | User: {user_id} | Action: {action} | Details: {details}"
    with open("activity.log", "a") as log_file:
        log_file.write(log_entry + "\n")
    return log_entry

# When should you create a user-defined function?

# 1. When you have code that repeats
# Before - Repetitive code
print("Processing user 1")
# 10 lines of processing code...

print("Processing user 2")
# Same 10 lines repeated...

print("Processing user 3")
# Same 10 lines repeated again...

# After - Create a function
def process_user(user):
    """Process a user with the same logic"""
    # 10 lines of processing code
    pass

process_user(user1)
process_user(user2)
process_user(user3)

# 2. When code is complex or long
# A 100-line function can be broken into smaller functions
def process_order(order):
    """Process an order (100+ lines)"""
    validate_order(order)
    calculate_total(order)
    apply_discount(order)
    process_payment(order)
    send_confirmation(order)
    return order

# 3. When code needs to be reused in different parts
# Defining once, using multiple times
def format_currency(amount):
    return f"${amount:,.2f}"

# 4. When code is hard to understand
# Give it a meaningful name
def calculate_average_employee_salary(department):
    """Calculate average salary for employees in a department"""
    # Complex calculation...
    pass

# 5. When you need to test code independently
# Functions are easier to unit test
def add(a, b):
    return a + b

# In tests
def test_add():
    assert add(2, 3) == 5
    assert add(-1, 1) == 0

# Best Practices for User-Defined Functions

# 1. Give descriptive names
# ✅ Good - Clear and descriptive
def calculate_average_score(scores):
    pass

def get_user_by_email(email):
    pass

# ❌ Bad - Vague and unclear
def calc(scores):
    pass

def get(email):
    pass

# 2. Include docstrings
def calculate_area(length, width):
    """Calculate the area of a rectangle.
    
    Args:
        length (float): The length of the rectangle
        width (float): The width of the rectangle
    
    Returns:
        float: The area of the rectangle
        
    Example:
        >>> calculate_area(5, 3)
        15
    """
    return length * width

# 3. Follow the Single Responsibility Principle
# ✅ Good - One function, one job
def calculate_total(items):
    return sum(item["price"] * item["quantity"] for item in items)

def apply_discount(total, discount_code):
    return total * (1 - get_discount_rate(discount_code))

def get_discount_rate(code):
    rates = {"SAVE10": 0.10, "SAVE20": 0.20}
    return rates.get(code, 0)

# ❌ Bad - One function doing too many things
def process_order(items, discount_code, customer_id):
    total = sum(item["price"] * item["quantity"] for item in items)
    discount = 0
    if discount_code == "SAVE10":
        discount = 0.10
    elif discount_code == "SAVE20":
        discount = 0.20
    total = total * (1 - discount)
    # ... and more processing
    return total

# 4. Use type hints
def multiply(a: float, b: float) -> float:
    """Multiply two numbers"""
    return a * b

# 5. Keep functions small
def process_data(data):
    """Process data through a pipeline"""
    cleaned = clean_data(data)
    transformed = transform_data(cleaned)
    validated = validate_data(transformed)
    return analyzed_data(validated)

# 6. Use default parameters for optional values
def greet_user(name: str, greeting: str = "Hello") -> str:
    """Greet a user with a customizable greeting"""
    return f"{greeting}, {name}!"