Properties & Descriptors

Reviewed & published by Brayan K

A property is a method dressed up as an attribute: you write obj.area with no parentheses, but a function runs behind the scenes to compute it, validate it, or guard it — giving you clean attribute syntax with full control.

Part of the free Python course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

Properties let you add computed values and validation without breaking the simple obj.x interface your callers expect. Descriptors take the idea one level deeper, letting you reuse that managed-attribute logic across many fields and classes.

What You'll Learn in This Lesson

• Computed read-only attributes with @property
• Adding a setter to validate assignments
• Making attributes deletable with a deleter
• How a property keeps the clean obj.x interface
• The descriptor protocol (__get__ / __set__)
• Caching expensive values with cached_property

1 Computed Attributes with @property

Decorate a method with @property and you access it like an attribute — no parentheses. The value is computed fresh each time from the data you already store:

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

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

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

c = Circle(5)
print(c.diameter)        # 10   (no parentheses!)
print(round(c.area, 2))  # 78.54

c.radius = 10            # change the source...
print(c.diameter)        # 20   (...the property follows)

c.diameter()   <- a normal method needs ()
c.diameter     <- a @property is accessed like data

Same logic, friendlier interface. diameter always reflects the current radius because it's recomputed on every access.

🛡️ Validation with a Setter

Add a @<name>.setter method and you can run code — including validation — every time someone assigns to the attribute. The convention is to store the real value in a "private" field like _celsius:

class Temperature:
    def __init__(self, celsius=0):
        self.celsius = celsius          # goes through the setter

    @property
    def celsius(self):
        return self._celsius

    @celsius.setter
    def celsius(self, value):
        if value < -273.15:
            raise ValueError("Below absolute zero!")
        self._celsius = value

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

t = Temperature(25)
print(t.fahrenheit)      # 77.0
t.celsius = 100          # validated, then stored
print(t.fahrenheit)      # 212.0

t.celsius = -300         # ValueError: Below absolute zero!

Notice the getter returns self._celsius while the setter writes self._celsius. The public name celsius is the property; the underscore name holds the actual data.

2 Getter, Setter & Deleter — the Full Trio

A property can have all three hooks. The @<name>.deleter runs when someone uses del obj.attr — handy for cleanup or to forbid deletion entirely:

class Profile:
    def __init__(self, name):
        self._name = name

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

    @name.setter
    def name(self, value):
        self._name = value.strip().title()

    @name.deleter
    def name(self):
        print("Clearing name")
        self._name = "anonymous"

p = Profile("  ada  ")
print(p.name)       # Ada   (setter cleaned it up)
del p.name          # Clearing name
print(p.name)       # anonymous

class Account:
    def __init__(self, balance=0):
        self.balance = balance          # routed through the setter

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

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

    @property
    def is_overdraft_safe(self):        # computed, read-only
        return self._balance >= 100

acct = Account(50)
print("Balance:", acct.balance)
print("Safe?", acct.is_overdraft_safe)

acct.balance = 250
print("Safe?", acct.is_overdraft_safe)

try:
    acct.balance = -10
except ValueError as e:
    print("Rejected:", e)

# ✅ Expected output:
# Balance: 50
# Safe? False
# Safe? True
# Rejected: Balance cannot be negative

3 The Descriptor Protocol

A property validates one attribute on one class. When you want to reuse the same validation across many attributes, write a descriptor: a class with __get__ and __set__ methods, stored as a class attribute. @property is itself a descriptor under the hood.

class Positive:
    """A reusable descriptor: the value must be > 0."""
    def __set_name__(self, owner, name):
        self.storage = "_" + name        # remember where to store it

    def __get__(self, obj, objtype=None):
        return getattr(obj, self.storage)

    def __set__(self, obj, value):
        if value <= 0:
            raise ValueError(f"must be positive, got {value}")
        setattr(obj, self.storage, value)

class Order:
    quantity = Positive()                # reuse the same logic...
    price = Positive()                   # ...on multiple fields

    def __init__(self, quantity, price):
        self.quantity = quantity
        self.price = price

o = Order(3, 9.99)
print(o.quantity, o.price)   # 3 9.99

o.quantity = -1              # ValueError: must be positive, got -1

⚡ cached_property — Compute Once, Reuse Forever

A plain @property recomputes on every access. For an expensive calculation that won't change, functools.cached_property runs the body once, stores the result in the instance, and returns the cached value thereafter:

from functools import cached_property

class Dataset:
    def __init__(self, numbers):
        self.numbers = numbers

    @cached_property
    def total(self):
        print("  (computing total...)")    # proves it runs once
        return sum(self.numbers)

d = Dataset([10, 20, 30, 40])
print(d.total)     #   (computing total...)  then  100
print(d.total)     # 100   <- cached, no recompute
print(d.total)     # 100

🎯 Your Turn: Fill in the Blank

Complete the property so celsius stays read-only and fahrenheit is computed. Replace each ___, then run it.

# 🎯 YOUR TURN: replace each ___
class Weather:
    def __init__(self, celsius):
        self._celsius = celsius

    @___                          # decorator that makes a property
    def celsius(self):
        return self.___           # return the stored value

    @property
    def fahrenheit(self):
        return self._celsius * 9 / 5 + ___   # the constant for F

w = Weather(20)
print(w.celsius)
print(w.fahrenheit)

# Expected output:
# 20
# 68.0

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

    @property
    def celsius(self):
        return self._celsius

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

w = Weather(20)
print(w.celsius)      # 20
print(w.fahrenheit)   # 68.0

Common Errors

❌ Infinite recursion in the getter

@property
def celsius(self):
    return self.celsius     # calls the property again -> crash!
# RecursionError: maximum recursion depth exceeded

✅ Store the real value under a different name and return that:

@property
def celsius(self):
    return self._celsius    # underscore = the actual storage

❌ Calling a property like a method

c = Circle(5)
print(c.area())   # TypeError: 'float' object is not callable

✅ A property is accessed without parentheses: c.area.

❌ Assigning to a read-only property

c.diameter = 20   # AttributeError: property has no setter

✅ Add a @diameter.setter if assignment should be allowed — otherwise it's read-only by design.

🎯 Mini Challenge: A Validated Rectangle

Build a Rectangle whose width and height reject non-positive values via setters, and whose area and perimeter are computed properties.

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

    @property
    def width(self):
        return self._width

    @width.setter
    def width(self, value):
        if value <= 0:
            raise ValueError("width must be positive")
        self._width = value

    @property
    def height(self):
        return self._height

    @height.setter
    def height(self, value):
        if value <= 0:
            raise ValueError("height must be positive")
        self._height = value

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

    @property
    def perimeter(self):
        return 2 * (self._width + self._height)

r = Rectangle(4, 6)
print("Area:", r.area)
print("Perimeter:", r.perimeter)
r.width = 10
print("New area:", r.area)
try:
    r.height = 0
except ValueError as e:
    print("Rejected:", e)

# ✅ Expected output:
# Area: 24
# Perimeter: 20
# New area: 60
# Rejected: height must be positive

📚 Keep Learning

• property() — built-in reference — the getter / setter / deleter mechanics in full.
• Descriptor HowTo Guide — the definitive walkthrough of __get__, __set__ and __set_name__.
• functools.cached_property — compute-once attributes for expensive values.

Frequently Asked Questions

Lesson complete — your attributes are smart now!

You can expose computed values with @property, validate assignments with a setter, hook deletion with a deleter, reuse logic across fields with the descriptor protocol, and cache expensive results with cached_property — all while keeping the clean obj.x interface.

Practice quiz

Continue this course

• Previous: Abstract Base Classes (abc)
• Next: __slots__ & Memory Optimization — Cut memory and speed up attribute access by dropping __dict__
• Quick reference: Python cheat sheet
• From the blog: Object-Oriented Programming in Python

Frequently asked questions

What does @property actually do?

@property turns a method into a managed attribute — you access it like obj.area (no parentheses) but a function runs behind the scenes. It lets you expose computed values and add validation while keeping a clean attribute-style interface, so callers never have to know whether something is stored or calculated.

When should I use a property instead of a plain attribute?

Start with a plain attribute. Reach for a property the moment you need to compute a value from other data, validate what gets assigned, make something read-only, or run side effects on access. The big win is that you can convert a plain attribute into a property later without changing any calling code.

What is the descriptor protocol?

A descriptor is any object that defines __get__, __set__, or __delete__ and is stored as a class attribute. When you access that attribute on an instance, Python calls those methods instead of returning the object directly. @property is itself a descriptor; writing your own lets you reuse the same validation logic across many attributes and classes.

How is functools.cached_property different from @property?

@property recomputes every single time you access it. functools.cached_property computes the value once on first access, stores it in the instance's __dict__, and returns the cached value on every later access. Use it for expensive calculations whose result won't change for the life of the object.