Last modified: Nov 19, 2026
Python Property Decorator Explained
The @property decorator is one of the most useful tools in Python classes. It lets you turn a method into something that looks like a normal attribute.
This keeps your code clean. You can add logic, checks, and computed values without changing how users access your data.
In this guide, you will learn what the property decorator does, why it matters, and how to use it well. We will walk through simple examples with code and output.
What Is the Property Decorator?
In Python, an attribute is a value stored on an object, like person.name. A method is a function you call, like person.show_name().
The @property decorator lets a method behave like an attribute. You access it without parentheses.
Behind the scenes, Python still runs your method. But the caller sees a plain value. This is called a getter.
class Circle:
def __init__(self, radius):
self.radius = radius
@property
def area(self):
# Computed each time it is accessed
return 3.14159 * self.radius ** 2
c = Circle(5)
print(c.area) # No parentheses needed
78.53975
Notice that we wrote c.area and not c.area(). That is the magic of the property decorator.
Why Use Properties?
Properties give you control over how attributes are read, set, and deleted. Without them, you would need getter and setter methods with awkward names.
Here are the main benefits:
- Clean syntax: users read values like normal attributes.
- Validation: you can check values before saving them.
- Computed values: you can calculate results on demand.
- Backward compatibility: you can add logic later without breaking callers.
Properties also help when your class grows. If you later need to add a check, you do not have to rewrite every line that touches the attribute.
The Getter: Reading a Value
The method decorated with @property is the getter. It runs every time the attribute is read.
You can put any logic inside it. For example, you can format a value or combine several fields.
class Person:
def __init__(self, first, last):
self.first = first
self.last = last
@property
def full_name(self):
# Combine two fields into one value
return f"{self.first} {self.last}"
p = Person("Ada", "Lovelace")
print(p.full_name)
Ada Lovelace
The full_name value is never stored. It is built each time you read it. This avoids data getting out of sync.
The Setter: Writing a Value Safely
To allow writing, you add a setter. Use @name.setter where name matches the property.
Setters are perfect for validation. You can reject bad input before it corrupts your object.
class Product:
def __init__(self, price):
self.price = price # Calls the setter below
@property
def price(self):
return self._price
@price.setter
def price(self, value):
if value < 0:
raise ValueError("Price cannot be negative")
self._price = value
item = Product(20)
print(item.price)
item.price = 35
print(item.price)
item.price = -5 # This will fail
20
35
ValueError: Price cannot be negative
We store the real value in self._price. The underscore signals that it is internal. Users should go through price instead.
This pattern is common in Python. If you want to compare it with other function tools, our guide on Python lambda vs function key differences shows when small functions help and when a full method is better.
The Deleter: Removing a Value
You can also define a deleter with @name.deleter. It runs when someone uses del on the attribute.
class Account:
def __init__(self):
self._balance = 100
@property
def balance(self):
return self._balance
@balance.deleter
def balance(self):
print("Balance removed")
del self._balance
acc = Account()
print(acc.balance)
del acc.balance
100
Balance removed
Deleters are less common. But they are useful when an object must clean up state or release a resource.
Read-Only Properties
If you define only the getter, the property becomes read-only. Trying to set it raises an error.
class Config:
@property
def version(self):
return "1.0"
cfg = Config()
print(cfg.version)
cfg.version = "2.0" # Not allowed
1.0
AttributeError: can't set attribute
Read-only properties are great for values that should never change from outside the class.
Properties vs Regular Attributes
A plain attribute is simple and fast. A property adds a function call behind the scenes. For most code, the small cost does not matter.
Use a property when you need logic. Use a plain attribute when you just store data.
Do not wrap every attribute in a property by default. Add one only when you need validation, computation, or control.
Common Mistakes to Avoid
Beginners often hit a few common traps. Watch out for these.
Forgetting the underscore. If your setter assigns to the same name as the property, it calls itself forever. Always use a private name like _value.
Calling the property. Remember, you access it without parentheses. Writing obj.name() on a property that returns a string will fail.
Overusing properties. Too many properties make classes hard to read. Keep them focused.
When you debug these issues, knowing how objects and values are identified helps. Our article on the Python id function and object identity explains how to check what an object really is.
Properties with Inheritance
Properties work well with inheritance. A child class can override a property or extend it.
class Animal:
@property
def sound(self):
return "Some sound"
class Dog(Animal):
@property
def sound(self):
return "Woof"
print(Dog().sound)
Woof
If your child class calls a parent method, the super function helps. See Python super() function explained for a clear walkthrough.
When to Use the Property Decorator
Use @property when you need to:
- Validate values before they are stored.
- Compute a value from other fields.
- Keep an API stable while adding logic.
- Expose read-only data.
Skip it when a simple attribute is enough. Simpler code is easier to maintain.
Conclusion
The Python property decorator turns methods into attribute-like values. It gives you clean syntax with full control over reading, writing, and deleting data.
Start with a simple getter. Add a setter when you need validation. Keep internal values in underscore-prefixed names.
Used well, properties make your classes safer and easier to use. Practice with small examples, and you will master them quickly.