Python property() Function

Generates a property

Usage

You generate a property by calling the property() built-in function, passing in three methods (getter, setter and deleter) as well as the docstring for the property.

If any argument is passed as None or omitted, that operation is not supported.

Syntax

attrib = property(fget,fset,fdel,doc)

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

Now, 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.

Python uses the argument you passed as doc as the docstring of the attribute.

Basic Example

Here is a simple example in which the Person class is defined.

This class has a single attribute named hidden_name which we do not want people to access directly. Hence, three methods are defined in the class – a getter called get_name(), a setter called set_name() and a deleter called del_name().

class Person():
    def __init__(self, value):
        self.hidden_name = value
    
    # getter function
    def get_name(self):
        print('Getting name:')
        return self.hidden_name

    # setter function
    def set_name(self, value):
        print('Setting name to', value)
        self.hidden_name = value
        
    # deleter function
    def del_name(self):
        print('Deleting name')
        del self.hidden_name

    # make a property
    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')

It creates a new class attribute called ‘name’ and defines the three methods as its properties.

Now when you refer to the name attribute of any Person object, Python actually calls the get_name() method.

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

When you assign a value to the name attribute, the set_name() method is called.

p.name = "Sam"
# Prints Setting name to Sam

print(p.name)
# Prints Getting name: Sam

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

del p.name
# Prints Deleting name

You can access the docstring through the __doc__ attribute.

print(Person.name.__doc__)
# Prints name of the person

Computed Attributes

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

Let’s define a Rectangle class that has two normal attributes (width and height) and one computed attribute (area)

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

    # computed attribute
    def area(self):
        return self.width * self.height

    # make a property
    area = property(area)

Let’s create a Rectangle object with an initial value for its width and height.

r = Rectangle(2, 5)

Now you can call the area as if it were an attribute:

print(r.area)
# Prints 10

Here’s the fun part: you can change the width and height of the rectangle at any time, and the area property will be computed accordingly:

r.width = 3
r.height = 6
print(r.area)
# Prints 18

As you can see we have not specified setter property for an attribute, we can’t set it from the outside. This is handy for read-only attributes:

r.area = 18     # Triggers AttributeError: can't set attribute

Equivalent Method – @property

A more elegant syntax to define properties in a class is to use property as a decorator

In the next example, we’ll define three different methods, each called name() but preceded by different decorators:

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

Here’s how they actually look in the code:

class Person():
    def __init__(self, value):
        self.hidden_name = value
    
    @property
    def name(self):
        print('Getting name:')
        return self.hidden_name

    @name.setter
    def name(self, value):
        print('Setting name to', value)
        self.hidden_name = value
        
    @name.deleter
    def name(self):
        print('Deleting name')
        del self.hidden_name

Here the first method is a getter, and establishes name as being a property. The other two methods attach setter and deleter to the name property.

You can still access name as if it were an attribute:

p = Person('Bob')

# calls the getter
print(p.name)
# Prints Getting name: Bob

# calls the setter
p.name = 'Sam'
# Prints Setting name to Sam

# calls the deleter
del p.name
# Prints Deleting name