How the @property Decorator Works in Python

A property is an object placed on a class that intercepts attribute access. @property is decorator syntax for calling property with the function immediately below it. The resulting property object provides .setter() and .deleter() methods, which return updated property objects and assign them back to the same class attribute name.

Python attributes do not always have to be plain stored values. A class can define a descriptor—such as a property—that runs code when an attribute is read, assigned, or deleted.

A property can hold up to four pieces of information:

• a getter function (fget) for obj.x
• a setter function (fset) for obj.x = value
• a deleter function (fdel) for del obj.x
• a documentation string

The direct constructor form is:

x = property(getx, setx, delx, "documentation")

Decorator syntax does not change what property is. It only provides shorter syntax for calling it. This:

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

means approximately:

def x():
     ._x

x = (x)

Think of a property as a receptionist at a door labelled x.

• Reading obj.x asks the receptionist to run the getter.
• Assigning obj.x = value asks the receptionist to run the setter.
• Deleting del obj.x asks the receptionist to run the deleter.

The real value is often stored in a separate internal attribute such as obj._x. The underscore is a convention meaning “internal implementation detail.”

@property hires the receptionist with a getter. @x.setter and @x.deleter add the other instructions to that same property definition.

The constructor signature is conceptually:

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

Direct constructor form

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

    def get_celsius(self):
        return self._celsius

    def set_celsius(self, value):
        if value < -273.15:
            raise ValueError("Temperature cannot be below absolute zero")
        self._celsius = value

    celsius = property(get_celsius, set_celsius)

Decorator form

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

    @property
     ():
         ._celsius


     ():
         value < -:
             ValueError()
        ._celsius = value

Consider this class:

class Box:
    @property
    def size(self):
        return self._size

    @size.setter
    def size(self, value):
        self._size = value

During class creation, Python evaluates it approximately as follows:

class Box:
    def size(self):
        return self._size

    size = property(size)

    def size(self, value):
        self._size = value

    size = size.setter(size)

Step by step:

1. The first def size(self) creates a normal function object.
2. @property calls property(function) and stores the returned property object under the name size.

Properties are useful when an attribute needs behavior without making callers use method syntax.

• Validation: reject invalid ages, quantities, dates, or configuration values.
• Normalization: strip whitespace from names or convert text to lowercase before storing it.
• Derived values: expose rectangle.area computed from width and height.
• Lazy values: calculate an expensive value only when it is first requested.
• Read-only values: provide a getter but no setter, such as order.total.
• API stability: start with a plain public attribute, then later add validation internally while preserving obj.name syntax.

Example of a read-only derived property:

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

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

rectangle = Rectangle(4, 3)
print(rectangle.area)  

In production code, properties are usually kept small, predictable, and free of surprising work.

Validation at a boundary

A setter protects an object's invariant: a rule that should always remain true.

class Account:
    def __init__(self, balance=0):
        self.balance = balance

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

    @balance.setter
    def balance(self, value):
        if not isinstance(value, (int, float)):
            raise TypeError("balance must be a number")
        if value < 0:
            raise ValueError("balance cannot be negative")
        self._balance = value

Read-only public interfaces

A property with no setter communicates that callers should not assign to it.

class :
     ():
        .first_name = first_name
        .last_name = last_name


     ():
         

Recursively accessing the property inside itself

This getter calls itself forever:

class Bad:
    @property
    def x(self):
        return self.x  # RecursionError

Use a separate backing attribute instead:

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

Recursively assigning through the property in its setter

@x.setter
def x(self, value):
    self.x = value  # RecursionError

Store the value in a backing attribute:

@x.setter
def x(self, value):
    self._x = value

Forgetting that a getter-only property is read-only

property() versus

class Example:
    def __init__(self, value):
        self._value = value

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

    @value.setter
    def value(self, new_value):
        self._value = new_value

    @value.deleter
    def value(self):
        del self._value

• @property means: value = property(value).
• @value.setter means: replace value with value.setter(setter_function).
• @value.deleter means: replace value with value.deleter(deleter_function).
• Use obj.value, not .

Is @property a built-in function or a decorator?

property is a built-in class that creates property objects. It can be used as a decorator because decorators are callable objects: @property calls property with the function beneath it.

What does @property pass to property?

It passes the decorated getter function as the first positional argument. @property def x(...) is approximately x = property(x).

Where do .setter and .deleter come from?

They are methods of the property object returned by property(...). Calling them supplies a setter or deleter function and returns a configured property object.

Why is def x written three times?

Each function has a different role: getter, setter, or deleter. The decorators repeatedly bind the name x to the latest property object containing those functions.

Does @x.setter modify the property in place?

Conceptually, treat it as returning a new property object with the added setter. The decorator syntax assigns that returned property back to .

• Decorators — @property uses the same @decorator syntax as function decorators.
• Descriptors — properties are descriptors that customize attribute lookup, assignment, and deletion.
• Encapsulation — properties expose a controlled public interface while storing implementation details internally.
• Instance and class attributes — the property lives on the class, while backing values usually live on instances.
• Getter and setter methods — the explicit method-based style that properties can replace.
• Dataclasses — useful for data containers; properties can add computed or validated attributes when needed.
• classmethod and staticmethod — other common built-in decorators, but they change method binding rather than manage attributes.