Python property() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Built-in type

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):

python
class Example:
    @property
    def value(self):
        return self._value

    @value.setter
    def value(self, new_value):
        self._value = new_value
CallWhat 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
python
property(fget=None, fset=None, fdel=None, doc=None)
# class property: a data descriptor

Parameters

ParameterDescription
fgetOptional. Function that returns the value.
fsetOptional. Function that receives the new value.
fdelOptional. Function called by del.
docOptional. Docstring; defaults to the getter's docstring.

Return Value

Return ValueDescription
propertyA property object to store as a class attribute.

Python Examples

Example 1 — A Read-Only Computed Attribute

Compute a diameter from a radius and see what happens when you assign to it.

python
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")

How It Works

  1. No parentheses. c.diameter calls the method but reads like an attribute.
  2. Always current. After the radius changes to 7, the diameter is recomputed as 14.
  3. Read-only. Without a setter, assignment raises AttributeError.
  4. 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.

python
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)

How It Works

  1. Getter and setter. @balance.setter attaches the setter to the same property.
  2. Hidden storage. The real value lives in self._balance.
  3. Validation everywhere. self.balance = balance in __init__ also goes through the setter, so Account(-1) fails.
  4. 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.

python
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

  1. Plain call. property(get, set, doc=...) builds what the decorators would.
  2. Convert on read. 100 °C is returned as 212.0 °F.
  3. Convert on write. Setting 32 °F stores 0.0 °C internally.
  4. Lives on the class. Temperature.fahrenheit is the property object itself, with its docstring.

Frequently Asked Questions

It turns a method into an attribute that is computed when read, so obj.x calls the method without parentheses.
Define another method with the same name decorated with @name.setter.
Use @property without a setter. Assigning to it raises AttributeError.
The getter or setter uses self.name instead of the backing field, like self._name, so it calls itself.
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

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

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