Python/functools/partial

تعيد الدّالة functools.partial()‎ كائن partial يتصرّف كالدّالة المُعطاة عند استدعائها بما مُرّر من مُعاملات (arguments) ومُعاملات كلمات مفتاحيّة (keyword arguments، أي المُعاملات التي تُمرّر مع ذكر أسمائها إضافةً إلى قيمها). إن استُدعيَ الكائن بمُعاملات إضافيّة، فستُضاف إلى مُعاملات الدّالة، و إن استُدعيَ الكائن بمُعاملات كلمات مفتاحيّة إضافيّة، فستُوسّع وتُعوّض معاملات الكلمات المفتاحيّة السّابقة.

تُستعمل لإنشاء دالّة جزئيّة من دالّة بتمرير قيم افتراضيّة ثابتة لها.

البنية العامة

functools.partial(func, *args, **keywords)

المعاملات

func

الدّالة المرغوب إنشاء دالّة جزئيّة منها.

args

المُعاملات التي ستُمرّر.

keywords

المُعاملات المفتاحيّة التي ستُمرّر.

القيمة المعادة

كائن partial يتصرّف كالدّالة المُعطاة عند استدعائها بما مُرّر من مُعاملات ومُعاملات مفتاحيّة ويُعدّ دالّة جزئيّة من الدّالة الأصليّة ذات قيم ثابتة مُمرّرة مُسبقًا.

كائنات partial تملك ثلاث خاصيّات قابلة للقراءة فقط (read-only):

partial.func

كائن قابل للاستدعاء أو دالّة. ستُوجّه استدعاءات partial إلى الكائن partial.func مع مُعاملات وكلمات مفتاحيّة جديدة.

partial.args

المُعاملات المكانيّة (positional arguments، أي المُعاملات التي تُمرّر قيَمُها دون ذكر اسمها) التي ستُضاف إلى أقصى يسار المُعاملات التي تُمرّر إلى الكائن partial.

partial.keywords

مُعاملات الكلمات المفتاحيّة التي ستُمرّر عندما يُستدعى الكائن partial.

كائنات partial مثلُها مثل الدّوال، إذ تكون كائناتٍ قابلة للاستدعاء، وذات إحالة ضعيفة (weak referencable)، ويُمكن لها أن تمتلك خاصيّات مُعيّنة. لكن هناك بعض الفروقات المُهمّة، على سبيل المثال، الخاصيّتان ‎__name__‎ (التي تحمل اسم الدّالة) و‎__doc__‎ (التي تُمثّل سلسلة التّوثيق النّصيّة) لا تُنشآن تلقائيًّا. إضافةً إلى أنّ كائنات partial المُعرفّة في الأصناف تتصرّف مثل التّوابع السّاكنة ولا تتحوّل إلى توابع مُرتبطة (bound methods) عند البحث عن خاصيّات النّسخة.

أمثلة

تُستخدم الدّالة functools.partial()‎ لإنشاء دالّة جزئيّة تُجمّد جزءًا ممّا يُمرّر إلى الدّالة من مُعاملات، ما يُنشئُ كائنًا ذا توقيع أبسط. على سبيل المثال، يُمكن استعمال الدّالة functools.partial()‎ لإنشاء كائن قابل للاستدعاء يتصرّف مثل الدّالة int()‎ بمُعامل أساس (base) يُساوي افتراضيًّا القيمة 2:

>>> from functools import partial
>>> basetwo = partial(int, base=2)
>>> basetwo('10010')
18

ملاحظات

الدّالة مُكافئة تقريبًا لما يلي:

def partial(func, *args, **keywords):
    def newfunc(*fargs, **fkeywords):
        newkeywords = keywords.copy()
        newkeywords.update(fkeywords)
        return func(*args, *fargs, **newkeywords)
    newfunc.func = func
    newfunc.args = args
    newfunc.keywords = keywords
    return newfunc

انظر أيضًا

• functools.partialmethod: لتابعٍ جزئيّ عوضًا عن دالّة.
• الأعداد الصّحيحة في بايثون.
• تعريف الدوال في بايثون.

مصادر

• قسم الدالة functools.partial في توثيق Python الرسمي.