الـ **kwarg

جزء من قسم Object Oriented Programming في رحلة Python على Coddy — الدرس 43 من 64.

**kwargs هو اختصار لـ "keyword arguments" (الوسائط الكلمات المفتاحية). فهو يسمح للدالة بقبول أي عدد من الوسائط المسماة (مثل أزواج key=value) دون الحاجة إلى تعريفها جميعًا مسبقًا.

كيفية العمل:

*args ← يجمع الوسائط الموضعية الإضافية في tuple
**kwargs ← يجمع الوسائط المسماة الإضافية في dictionary

مثال بسيط

لنبدأ بأبسط مثال ممكن:

def greet(**kwargs):
    print(kwargs)

greet(name="Alice", age=25, country="Australia")

الناتج:

{'name': 'Alice', 'age': 25, 'country': 'Australia'}

كما ترى، يقوم **kwargs تلقائياً بجمع كافة الوسائط المسماة (keyword arguments) في قاموس (dictionary).

استخدام القاموس

بما أن kwargs هو بالفعل قاموس (dictionary)، يمكنك التكرار خلاله مباشرة:

def print_info(**kwargs):
    print("Information received:")
    for key, value in kwargs.items():
        print(f"{key}: {value}")

print_info(name="Bob", age=30, job="Teacher")

المخرجات:

Information received:
name: Bob
age: 30
job: Teacher

دمج المعاملات العادية مع **kwargs

يمكنك دمج المعلمات العادية مع **kwargs:

def create_profile(name, **details):
    print(f"Creating profile for: {name}")
    print("Additional details:")
    for key, value in details.items():
        print(f"  {key}: {value}")

create_profile("Sarah", age=28, city="London", hobby="Reading")

المخرجات:

Creating profile for: Sarah
Additional details:
  age: 28
  city: London
  hobby: Reading

**kwargs فارغة

إذا لم يتم تمرير أي وسيطات كلمات رئيسية (keyword arguments)، فسيكون kwargs قاموساً فارغاً:

def show_data(**kwargs):
    if kwargs:
        print("Data:", kwargs)
    else:
        print("No data provided")

show_data()  # لا توجد وسيطات
show_data(item="apple")  # مع وسيطات

المخرجات:

No data provided
Data: {'item': 'apple'}

مثال واقعي: فئة مع **kwargs

إليك كيفية استخدام **kwargs في فئة (class):

class Person:
    def __init__(self, name, **kwargs):
        self.name = name
        self.details = kwargs
    
    def show_info(self):
        print(f"Name: {self.name}")
        for key, value in self.details.items():
            print(f"{key}: {value}")

person = Person("Alice", age=25, city="New York", job="Engineer")
person.show_info()

المخرجات:

Name: Alice
age: 25
city: New York
job: Engineer

تفكيك القواميس

يمكنك أيضاً فك القواميس (unpack dictionaries) عند استدعاء الدوال:

def display_settings(**kwargs):
    for setting, value in kwargs.items():
        print(f"{setting} = {value}")

settings = {"debug": True, "verbose": False, "timeout": 30}
display_settings(**settings)  # يقوم بفك القاموس

المخرجات:

debug = True
verbose = False
timeout = 30

النقاط الرئيسية:

**kwargs يجمع الوسائط المسماة (keyword arguments) في قاموس — لا حاجة للتحويل، فهو قاموس بالفعل
الاسم kwargs هو مجرد عرف - يمكنك استخدام أي اسم بعد **
استخدمه عندما تريد تواقيع دوال مرنة
رائع للتعامل مع المعاملات الاختيارية أو إعدادات التكوين

التحدي

سهل

في هذا التحدي، ستقوم بتنفيذ نظام لإنشاء الأشخاص مع تغطية اختبارية شاملة.

تحتاج إلى تعديل ملف person_creator.py فقط، باتباع تعليقات TODO التي توجه تنفيذك. يحتوي الملف على هيكل فئة (class) لإنشاء وإدارة كائنات الأشخاص بخصائص متنوعة.

ورقة مرجعية

يسمح المعامل **kwargs للميثود بقبول أي عدد من الوسائط المسماة (keyword arguments)، وتجميعها في قاموس (dictionary):

class Person:
    def __init__(self, name, **kwargs):
        self.name = name
        self.details = kwargs
    
    def show_info(self):
        print(f"Name: {self.name}")
        for key, value in self.details.items():
            print(f"{key}: {value}")

person = Person("Alice", age=25, city="New York", job="Engineer")

الدمج بين المعاملات العادية، و *args، و **kwargs:

class Logger:
    def log(self, level, *messages, **options):
        timestamp = options.get('timestamp', False)
        color = options.get('color', 'default')
        
        if timestamp:
            print("[2024-01-01 12:00:00]", end=" ")
        print(f"[{level}]", end=" ")
        for message in messages:
            print(message, end=" ")

logger = Logger()
logger.log("INFO", "User", "logged", "in", timestamp=True, color="green")

فك حزم القواميس (Unpack dictionaries) عند استدعاء الميثودز باستخدام **:

settings = {"debug": True, "verbose": False, "log_level": "INFO"}
config = Config(**settings)  # Unpacks the dictionary

الوصول إلى قيم **kwargs باستخدام دوال القاموس:

def get_setting(self, key, default=None):
    return self.settings.get(key, default)

# Iterate through all kwargs
for key, value in self.settings.items():
    print(f"{key} = {value}")

جرّب بنفسك

from person_creator import create_person

# معالج حالات الاختبار الشاملة
test_case = input()

if test_case == "basic_test":
    create_person(name="John", age=25, occupation="Engineer")
    # المخرجات:
    # Person created with properties:
    # name: John
    # age: 25
    # occupation: Engineer

elif test_case == "empty_test":
    create_person()
    # المخرجات:
    # Person created with properties:
    # (لا توجد مخرجات إضافية لعدم وجود خصائص)

elif test_case == "many_properties":
    create_person(name="Alice", age=30, occupation="Doctor", city="New York", 
                 country="USA", hobby="Reading", email="alice@example.com")
    # المخرجات:
    # Person created with properties:
    # name: Alice
    # age: 30
    # occupation: Doctor
    # city: New York
    # country: USA
    # hobby: Reading
    # email: alice@example.com

elif test_case == "special_characters":
    create_person(name="Bob", email="bob@example.com", phone="123-456-7890")
    # المخرجات:
    # Person created with properties:
    # name: Bob
    # email: bob@example.com
    # phone: 123-456-7890

elif test_case == "numeric_keys":
    create_person(name="Charlie", age=35, height=175, weight=70)
    # المخرجات:
    # Person created with properties:
    # name: Charlie
    # age: 35
    # height: 175
    # weight: 70

elif test_case == "boolean_values":
    create_person(name="David", is_student=True, is_employed=False)
    # المخرجات:
    # Person created with properties:
    # name: David
    # is_student: True
    # is_employed: False

elif test_case == "nested_structures":
    create_person(name="Eve", hobbies=["Reading", "Swimming", "Coding"], 
                 address={"city": "Boston", "state": "MA", "zip": "02108"})
    # المخرجات:
    # Person created with properties:
    # name: Eve
    # hobbies: ['Reading', 'Swimming', 'Coding']
    # address: {'city': 'Boston', 'state': 'MA', 'zip': '02108'}

elif test_case == "unicode_characters":
    create_person(name="José", city="São Paulo", country="Brasil")
    # المخرجات:
    # Person created with properties:
    # name: José
    # city: São Paulo
    # country: Brasil