Python Functions: Default Parameters

Common Patterns and Best Practices

Based on the examples we've seen, let's explore some common patterns and best practices for working with default parameters:

Choosing Good Default Values

# File: good_defaults.py
# Location: /python_projects/functions_tutorial/

# GOOD: Sensible, safe defaults that work for most cases
def connect_to_database(
    host="localhost",
    port=5432,
    username="app_user",
    password=None,
    database="main",
    ssl=True,
    timeout=30
):
    """
    Connect to a database with sensible defaults.
    
    Args:
        host (str): Database host
        port (int): Database port
        username (str): Database username
        password (str, optional): Database password
        database (str): Database name
        ssl (bool): Whether to use SSL
        timeout (int): Connection timeout in seconds
    """
    # Implementation details...
    connection_string = f"{username}@{host}:{port}/{database}"
    print(f"Connecting to: {connection_string}")
    print(f"SSL: {'Enabled' if ssl else 'Disabled'}")
    print(f"Timeout: {timeout} seconds")
    
    # Note: password is intentionally not printed for security
    
    if password is None:
        print("Warning: No password provided, using environment variable or config file")

# POOR: Defaults that might cause problems or be inappropriate for most cases
def connect_to_database_poor(
    host="production-db.example.com",  # Bad default - should not default to production
    port=5432,
    username="admin",  # Bad default - should not use admin by default
    password="default_password",  # Bad default - should never hardcode passwords
    database="main",
    ssl=False,  # Bad default - connections should be secure by default
    timeout=0  # Bad default - no timeout could lead to hanging connections
):
    """An example of poor default parameter choices."""
    # Implementation details...
    pass

Good default values should be:

• Safe: They should not cause security risks or data loss.
• Conservative: They should work for the majority of use cases.
• Explicit: They should make it clear what the function will do.
• Performant: They should not unnecessarily degrade performance.

Default Parameter Documentation

# File: documented_defaults.py
# Location: /python_projects/functions_tutorial/

def resize_image(
    image,
    width=None,
    height=None,
    keep_aspect_ratio=True,
    quality=85,
    format=None
):
    """
    Resize an image with various options.
    
    Args:
        image: The image to resize
        width (int, optional): New width in pixels. If None, calculated from height
            and aspect ratio if possible.
        height (int, optional): New height in pixels. If None, calculated from width
            and aspect ratio if possible.
        keep_aspect_ratio (bool): Whether to maintain the original aspect ratio.
            If True, the image will be resized to fit within the width/height bounds
            while maintaining its aspect ratio.
        quality (int): JPEG quality (1-100) if saving as JPEG. Higher values mean
            better quality but larger file size. Default is 85, which provides a good
            balance between quality and size.
        format (str, optional): Output format (e.g., 'JPEG', 'PNG'). If None, the
            original format is maintained.
    
    Returns:
        The resized image object
    
    Raises:
        ValueError: If both width and height are None, or if quality is outside 1-100.
    
    Examples:
        # Resize to a specific width, maintaining aspect ratio
        resize_image(img, width=800)
        
        # Resize to fit within 800x600, maintaining aspect ratio
        resize_image(img, width=800, height=600)
        
        # Resize to exactly 800x600, ignoring aspect ratio
        resize_image(img, width=800, height=600, keep_aspect_ratio=False)
    """
    # We'll just simulate the functionality for this example
    
    # Validate inputs
    if width is None and height is None:
        raise ValueError("At least one of width or height must be specified")
    
    if quality < 1 or quality > 100:
        raise ValueError("Quality must be between 1 and 100")
    
    # Simulate image dimensions (in a real function, we'd get these from the image)
    original_width, original_height = 1920, 1080
    aspect_ratio = original_width / original_height
    
    # Calculate target dimensions
    target_width = width
    target_height = height
    
    if keep_aspect_ratio:
        if width is None:
            target_width = int(height * aspect_ratio)
        elif height is None:
            target_height = int(width / aspect_ratio)
        else:
            # Fit within the specified bounds
            proposed_height = int(width / aspect_ratio)
            if proposed_height <= height:
                target_height = proposed_height
            else:
                target_width = int(height * aspect_ratio)
    
    # Use defaults for any remaining None values
    if target_width is None:
        target_width = original_width
    if target_height is None:
        target_height = original_height
    
    output_format = format if format else "original format"
    
    # Print what we'd be doing (in a real function, we'd actually resize the image)
    print(f"Resizing image from {original_width}x{original_height} to {target_width}x{target_height}")
    print(f"Quality: {quality}, Format: {output_format}")
    
    # Return a placeholder result (in a real function, this would be the resized image)
    return f"Resized image ({target_width}x{target_height})"

# Example usage
try:
    # Resize to a specific width
    result1 = resize_image("vacation.jpg", width=800)
    print(f"Result 1: {result1}")
    
    # Resize to fit within dimensions
    result2 = resize_image("profile.png", width=400, height=300)
    print(f"Result 2: {result2}")
    
    # Resize with custom format and quality
    result3 = resize_image("photo.jpg", width=1200, quality=95, format="PNG")
    print(f"Result 3: {result3}")
    
    # This would raise an error
    # resize_image("error.jpg")
    
except ValueError as e:
    print(f"Error: {e}")

Well-documented default parameters help users understand:

• What each parameter does
• Why certain defaults were chosen
• How parameters interact with each other
• Common usage patterns and examples

Good documentation makes functions more accessible to new users while still providing all the information that advanced users need.

Building Functions with Increasing Complexity

Default parameters allow you to design functions that are simple to use for basic cases but can be extended for more complex scenarios:

# File: progressive_complexity.py
# Location: /python_projects/functions_tutorial/

def send_email(
    to,
    subject,
    body,
    from_email=None,  # Level 1: Basic customization
    cc=None,
    bcc=None,
    reply_to=None,
    attachments=None,  # Level 2: Additional features
    html=False,
    priority=3,
    tracking=False,  # Level 3: Advanced features
    template_id=None,
    template_vars=None,
    scheduled_time=None,
    custom_headers=None  # Level 4: Expert features
):
    """
    Send an email with various configuration options.
    
    This function demonstrates progressive complexity - users can start with
    just the required parameters and gradually add more as needed.
    """
    # Set default for from_email if not provided
    if from_email is None:
        from_email = "noreply@example.com"
    
    # Set defaults for mutable parameters
    if cc is None:
        cc = []
    if bcc is None:
        bcc = []
    if attachments is None:
        attachments = []
    if template_vars is None:
        template_vars = {}
    if custom_headers is None:
        custom_headers = {}
    
    # Build the email details (in a real function, we'd actually send the email)
    email_details = {
        "to": to,
        "from": from_email,
        "subject": subject,
        "body": body,
        "cc": cc,
        "bcc": bcc
    }
    
    # Include additional parameters if they're set
    if reply_to:
        email_details["reply_to"] = reply_to
    
    if attachments:
        email_details["attachments"] = attachments
    
    if html:
        email_details["format"] = "html"
    else:
        email_details["format"] = "text"
    
    if priority != 3:
        email_details["priority"] = priority
    
    if tracking:
        email_details["tracking"] = True
    
    if template_id:
        email_details["template_id"] = template_id
        email_details["template_vars"] = template_vars
    
    if scheduled_time:
        email_details["scheduled_time"] = scheduled_time
    
    if custom_headers:
        email_details["headers"] = custom_headers
    
    # Print what we'd be doing (in a real function, we'd actually send the email)
    print("Sending email with the following details:")
    for key, value in email_details.items():
        print(f"  {key}: {value}")
    
    return "Email sent successfully"

# Level 1: Simple email (just the required parameters)
send_email(
    "user@example.com",
    "Hello",
    "This is a simple email."
)

print("\n---\n")

# Level 2: Email with CC and attachments
send_email(
    "user@example.com",
    "Project Update",
    "Please see the attached report.",
    from_email="project@example.com",
    cc=["manager@example.com"],
    attachments=["report.pdf"]
)

print("\n---\n")

# Level 3: HTML email with tracking
send_email(
    "customer@example.com",
    "Your Order Confirmation",
    "<h1>Thank you for your order!</h1><p>Your order #12345 has been confirmed.</p>",
    from_email="orders@example.com",
    html=True,
    tracking=True
)

print("\n---\n")

# Level 4: Advanced email with templates and scheduling
send_email(
    "subscriber@example.com",
    "Weekly Newsletter",
    "This will be replaced by the template content.",
    template_id="newsletter-template",
    template_vars={"user_name": "John", "content_id": "weekly-123"},
    scheduled_time="2023-12-01T10:00:00Z",
    custom_headers={"X-Campaign-ID": "winter-2023"}
)

This pattern allows users to start with the simplest version of the function and gradually add more complexity as they need it. It's like having a basic version of a product with optional add-ons that users can select as they become more experienced.