14.15. property(): Create an access-controlled attribute

14.15. `property()`: Create an access-controlled attribute

The purpose of this function is to create a property of a class. A property looks and acts like an ordinary attribute, except that you provide methods that controls access to the attribute.

There are three kinds of attribute access: read, write, and delete. When you create a property, you can provide any or all of three methods that handle requests to read, write, or delete that attribute.

Here is the general method for adding a property named p to a new-style class C.

class C(...):
    def R(self):
        ...read method...
    def W(self, value):
        ...write method...
    def D(self):
        ...delete method...
    p = property(R, W, D, doc)
    ...

where:

R is a method that takes no arguments and returns the effective attribute value. If omitted, any attempt to read that attribute will raise AttributeError.
W is a method that takes one argument and sets the attribute to that argument's value. If omitted, any attempt to write that attribute will raise AttributeError.
D is a method that deletes the attribute. If omitted, any attempt to delete that attribute will raise AttributeError.
doc is a documentation string that describes the attribute. If omitted, defaults to the documentation string of the R method if any, otherwise None.
To retrieve a property's documentation, use this form:
```
C.p.__doc__
```
where C is the class name and p is the property name.

As an example, here is a small class that defines a property named x:

class C(object):
    def __init__(self):
        self.__x=None
    def getx(self):
        print "+++ getx()"
        return self.__x
    def setx(self, v):
        print "+++ setx(%s)" % v
        self.__x  =  v
    def delx(self):
        print "+++ delx()"
        del self.__x
    x=property(getx, setx, delx, "Me property 'x'.")

Assuming that class is defined, here is a conversational example.

>>> c=C()
>>> print c.x
+++ getx()
None
>>> print C.x.__doc__
Me property 'x'.
>>> c.x=15
+++ setx(15)
>>> c.x
+++ getx()
15
>>> del c.x
+++ delx()
>>> c.x
+++ getx()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 6, in getx
AttributeError: 'C' object has no attribute '_C__x'

Python 2.5 quick reference

14.15. property(): Create an access-controlled attribute

14.15. `property()`: Create an access-controlled attribute