Properties in Python - Learn By Example

Some object-oriented languages such as Java and C# support private object attributes; which cannot be directly accessed from outside. Programmers often have to write getter and setter methods to access such private attributes.

However in Python, all the attributes and methods are public, so it is useless to write getters or setters.

If you want to prevent direct access to an attribute, you should define it as a property.

It is a simple way to customize access to an attribute.

Define a Property

Let’s see how properties can be defined in Python. 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, two methods are defined in the class – a getter called get_name() and a setter called set_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
    
    # make a property
    name = property(get_name, set_name)

The get_name() and set_name() methods act like normal getter and setter until this line.

name = property(get_name, set_name)

It creates a new class attribute called ‘name’ and defines the two methods as 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

A great feature of a property is that it looks like a normal attribute, but when you access it, it automatically triggers the getter and setter methods.

property() Function

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.

The property() function has the following syntax:

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

This creates a 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.

Rewriting Person Class

Let’s rewrite our previous example, including the deleter method and docstring.

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')

Here is an example of the new class in use:

p = Person('Bob')

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

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

# docstring
print('Docstring:', Person.name.__doc__)
# Prints Docstring: name of the person

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

@property – Property as a Decorator

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

Please note that you cannot define @name.setter and @name.deleter decorators unless you already establish name as a property using @property decorator.

Real World Example

Properties are generally used in cases where you want to add extra processing (e.g., type checking or validation) to the getting or setting of an instance attribute.

For example, below code defines a property that adds simple type checking to an attribute:

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

    @property
    def name(self):
        return self._name

    @name.setter
    def name(self, value):
        if not isinstance(value, str):
            raise TypeError('Expected a string')
        self._name = value

    @name.deleter
    def name(self):
        raise AttributeError("Can't delete attribute")

p = Person(42)      # Triggers TypeError: Expected a string

p = Person('Bob')

print(p.name)       # Prints Bob

p.name = 42         # Triggers TypeError: Expected a string

del p.name          # Triggers AttributeError: Can't delete attribute

In above example,

1. Type checking is performed in the setter function. It checks whether the type of the assigned value is a string. If it is other than string, the TypeError exception is raised.

p.name = 42       # Triggers TypeError: Expected a string

2. AttributeError exception is raised when user tries to delete an attribute.

del p.name        # Triggers AttributeError: Can't delete attribute

3. Type checking is performed during initialization as well.

p = Person(42)    # Triggers TypeError: Expected a string

The whole point of our example is to apply type checking when setting an attribute which means that checking should also be done during initialization.

That’s why the __init__() method sets self.name instead of self._name. By setting self name, the __init__() method automatically calls the setter method.

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

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

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

Extending a Property in a Subclass

Because a property is not a single method but a collection of getter, setter, and deleter methods, extending it in a subclass introduces many problems.

You need to figure out whether you will redefine all of the methods together or just one of the methods.

Here is an example of a class that inherits from Person and extends the name property with new functionality:

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

class SubPerson(Person):
    @property
    def name(self):
        print('Inside subperson getter')
        return super().name

    @name.setter
    def name(self, value):
        print('Inside subperson setter')
        super(SubPerson, SubPerson).name.__set__(self, value)

    @name.deleter
    def name(self):
        print('Inside subperson deleter')
        super(SubPerson, SubPerson).name.__delete__(self)

Here is an example of the new class in use:

s = SubPerson('Bob')

# calls the getter
print(s.name)
# Prints Inside subperson getter
# Prints Getting name: Bob

# calls the setter
s.name = 'Sam'
# Prints Inside subperson setter
# Prints Setting name to Sam

# calls the deleter
del s.name
# Prints Inside subperson deleter
# Prints Deleting name

In above example, all of the property methods are redefined together. Within each method, super() function is used to call the superclass’s implementation.

If you only want to redefine one of the methods, it’s not enough to use @property by itself, use code such as the following:

class SubPerson(Person):
    @Person.name.getter
    def name(self):
        print('Inside subperson getter')
        return super().name

When you do this, only the getter method is replaced and the remaining methods of the property are copied.

If you just want to redefine the setter, use this code:

class SubPerson(Person):
    @Person.name.setter
    def name(self, value):
        print('Inside subperson setter')
        super(SubPerson, SubPerson).name.__set__(self, value)