Python: Elements of User-Defined Function

# The def keyword is used to define a function
# Syntax: def function_name(parameters):
# The colon (:) indicates the start of the function body

# Example 1: Simple function definition
def greet():
    """Print a greeting"""
    print("Hello, World!")

# Example 2: Function with parameters
def greet_person(name):
    """Greet a specific person"""
    print(f"Hello, {name}!")

# Example 3: Function with return value
def add(a, b):
    """Add two numbers and return the result"""
    return a + b

# Key points about def:
# 1. Must be followed by a space and the function name
# 2. Parentheses () are required even if no parameters
# 3. A colon : ends the first line
# 4. The body must be indented (4 spaces recommended)

# Function names follow the same rules as variable names

# Rules for valid function names:
# 1. Must start with a letter (a-z, A-Z) or underscore (_)
# 2. Can contain letters, numbers, and underscores
# 3. Cannot start with a number
# 4. Cannot be a Python keyword (if, for, while, etc.)

# ✅ Valid function names
def calculate_area():
    pass

def process_data():
    pass

def get_user_info():
    pass

def _private_helper():
    pass

# ❌ Invalid function names
# def 123_invalid():    # Cannot start with number
# def if():             # Cannot use keyword
# def my-function():    # Cannot use hyphen

# Best practices for naming:
# 1. Use descriptive names (what does the function do?)
# 2. Use snake_case (lowercase with underscores)
# 3. Start with a verb (get, set, calculate, process)
# 4. Be consistent in your naming

# Good examples:
def calculate_total_price(items):
    """Calculate the total price of items"""
    pass

def find_maximum(numbers):
    """Find the maximum value in a list"""
    pass

def is_valid_email(email):
    """Check if an email is valid"""
    pass

# Bad examples:
def calc(items):  # Too vague
    pass

def func1():      # Meaningless name
    pass

# Parameters are placeholders for values passed to the function

# 1. Function with no parameters
def say_hello():
    print("Hello!")

# 2. Function with one parameter
def greet(name):
    print(f"Hello, {name}!")

# 3. Function with multiple parameters
def calculate_total(price, quantity, tax_rate=0.10):
    """Calculate total cost with tax"""
    subtotal = price * quantity
    tax = subtotal * tax_rate
    return subtotal + tax

# 4. Function with default parameters
def greet_user(name="Guest", greeting="Hello"):
    """Greet a user with customizable greeting"""
    return f"{greeting}, {name}!"

# 5. Function with variable arguments (*args)
def sum_all(*args):
    """Sum any number of arguments"""
    return sum(args)

# 6. Function with keyword arguments (**kwargs)
def print_user_info(**kwargs):
    """Print user information"""
    for key, value in kwargs.items():
        print(f"{key}: {value}")

# 7. Function with positional-only arguments (Python 3.8+)
def greet_person(name, /, greeting="Hello"):
    """name must be passed positionally"""
    return f"{greeting}, {name}!"

# 8. Function with keyword-only arguments (Python 3.8+)
def greet_person(*, name, greeting="Hello"):
    """name and greeting must be passed as keywords"""
    return f"{greeting}, {name}!"

# Docstrings are strings that document what a function does
# They are written as the first line of the function body

# 1. Simple docstring
def greet(name):
    """Greet a person by name."""
    return f"Hello, {name}!"

# 2. Multi-line docstring
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. Docstring with type hints
def multiply(a: int, b: int) -> int:
    """
    Multiply two integers.
    
    This function takes two integers and returns their product.
    
    Parameters:
    -----------
    a : int
        The first number
    b : int
        The second number
        
    Returns:
    --------
    int
        The product of a and b
        
    Examples:
    ---------
    >>> multiply(2, 3)
    6
    >>> multiply(-1, 5)
    -5
    """
    return a * b

# 4. Accessing docstrings
print(greet.__doc__)  # Prints the docstring
help(greet)           # Shows help information

# 5. Google-style docstring
def process_data(data, clean=True):
    """
    Process data with optional cleaning.
    
    Args:
        data (list): List of data items to process
        clean (bool): Whether to clean data before processing
        
    Returns:
        dict: Processed results
    """
    pass

# 6. Numpy-style docstring
def calculate_statistics(data):
    """
    Calculate basic statistics for a dataset.
    
    Parameters
    ----------
    data : array-like
        Input data for statistical analysis
    
    Returns
    -------
    dict
        Dictionary containing mean, median, and standard deviation
    
    Raises
    ------
    ValueError
        If data is empty
    """
    pass

# The function body contains the code that does the work
# It must be indented (4 spaces recommended)

# 1. Simple function body
def greet(name):
    """Greet a person"""
    message = f"Hello, {name}!"  # Body starts here
    return message

# 2. Multi-line function body
def calculate_average(scores):
    """Calculate the average of scores"""
    # Body with multiple statements
    if not scores:
        return 0
    
    total = 0
    count = 0
    
    for score in scores:
        total += score
        count += 1
    
    average = total / count
    return average

# 3. Function body with conditionals
def validate_age(age):
    """Validate that age is reasonable"""
    if age < 0:
        return "Invalid: Age cannot be negative"
    elif age < 18:
        return "Invalid: Must be 18 or older"
    elif age > 120:
        return "Invalid: Age seems too old"
    else:
        return "Valid"

# 4. Function body with loops
def find_primes(limit):
    """Find all prime numbers up to a limit"""
    primes = []
    for num in range(2, limit + 1):
        is_prime = True
        for i in range(2, int(num ** 0.5) + 1):
            if num % i == 0:
                is_prime = False
                break
        if is_prime:
            primes.append(num)
    return primes

# 5. Function body with exception handling
def safe_divide(a, b):
    """Divide two numbers safely"""
    try:
        result = a / b
        return result
    except ZeroDivisionError:
        return "Error: Division by zero"
    except TypeError:
        return "Error: Invalid input types"

# 6. Empty function body
def placeholder():
    """Placeholder function - to be implemented later"""
    pass  # pass is used for empty bodies

# The return statement sends a value back to the caller

# 1. Function with a single return value
def add(a, b):
    """Add two numbers"""
    return a + b

result = add(5, 3)
print(result)  # 8

# 2. Function with multiple return values
def get_user_info():
    """Return multiple values as a tuple"""
    return "Alice", 25, "Engineer"

name, age, job = get_user_info()
print(name, age, job)  # Alice 25 Engineer

# 3. Function with early return
def validate_age(age):
    """Validate age with early returns"""
    if age < 0:
        return "Invalid: Negative age"
    if age < 18:
        return "Invalid: Too young"
    if age > 120:
        return "Invalid: Too old"
    return "Valid"

print(validate_age(25))   # Valid
print(validate_age(-5))   # Invalid: Negative age

# 4. Function with no return (returns None)
def print_message(msg):
    """Print a message - no return"""
    print(msg)
    # No return statement → returns None

result = print_message("Hello")
print(result)  # None

# 5. Function with conditional return
def get_discount(price, member_level):
    """Calculate discount based on membership"""
    if member_level == "gold":
        return price * 0.20
    elif member_level == "silver":
        return price * 0.10
    elif member_level == "bronze":
        return price * 0.05
    return 0  # No discount

# 6. Function returning different types
def process_data(data, operation):
    """Process data with different operations"""
    if operation == "sum":
        return sum(data)
    elif operation == "avg":
        return sum(data) / len(data) if data else 0
    elif operation == "max":
        return max(data) if data else None
    elif operation == "min":
        return min(data) if data else None
    else:
        return "Invalid operation"

# 7. Function returning a function (closure)
def create_multiplier(factor):
    """Create a function that multiplies by a factor"""
    def multiplier(x):
        return x * factor
    return multiplier

double = create_multiplier(2)
print(double(5))  # 10