آموزش args و kwargs در پایتون با مثال کاربردی

سلام رفیق برنامه‌نویس! اگه مدت زیادیه که با پایتون سروکله می‌زنی یا حتی تازه‌کاری و دنبال راه‌هایی هستی که کدنویسیت رو حرفه‌ای‌تر و انعطاف‌پذیرتر کنی، احتمالاً اسم `*args` و `**kwargs` به گوشت خورده. این دوتا، ابزارهای جادویی پایتون هستن که به تو اجازه می‌دن توابع بسیار قدرتمند و همه‌کاره بنویسی که بتونن با تعداد متغیری از ورودی‌ها کار کنن. دیگه لازم نیست برای هر تعداد ورودی، تابع جدیدی تعریف کنی. قراره اینجا یه سفر عمیق به دنیای این دو مفهوم داشته باشیم و با مثال‌های کاربردی، تمام زوایاشون رو کشف کنیم تا بتونی تو پروژه‌هات حسابی ازشون بهره ببری و کدت تمیزتر و پویاتر بشه.

قبل از اینکه شیرجه بزنیم تو کدها، یه پیشنهاد دوستانه: اگه دنبال ابزارهای پایتونی درجه یک برای سرعت بخشیدن به کارات هستی یا می‌خوای بهترین اسنیپت‌های CSS، JS و HTML رو دم دستت داشته باشی، حتماً یه سری به فروشگاه ابزارهای برنامه‌نویسی fa-tools.ir بزن! اونجا یه عالمه کد و ابزار کاربردی هست که مطمئنم به کارت میاد.

📞 سوالی داری؟ مستقیم با ما تماس بگیر: 09202232789

✨ نقشه راه سریع: args و kwargs در یک نگاه ✨

فرض کن یه تابعی می‌خوای بنویسی که بتونه هر تعداد عددی رو که بهش می‌دی با هم جمع کنه. شاید امروز سه تا عدد بدی، فردا پنج تا و پس‌فردا ده تا. اگه بخوای برای هر تعداد ورودی یه تابع جدا بنویسی، کدت خیلی شلوغ و غیرقابل مدیریت می‌شه. اینجا `*args` مثل یه قهرمان وارد میدون می‌شه.

وقتی تو تعریف یه تابع از *args استفاده می‌کنی، به پایتون می‌گی که این تابع می‌تونه تعداد دلخواهی از آرگومان‌های موقعیتی (positional arguments) رو بپذیره. پایتون هم باهوشه و تمام اون آرگومان‌ها رو جمع‌آوری می‌کنه و به صورت یه تاپل (tuple) در میاره که می‌تونی داخل تابع ازش استفاده کنی. اسم args یک قرارداده، می‌تونی هر اسمی بذاری (مثلاً *numbers)، اما args متداول‌ترین و خواناترین روشه.

مثال 1: جمع کردن هر تعداد عدد

def جمع_اعداد(*اعداد):
    مجموع = 0
    for عدد in اعداد:
        مجموع += عدد
    return مجموع

print(جمع_اعداد(1, 2, 3))  # خروجی: 6
print(جمع_اعداد(10, 20, 30, 40))  # خروجی: 100
print(جمع_اعداد())  # خروجی: 0 (تاپل خالی)
    

مثال 2: نمایش پیام‌های مختلف

def نمایش_پیام‌ها(*پیام‌ها):
    print("--- شروع پیام‌ها ---")
    for پیام in پیام‌ها:
        print(پیام)
    print("--- پایان پیام‌ها ---")

نمایش_پیام‌ها("سلام", "خوش اومدی")
# خروجی:
# --- شروع پیام‌ها ---
# سلام
# خوش اومدی
# --- پایان پیام‌ها ---

نمایش_پیام‌ها("این یک پیام طولانی است.", "یک پیام دیگر.", 123, True)
# خروجی:
# --- شروع پیام‌ها ---
# این یک پیام طولانی است.
# یک پیام دیگر.
# 123
# True
# --- پایان پیام‌ها ---
    

حالا فرض کن می‌خوای یه تابع بنویسی که اطلاعات یک کاربر رو دریافت کنه. این اطلاعات می‌تونه شامل نام، سن، ایمیل، شهر و هر چیز دیگه‌ای باشه. بعضی وقتا فقط نام و سن لازمه، بعضی وقتا همه اطلاعات. اینجا `**kwargs` به کمکت می‌آد.

نماد **kwargs در تعریف تابع به پایتون می‌گه که این تابع می‌تونه تعداد دلخواهی از آرگومان‌های کلیدواژه‌ای (keyword arguments) رو بپذیره. پایتون تمام این آرگومان‌های نام‌گذاری شده رو جمع‌آوری می‌کنه و اون‌ها رو به صورت یه دیکشنری (dictionary) در میاره. هر کلید در دیکشنری، همون نام آرگومان و هر مقدار، همون مقدار آرگومان خواهد بود. مثل *args، اسم kwargs هم قرارداده، و می‌تونی از اسامی دیگه‌ای مثل **data استفاده کنی.

مثال 1: نمایش اطلاعات کاربر

def نمایش_مشخصات_کاربر(**مشخصات):
    print("--- مشخصات کاربر ---")
    if "نام" in مشخصات:
        print(f"نام: {مشخصات['نام']}")
    if "سن" in مشخصات:
        print(f"سن: {مشخصات['سن']}")
    if "شهر" in مشخصات:
        print(f"شهر: {مشخصات['شهر']}")
    if "پست_الکترونیک" in مشخصات:
        print(f"پست الکترونیک: {مشخصات['پست_الکترونیک']}")
    for کلید, مقدار in مشخصات.items():
        if کلید not in ["نام", "سن", "شهر", "پست_الکترونیک"]:
            print(f"{کلید.replace('_', ' ')}: {مقدار}")
    print("--- پایان مشخصات ---")

نمایش_مشخصات_کاربر(نام="سارا", سن=28)
# خروجی:
# --- مشخصات کاربر ---
# نام: سارا
# سن: 28
# --- پایان مشخصات ---

نمایش_مشخصات_کاربر(نام="امیر", شهر="تهران", شغل="برنامه‌نویس")
# خروجی:
# --- مشخصات کاربر ---
# نام: امیر
# شهر: تهران
# شغل: برنامه‌نویس
# --- پایان مشخصات ---
    

مثال 2: تنظیمات یک ابزار

def اعمال_تنظیمات(**تنظیمات):
    print("اعمال تنظیمات...")
    for کلید, مقدار in تنظیمات.items():
        print(f"- {کلید}: {مقدار}")
    print("تنظیمات با موفقیت اعمال شد.")

اعمال_تنظیمات(رنگ_زمینه="آبی", اندازه_فونت=14)
# خروجی:
# اعمال تنظیمات...
# - رنگ_زمینه: آبی
# - اندازه_فونت: 14
# تنظیمات با موفقیت اعمال شد.

اعمال_تنظیمات(مد_تاریک=True)
# خروجی:
# اعمال تنظیمات...
# - مد_تاریک: True
# تنظیمات با موفقیت اعمال شد.
    

حالا که با هر کدوم از این ستاره‌ها جداگانه آشنا شدیم، وقتشه که ببینیم چطور می‌تونیم اون‌ها رو با هم تو یه تابع استفاده کنیم. این ترکیب بهت اجازه می‌ده توابعی بنویسی که واقعاً همه‌کاره باشن و بتونن هر نوع ورودی رو بپذیرن، چه موقعیتی باشن و چه کلیدواژه‌ای.

قانون طلایی: وقتی *args و **kwargs رو در تعریف یک تابع با هم استفاده می‌کنی، `*args` همیشه باید قبل از `**kwargs` قرار بگیره. اگر آرگومان‌های معمولی (ثابت) هم داری، اون‌ها هم باید قبل از `*args` باشن. ترتیب درست به این صورته:

def my_function(fixed_arg, *args, **kwargs):

تابع پردازش‌گر همه‌کاره

def پردازش_داده(شناسه_کاربری, *داده_موقعیتی, **داده_کلیدواژه‌ای):
    print(f"شناسه کاربری: {شناسه_کاربری}")

    if داده_موقعیتی:
        print("داده‌های موقعیتی:")
        for داده in داده_موقعیتی:
            print(f"- {داده}")
    else:
        print("هیچ داده موقعیتی وجود ندارد.")

    if داده_کلیدواژه‌ای:
        print("داده‌های کلیدواژه‌ای:")
        for کلید, مقدار in داده_کلیدواژه‌ای.items():
            print(f"- {کلید}: {مقدار}")
    else:
        print("هیچ داده کلیدواژه‌ای وجود ندارد.")

print("n--- سناریو 1: فقط آرگومان‌های موقعیتی ---")
پردازش_داده(123, "گزینه A", "گزینه B")
# خروجی:
# --- سناریو 1: فقط آرگومان‌های موقعیتی ---
# شناسه کاربری: 123
# داده‌های موقعیتی:
# - گزینه A
# - گزینه B
# هیچ داده کلیدواژه‌ای وجود ندارد.

print("n--- سناریو 2: فقط آرگومان‌های کلیدواژه‌ای ---")
پردازش_داده(456, حالت="فعال", سطح="بالا")
# خروجی:
# --- سناریو 2: فقط آرگومان‌های کلیدواژه‌ای ---
# شناسه کاربری: 456
# هیچ داده موقعیتی وجود ندارد.
# داده‌های کلیدواژه‌ای:
# - حالت: فعال
# - سطح: بالا

print("n--- سناریو 3: ترکیب هر دو ---")
پردازش_داده(789, "ورودی اول", 100, وضعیت="تایید شده", تعداد=5)
# خروجی:
# --- سناریو 3: ترکیب هر دو ---
# شناسه کاربری: 789
# داده‌های موقعیتی:
# - ورودی اول
# - 100
# داده‌های کلیدواژه‌ای:
# - وضعیت: تایید شده
# - تعداد: 5
    

استفاده از *args و **kwargs قدرتمنده، اما مثل هر ابزار قدرتمند دیگه‌ای، نیاز به درک صحیح و استفاده درست داره تا کدت خوانا و قابل نگهداری بمونه.

• ترتیب آرگومان‌ها: این مورد رو باید حتماً رعایت کنی. اگر هم آرگومان‌های معمولی (positional-only) و هم کلیدواژه‌ای (keyword-only) داری، ترتیب به این صورت خواهد بود:
  def func(positional_arg_1, positional_arg_2, *args, keyword_only_arg, **kwargs):

  positional_arg_1 و positional_arg_2 آرگومان‌های ثابت هستند. *args آرگومان‌های موقعیتی متغییر را می‌گیرد. keyword_only_arg یک آرگومان است که حتماً باید به صورت کلیدواژه‌ای (مثلاً keyword_only_arg=value) به تابع پاس داده شود. **kwargs هم آرگومان‌های کلیدواژه‌ای متغیر را جمع می‌کند. (البته استفاده از positional-only و keyword-only آرگومان‌ها با نماد / و * در پایتون ۳.۸ به بعد کمی متفاوت تعریف می‌شود.)

• خوانایی: سعی کن نام args و kwargs رو تغییر ندی مگر اینکه واقعاً نام مناسب‌تری برای مفهوم خاصی داشته باشی (مثلاً *numbers یا **options).
• زیاده‌روی نکن: همیشه از این قابلیت‌ها استفاده نکن. اگه می‌دونی تابعت ورودی‌های ثابتی داره، بهتره همون‌ها رو به صورت صریح تعریف کنی. این کار خوانایی رو بالا می‌بره و اشکال‌زدایی رو آسون‌تر می‌کنه.
• مستندسازی (Docstrings): حتماً در Docstring تابعت توضیح بده که *args و **kwargs چه نوع ورودی‌هایی رو انتظار دارن.
• گسترش آرگومان‌ها (Argument Unpacking): می‌تونی از * و ** برای “باز کردن” (unpacking) لیست‌ها/تاپل‌ها و دیکشنری‌ها هنگام فراخوانی تابع استفاده کنی. این موضوع در صفحه اسنیپت‌ها به طور کاملتر توضیح داده شده.

استفاده از * و ** در هنگام فراخوانی تابع

def نمایش_اطلاعات(پیام_اصلی, *بقیه_پیام‌ها, **گزینه‌ها):
    print(f"پیام اصلی: {پیام_اصلی}")
    if بقیه_پیام‌ها:
        print(f"پیام‌های اضافی: {', '.join(map(str, بقیه_پیام‌ها))}")
    if گزینه‌ها:
        print("گزینه‌ها:")
        for کلید, مقدار in گزینه‌ها.items():
            print(f"- {کلید}: {مقدار}")

لیست_پیام‌ها = ["آیتم ۱", "آیتم ۲", "آیتم ۳"]
تنظیمات_اضافی = {"حالت": "تست", "ورژن": 1.0}

نمایش_اطلاعات("این پیغام اصلی است", *لیست_پیام‌ها, **تنظیمات_اضافی)
# خروجی:
# پیام اصلی: این پیغام اصلی است
# پیام‌های اضافی: آیتم ۱, آیتم ۲, آیتم ۳
# گزینه‌ها:
# - حالت: تست
# - ورژن: 1.0
    

علاوه بر کاربردهای پایه‌ای که دیدیم، *args و **kwargs در الگوهای طراحی پیشرفته‌تر و ساختاردهی کد نقش مهمی دارن. اینجا به دو مورد از اون‌ها اشاره می‌کنیم.

مثال دکوراتور برای اندازه‌گیری زمان اجرا

import time

def زمان_اجرا(func):
    def wrapper(*args, **kwargs):
        شروع = time.time()
        نتیجه = func(*args, **kwargs)  # فراخوانی تابع اصلی با args و kwargs
        پایان = time.time()
        print(f"تابع {func.__name__} در {پایان - شروع:.4f} ثانیه اجرا شد.")
        return نتیجه
    return wrapper

@زمان_اجرا
def محاسبه_پیچیده(حد_بالا):
    sum_val = 0
    for i in range(حد_بالا):
        sum_val += i ** 2
    return sum_val

محاسبه_پیچیده(1000000)
# خروجی (زمان ممکن است متفاوت باشد):
# تابع محاسبه_پیچیده در 0.1601 ثانیه اجرا شد.
    

مثال: تابع واسط برای لاگ‌برداری

def عملیات_اصلی(نام, مقدار=1):
    print(f"اجرای عملیات اصلی: نام={نام}, مقدار={مقدار}")
    return نام * مقدار

def تابع_واسط_لاگ(func, *args, **kwargs):
    print(f"لاگ: فراخوانی تابع {func.__name__} با args={args}, kwargs={kwargs}")
    نتیجه = func(*args, **kwargs)  # پاس دادن آرگومان‌ها
    print(f"لاگ: تابع {func.__name__} با نتیجه {نتیجه} به پایان رسید.")
    return نتیجه

تابع_واسط_لاگ(عملیات_اصلی, "A", مقدار=5)
# خروجی:
# لاگ: فراخوانی تابع عملیات_اصلی با args=('A',), kwargs={'مقدار': 5}
# اجرای عملیات اصلی: نام=A, مقدار=5
# لاگ: تابع عملیات_اصلی با نتیجه AAAAA به پایان رسید.
    

این بخش بهت کمک می‌کنه تا مشکلات رایجی که ممکنه هنگام کار با *args و **kwargs باهاشون روبرو بشی رو شناسایی و رفع کنی. درک این موارد باعث می‌شه مهارتتان در دیباگینگ خیلی بهتر بشه.

• مشکل: خطای TypeError: takes X positional arguments but Y were given
  
  دلیل: این خطا زمانی رخ می‌ده که تعداد آرگومان‌های موقعیتی که به تابع پاس می‌دی با تعداد مورد انتظار مطابقت نداره. اغلب به دلیل اشتباه در ترتیب آرگومان‌هاست.
  
  راه حل:
  • مطمئن شو که آرگومان‌های ثابت (non-*args) رو به تعداد صحیح پاس دادی.
  • ترتیب آرگومان‌ها رو چک کن: آرگومان‌های ثابت، بعد *args، و بعد **kwargs.
• مشکل: خطای TypeError: got multiple values for keyword argument '...'
  
  دلیل: این خطا وقتی پیش میاد که برای یک آرگومان خاص، هم به صورت موقعیتی (positional) و هم به صورت کلیدواژه‌ای (keyword) مقدار ارسال کردی. یا اگر یک کلید رو چندین بار در **kwargs تکرار کنی.
  
  راه حل:
  • آرگومان‌های تکراری رو حذف کن.
  • مطمئن شو که آرگومان‌های موقعیتی و کلیدواژه‌ای با هم تداخل ندارند.
• مشکل: عدم دسترسی به مقادیر داخل args یا kwargs
  
  دلیل: فراموش کردن این که args یک تاپل و kwargs یک دیکشنری است.
  
  راه حل:
  • برای دسترسی به آیتم‌های args، از اندیس‌گذاری (مثلاً args[0]) یا حلقه‌ی for استفاده کن.
  • برای دسترسی به آیتم‌های kwargs، از کلیدها (مثلاً kwargs['name']) یا متد .get() یا حلقه‌ی for برای پیمایش .items() استفاده کن.
• مشکل: پاس ندادن * یا ** هنگام Unpacking
  
  دلیل: اگر یک لیست یا دیکشنری رو به تابعی که انتظار *args یا **kwargs داره پاس بدی، اما از * یا ** قبل از نام متغیر استفاده نکنی، پایتون اون‌ها رو به عنوان یک آرگومان واحد (نه مجموعه‌ای از آرگومان‌ها) در نظر می‌گیره.
  
  راه حل:
  • همیشه برای Unpacking لیست/تاپل از * و برای دیکشنری از ** استفاده کن.

در این بخش به سوالات رایجی که ممکنه در مورد *args و **kwargs پیش بیاد، پاسخ می‌دیم.

امیدوارم این مقاله جامع، بهت کمک کرده باشه تا مفاهیم *args و **kwargs رو به طور کامل درک کنی و بتونی تو پروژه‌هات با اطمینان و خلاقیت ازشون استفاده کنی. این ابزارها واقعاً می‌تونن کدت رو انعطاف‌پذیرتر و قدرتمندتر کنن. اگه سوالی داشتی یا تجربه‌ای برای به اشتراک گذاشتن، حتماً با ما در میون بذار.

برنامه‌نویسی لذت‌بخش و پرکاربرد!