Properties & Descriptors — Managed Attributes

In Python you start with plain attributes — self.radius = r, and callers read c.radius. The thesis of this chapter: @property lets that same attribute access run method code behind the scenes, so you can compute a value on the fly, validate an assignment, or make an attribute read-only — all without changing how callers write obj.x. This is why Python culture says don't write get_x()/set_x() up front: a plain attribute can be upgraded to a managed one later, invisibly. Underneath @property sits the general descriptor protocol (__get__/__set__), the same mechanism that turns functions into bound methods.

We build from the everyday tool (@property) down to the protocol that explains it. Every output below was produced by running the code.

Table of Contents

1. @property for a computed attribute
2. A setter with validation
3. Read-only by omitting the setter
4. Why properties beat get_x()/set_x()
5. The descriptor protocol
6. Mental-model summary
7. Gotcha checklist

1. @property for a computed attribute

@property turns a method into a managed attribute: callers access it like data (no parentheses), but each access runs the method. The classic use is a value derived from others — here, a circle's area computed from its radius.

Output:

12.566370614359172
28.274333882308138

Analysis. area is defined as a method but accessed as an attribute — c.area, not c.area(). The @property decorator is what makes that work. Crucially, area stores nothing: each access recomputes from the current radius, so after c.radius = 3 the area updates automatically. There is no stale value to keep in sync.

Intuition. Mechanism. @property wraps the getter function in a property object and binds it to the class attribute area. When you write c.area, attribute lookup finds that property object on the class and calls its __get__, which runs your getter with self = c. The result is computed on demand — area never occupies a slot in c.__dict__.

Concrete bite. Because it runs on every access, a property is recomputed each time — convenient for correctness, but it is not a cached field:

computing area
computing area

Two accesses, two computations. For a cheap formula that's ideal. For an expensive one, naive @property recomputes every time — reach for functools.cached_property to compute once and store the result.

2. A setter with validation

A property can also intercept assignment. Pair the getter with a @<name>.setter method, and obj.x = value runs your code — the natural place to validate.

Output:

2
5

Analysis. There are now two radius methods: the getter (returns the private self._radius) and the setter (validates, then stores). Even __init__'s self.radius = radius flows through the setter, so the validation runs at construction too. The real value lives in _radius (the leading underscore signals "internal"); radius is the managed public name. Valid assignments succeed silently.

Intuition. Mechanism. @radius.setter attaches a setter function to the same property object created by @property. Now c.radius = 5 doesn't write to c.__dict__["radius"]; instead the property's __set__ runs your setter with value = 5. The actual storage is wherever the setter puts it — by convention a "private" self._radius. Reading and writing radius are now two different functions you control.

Concrete bite. An invalid assignment is rejected at the point of assignment, by your raise:

Traceback (most recent call last):
  File "/w/main.py", line 14, in <module>
    c.radius = -1        # rejected by the setter
    ^^^^^^^^
  File "/w/main.py", line 10, in radius
    raise ValueError(f"radius must be non-negative, got {value}")
ValueError: radius must be non-negative, got -1

c.radius = -1 looks like a plain assignment, but it invoked the setter, which raised ValueError. The object can never hold a negative radius — the invariant is enforced at the boundary, not merely documented.

3. Read-only by omitting the setter

Define a property with a getter and no setter, and the attribute becomes read-only — assignment is rejected by the property machinery itself.

Output:

2

Traceback (most recent call last):
  File "/w/main.py", line 10, in <module>
    c.radius = 5         # no setter defined
    ^^^^^^^^
AttributeError: property 'radius' of 'Circle' object has no setter

Analysis. Reading c.radius works (2); the assignment crashes. Note __init__ writes to self._radius directly (not self.radius), since there's no setter to go through. The error is raised by the property object — not by any code we wrote — because a getter-only property defines __get__ but no __set__.

Intuition. Mechanism. A property object always defines __set__; when you supply no setter, that __set__ simply raises AttributeError. Because the property lives on the class and defines __set__, it is a data descriptor — and data descriptors take priority over the instance __dict__. So Python doesn't quietly fall back to creating an instance attribute; it routes the assignment to the property's __set__, which refuses.

Concrete bite. The exact wording on Python 3.13 names the property and class:

Traceback (most recent call last):
  File "/w/main.py", line 8, in <module>
    Circle(2).radius = 5
    ^^^^^^^^^^^^^^^^
AttributeError: property 'radius' of 'Circle' object has no setter

On 3.13 the message is property 'radius' of 'Circle' object has no setter (older Pythons said the terser can't set attribute). It is an AttributeError either way — the read-only guarantee holds, and the message tells you precisely which property refused.

4. Why properties beat get_x()/set_x()

The Pythonic argument for properties is concrete: start with a plain attribute, and upgrade to a property later without touching a single caller. Begin with the simplest thing.

Output:

100
250

Analysis. balance is an ordinary attribute — no ceremony, no getter, no setter. Callers read and write it directly. In a Java-style design you'd have written getBalance()/setBalance() defensively from day one, just in case validation became necessary. Python lets you defer that decision, because the attribute can become managed later with no API change.

Intuition. Mechanism. obj.x is the public interface whether x is a plain attribute or a property — the syntax is identical. Promoting a plain attribute to a property changes only the class, not any caller: every a.balance read and a.balance = v write keeps working, now routed through your getter/setter. Callers literally cannot tell the difference.

Concrete bite. Add validation later by converting balance to a property — the caller code from above is byte-for-byte unchanged and still runs:

100
250

Same output as the plain-attribute version, same caller lines — but now negative balances are impossible. Had you exposed getBalance()/setBalance() instead, you'd have forced that ceremony on callers forever, for a check you didn't need yet.

5. The descriptor protocol

@property is convenient but not magic — it's one example of a descriptor: any object that defines __get__ (and optionally __set__). When such an object is a class attribute, Python routes attribute access through its methods. This is also how plain methods become bound methods. You can write your own descriptor to reuse managed-attribute behavior across many attributes.

Output:

10 3
20

Analysis. Positive is a descriptor: __get__ reads the backing field, __set__ validates then writes it. __set_name__ is a convenience hook Python calls when the class body runs, telling the descriptor the attribute name it was assigned to (price, quantity), so each instance stores into a distinct _price/_quantity. Declaring price = Positive() and quantity = Positive() reuses the same validation logic for two attributes — something a @property can't do without writing the getter/setter twice.

Intuition. Mechanism. When Positive is a class attribute, p.price calls Positive.__get__(self, p, Product) and p.price = 20 calls Positive.__set__(self, p, 20). Because the descriptor defines __set__, it's a data descriptor and intercepts the assignment instead of letting it land in p.__dict__. The same protocol underlies methods: a plain function is a (non-data) descriptor whose __get__ returns a bound method — which is why obj.method automatically receives self. @property is just a ready-made data descriptor.

Concrete bite. The shared validation fires for both attributes from one class — here it rejects a bad price at construction, via __set__:

Traceback (most recent call last):
  File "/w/main.py", line 18, in <module>
    Product(-5)
    ~~~~~~~^^^^
  File "/w/main.py", line 16, in __init__
    self.price = price
    ^^^^^^^^^^
  File "/w/main.py", line 10, in __set__
    raise ValueError(f"{self.name[1:]} must be positive, got {value}")
ValueError: price must be positive, got -5

self.price = price in __init__ routed through Positive.__set__, which rejected -5. One descriptor class enforces the rule for price, quantity, and any other Positive() attribute you add — no per-attribute boilerplate.

6. Mental-model summary

7. Gotcha checklist

Your Turn

Before you move on, check your understanding with the coach — explain the idea, apply it, weigh the trade-offs, then defend your reasoning.