الدالة weakref.ref() في بايثون
تنشئ هذه الدالة البانية للكائن ref إشارة ضعيفة إلى الكائن المعطى.
البنية العامة
weakref.ref(object[, callback])
المعاملات
object
الكائن المراد إنشاء إشارة ضعيفة له.
callback
في حال توفّر قيمة للمعامل callback ولم يأخذ القيمة None وكان كائن weakref المعاد حيًّا، فسيُستدعى callback عندما يوشك الكائن على أن يُنهى، وسيمرّر كائن الإشارة الضعيفة كمعامل وحيد للاستدعاء الخلفي، ولن يكون الكائن المشار إليه متاحًا بعد ذلك.
يمكن إنشاء إشارات ضعيفة متعددة للكائن الواحد، وتُستدعى الاستدعاءات الخلفية المسجّلة لكل إشارة ضعيفة حسب ترتيب التسجيل، من الأحدث إلى الأقدم.
تُسجّل الاستثناءات التي يطلقها الاستدعاء الخلفي في خرج الأخطاء المعيارية، ولكن لا يمكن لها أن تتمدد، ويجري التعامل معها بنفس الطريقة المتبعة مع الأخطاء المنبثقة من التابع __del__().
القيمة المعادة
تعيد هذه الدالة البانية إشارة ضعيفة إلى الكائن المعطى، ويمكن استعادة الكائن الأصلي عن طريق استدعاء كائن الإشارة إن كان الكائن المشار إليه حيًّا. أما إن كان الكائن المشار إليه غير حيٍّ، فسيؤدّي استدعاء كائن الإشارة إلى إعادة القيمة None.
تكون الإشارات الضعيفة قابلة للتقطيع hashable إن كان الكائن المعطى قابلًا للتقطيع. وتحافظ الإشارات الضعيفة على قيمة التقطيع الخاصّة بها حتى بعد حذف الكائن المعطى. إن كان أول استدعاء للدالة hash() بعد حذف الكائن المعطى، فإنّ الاستدعاء سيطلق الخطأ TypeError.
يمكن اختبار المساواة على الإشارات الضعيفة، ولكن لا يمكن اختبار الترتيب عليها. إن كانت الكائنات المشار إليها حيّة، فإنّ علاقة المساواة التي تربط بين إشارتين معيّنتين، هي نفسها العلاقة التي تربط بين الكائنين المشار إليهما (بصرف النظر عن callback). وإن جرى حذف أحد الكائنين المشار إليهما، فإن الإشارتين تكونان متساويتين فقط إن كان كائنا الإشارة هما نفس الكائن.
يعدّ هذا نوعًا قابلًا للتفريع أكثر منه دالة بانية.
الخاصية __callback__
خاصية للقراءة فقط، وتعيد الاستدعاء الخلفي المرتبط بكائن weakref. إن لم يكن هناك استدعاء خلفي فإنّ الكائن المشار إليه بواسطة weakref لن يكون حيًّا، وستأخذ هذه الخاصية القيمة None.
ملاحظة: أضيفت الخاصية __callback__ في الإصدار 3.4 من بايثون.