property()

The built-in property() function lets you add managed attributes—also known as properties—to your custom classes. It allows you to define methods in a class that behave like attributes, enabling you to control access, mutation, and deletion of the underlying data without changing the class’s public API:

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

    @property
    def radius(self):
        return self._radius

    @radius.setter
    def radius(self, value):
        self._radius = value

# Usage
circle = Circle(10)
print(f"Initial radius: {circle.radius}")
circle.radius = 20
print(f"Updated radius: {circle.radius}")

property() Signature

Python Syntax 
property(fget=None, fset=None, fdel=None, doc=None)

Arguments

Argument Description Default Value
fget A function object that returns the value of the managed attribute None
fset A function object that sets the value of the managed attribute None
fdel A function object that deletes the managed attribute None
doc A string representing the property’s docstring None

Return Value

  • A property object that allows controlled access and mutation of an instance attribute.

property() Examples

With a read-only attribute:

Python point.py 
class Point:
    def __init__(self, x, y):
        self._x = x
        self._y = y

    @property
    def x(self):
        return self._x

    @property
    def y(self):
        return self._y

# Usage:
point = Point(3, 4)
print(p.x)  # Output: 3
print(p.y)  # Output: 4
p.x = 10  # This will raise an AttributeError

With a read-write attribute:

Python 
class Square:
    def __init__(self, side):
        self._side = side

    @property
    def side(self):
        return self._side

    @side.setter
    def side(self, value):
        self._side = value

# Usage
rectangle = Square(10)
print(rectangle.side)  # Output: 10
rectangle.side = 15
print(rectangle.side)  # Output: 15

property() Common Use Cases

The most common use cases for the property() function include the following:

  • Creating read-only, read-write, or write-only attributes
  • Validating input data for attributes
  • Computing attribute values dynamically
  • Logging attribute access and mutation
  • Maintaining backward-compatible public APIs

property() Real-World Example

Here’s an example where you use property() to manage a circle’s radius and diameter. Note that the radius is a user-provided attribute while the diameter is a computed attribute:

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

    @property
    def radius(self):
        return self._radius

    @radius.setter
    def radius(self, value):
        self._radius = float(value)

    @property
    def diameter(self):
        return self.radius * 2

    @diameter.setter
    def diameter(self, value):
        self.radius = value / 2

# Usage
circle = Circle(10)
print(circle.diameter)  # Output: 20.0
circle.diameter = 30
print(circle.radius)    # Output: 15.0

This example demonstrates how property() helps you manage related attributes without changing the public API of a class by turning attributes into methods.

Python's property(): Add Managed Attributes to Your Classes

Tutorial

Python's property(): Add Managed Attributes to Your Classes

In this tutorial, you'll learn how to create managed attributes in your classes using Python's property(). Managed attributes are attributes that have function-like behavior, which allows for performing actions during the attribute access and update.

intermediate best-practices python

For additional information on related topics, take a look at the following resources:

By Leodanis Pozo Ramos • Updated Nov. 21, 2024 • Reviewed by Dan Bader
Python’s Built-in Functions Share Feedback