ఫంక్షన్స్ ఫండమెంటల్స్ & ఆర్గ్యుమెంట్స్

1 ఫంక్షన్ అంటే ఏమిటి? (What is a Function in Python?)

పైథాన్‌లో ఫంక్షన్ (Function) అనేది ఒక నిర్దిష్టమైన పనిని (Specific Task) పూర్తి చేయడానికి రూపొందించబడిన, పేరు పెట్టబడిన కోడ్ బ్లాక్. అవసరమైనప్పుడు దానికి డేటాను ఇన్‌పుట్‌గా పంపవచ్చు, అది ఆ డేటాను ప్రాసెస్ చేసి మనకు కావలసిన ఫలితాన్ని (Output) తిరిగి అందిస్తుంది.

ఫంక్షన్ల ప్రధాన ప్రయోజనాలు:

• కోడ్ పునర్వినియోగం (Reusability): ఒక లాజిక్‌ను ఒక్కసారి మాత్రమే రాస్తాము, కానీ ప్రాజెక్ట్‌లో అవసరమైన చోటల్లా పేరుతో పిలిచి (Call) ఎన్నిసార్లైనా వాడుకోవచ్చు.
• మాడ్యులారిటీ & నిర్వహణ సౌలభ్యం (Modularity & Maintainability): పెద్ద అప్లికేషన్‌ను చిన్న చిన్న స్వతంత్ర భాగాలుగా విభజించడం వల్ల బగ్‌లను గుర్తించడం మరియు సరిచేయడం చాలా సులభం అవుతుంది.
• టెస్టింగ్ & డీబగ్గింగ్: ప్రతి ఫంక్షన్‌ను విడివిడిగా యూనిట్ టెస్టింగ్ (Unit Testing) చేయవచ్చు.

2 CPython లో ఫంక్షన్ ఎలా పనిచేస్తుంది? (Call Stack & Frames)

మీరు ఒక ఫంక్షన్‌ను కాల్ చేసినప్పుడు CPython అంతర్గతంగా ఆపరేటింగ్ సిస్టమ్ మెమరీలో కాల్ స్టాక్ (Call Stack) పై ఒక ప్రత్యేకమైన స్టాక్ ఫ్రేమ్ (Stack Frame / Activation Record) ను సృష్టిస్తుంది.

• లోకల్ వేరియబుల్స్ ఐసోలేషన్: ఫంక్షన్ లోపల సృష్టించిన వేరియబుల్స్ ఆ స్టాక్ ఫ్రేమ్‌లో మాత్రమే ఉంటాయి. బయట ప్రపంచానికి అవి కనిపించవు (ఎన్‌క్యాప్సులేషన్).
• ఫంక్షన్ రిటర్న్ కాగానే మెమరీ క్లీనప్: ఫంక్షన్ పని పూర్తి కాగానే లేదా return స్టేట్‌మెంట్ తగలగానే ఆ స్టాక్ ఫ్రేమ్ స్టాక్ నుండి పాప్ (Pop) అయిపోతుంది. అందులోని లోకల్ వేరియబుల్స్ మెమరీ నుండి తక్షణమే విడుదలవుతాయి.

3 ఫంక్షన్ డిక్లరేషన్ & సింటాక్స్ (The def Keyword)

పైథాన్‌లో ఫంక్షన్‌ను డిక్లేర్ చేయడానికి def (define కు సంక్షిప్త రూపం) కీవర్డ్‌ను ఉపయోగిస్తాము.

ప్రాథమిక సింటాక్స్:

ముఖ్యమైన నియమాలు: ఫంక్షన్ పేరు తప్పనిసరిగా వేరియబుల్ నామకరణ నియమాలను పాటించాలి (చిన్న అక్షరాలు, పదాల మధ్య అండర్‌స్కోర్ — snake_case). పారాంథసిస్ () చివర కాలన్ : ఉండటం తప్పనిసరి.

4 పారామీటర్లు (Parameters) vs ఆర్గ్యుమెంట్స్ (Arguments)

ఈ రెండు పదాలను బిగినర్స్ తరచూ ఒకే అర్థంలో వాడుతుంటారు, కానీ వాటి మధ్య చాలా స్పష్టమైన సాంకేతిక వ్యత్యాసం ఉంది:

5 return స్టేట్‌మెంట్ & ఎర్లీ ఎగ్జిట్ (Early Return Guard Clauses)

ఫంక్షన్ తన లెక్కింపు పూర్తయిన తర్వాత ఫలితాన్ని పిలిచిన చోటుకి తిరిగి పంపడానికి return స్టేట్‌మెంట్‌ను ఉపయోగిస్తుంది.

• రిటర్న్ తగలగానే ఫంక్షన్ ఆగిపోతుంది: return స్టేట్‌మెంట్ ఎగ్జిక్యూట్ అయిన తక్షణమే ఆ ఫంక్షన్ ఎగ్జిక్యూషన్ ముగుస్తుంది. దాని క్రింద ఎన్ని లైన్ల కోడ్ ఉన్నా అవి రన్ కావు.
• ఇంప్లిసిట్ return None: ఒక ఫంక్షన్‌లో మీరు ఎటువంటి return స్టేట్‌మెంట్ రాయకపోతే, ఫంక్షన్ ముగింపులో పైథాన్ తెరవెనుక స్వయంచాలకంగా return None ను అమర్చుతుంది!
• గార్డ్ క్లాజ్ ప్యాటర్న్ (Early Exit Guard Clauses): నెస్టెడ్ if-else లు రాయడానికి బదులుగా, తప్పుడు ఇన్‌పుట్స్ రాగానే వెంటనే ఫంక్షన్ నుండి బయటకు రావడం క్లీన్ కోడింగ్ పద్ధతి:
  def withdraw_money(balance, amount):
      if amount <= 0: return "తప్పుడు అమౌంట్!" # Guard 1
      if amount > balance: return "తగినంత బ్యాలెన్స్ లేదు!" # Guard 2
      return balance - amount # హ్యాపీ పాత్!

6 మల్టిపుల్ రిటర్న్స్ (Multiple Returns via Tuples)

C లేదా Java వంటి భాషల్లో ఒక ఫంక్షన్ కేవలం ఒకే ఒక విలువను మాత్రమే రిటర్న్ చేయగలదు. కానీ పైథాన్‌లో కామాలతో వేరుచేసి ఎన్ని విలువలనైనా ఒకేసారి రిటర్న్ చేయవచ్చు!

తెరవెనుక పైథాన్ వాటన్నింటినీ ఒక ఇమ్మ్యుటబుల్ టుపుల్ (Tuple) గా ప్యాక్ చేసి రిటర్న్ చేస్తుంది. కాలర్ సైడ్ వాటిని నేరుగా అన్‌ప్యాక్ చేసుకోవచ్చు:

7 పొజిషనల్ వర్సెస్ కీవర్డ్ ఆర్గ్యుమెంట్స్ (Positional vs Keyword)

ఫంక్షన్‌కు ఆర్గ్యుమెంట్లను పంపేటప్పుడు రెండు ముఖ్యమైన మార్గాలు ఉన్నాయి:

• 1. పొజిషనల్ ఆర్గ్యుమెంట్స్ (Positional Arguments): ఆర్గ్యుమెంట్లు పంపిన వరుస క్రమాన్ని బట్టి పారామీటర్లలోకి వెళ్తాయి. వరుస మారితే అర్థం మారిపోతుంది: create_user("రాము", "admin") → పేరు "రాము", రోల్ "admin".
• 2. కీవర్డ్ ఆర్గ్యుమెంట్స్ (Keyword Arguments): పారామీటర్ పేరును స్పష్టంగా పేర్కొంటూ ఆర్గ్యుమెంట్లను పంపుతాము. దీనివల్ల వరుస క్రమంతో పనిలేదు, కోడ్ చాలా రీడబుల్‌గా ఉంటుంది: create_user(role="admin", user_name="రాము")
• గోల్డెన్ సింటాక్స్ రూల్: ఒకే కాల్‌లో రెండింటినీ వాడేటప్పుడు, పొజిషనల్ ఆర్గ్యుమెంట్లు ఎల్లప్పుడూ కీవర్డ్ ఆర్గ్యుమెంట్ల కంటే ముందే ఉండాలి! func(a=1, 2) అని రాస్తే SyntaxError: positional argument follows keyword argument వస్తుంది.

8 డిఫాల్ట్ పారామీటర్లు & The Mutable Default Parameter Trap ⚠️

ఒక ఫంక్షన్ కాల్ చేసేటప్పుడు కొన్ని ఆర్గ్యుమెంట్లు ఇవ్వకపోయినా పనిచేసేలా వాటికి డిఫాల్ట్ విలువలు (Default Values) కేటాయించవచ్చు:

9 కోడ్ డెమో 1: లైవ్ బ్యాంకింగ్ ట్రాన్సాక్షన్స్ & క్యాలిక్యులేషన్స్

పారామీటర్లు, కీవర్డ్ ఆర్గ్యుమెంట్లు, మరియు సేఫ్ డిఫాల్ట్ పారామీటర్లను ఉపయోగించి బ్యాంకింగ్ లావాదేవీల ఫంక్షన్‌ను పరిశీలిద్దాం:

# =====================================================================
# చాప్టర్ 16 డెమో 1: ఫంక్షన్స్, గార్డ్ క్లాజ్ & సేఫ్ డిఫాల్ట్ పారామీటర్లు
# =====================================================================

def calculate_simple_interest(principal: float, rate_pct: float = 7.5, tenure_years: int = 1):
    """సాధారణ వడ్డీ మరియు మెచ్యూరిటీ మొత్తాన్ని లెక్కిస్తుంది."""
    if principal <= 0 or tenure_years <= 0:
        return 0.0, 0.0  # Guard clause for invalid inputs

    interest = (principal * rate_pct * tenure_years) / 100.0
    total_maturity = principal + interest
    return round(interest, 2), round(total_maturity, 2)

# 1. డిఫాల్ట్ వడ్డీ రేటుతో కాల్ చేయడం (Positional)
interest_1, total_1 = calculate_simple_interest(100000, tenure_years=3)
print(f"డిపాజిట్: ₹1,00,000 | వడ్డీ: ₹{interest_1:,.2f} | మొత్తం: ₹{total_1:,.2f}")

# 2. కీవర్డ్ ఆర్గ్యుమెంట్లతో కస్టమ్ వడ్డీ రేటు ఇవ్వడం
interest_2, total_2 = calculate_simple_interest(rate_pct=8.2, principal=250000, tenure_years=5)
print(f"డిపాజిట్: ₹2,50,000 | వడ్డీ: ₹{interest_2:,.2f} | మొత్తం: ₹{total_2:,.2f}")

10 Modern Python 3.5+ Type Hints & PEP 484

పైథాన్ డైనమిక్ టైప్డ్ లాంగ్వేజ్ అయినప్పటికీ, పెద్ద కార్పొరేట్ ప్రాజెక్టులలో కోడ్ క్వాలిటీ మరియు ఎడిటర్ ఆటోకంప్లీషన్ కోసం Type Hints ప్రామాణికంగా మారాయి.

గుర్తుంచుకోండి: టైప్ హింట్స్ రన్‌టైమ్‌లో ఎర్రర్స్ ఇవ్వవు (పైథాన్ స్పీడ్ తగ్గదు), కానీ mypy లేదా VS Code వంటి టూల్స్ ద్వారా కోడ్ రన్ అవ్వకముందే బగ్‌లను పట్టుకోవడానికి ఎంతగానో తోడ్పడతాయి.

11 Python 3.8+ Positional-Only (/) & Keyword-Only (*)

పైథాన్ 3.8 లో API డిజైనర్ల కోసం సరికొత్త పారామీటర్ రూల్స్ ప్రవేశపెట్టబడ్డాయి:

• స్లాష్ (/) కి ఎడమవైపు ఉన్నవి Positional-Only: వీటిని కాల్ చేసేటప్పుడు కీవర్డ్ రూపంలో (పేరుతో) పంపలేము! కేవలం విలువను మాత్రమే పంపాలి (ఉదా: len() లాగా).
• స్టార్ (*) కి కుడివైపు ఉన్నవి Keyword-Only: వీటిని కాల్ చేసేటప్పుడు తప్పనిసరిగా పేరుతో మాత్రమే పంపాలి (పొజిషనల్‌గా పంపితే ఎర్రర్).

# Modern Python 3.8+ API డిజైన్ ప్యాటర్న్
# a, b -> Positional-Only (/)
# c    -> Standard (పొజిషనల్ లేదా కీవర్డ్ ఏదైనా కావచ్చు)
# key  -> Keyword-Only (*)
def secure_transfer(sender_acc, amount, /, note="NEFT", *, auth_token):
    print(f"బదిలీ ఖాతా : {sender_acc} | మొత్తం : ₹{amount}")
    print(f"వివరణ      : {note} | టోకెన్ : {auth_token}")

# సరైన కాల్:
secure_transfer("ACC-101", 50000, "ఫీజు చెల్లింపు", auth_token="SEC-9981")

# తప్పుడు కాల్స్ (రన్ చేస్తే ఎర్రర్స్ వస్తాయి):
# secure_transfer(sender_acc="ACC-101", amount=50000, auth_token="SEC-9981") # TypeError: Positional-only!
# secure_transfer("ACC-101", 50000, "ఫీజు", "SEC-9981") # TypeError: Keyword-only auth_token needed!

12 కామన్ బిగినర్స్ మిస్టేక్స్ & ప్రొడక్షన్ బెస్ట్ ప్రాక్టీసెస్

• Mistake 1: ఫంక్షన్ కాల్‌లో పారాంథసిస్ మర్చిపోవడం: x = calculate_tax అని రాస్తే ఫంక్షన్ ఎగ్జిక్యూట్ కాదు; కేవలం ఫంక్షన్ ఆబ్జెక్ట్ రిఫరెన్స్ మాత్రమే అసైన్ అవుతుంది! ఫంక్షన్‌ను రన్ చేయడానికి తప్పనిసరిగా బ్రాకెట్లు పెట్టాలి: x = calculate_tax().
• Mistake 2: డిఫాల్ట్ ఆర్గ్యుమెంట్లలో లిస్ట్/డిక్ట్ వాడటం: పైన వివరించిన Mutable Default Parameter ట్రాప్‌లో పడకుండా ఎల్లప్పుడూ None ను డిఫాల్ట్‌గా పెట్టి ఫంక్షన్ లోపల కొత్త కలెక్షన్‌ను ప్రారంభించండి.
• Mistake 3: రిటర్న్ వాల్యూ తీసుకోకుండా ప్రింట్ చేయడం: None రిటర్న్ చేసే ఫంక్షన్‌ను వేరియబుల్‌లో పెట్టి వాడుకోవాలని చూడటం.
• Best Practice: సింగిల్ రెస్పాన్సిబిలిటీ ప్రిన్సిపల్ (SRP): ఒక ఫంక్షన్ కేవలం ఒకే ఒక్క పనిని మాత్రమే సమర్థవంతంగా చేయాలి. జీతం లెక్కించడం మరియు డేటాబేస్‌లో సేవ్ చేయడం రెండూ ఒకే ఫంక్షన్‌లో కలపకండి.
• Best Practice: Docstrings రాయడం: ఫంక్షన్ మొదటి లైన్‌లో """Docstring""" రాయడం వల్ల మీ ఫంక్షన్‌ను వాడుకునే ఇతర డెవలపర్లకు హెల్ప్ టూల్‌టిప్స్ కనిపిస్తాయి.

13 రియల్-వరల్డ్ ప్రాజెక్ట్: "Enterprise Payroll & Salary Calculation Engine"

ఈ పదహారవ అధ్యాయంలో నేర్చుకున్న అన్ని ఫంక్షన్ కాన్సెప్టులను (def, Type Hints, మల్టిపుల్ రిటర్న్స్, గార్డ్ క్లాజెస్, కీవర్డ్ ఆర్గ్యుమెంట్స్, క్యాలిక్యులేషన్ మాడ్యులారిటీ) అనుసంధానిస్తూ — కార్పొరేట్ ఉద్యోగుల జీతాలు, అలవెన్సులు, పన్నులు మరియు టేక్-హోమ్ శాలరీని లెక్కించే పూర్తి స్థాయి Enterprise Payroll & Salary Calculation Engine ను నిర్మిద్దాం!

# =====================================================================
# చాప్టర్ 16 మినీ ప్రాజెక్ట్: Enterprise Payroll & Salary Calculation Engine
# కాన్సెప్ట్స్: Modular Functions, Type Annotations, Multiple Returns,
#             Guard Clauses, Keyword Arguments, Default Parameters
# =====================================================================

def calculate_allowances(basic_salary: float, metro_city: bool = True) -> tuple[float, float, float]:
    """HRA, DA, మరియు స్పెషల్ అలవెన్సులను లెక్కిస్తుంది."""
    hra_rate = 0.50 if metro_city else 0.40  # మెట్రో నగరాల్లో 50% HRA
    hra = basic_salary * hra_rate
    da = basic_salary * 0.15                  # 15% DA
    special_allowance = basic_salary * 0.20   # 20% Special Allowance
    return hra, da, special_allowance

def calculate_pf_deduction(basic_salary: float, pf_rate: float = 0.12) -> float:
    """ప్రావిడెంట్ ఫండ్ (PF) డిడక్షన్‌ను లెక్కిస్తుంది."""
    return round(basic_salary * pf_rate, 2)

def calculate_income_tax(annual_gross: float) -> float:
    """వార్షిక స్థూల జీతంపై ఆదాయపు పన్నును లెక్కిస్తుంది (కొత్త పన్ను విధానం)."""
    if annual_gross <= 700000:
        return 0.0  # ₹7 లక్షల వరకు పన్ను మినహాయింపు (Rebate)
    elif annual_gross <= 1000000:
        return (annual_gross - 700000) * 0.10
    elif annual_gross <= 1500000:
        return 30000 + (annual_gross - 1000000) * 0.15
    else:
        return 105000 + (annual_gross - 1500000) * 0.20

def generate_employee_payslip(
    emp_id: str,
    emp_name: str,
    designation: str,
    monthly_basic: float,
    *,
    is_metro: bool = True,
    performance_bonus: float = 0.0
) -> dict:
    """ఉద్యోగికి పూర్తి స్థాయి పేస్లిప్ డేటాను గణించి డిక్షనరీగా రిటర్న్ చేస్తుంది."""
    # గార్డ్ క్లాజ్: తప్పుడు శాలరీ చెక్
    if monthly_basic <= 0:
        return {"error": "తప్పుడు బేసిక్ శాలరీ!"}

    hra, da, special = calculate_allowances(monthly_basic, metro_city=is_metro)
    monthly_gross = monthly_basic + hra + da + special + performance_bonus

    pf_deduction = calculate_pf_deduction(monthly_basic)
    annual_gross = monthly_gross * 12
    annual_tax = calculate_income_tax(annual_gross)
    monthly_tax = round(annual_tax / 12.0, 2)

    total_deductions = pf_deduction + monthly_tax
    net_take_home = round(monthly_gross - total_deductions, 2)

    return {
        "emp_id": emp_id,
        "name": emp_name,
        "designation": designation,
        "basic": monthly_basic,
        "hra": hra,
        "da": da,
        "special": special,
        "bonus": performance_bonus,
        "gross": monthly_gross,
        "pf": pf_deduction,
        "tax": monthly_tax,
        "deductions": total_deductions,
        "net_pay": net_take_home
    }

def print_payslip_card(slip: dict):
    """అందమైన కార్పొరేట్ పేస్లిప్ ప్రింటింగ్."""
    print("\n" + "=" * 70)
    print(f"{'💼 మన సాఫ్ట్‌వేర్ సొల్యూషన్స్ — అధికారిక శాలరీ స్లిప్ 2026':^70}")
    print("=" * 70)
    print(f"ఉద్యోగి ID   : {slip['emp_id']:<20} పేరు     : {slip['name']}")
    print(f"హోదా        : {slip['designation']:<20} జీతం నెల : అక్టోబర్ 2026")
    print("-" * 70)
    print(f"{'ఆర్జనలు (Earnings)':<35} | {'తగ్గింపులు (Deductions)':<30}")
    print("-" * 70)
    print(f"బేసిక్ శాలరీ      : ₹{slip['basic']:>10,.2f}  | ప్రావిడెంట్ ఫండ్ (PF) : ₹{slip['pf']:>10,.2f}")
    print(f"ఇంటి అద్దె (HRA)   : ₹{slip['hra']:>10,.2f}  | ప్రొఫెషనల్ ట్యాక్స్ (TDS): ₹{slip['tax']:>10,.2f}")
    print(f"కరువు భత్యం (DA)   : ₹{slip['da']:>10,.2f}  |")
    print(f"స్పెషల్ అలవెన్స్  : ₹{slip['special']:>10,.2f}  |")
    if slip['bonus'] > 0:
        print(f"పర్ఫార్మెన్స్ బోనస్ : ₹{slip['bonus']:>10,.2f}  |")
    print("-" * 70)
    print(f"మొత్తం స్థూల జీతం (Gross) : ₹{slip['gross']:>10,.2f}  | మొత్తం తగ్గింపులు   : ₹{slip['deductions']:>10,.2f}")
    print("=" * 70)
    print(f"👉 నికర చెల్లింపు (Net Take-Home Salary) : ₹{slip['net_pay']:>12,.2f} 💵")
    print("=" * 70 + "\n")

# లైవ్ టెస్టింగ్
emp1_slip = generate_employee_payslip(
    emp_id="EMP-1044",
    emp_name="రాజేష్ వర్మ",
    designation="సీనియర్ క్లౌడ్ ఆర్కిటెక్ట్",
    monthly_basic=65000.0,
    is_metro=True,
    performance_bonus=15000.0
)

emp2_slip = generate_employee_payslip(
    emp_id="EMP-2091",
    emp_name="స్వప్న ప్రియ",
    designation="పైథాన్ డేటా ఇంజనీర్",
    monthly_basic=45000.0,
    is_metro=False
)

print_payslip_card(emp1_slip)
print_payslip_card(emp2_slip)

★ ఈ అధ్యాయంపై ప్రాక్టీస్ క్విజ్ (Knowledge Check)