عرض مصدر Python/functools/update wrapper

<noinclude>{{DISPLAYTITLE:الدالة <code>functools.update_wrapper()‎</code> في بايثون}}</noinclude>
تُحدّث الدّالة <code>functools.update_wrapper()‎</code> دالّة مُحيطةً (wrapper) لتبدوَ مثل الدّالة المُحاطة (wrapped).

المُعاملات الاختياريّة هي صفوفٌ تُستخدم لتحديد أيّ خاصيّات الدّالة الأصليّة ستُعيّن مُباشرة للخاصيّات الموافقة لها على الدّالة المُحيطة وأيّ الخاصيّات من خاصيّات الدّالة المُحيطة ستُحدَّثُ بالخاصيّات المُوافقة لها في الدّالة الأصليّة. القيم الافتراضيّة لهذه المُعاملات هي الثّوابت المُتاحة على مستوى الوحدة:
-<code>WRAPPER_ASSIGNMENTS‎</code>: والتي تُعيّن كلّا من <code>‎__module__‎</code>، و<code>‎__name__‎</code>، و<code>‎__qualname__‎</code>، و<code>‎__annotations__‎‎</code>، و<code>‎__doc__‎‎</code>، التي تُعدّ خاصيّاتٍ تُضيف معلومات حول الدّالة.
-<code>WRAPPER_UPDATES‎</code>: التي تُحدّث خاصيّة <code>‎__dict__‎</code> الخاصّة بالدّالة المُحيطة، أي قاموس النّسخة (the instance dictionary) الخاصّ بها.

تُضيف هذه الدّالة الخاصيّة <code>‎__wrapped__‎</code> إلى الدّالة المُحيطة، وهذه الخاصيّة تُشير إلى الدّالة المُحاطة، وذلك للتّمكن من الوصول إلى الدّالة الأصليّة للتحقيق فيها (تجاهل مُزخرف تخبئة مثل المزخرف <code>functools.lru_cache()‎</code> مثلًا).

تُستخدم هذه الدّالة أساسًا في الدّوال المُزخرِفة (decorator functions) التي تُحيط الدّالة المُزخرفَة وتُعيد الدّالة المُحيطة. إن لم تُحدَّث الدّالة المُحيطة، فالبيانات الوصفيّة (metadata) الخاصّة بالدّالة المُعادة ستُشير إلى تعريف الدّالة المُحيطة عوضًا عن تعريف الدّالة الأصليّة، الشيء الذي لا يكون مُفيدًا عادةً. 

يُمكن استخدام الدّالة <code>functools.update_wrapper()‎</code> مع الكائنات القابلة للاستدعاء الأخرى التي لا تكون دوالا.  الخاصيّات التي تكون في الصّف <code>assigned‎</code> أو الصّف <code>updated</code> والتي تكون مفقودةً في الكائن المُحاط ستُتجاهَل (ولن تُحاول هذه الدّالة ضبط قيم لهذه الخاصيّات على الدّالة المُحيطة). يُطلق الاستثناء <code>AttributeError</code> إن كانت الدّالة المُحيطة تفتقد أحد الخاصيّات المذكورة في الصّف <code>updated</code>.

== البنية العامة ==
<syntaxhighlight lang="python3">
functools.update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)
</syntaxhighlight>

== المعاملات ==
=== <code>wrapper</code> ===
الدّالة المُحيطة.

=== <code>wrapped</code> ===
الدّالة المُحاطة.

=== <code>assigned</code> ===
الخاصيّات التي ستُعيّن.

=== <code>updated</code> ===
الخاصيّات التي ستُحدّث.

== القيمة المعادة ==
تُحدّث دالّة مُحيطةً لتبدوَ مثل الدّالة المُحاطة.

== أمثلة ==

المثال التّالي يوضّح كيفيّة إنشاء دالة مُحيطة دون تحديثها بالدّالة، لاحظ أنّ اسم الدّالة خطأ:
<syntaxhighlight lang="python3">
>>> def to_str(function):
...     def str_val(*args, **kwargs):
...         result = function(*args, **kwargs)
...         return str(result)
...     return str_val # هنا نُعيد الدّالة المُحيطة
... 
>>> @to_str
... def square(n):
...     return n*n
... 
>>> square(40)
'1600'

>>> square.__name__ # اسم الدّالة خطأ
'to_str'
</syntaxhighlight>

وهنا نُحدّث الدّالة المُحيطة لتبدو مثل الدّالة المُحاطة، لاحظ أنّ اسم الدّالة المُحاطة أصبح يُعبّر عنها بشكل صحيح:

<syntaxhighlight lang="python3">
>>> def to_str(function):
...     def str_val(*args, **kwargs):
...         result = function(*args, **kwargs)
...         return str(result)
...     return functools.update_wrapper(str_val, function) # نُحدّث الدّالة المُحيطة بالدّالة الأصليّة قبل إعادتها
... 

>>> @to_str
... def _square(n):
...     return n*n
... 


>>> _square.__name__ # اسم الدّالة صحيح
'_square'
</syntaxhighlight>

== انظر أيضًا ==
* [[Python/defining-functions|تعريف الدوال في بايثون]].

== مصادر ==
* [https://docs.python.org/3/library/functools.html#functools.update_wrapper قسم الدالة functools.update_wrapper في توثيق Python الرسمي].
[[تصنيف:Python]]
[[تصنيف:Python Function]]
[[تصنيف:Python functools]]