Unit 8: Functions in Python

def function_name(parameter_1, parameter_2, ...):
    """Optional: Documentation string (docstring) describing what the function does."""
    # Statement 1 (indented)
    # Statement 2 (indented)
    return output_value  # Optional

# 1. Defining a function with docstring
def display_welcome_banner():
    """Prints the official academy portal header message."""
    print("============================================")
    print("🎓 DEVASCENT ACADEMY: STUDENT PORTAL 2026")
    print("⚡ Empowering 1st Year Engineers with Python")
    print("============================================")

# 2. Calling (invoking) the function
print("Program begins...")
display_welcome_banner()  # First call

print("\nDoing some other tasks...\n")

display_welcome_banner()  # Second call (reused effortlessly!)

# 'student_name', 'roll_number', and 'branch' are FORMAL PARAMETERS
def issue_library_card(student_name, roll_number, branch):
    print(f"📚 Library Card Issued!")
    print(f"   Name   : {student_name}")
    print(f"   Roll No: {roll_number}")
    print(f"   Branch : {branch}\n")

# When calling, the provided data are ACTUAL ARGUMENTS:
# Case A: Passing literal values directly
issue_library_card("Sneha Roy", 1082, "BCA")

# Case B: Passing variables containing data
name_input = "Kunal Sen"
roll_input = 1083
branch_input = "B.Tech CSE"
issue_library_card(name_input, roll_input, branch_input)

# Example 1: Functions without return implicitly return None
def greet_void(name):
    print(f"Hello, {name}!")

output = greet_void("Aakash")
print("What was stored in output?:", output)  # Prints None

# Example 2: Fruitful function returning calculated data
def calculate_circle_area(radius):
    pi = 3.14159
    area = pi * (radius ** 2)
    return area  # Returns float value to caller

radius_val = 7
calculated_area = calculate_circle_area(radius_val)
print(f"Area of Circle (r={radius_val}): {calculated_area:.2f}")

# We can now use calculated_area in further formulas!
cylinder_volume = calculated_area * 10  # height = 10
print(f"Volume of Cylinder (h=10): {cylinder_volume:.2f}")

def compute_arithmetic_operations(a, b):
    """Returns sum, difference, product, and quotient in one call."""
    summation = a + b
    difference = a - b
    product = a * b
    quotient = a / b if b != 0 else None
    
    # Python packs these 4 values into a tuple: (sum, diff, prod, quot)
    return summation, difference, product, quotient

# Caller unpacks the returned tuple into 4 distinct variables
s, d, p, q = compute_arithmetic_operations(20, 5)

print(f"Sum: {s} | Difference: {d} | Product: {p} | Quotient: {q}")

# tax_rate has a default value of 0.18 (18% GST)
def generate_retail_bill(item_name, price, tax_rate=0.18):
    tax_amount = price * tax_rate
    total_bill = price + tax_amount
    print(f"Item: {item_name:<10} | Price: ₹{price:<6} | Tax ({tax_rate*100}%): ₹{tax_amount:<5.2f} | Total: ₹{total_bill:.2f}")

# Case 1: Caller does NOT pass tax_rate -> Default 18% is used
generate_retail_bill("Keyboard", 1200)

# Case 2: Caller overrides tax_rate with 5% (0.05)
generate_retail_bill("Notebook", 80, 0.05)

def create_email_notification(recipient, subject, body, priority="NORMAL"):
    print(f"Sending [{priority}] Email to: {recipient}")
    print(f"  Subject: {subject}")
    print(f"  Body   : {body}\n")

# Standard positional invocation (order matters)
create_email_notification("user1@gmail.com", "Fee Receipt", "Your payment of ₹15,000 received.")

# Keyword invocation: Order can be completely scrambled safely!
create_email_notification(
    body="Tomorrow's lab session will begin at 9:00 AM sharp.",
    priority="URGENT",
    recipient="bca_batch_1@devascent.me",
    subject="Lab Schedule Update"
)

# Part 1: *args receives variable count of numbers
def calculate_average(subject_name, *marks):
    """Calculates average marks for any number of tests."""
    total_score = sum(marks)
    test_count = len(marks)
    average = total_score / test_count if test_count > 0 else 0
    
    print(f"Subject: {subject_name}")
    print(f"  Marks received (type {type(marks).__name__}): {marks}")
    print(f"  Tests taken: {test_count} | Average: {average:.2f}\n")

calculate_average("Python Lab", 85, 90)             # 2 marks
calculate_average("Mathematics", 70, 82, 65, 94)      # 4 marks

# Part 2: **kwargs receives variable configuration options
def register_hostel_student(name, room_no, **additional_details):
    """Stores flexible student records in key-value format."""
    print(f"🏨 Hostel Admission: {name} (Room #{room_no})")
    for attr, val in additional_details.items():
        print(f"   • {attr.title()}: {val}")
    print()

register_hostel_student("Pooja Mehta", 204, city="Udaipur", phone="9876543210")
register_hostel_student("Arjun Nair", 108, blood_group="B+", guardian="R. Nair", dietary="Veg")

# 1. Global Variable: Defined at top-level
college_name = "DevAscent Polytechnic"
annual_budget = 500000

def sports_department():
    # Local Variable: Exists ONLY inside sports_department
    equipment_count = 45
    print("Inside sports_department():")
    print(f"  Can read local equipment_count: {equipment_count}")
    print(f"  Can read global college_name   : {college_name}")

sports_department()

# 2. Modifying Global Variables using the 'global' Keyword
def sanction_new_budget(additional_funds):
    global annual_budget  # Tells Python: "We want to update the GLOBAL annual_budget!"
    annual_budget += additional_funds
    print(f"Funds sanctioned: ₹{additional_funds}. New Budget: ₹{annual_budget}")

print(f"\nBudget before meeting: ₹{annual_budget}")
sanction_new_budget(150000)
print(f"Budget after meeting : ₹{annual_budget}")

# Classical Problem 1: Factorial
def factorial(n):
    """Calculates n! = n * (n-1) * ... * 1"""
    if n == 0 or n == 1:     # BASE CASE
        return 1
    return n * factorial(n - 1)  # RECURSIVE STEP

print("Factorial of 5:", factorial(5))  # 120

# Classical Problem 2: Fibonacci Sequence (0, 1, 1, 2, 3, 5, 8, ...)
def fibonacci(n):
    """Returns the n-th Fibonacci number."""
    if n <= 0:
        return 0
    elif n == 1:
        return 1
    return fibonacci(n - 1) + fibonacci(n - 2)

print("First 7 Fibonacci terms:", [fibonacci(i) for i in range(7)])

# Standard function vs Lambda
def cube_normal(x):
    return x ** 3

cube_lambda = lambda x: x ** 3

print("Normal def cube(4):", cube_normal(4))
print("Lambda cube(4)    :", cube_lambda(4))

# Ideal Practical Use: Custom sorting on lists of tuples
employees = [
    ("Rahul", "Sales", 45000),
    ("Pooja", "Tech", 85000),
    ("Amit", "HR", 40000),
    ("Zoya", "Tech", 92000)
]

# Sort employees by salary (index 2) from highest to lowest
employees.sort(key=lambda emp: emp[2], reverse=True)

print("\nEmployees Sorted by Salary (Highest First):")
for name, dept, sal in employees:
    print(f"  ₹{sal} | {name} ({dept})")

from functools import reduce

temperatures_celsius = [0, 15, 22, 35, 40, -5]
print("Recorded Celsius Temperatures:", temperatures_celsius)

# 1. filter(): Keep only above-freezing temperatures (temp > 0)
above_freezing = list(filter(lambda c: c > 0, temperatures_celsius))
print("1. filter() (Above 0°C):", above_freezing)

# 2. map(): Convert Celsius to Fahrenheit formula: (C * 9/5) + 32
temperatures_fahrenheit = list(map(lambda c: round((c * 9/5) + 32, 1), above_freezing))
print("2. map() (Converted to °F):", temperatures_fahrenheit)

# 3. functools.reduce(): Find the highest temperature in the list
highest_temp = reduce(lambda a, b: a if a > b else b, temperatures_fahrenheit)
print(f"3. reduce() (Peak Temperature): {highest_temp}°F")

def evaluate_student_record(student_name, *subject_scores, passing_threshold=40, **metadata):
    """
    Generates a formal academic evaluation report.
    - student_name: Positional parameter
    - *subject_scores: Variadic tuple of numbers
    - passing_threshold: Default parameter
    - **metadata: Variadic keyword dictionary of extra attributes
    """
    total_subjects = len(subject_scores)
    total_obtained = sum(subject_scores)
    max_possible = total_subjects * 100
    percentage = (total_obtained / max_possible) * 100 if max_possible > 0 else 0
    
    # Use filter() to identify passing marks
    passed_subjects = list(filter(lambda score: score >= passing_threshold, subject_scores))
    failed_count = total_subjects - len(passed_subjects)
    
    # Determine grade based on percentage
    if percentage >= 85:
        grade = "A+ (Distinction)"
    elif percentage >= 70:
        grade = "A (First Class)"
    elif percentage >= 50:
        grade = "B (Second Class)"
    else:
        grade = "C (Pass)"
    
    status = "PASSED" if failed_count == 0 else f"RE-APPEAR IN {failed_count} SUBJECT(S)"

    # Print formatted report
    print("\n" + "="*50)
    print(f"  ACADEMIC EVALUATION: {student_name.upper()}")
    print("="*50)
    for key, value in metadata.items():
        print(f"  {key.replace('_', ' ').title():<15}: {value}")
    print("-"*50)
    print(f"  Scores Obtained: {list(subject_scores)}")
    print(f"  Aggregate Marks: {total_obtained} / {max_possible}")
    print(f"  Percentage     : {percentage:.2f}%")
    print(f"  Academic Grade : {grade}")
    print(f"  Final Status   : {status}")
    print("="*50)

    return {"name": student_name, "pct": percentage, "passed": failed_count == 0}

# Testing the engine with different student profiles
s1 = evaluate_student_record(
    "Pooja Kashyap",
    88, 92, 79, 85, 94,
    passing_threshold=40,
    roll_number=2026101,
    degree="BCA 1st Year",
    attendance="92%"
)

s2 = evaluate_student_record(
    "Mohit Sharma",
    65, 32, 70, 54,  # 32 is below 40 threshold
    roll_number=2026102,
    degree="BCA 1st Year",
    attendance="76%"
)