عرض مصدر Python/property

<noinclude>{{DISPLAYTITLE:الدالة <code>property()‎</code> في بايثون}}</noinclude>
تعيد الدّالة <code>property()‎</code> خاصيّةً يُمكن التّحكم في تابع الحصول على قيمتها، وتابع تعيين قيمة لها، وتابع حذف قيمتها، وسلسلة التّوثيق (docstring) الخاصّة بها. ويُمكن كذلك استخدامها كمُزخرف لتحويل تابع إلى خاصيّة.

== البنية العامة ==
<syntaxhighlight lang="python3">
property(fget=None, fset=None, fdel=None, doc=None)
</syntaxhighlight>

== المعاملات ==
=== <code>fget</code> ===
الدالّة التّي ستُستخدم للحصول على قيمة الخاصيّة.

=== <code>fset</code> ===
الدالّة التّي ستُستخدم لتعيين قيمة للخاصيّة.

=== <code>fdel</code> ===
الدالّة التّي ستُستخدم لحذف قيمة الخاصيّة.

=== <code>doc</code> ===
سلسلة توثيق الخاصيّة.

== القيمة المعادة ==
كائن خاصيّة (property object).

الكائن المُعاد يحتوي على الخاصيّات <code>fget</code>، و<code>fset</code>، و<code>fdel</code> التي تُمثّل الدّوال المُمرّرة.

== أمثلة ==
عادة ما تُستخدم الدّالة لتعريف خاصيّة مُدارة كالخاصيّة <code>x</code> في المثال التّالي:
<syntaxhighlight lang="python3">
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.") # إنشاء الخاصيّة
</syntaxhighlight>
إن كان الكائن <code>c</code> نسخة من الصّنف <code>C</code>، فالجملة <code>‎c‎.‎x‎</code> ستستدعي دالّة الحصول على القيمة، و<code>‎c‎.‎x ‎=‎ ‎value</code> ستستدعي دالّة ضبط القيمة، و<code>‎del‎ ‎c‎.‎x‎</code> ستستدعي دالّة حذف قيمة الخاصيّة.

إن أُعطِيَت قيمة للمُعامل <code>doc</code>، فستكون قيمته هي سلسلة توثيق الخاصيّة. أمّا إن لم تُمرّر قيمة للمُعامل، فستنسخ الخاصيّة سلسلة توثيق الدّالة <code>fget</code> (إن كانت موجودة). ما يسمح بإنشاء خاصيّات قابلة للقراءة فقط (read-only) باستخدام الدّالة <code>property()‎</code> كمُزخرف:
<syntaxhighlight lang="python3">
class Parrot:
    def __init__(self):
        self._voltage = 100000

    @property
    def voltage(self):
        """الحصول على قيمة الجهد الحاليّة"""
        return self._voltage
</syntaxhighlight>
يُحوّل المُزخرِف <code>‎@‎property</code> التّابع <code>voltage()‎</code> إلى دالّة تحصل على قيمة الخاصيّة ذات نفس الاسم، وتكون سلسلة التّوثيق الخاصّة بالخاصيّة <code>voltage</code> هي السّلسلة <code>"الحصول على قيمة الجهد الحاليّة"</code>. ما يعني بأنّك تستطيع الحصول على قيمة الخاصيّة <code>voltage</code> كما يلي (لاحظ أنّنا لم نستدعي التّابع <code>voltage()‎</code>):
<syntaxhighlight lang="python3">
>>> p = Parrot()
>>> p.voltage
100000
</syntaxhighlight>

كائن الخاصيّة يحتوي على التّابع <code>voltage</code> للحصول على القيمة والتّابع <code>voltage</code> لضبط قيمة للخاصيّة و<code>voltage</code> لحذف قيمة الخاصيّة، ويُمكن استخدام هذه التّوابع كمُزخرِفات تُنشؤ نسخةً من الخاصيّة ذات دوالٍ مُتحكّمةٍ تتمثّل في الدّوال المُزخرَفة. بالمثال يتّضح المقال:
<syntaxhighlight lang="python3">
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
</syntaxhighlight>
الشّيفرة أعلاه مُكافئةٌ تمامًا مع الشّيفرة في المثال الأول. لكن تأكّد من أن تُسمّيَ الدّوال المُضافَة بنفس اسم الخاصيّة الأصليّة (الاسم <code>x</code> في هذه الحالة.)

== انظر أيضًا ==
* [[Python/documentation-strings|سلاسل التوثيق النصية في بايثون]].
* [[Python/class-definition|تعريف الأصناف في بايثون]].

== مصادر ==
* [https://docs.python.org/3/library/functions.html#property قسم الدالة property في صفحة Functions في توثيق Python الرسمي].
[[تصنيف:Python]]
[[تصنيف:Python Function]]
[[تصنيف:Python Built-in Functions]]