Python/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 في هذه الحالة.)

انظر أيضًا

• سلاسل التوثيق النصية في بايثون.
• تعريف الأصناف في بايثون.

مصادر

• قسم الدالة property في صفحة Functions في توثيق Python الرسمي.