Python property() Function

The property() function allows to create a special type of attribute called a property for a class.

Syntax

property(fget, fset, fdel, doc)

property() Parameters

Python property() function parameters:

property() Return Value

Python property() function returns:

• a property attribute from the given getter, setter, and deleter.
• a base property attribute that does not contain any getter, setter, or deleter, if no arguments are given.

Observations

attrib = property(fget, fset, fdel, doc) creates a new class attribute called attrib and defines the three methods as properties.

So:

• When you reference x.attrib, Python calls the fget method.
• When you assign x.attrib = value, Python calls the fset method and passes value as an argument.
• When you execute del x.attrib, Python calls the fdel method.

Examples

Example 1: Basic Example

class Person:
    def __init__(self, name):
        self._name = name

    def get_name(self):
        print('Getting name')
        return self._name

    def set_name(self, value):
        print('Setting name to ' + value)
        self._name = value

    def del_name(self):
        print('Deleting name')
        del self._name

    name = property(get_name, set_name, del_name, doc='name of the person')

The get_name(), set_name() and del_name() methods act like normal getter, setter and deleter until this line:

name = property(get_name, set_name, del_name, doc='name of the person')

because it creates a new class attribute called name and defines the three methods as its properties.

So, now, when you refer to the name attribute of any Person object, Python actually calls the get_name() method:

p = Person('Ryan')
print(p.name)   # Prints Getting name: Ryan

In the same way, when you assign a value to the name attribute, the set_name() method is called.

p.name = "Tom"  # Output: Setting name to Tom
print(p.name)   # Output: Getting name: Tom

And when you try to delete the name attribute, the del_name() method is called.

del p.name  # Output: Deleting name

Moreover, you can access the docstring through the __doc__ attribute:

print(Person.name.__doc__)  # Output: name of the person

Example 2: Computed Attributes

Properties can also be a way to define "computed attributes", i.e. attributes that are not actually stored, but are calculated dynamically on demand.

For example, let's define a class Rectangle that has a computed attribute for the area:

class Rectangle(object):
    def __init__(self, width, height):
        self.width = width
        self.height = height

    def area(self):
        return self.width * self.height

    area = property(area)

Then we can do:

r = Rectangle(10, 5) # Create a Rectangle object with width=10 and height=5

print(r.area)        # Output: 50

output

50

Moreover, you can change width and height and the area property will be computed accordingly:

r = Rectangle(10, 5)
print(r.area)   # Output: 50

r.width = 2
print(r.area)   # Output: 10

r.height = 10
print(r.area)   # Output: 20

output

50
10
20

Equivalent Method with @property decorator

Instead of using property(), a more elegant way is to use the Python decorator @property to assign the getter, setter, and deleter.

Decorators for an attribute called attr must be used in this way:

• @property decorator goes before the getter method
• @attr.setter decorator goes before the setter method
• @attr.deleter decorator goes before the deleter method

For example, the Person class with decorators:

class Person:
    def __init__(self, name):
        self._name = name

    @property
    def name(self):
        print('Getting name')
        return self._name

    @name.setter
    def name(self, value):
        print('Setting name to ' + value)
        self._name = value

    @name.deleter
    def name(self):
        print('Deleting name')
        del self._name

and so you can do:

p = Person('Tom')

print('The name is:', p.name)

p.name = 'Ryan'

del p.name

output

Getting name
The name is: Tom
Setting name to Ryan
Deleting name