How to Master Python's property() Function / Decorator With Practical Examples Insights

Python offers a multitude of powerful features for advanced developers. Among these features is the `property()` function or property decorator, which is a versatile tool for managing attributes and creating elegant, maintainable code. In this article, we’ll dive deep into the `property()` function / property decorator, exploring its syntax, purpose, and real-world applications through a series of illustrative examples.

Table of Contents

1. Understanding the property() Function.

The `property()` function is a built-in Python function that allows you to define custom behavior for getting, setting, and deleting attributes of an object.

It acts as a decorator, transforming methods into special properties, giving you control over how you access and modify object attributes.
This can be incredibly useful for encapsulation, data validation, and maintaining code integrity.

1.1 Syntax of property().

Here’s the basic syntax of the `property()` function:
```
property(fget=None, fset=None, fdel=None, doc=None)
```

`fget` (optional): A function to get the attribute value.
`fset` (optional): A function to set the attribute value.
`fdel` (optional): A function to delete the attribute.

`doc` (optional): A string that documents the attribute.
Let’s explore each of these parameters in detail by examples.

2. Understanding the Python Property Decorator.

The Python property decorator is a built-in function that allows you to define methods that are accessed like attributes.

It is used to manage the access, modification, and deletion of class attributes, providing a level of abstraction and control.
In essence, it transforms ordinary class attributes into properties with custom-defined getter, setter, and deleter methods.

2.1 Python Property Decorator Demo.

Let’s take a closer look at how the property decorator is defined:

class MyClass:
    def __init__(self, value):
        self._value = value  # Note the underscore convention for private attribute

    @property
    def value(self):
        return self._value

    @value.setter
    def value(self, new_value):
        if new_value < 0:
            raise ValueError("Value cannot be negative")
        self._value = new_value

In this example, we’ve created a class MyClass with a private attribute _value.
By using the @property decorator, we can define a getter method value() to access the attribute’s value.
The @value.setter decorator defines a setter method to modify the attribute’s value, and it includes custom validation logic.

3. Examples of property() Function / Decorator in Action.

3.1 Example 1: Basic Usage of Python property() Function.

Source code.

class Circle:
    def __init__(self, radius):
        self._radius = radius

    def get_radius(self):
        print('get_radius() is called.')
        return self._radius

    def set_radius(self, value):
        print('set_radius() is called.')
        if value < 0:
            raise ValueError("Radius cannot be negative")
        self._radius = value

    def area(self):
        return 3.14 * self._radius ** 2

    radius = property(get_radius, set_radius)

def test_circle():    
    c = Circle(5)
    print(c.radius)  # Calls get_radius
    c.radius = 7      # Calls set_radius
    print(c.radius) # Calls get_radius

if __name__ == "__main__":
    test_circle()

Below is the above source code execution output.

get_radius() is called.
5
set_radius() is called.
get_radius() is called.
7

In this example, we use the `property()` function to create a computed property for the `radius` attribute, ensuring that it can’t be negative.

3.2 Example 2: Using Python @property Decorators.

Source code.

class Circle1:
    def __init__(self, radius):
        self._radius = radius

    @property
    def radius(self):
        print('radius() is called.')
        return self._radius

    @radius.setter
    def radius(self, value):
        print('radius.setter is called.')
        if value < 0:
            raise ValueError("Radius cannot be negative")
        self._radius = value

    def area(self):
        return 3.14 * self._radius ** 2


def test_circle1():

    c = Circle1(5)
    print(c.radius)  # Calls the radius getter
    c.radius = 7      # Calls the radius setter
    print(c.radius)  # Calls the radius getter


if __name__ == "__main__":
    test_circle1()

Below is the execution output of the above Python source code.

radius() is called.
5
radius.setter is called.
radius() is called.     
7

This example achieves the same result as the previous one but uses property decorators, which are more concise and Pythonic.

3.3 Example 3: Read-Only Properties Using @property Decorator.

Source code.

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

    @property
    def area(self):
        return self._width * self._height
    

def test_rectangle():
    r = Rectangle(4, 5)
    print(r.area)  # Calls the area getter
    r.area = 20     # Raises an AttributeError


if __name__ == "__main__":
    test_rectangle()

When you run the above Python source code, you will get the below output.

    r.area = 20     # Raises an AttributeError
AttributeError: can't set attribute

In this case, we create a read-only property for the `area` attribute by omitting the setter method, ensuring that the attribute can’t be modified directly.

3.4 Example 4: Documenting Properties Using @property Decorator.

Source code.

class Book:
    def __init__(self, title, author):
        self._title = title
        self._author = author

    @property
    def title(self):
        """The title of the book."""
        return self._title

    @property
    def author(self):
        """The author of the book."""
        return self._author


def test_book():
    b = Book("Python Unleashed", "John")
    print(b.title)   # Calls the title getter
    print(b.author)  # Calls the author getter
    help(b)          # Displays documentation for the properties


if __name__ == "__main__":
    test_book()

Below is the above source code execution output.

Python Unleashed
John
Help on Book in module __main__ object:

class Book(builtins.object)
 |  Book(title, author)
 |
 |  Methods defined here:
 |
 |  __init__(self, title, author)
 |      Initialize self.  See help(type(self)) for accurate signature.
 |
 |  ----------------------------------------------------------------------
 |  Readonly properties defined here:
 |
 |  author
 |      The author of the book.
 |
 |  title
 |      The title of the book.
 |
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |
 |  __dict__
 |      dictionary for instance variables (if defined)
 |
 |  __weakref__
 |      list of weak references to the object (if defined)

In this example, we document the properties using the `doc` parameter, making it easier for developers to understand their purpose.

3.5 Example 5: Temperature Converter.

Imagine you have a class representing temperature in Celsius, and you want to provide an option to retrieve the temperature in Fahrenheit.

You can use the @property decorator to create a fahrenheit property:

class Temperature:
    def __init__(self, celsius):
        self._celsius = celsius

    @property
    def fahrenheit(self):
        return (self._celsius * 9/5) + 32

Now, you can access the temperature in Fahrenheit effortlessly:

temp = Temperature(25)
print(temp.fahrenheit)  # Output: 77.0

Below is the full source code.

class Temperature:
    def __init__(self, celsius):
        self._celsius = celsius

    @property
    def fahrenheit(self):
        return (self._celsius * 9/5) + 32


def test_temperature():
    temp = Temperature(25)
    print(temp.fahrenheit)  # Output: 77.0


if __name__ == "__main__":
    test_temperature()

When you run the above source code, it will generate the below output.
```
77.0
```

3.6 Example 6: Bank Account Balance.

Suppose you have a BankAccount class, and you want to ensure that the account balance is never negative.

You can use the @property decorator to enforce this rule:

class BankAccount:
    def __init__(self):
        self._balance = 0

    @property
    def balance(self):
        return self._balance

    @balance.setter
    def balance(self, new_balance):
        if new_balance < 0:
            raise ValueError("Balance cannot be negative")
        self._balance = new_balance

Now, you can safely set the account balance:

account = BankAccount()
account.balance = 1000
print(account.balance)  # Output: 1000

account.balance = -100  # this will trigger the error.
print(account.balance)

Below is the full source code.

class BankAccount:
    def __init__(self):
        self._balance = 0

    @property
    def balance(self):
        return self._balance

    @balance.setter
    def balance(self, new_balance):
        if new_balance < 0:
            raise ValueError("Balance cannot be negative")
        self._balance = new_balance

def test_bank_account():
    account = BankAccount()
    account.balance = 1000
    print(account.balance)  # Output: 1000

    account.balance = -100  # this will trigger the error.
    print(account.balance)  


if __name__ == "__main__":
    test_bank_account()

When you run the above code, you will get the below error message.

    raise ValueError("Balance cannot be negative")
ValueError: Balance cannot be negative

4. Conclusion.

The `property()` function is a powerful tool that allows you to customize attribute access in your Python classes.
Whether you need to enforce data validation, create computed properties, or improve code readability, `property()` can help you achieve your goals.

By mastering this feature, you can write cleaner, more maintainable code and unlock the full potential of Python in your projects.

How to Master Python’s property() Function / Decorator With Practical Examples Insights

1. Understanding the property() Function.

1.1 Syntax of property().

2. Understanding the Python Property Decorator.

2.1 Python Property Decorator Demo.

3. Examples of property() Function / Decorator in Action.

3.1 Example 1: Basic Usage of Python property() Function.

3.2 Example 2: Using Python @property Decorators.

3.3 Example 3: Read-Only Properties Using @property Decorator.

3.4 Example 4: Documenting Properties Using @property Decorator.

3.5 Example 5: Temperature Converter.

3.6 Example 6: Bank Account Balance.

4. Conclusion.

Leave a Comment Cancel Reply