الدالة property() في بايثون
تعيد الدّالة property() خاصيّةً يُمكن التّحكم في تابع الحصول على قيمتها، وتابع تعيين قيمة لها، وتابع حذف قيمتها، وسلسلة التّوثيق (docstring) الخاصّة بها. ويُمكن كذلك استخدامها كمُزخرف لتحويل تابع إلى خاصيّة.
البنية العامة
property(fget=None, fset=None, fdel=None, doc=None)
المعاملات
fget
الدالّة التّي ستُستخدم للحصول على قيمة الخاصيّة.
fset
الدالّة التّي ستُستخدم لتعيين قيمة للخاصيّة.
fdel
الدالّة التّي ستُستخدم لحذف قيمة الخاصيّة.
doc
سلسلة توثيق الخاصيّة.
القيمة المعادة
كائن خاصيّة (property object).
الكائن المُعاد يحتوي على الخاصيّات fget، وfset، وfdel التي تُمثّل الدّوال المُمرّرة.
أمثلة
عادة ما تُستخدم الدّالة لتعريف خاصيّة مُدارة كالخاصيّة x في المثال التّالي:
class C:
def __init__(self):
self._x = None
def getx(self):
return self._x
def setx(self, value):
self._x = value
def delx(self):
del self._x
x = property(getx, setx, delx, "The 'x' property.") # إنشاء الخاصيّة
إن كان الكائن c نسخة من الصّنف C، فالجملة c.x ستستدعي دالّة الحصول على القيمة، وc.x = value ستستدعي دالّة ضبط القيمة، وdel c.x ستستدعي دالّة حذف قيمة الخاصيّة.
إن أُعطِيَت قيمة للمُعامل doc، فستكون قيمته هي سلسلة توثيق الخاصيّة. أمّا إن لم تُمرّر قيمة للمُعامل، فستنسخ الخاصيّة سلسلة توثيق الدّالة fget (إن كانت موجودة). ما يسمح بإنشاء خاصيّات قابلة للقراءة فقط (read-only) باستخدام الدّالة property() كمُزخرف:
class Parrot:
def __init__(self):
self._voltage = 100000
@property
def voltage(self):
"""الحصول على قيمة الجهد الحاليّة"""
return self._voltage
يُحوّل المُزخرِف @property التّابع voltage() إلى دالّة تحصل على قيمة الخاصيّة ذات نفس الاسم، وتكون سلسلة التّوثيق الخاصّة بالخاصيّة voltage هي السّلسلة "الحصول على قيمة الجهد الحاليّة". ما يعني بأنّك تستطيع الحصول على قيمة الخاصيّة voltage كما يلي (لاحظ أنّنا لم نستدعي التّابع voltage()):
>>> p = Parrot()
>>> p.voltage
100000
كائن الخاصيّة يحتوي على التّابع getter للحصول على القيمة والتّابع setter لضبط قيمة للخاصيّة وdeleter لحذف قيمة الخاصيّة، ويُمكن استخدام هذه التّوابع كمُزخرِفات تُنشؤ نسخةً من الخاصيّة ذات دوالٍ مُتحكّمةٍ تتمثّل في الدّوال المُزخرَفة. بالمثال يتّضح المقال:
class C:
def __init__(self):
self._x = None
@property
def x(self):
"""The 'x' property."""
return self._x
@x.setter
def x(self, value):
self._x = value
@x.deleter
def x(self):
del self._x
الشّيفرة أعلاه مُكافئةٌ تمامًا للشّيفرة في المثال الأول. لكن تأكّد من أن تُسمّيَ الدّوال المُضافَة بنفس اسم الخاصيّة الأصليّة (الاسم x في هذه الحالة.)