Home Python Built-in Functions property() Python property() Function Definition In Python, property() creates a managed attribute : code that looks like plain attribute access, obj.x, actually calls a method. It is almost always used as the @property decorator on a getter method.
Add @x.setter to run code on assignment, for example to validate the value, and @x.deleter for del obj.x. Without a setter, the attribute is read-only . This lets a class start with simple attributes and add logic later without changing the code that uses it.
property is a built-in type (a class) that you call like a function: each call creates a new property object. Like every built-in, it lives in the builtins module and is always available without an import.
Syntax Decorator form (most common):
class Example:
@property
def value(self):
return self._value
@value.setter
def value(self, new_value):
self._value = new_value Call What it does @propertyDefines the getter. @value.setterRuns on obj.value = x. @value.deleterRuns on del obj.value. property(fget, fset)The same, without decorators.
Store the real data under a different name, such as self._value; using the property name inside its own getter would call itself forever.
Library declarations property(fget=None, fset=None, fdel=None, doc=None)
# class property: a data descriptor Parameters Parameter Description fget Optional. Function that returns the value. fset Optional. Function that receives the new value. fdel Optional. Function called by del. doc Optional. Docstring; defaults to the getter's docstring.
Return Value Return Value Description property A property object to store as a class attribute.
Python Examples 1. Computed attribute 2. Validation 3. property() call Example 1 — A Read-Only Computed Attribute Compute a diameter from a radius and see what happens when you assign to it.
class Circle:
def __init__(self, radius):
self.radius = radius
@property
def diameter(self):
return self.radius * 2
c = Circle(5)
print(c.diameter)
c.radius = 7
print(c.diameter)
try:
c.diameter = 20
except AttributeError:
print("diameter is read-only") 10
14
diameter is read-only How It Works No parentheses. c.diameter calls the method but reads like an attribute.Always current. After the radius changes to 7, the diameter is recomputed as 14.Read-only. Without a setter, assignment raises AttributeError.Nothing stored. The diameter is calculated on every access, so it can never go stale.Example 2 — Validate Values with a Setter Reject negative balances, including the value passed to the constructor.
class Account:
def __init__(self, balance):
self.balance = balance
@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
acct = Account(100)
acct.balance = 250
print(acct.balance)
try:
acct.balance = -5
except ValueError:
print("rejected a negative balance")
try:
Account(-1)
except ValueError:
print("the setter also runs inside __init__")
print(acct.balance) 250
rejected a negative balance
the setter also runs inside __init__
250 How It Works Getter and setter. @balance.setter attaches the setter to the same property.Hidden storage. The real value lives in self._balance.Validation everywhere. self.balance = balance in __init__ also goes through the setter, so Account(-1) fails.Unchanged on error. The rejected assignment leaves the balance at 250.Example 3 — Create a Property Without Decorators Pass getter and setter functions to property() and inspect the result.
class Temperature:
def __init__(self, celsius):
self._celsius = celsius
def get_fahrenheit(self):
return self._celsius * 9 / 5 + 32
def set_fahrenheit(self, value):
self._celsius = (value - 32) * 5 / 9
fahrenheit = property(get_fahrenheit, set_fahrenheit, doc="Degrees F")
t = Temperature(100)
print(t.fahrenheit)
t.fahrenheit = 32
print(t._celsius)
print(type(Temperature.fahrenheit).__name__, Temperature.fahrenheit.__doc__) How It Works Plain call. property(get, set, doc=...) builds what the decorators would.Convert on read. 100 °C is returned as 212.0 °F.Convert on write. Setting 32 °F stores 0.0 °C internally.Lives on the class. Temperature.fahrenheit is the property object itself, with its docstring.Frequently Asked Questions What does @property do in Python? It turns a method into an attribute that is computed when read, so obj.x calls the method without parentheses.
How do I add a setter to a property? Define another method with the same name decorated with @name.setter.
How do I make a read-only attribute? Use @property without a setter. Assigning to it raises AttributeError.
Why do I get RecursionError in my property? The getter or setter uses self.name instead of the backing field, like self._name, so it calls itself.
When should I use a property instead of a method? For cheap values that feel like data, such as area or full_name. Use a method for slow work or actions.
Next: range() Lazy sequence of integers for loops and indexing.
range() → About the author Developer, cloud engineer, and technical writer
I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.
7 people found this page helpful
Helpful Share Copy link Suggestion