عرض مصدر Python/weakref/ref

<noinclude>{{DISPLAYTITLE:الدالة <code>weakref.ref()‎</code> في بايثون}}</noinclude>

تنشئ هذه الدالة البانية لكائنات <code>weakref</code> إشارة ضعيفة إلى الكائن المعطى.

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

<syntaxhighlight lang="python3">
weakref.ref(object[, callback])
</syntaxhighlight>

== المعاملات ==

===<code>object</code>===

الكائن المراد إنشاء إشارة ضعيفة إليه.

===<code>callback</code>===

في حال توفّر قيمة للمعامل <code>callback</code> ولم يأخذ القيمة <code>None</code> وكان كائن <code>weakref</code> المعاد حيًّا، فسيُستدعى <code>callback</code> عندما يوشك الكائن على أن يُنهى، وسيمرّر كائن الإشارة الضعيفة كمعامل وحيد للاستدعاء الخلفي، ولن يكون الكائن المشار إليه متاحًا بعد ذلك.

يمكن إنشاء إشارات ضعيفة متعددة للكائن الواحد، وتُستدعى الاستدعاءات الخلفية المسجّلة لكل إشارة ضعيفة حسب ترتيب التسجيل، من الأحدث إلى الأقدم.

تُسجّل الاستثناءات التي يطلقها الاستدعاء الخلفي في خرج الأخطاء المعيارية، ولكن لا يمكن لها أن تتمدد، ويجري التعامل معها بنفس الطريقة المتبعة مع الأخطاء المنبثقة من التابع <code>‎__del__()‎</code>.

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

تعيد هذه الدالة البانية إشارة ضعيفة إلى الكائن المعطى، ويمكن استعادة الكائن الأصلي عن طريق استدعاء كائن الإشارة إن كان الكائن المشار إليه حيًّا. أما إن كان الكائن المشار إليه غير حيٍّ، فسيؤدّي استدعاء كائن الإشارة إلى إعادة القيمة <code>None</code>.

تكون الإشارات الضعيفة قابلة للتقطيع hashable إن كان الكائن المعطى قابلًا للتقطيع. وتحافظ الإشارات الضعيفة على قيمة التقطيع الخاصّة بها حتى بعد حذف الكائن المعطى. إن كان أول استدعاء للدالة <code>hash()‎</code> بعد حذف الكائن المعطى، فإنّ الاستدعاء سيطلق الخطأ <code>TypeError</code>.

يمكن اختبار المساواة على الإشارات الضعيفة، ولكن لا يمكن اختبار الترتيب عليها. إن كانت الكائنات المشار إليها حيّة، فإنّ علاقة المساواة التي تربط بين إشارتين معيّنتين، هي نفسها العلاقة التي تربط بين الكائنين المشار إليهما (بصرف النظر عن <code>callback</code>). وإن جرى حذف أحد الكائنين المشار إليهما، فإن الإشارتين تكونان متساويتين فقط إن كان كائنا الإشارة هما نفس الكائن.

يعدّ هذا نوعًا قابلًا للتفريع أكثر منه دالة بانية.

== الخاصية <code>__callback__</code> ==
خاصية للقراءة فقط، وتعيد الاستدعاء الخلفي المرتبط بكائن <code>weakref</code>. إن لم يكن هناك استدعاء خلفي فإنّ الكائن المشار إليه بواسطة <code>weakref</code> لن يكون حيًّا، وستأخذ هذه الخاصية القيمة None.

'''ملاحظة:''' أضيفت الخاصية __callback__ في الإصدار 3.4 من بايثون.

== مصادر ==
[https://docs.python.org/3/library/weakref.html#weakref.ref صفحة Weak references في توثيق بايثون الرسمي.]

[[تصنيف:Python]]
[[تصنيف:Python Modules]]