{"title":"@property Decorator","description":"","content":"In some languages you write `getPrice()` and `setPrice(value)` for every field that needs validation or computation. Python doesn't make you do that. You start with a plain attribute, and if it later needs validation or a computed value, you swap it for a property without changing any of the code that reads or writes it. This lesson covers `@property`, writable and deletable properties, computed and read-only fields, the small cost of going through a property, and where `functools.cached_property` fits in.\n\n---\n\n# Why Python Doesn't Need Getters and Setters\n\nMost languages teach you to wrap every field in a pair of methods because exposing the field directly locks you in. Once outside code writes `product.price = 30`, you can't later say \"wait, I need to reject negative prices\" without breaking every caller. So you start with `getPrice()` and `setPrice(value)` from day one, just in case.\n\nPython solves this differently. You can ship a class with a plain attribute today, and tomorrow turn that attribute into a method-backed property. Every line of caller code keeps working unchanged, because the syntax for reading and writing a property is the same as the syntax for reading and writing a plain attribute.\n\nStart with the most boring version of a product:\n\n\n```python\nclass Product:\n def __init__(self, name, price):\n self.name = name\n self.price = price\n\nmouse = Product(\"Wireless Mouse\", 29.99)\nprint(mouse.price)\nmouse.price = 24.99\nprint(mouse.price)\n```\n\n\nBoth reads and the write go straight to the attribute. There's no method call, no validation, nothing in between. Now suppose three weeks later someone files a bug: a customer was charged `-50.00` for a mouse because an admin tool wrote a negative number into `price`. You need to reject negative prices.\n\nIn a language that forces getters and setters, you'd already have `setPrice(value)` everywhere and you'd just add the check inside. In Python, you have `product.price = -50` scattered across the codebase. Rewriting every assignment to call a new method would be painful. So Python lets you keep the attribute syntax and add the validation behind it:\n\n\n```python\nclass Product:\n def __init__(self, name, price):\n self.name = name\n self.price = price\n\n @property\n def price(self):\n return self._price\n\n @price.setter\n def price(self, value):\n if value < 0:\n raise ValueError(\"price cannot be negative\")\n self._price = value\n\nmouse = Product(\"Wireless Mouse\", 29.99)\nprint(mouse.price)\nmouse.price = 24.99\nprint(mouse.price)\n```\n\n\nThe caller's code from the first snippet still works without a single edit. The difference is invisible from outside: `mouse.price` looks like an attribute, behaves like an attribute, but actually runs a method on every read and write. This is the payoff. You don't pay the getter/setter tax up front. You add a property only when you actually need one.\n\nThe convention \"private name with underscore + public property\" is how Python keeps the real value (`self._price`) separate from the public interface (`self.price`). Without that split, the setter would call itself recursively, which we'll see in a moment.\n\n---\n\n# `@property`: Make a Method Look Like an Attribute\n\n`@property` is a decorator that turns a method into something callers access without parentheses. The method becomes a read-only computed attribute. When someone writes `cart.total`, Python actually runs the `total` method behind the scenes and returns its result.\n\nStart with a cart that computes its total from its items:\n\n\n```python\nclass Cart:\n def __init__(self):\n self.items = []\n\n @property\n def total(self):\n return sum(item[\"price\"] * item[\"quantity\"] for item in self.items)\n\ncart = Cart()\ncart.items.append({\"name\": \"Wireless Mouse\", \"price\": 29.99, \"quantity\": 2})\ncart.items.append({\"name\": \"USB Cable\", \"price\": 9.99, \"quantity\": 1})\n\nprint(f\"Cart total: ${cart.total:.2f}\")\n```\n\n\nNotice the call site: `cart.total`, not `cart.total()`. The decorator handled that. Inside the class, `total` is still a regular method that takes `self`. Outside, callers see it as an attribute. That asymmetry is exactly what we want; the implementation can be a method, while the interface is an attribute.\n\nWhat `@property` actually does is replace the function `total` on the class with a special **property object** that knows how to behave when you read or write `cart.total`. When you say `cart.total`, Python doesn't find a normal attribute on `cart`; it finds the property object on the class, and the property object calls the function for you.\n\nHere's the access flow in pictures:\n\n\n```mermaid\nflowchart LR\n A[\"cart.price = 24.99
or
price = cart.price\"]:::cyan\n B{\"is 'price'
a property?\"}:::orange\n C[\"plain attribute
read/write self.__dict__\"]:::green\n D[\"property object
calls getter or setter\"]:::teal\n E[\"method runs
(validate / compute / store)\"]:::orange\n F[\"value returned
(or stored)\"]:::green\n\n A --> B\n B -->|no| C\n B -->|yes| D\n D --> E\n E --> F\n C --> F\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe diagram shows the fork. For a plain attribute (green), Python just reads or writes the instance dictionary. For a property (teal), Python routes through the property object, which calls the method you wrote. Same `cart.price` syntax at the call site, two very different paths underneath.\n\nBecause `total` here has only a getter, trying to assign to it fails:\n\n\n```python\ncart.total = 0\n```\n\n\nThat's read-only behavior, and we'll come back to it deliberately later in the lesson. For now, the takeaway is: `@property` alone gives you a computed attribute that callers read with no parentheses.\n\n---\n\n# `@.setter`: Make a Property Writable\n\nA property with only `@property` is read-only. To allow assignment, you pair the getter with a setter, decorated as `@.setter`. The name has to match the property name, and the setter takes `self` and the value being assigned.\n\nThis is the place to put validation. The setter runs on every write, so any rule you want to enforce (\"price must be non-negative\", \"stock can't be a float\", \"email needs an @ sign\") goes here:\n\n\n```python\nclass Product:\n def __init__(self, name, price):\n self.name = name\n self.price = price\n\n @property\n def price(self):\n return self._price\n\n @price.setter\n def price(self, value):\n if not isinstance(value, (int, float)):\n raise TypeError(\"price must be a number\")\n if value < 0:\n raise ValueError(\"price cannot be negative\")\n self._price = round(value, 2)\n\nmouse = Product(\"Wireless Mouse\", 29.99)\nmouse.price = 24.999\nprint(mouse.price)\n\nmouse.price = -5\n```\n\n\nThree things to notice:\n\n1. **The setter ran on `__init__` too.** When `__init__` writes `self.price = price`, that assignment goes through the setter. So the validation kicks in for the constructor, not just for later edits. This is what you want: no way for a `Product` to exist with a negative price.\n2. **The setter can transform the value.** It stored `round(value, 2)`, not `value` directly. So `24.999` became `24.99`. The caller's view never sees the rounding, only the cleaned value.\n3. **The storage name is different from the public name.** The real value lives in `self._price`, and the property `price` is the public face. If you tried to store it in `self.price` from inside the setter, you'd recurse forever, because `self.price = ...` would call the setter again. The leading underscore is the standard convention for \"this is the storage, not the API\".\n\nLet's see what happens if you forget the underscore:\n\n**What's wrong with this code?**\n\n\n```python\nclass Product:\n def __init__(self, price):\n self.price = price\n\n @property\n def price(self):\n return self.price\n\n @price.setter\n def price(self, value):\n self.price = value\n```\n\n\n`self.price = value` inside the setter is the same as any other `self.price = ...`. It triggers the setter again, which assigns to `self.price`, which triggers the setter again, and so on. The fix is to store the value under a different name (`self._price`) and have the getter return that same private name.\n\n**Fix:**\n\n\n```python\nclass Product:\n def __init__(self, price):\n self.price = price\n\n @property\n def price(self):\n return self._price\n\n @price.setter\n def price(self, value):\n self._price = value\n```\n\n\nThe setter is also the place where you'd raise `ValueError` for bad inputs. Bad type? Raise `TypeError`. Bad value but right type? Raise `ValueError`. Following Python's convention here makes your class feel like the standard library.\n\n---\n\n# `@.deleter`: The Rare Delete Case\n\nYou can also tell a property what to do when someone writes `del product.price`. The decorator is `@.deleter`, and the method takes only `self`. This is the least-used of the three, but it shows up when \"deleting\" needs to mean something specific, like resetting to a default or clearing a cached value.\n\n\n```python\nclass Product:\n def __init__(self, name):\n self.name = name\n self._discount = 0.0\n\n @property\n def discount(self):\n return self._discount\n\n @discount.setter\n def discount(self, value):\n if not 0.0 <= value <= 1.0:\n raise ValueError(\"discount must be between 0 and 1\")\n self._discount = value\n\n @discount.deleter\n def discount(self):\n print(f\"clearing discount on {self.name}\")\n self._discount = 0.0\n\nmouse = Product(\"Wireless Mouse\")\nmouse.discount = 0.25\nprint(mouse.discount)\n\ndel mouse.discount\nprint(mouse.discount)\n```\n\n\n`del mouse.discount` doesn't remove the attribute or the property. It just calls the deleter, which in this case resets the underlying storage to `0.0`. The property itself stays in place; you can read and write `mouse.discount` again right after.\n\nMost of the time you don't need a deleter. The two common reasons to add one are: clearing a cached or derived value so it gets recomputed next time, and resetting a piece of state to a default in a way that's more readable than `obj.field = DEFAULT`. If neither of those matches your case, skip the deleter.\n\n---\n\n# Computed Properties: Values Calculated on the Fly\n\nThe `Cart.total` we saw earlier is a **computed property**: there's no `self._total` stored anywhere. The value is calculated fresh from other attributes each time you read it. This is one of the most useful uses of `@property`, because it keeps related values automatically in sync without any code on your side.\n\nHere's a slightly fuller cart that uses two computed properties:\n\n\n```python\nclass Cart:\n def __init__(self):\n self.items = []\n\n @property\n def item_count(self):\n return sum(item[\"quantity\"] for item in self.items)\n\n @property\n def total(self):\n return sum(item[\"price\"] * item[\"quantity\"] for item in self.items)\n\ncart = Cart()\ncart.items.append({\"name\": \"Wireless Mouse\", \"price\": 29.99, \"quantity\": 2})\ncart.items.append({\"name\": \"USB Cable\", \"price\": 9.99, \"quantity\": 1})\n\nprint(f\"Items in cart: {cart.item_count}\")\nprint(f\"Cart total: ${cart.total:.2f}\")\n\ncart.items.append({\"name\": \"HDMI Cable\", \"price\": 14.99, \"quantity\": 1})\n\nprint(f\"Items in cart: {cart.item_count}\")\nprint(f\"Cart total: ${cart.total:.2f}\")\n```\n\n\nNobody told `item_count` or `total` to refresh. They didn't have to. Every read recomputes from the current list of items. There's no `update_total()` to call, no risk of a stale total that doesn't match the items list. The trade-off is that each read does the work again, which matters once the computation gets heavy. We'll see how to cache the result in a moment.\n\nComputed properties pair well with classes whose internal state changes over time:\n\n\n```python\nclass Order:\n SHIPPING_FEE = 5.99\n FREE_SHIPPING_THRESHOLD = 50.00\n\n def __init__(self, items):\n self.items = items\n\n @property\n def subtotal(self):\n return sum(self.items)\n\n @property\n def shipping(self):\n if self.subtotal >= self.FREE_SHIPPING_THRESHOLD:\n return 0.0\n return self.SHIPPING_FEE\n\n @property\n def total(self):\n return self.subtotal + self.shipping\n\nsmall_order = Order([19.99, 9.99])\nbig_order = Order([29.99, 14.99, 19.99])\n\nprint(f\"small subtotal: ${small_order.subtotal:.2f}, ship: ${small_order.shipping:.2f}, total: ${small_order.total:.2f}\")\nprint(f\"big subtotal: ${big_order.subtotal:.2f}, ship: ${big_order.shipping:.2f}, total: ${big_order.total:.2f}\")\n```\n\n\nThree properties, each derived from `self.items`. `total` even depends on another property (`subtotal` and `shipping`). You can build derived values on top of derived values, and each one always reflects the current items list.\n\n---\n\n# Read-Only Properties: Getter Without a Setter\n\nLeave off the `@.setter` and you get a **read-only** property. Callers can read it, but any attempt to assign raises `AttributeError`. This is the right tool for fields that should be set once at construction time and never change afterward, like a customer's ID:\n\n\n```python\nclass Customer:\n def __init__(self, customer_id, name, email):\n self._customer_id = customer_id\n self.name = name\n self.email = email\n\n @property\n def customer_id(self):\n return self._customer_id\n\nalice = Customer(1001, \"Alice\", \"alice@example.com\")\nprint(alice.customer_id)\nprint(alice.name)\n\nalice.name = \"Alice B.\"\nprint(alice.name)\n\nalice.customer_id = 9999\n```\n\n\n`name` is a plain attribute and accepts reassignment. `customer_id` is a read-only property and refuses. The `_customer_id` storage is technically still reachable as `alice._customer_id` (Python doesn't enforce true privacy), but the leading underscore is a strong \"do not touch\" signal, and going through the property is the only intended way.\n\nRead-only properties also work well with computed values you want to expose but never accept writes for:\n\n\n```python\nclass Cart:\n def __init__(self):\n self.items = []\n\n @property\n def total(self):\n return sum(item[\"price\"] * item[\"quantity\"] for item in self.items)\n```\n\n\nThis is exactly the cart from earlier. Because there's no setter, `cart.total = 0` fails. That's the right behavior: a total isn't something you set, it's something derived from the items. Refusing the assignment catches a whole class of bugs where someone tries to \"fix\" the total instead of fixing the items.\n\n\n> **INFO**\n>\n> **Cost:** A property read calls a function under the hood. It's slightly slower than a plain attribute read, maybe a few hundred nanoseconds versus tens of nanoseconds. Imperceptible in normal code. Measurable only inside tight numeric loops that read the same property millions of times. If a benchmark says you have a problem, cache the value in a local variable before the loop instead of reading the property each iteration.\n\n\n---\n\n# `functools.cached_property`: When the Computation Is Expensive\n\nA computed property is great until the computation is expensive and the inputs don't change. Reading `cart.total` 50 times in a render loop runs the sum 50 times, even when no items have been added between reads. For a small cart that's fine. For something that scans 10,000 items or hits a database, it isn't.\n\n`functools.cached_property` solves this for cases where the value is computed once and then doesn't need to change. It's a decorator from the standard library that works almost exactly like `@property`, except the first access stores the result on the instance, and every later access reads that stored value directly. No more recomputation.\n\n\n```python\nfrom functools import cached_property\n\nclass Order:\n def __init__(self, items):\n self.items = items\n\n @cached_property\n def total(self):\n print(\"computing total...\")\n return sum(item[\"price\"] * item[\"quantity\"] for item in self.items)\n\norder = Order([\n {\"name\": \"Wireless Mouse\", \"price\": 29.99, \"quantity\": 2},\n {\"name\": \"USB Cable\", \"price\": 9.99, \"quantity\": 1},\n])\n\nprint(order.total)\nprint(order.total)\nprint(order.total)\n```\n\n\n`\"computing total...\"` prints once, not three times. The first read runs the method, stores the result as `order.total` on the instance, and returns it. From then on, attribute lookup finds the stored value directly without calling the method.\n\nThe catch is exactly what makes it fast: the cached value doesn't update when the inputs change. If you mutate `order.items` after reading `order.total` once, the cached total stays at the old value. You'd have to delete the cached attribute (`del order.total`) to force a recomputation. So `cached_property` fits values that are effectively immutable for the lifetime of the object, or where you control invalidation yourself. For values that can change at any time, a regular `@property` is safer because it always reflects the current state.\n\n`cached_property` has been in the standard library since Python 3.8. Before that, the common workaround was a manual cache attribute inside a regular `@property`. The standard library version is cleaner and handles the lookup correctly without you writing the cache logic each time.\n\n---\n\n# A Fuller Example: Product, Cart, Customer\n\nHere's a small e-commerce snippet that pulls every piece of this lesson together: validation in a setter, a computed property, a read-only property, and a deleter that resets to a default.\n\n\n```python\nfrom functools import cached_property\n\nclass Product:\n def __init__(self, name, price):\n self.name = name\n self.price = price\n\n @property\n def price(self):\n return self._price\n\n @price.setter\n def price(self, value):\n if not isinstance(value, (int, float)):\n raise TypeError(\"price must be a number\")\n if value < 0:\n raise ValueError(\"price cannot be negative\")\n self._price = round(value, 2)\n\nclass Cart:\n def __init__(self):\n self.items = []\n\n @property\n def total(self):\n return sum(p.price * qty for p, qty in self.items)\n\nclass Customer:\n def __init__(self, customer_id, name):\n self._customer_id = customer_id\n self.name = name\n self._discount = 0.0\n\n @property\n def customer_id(self):\n return self._customer_id\n\n @property\n def discount(self):\n return self._discount\n\n @discount.setter\n def discount(self, value):\n if not 0.0 <= value <= 1.0:\n raise ValueError(\"discount must be between 0 and 1\")\n self._discount = value\n\n @discount.deleter\n def discount(self):\n self._discount = 0.0\n\nmouse = Product(\"Wireless Mouse\", 29.99)\ncable = Product(\"USB Cable\", 9.99)\n\ncart = Cart()\ncart.items.append((mouse, 2))\ncart.items.append((cable, 1))\n\nalice = Customer(1001, \"Alice\")\nalice.discount = 0.10\n\nraw_total = cart.total\nfinal_total = raw_total * (1 - alice.discount)\n\nprint(f\"customer: {alice.name} (id={alice.customer_id})\")\nprint(f\"raw total: ${raw_total:.2f}\")\nprint(f\"discount: {alice.discount * 100:.0f}%\")\nprint(f\"final total: ${final_total:.2f}\")\n\ndel alice.discount\nprint(f\"discount after del: {alice.discount}\")\n```\n\n\nEvery property pulls its weight. `Product.price` validates type and value on every write, including the one inside `__init__`. `Cart.total` is a fresh computation each time, so adding items to the cart is immediately reflected in the total. `Customer.customer_id` is read-only; you can't accidentally renumber a customer. `Customer.discount` validates the range on writes and resets to zero on `del`. The caller code reads all of these the same way: with a dot and no parentheses.","pageType":"python"}

@property Decorator

Get Premium