2.14. تعريف الدوال¶

تحزم الدالة كتلة من الشيفرة تحت اسم بحيث يمكن استدعاؤها من أماكن عديدة. وأينما ظهر حساب أو إجراء أو جزء من العمل أكثر من مرة، تحوّله الدالة إلى شيء واحد مسمى.

الكلمة المفتاحية هي def:

def greet(name):
    print("hello,", name)

greet("Alice")
greet("Bob")

الناتج:

hello, Alice
hello, Bob

السطر الذي يبدأ بـ def هو التعريف -- فهو ينشئ الدالة لكنه لا يشغّل جسمها. واستدعاء greet("Alice") هو ما يشغّل الكتلة المزاحة.

2.14.1. المعاملات والوسائط¶

الأسماء داخل الأقواس في سطر def هي معاملات -- نائبات للقيم التي سيوفرها المستدعي. والقيم الفعلية المُمرَّرة هي وسائط. يمكن للدالة أن تأخذ صفرًا أو أكثر من المعاملات:

def square(x):
    return x * x

def add(a, b):
    return a + b

def is_even(n):
    return n % 2 == 0

الاستدعاء بعدد خاطئ من الوسائط يرفع الاستثناء TypeError على الفور.

2.14.2. return¶

تنهي عبارة return الدالة فورًا وتعيد قيمة إلى المستدعي:

def absolute(x):
    if x < 0:
        return -x
    return x

الدالة التي لا تصل أبدًا إلى return (أو لها return مجردة بلا قيمة) تعيد None:

>>> def shout(text):
...     print(text.upper())
...
>>> result = shout("hi")
HI
>>> print(result)
None

يمكن أن تحتوي الدالة على عدة عبارات return؛ تفوز أول واحدة يُوصَل إليها، ويُتخطّى باقي الجسم.

2.14.2.1. إعادة قيم متعددة¶

يعيد Python كائنًا واحدًا لكل استدعاء، لكن ذلك الكائن يمكن أن يكون tuple -- ويمكن للمستدعي فك تعبئته على الفور:

def minmax(values):
    return (min(values), max(values))

lo, hi = minmax([3, 1, 4, 1, 5, 9])

الأقواس المحيطة بالقيمة المُعادة اختيارية؛ فـ return a, b و return (a, b) متماثلتان.

2.14.3. سلاسل التوثيق (Docstrings)¶

سلسلة نصية حرفية موضوعة كأول عبارة في جسم الدالة تُعد سلسلة توثيق (docstring). تُخزَّن على كائن الدالة وهي ما تعرضه help():

def scale(value, factor):
    """Multiply ``value`` by ``factor`` and return the result."""
    return value * factor

تعرض الواجهة (IDE) سلاسل التوثيق في تلميحات الأدوات عندما يحوم المؤشر فوق اسم الدالة، لذا فحتى الملخص المكون من سطر واحد يستحق العناء. تتيح السلاسل ثلاثية الاقتباس لسلسلة التوثيق أن تمتد على عدة أسطر عندما تكون التفاصيل الإضافية مفيدة.

2.14.4. اصطلاحات التسمية¶

تستخدم أسماء الدوال أسلوب snake_case -- كلمات بأحرف صغيرة مفصولة بشرطات سفلية. ينبغي أن يصف الاسم ما تفعله الدالة:

جيد: read_temperature، parse_header، is_valid.
تجنّب: do_stuff، handle1، temp_func.

الشرطة السفلية البادئة (_helper) تشير إلى أن الدالة داخلية للوحدة الخاصة بها. هذا الاصطلاح محترم على نطاق واسع لكن Python لا يفرضه.