Properties

Intermediate ~25 min read

The @property decorator transforms methods into attribute-like access, giving you the clean syntax of obj.value while keeping the control of getter/setter methods. This is Python's preferred way to implement managed attributes with validation, computation, or lazy loading.

Why Properties?

Properties let you:

Add validation without changing how users access the attribute
Create computed values that look like attributes
Make read-only attributes
Refactor internal implementation without breaking the public API

Property Basics

The @property decorator turns a method into a "getter" that's accessed like an attribute - no parentheses needed.

# Property Basics - The @property Decorator

print("=== @property Basics ===\n")

# 1. The problem with getter methods
print("1. Traditional getter methods are verbose:")

class CircleBad:
    def __init__(self, radius):
        self._radius = radius

def get_radius(self):
        return self._radius

def get_area(self):
        import math
        return math.pi * self._radius ** 2

c = CircleBad(5)
print(f"   radius: {c.get_radius()}")  # Verbose!
print(f"   area: {c.get_area()}")      # Verbose!
print()

# 2. Properties - access like attributes
print("2. Properties - cleaner attribute-like access:")

class Circle:
    def __init__(self, radius):
        self._radius = radius

@property
    def radius(self):
        """Getter - called when you access circle.radius"""
        return self._radius

@property
    def area(self):
        """Read-only computed property."""
        import math
        return math.pi * self._radius ** 2

c = Circle(5)
print(f"   radius: {c.radius}")  # Looks like an attribute!
print(f"   area: {c.area:.2f}")  # Computed on access!
print()

# 3. Properties under the hood
print("3. What @property does:")
print("""
   @property
   def radius(self):
       return self._radius

Is equivalent to:

def get_radius(self):
       return self._radius
   radius = property(get_radius)
""")

# 4. Read-only properties (getter only)
print("4. Read-only properties (no setter defined):")

class Employee:
    def __init__(self, first_name, last_name, salary):
        self._first_name = first_name
        self._last_name = last_name
        self._salary = salary

@property
    def full_name(self):
        """Read-only: computed from first and last name."""
        return f"{self._first_name} {self._last_name}"

@property
    def annual_salary(self):
        """Read-only: computed from monthly salary."""
        return self._salary * 12

emp = Employee("John", "Doe", 5000)
print(f"   full_name: {emp.full_name}")
print(f"   annual_salary: ${emp.annual_salary:,}")

# Try to set read-only property
try:
    emp.full_name = "Jane Doe"
except AttributeError as e:
    print(f"   Setting full_name failed: property 'full_name' has no setter")
print()

# 5. Why use properties?
print("5. Benefits of @property:")
print("""
   - Cleaner syntax: obj.value instead of obj.get_value()
   - Can add validation later without changing interface
   - Can create computed/derived attributes
   - Backward compatible: change implementation without API change
   - Pythonic: follows Python conventions
""")

Output

Click Run to execute your code

Start Public, Add Properties Later

Python's philosophy: start with simple public attributes. If you later need validation or computation, convert to a property - the interface stays the same! Users still write obj.value, not obj.get_value().

Property Setters

Add a setter to allow assignment (obj.value = x) with validation. Use the @property_name.setter decorator.

# Property Setters - @property.setter

print("=== Property Setters ===\n")

# 1. Adding a setter to a property
print("1. Getter and setter together:")

class Temperature:
    def __init__(self, celsius=0):
        self._celsius = celsius

@property
    def celsius(self):
        """Getter for celsius."""
        return self._celsius

@celsius.setter
    def celsius(self, value):
        """Setter with validation."""
        if value < -273.15:
            raise ValueError("Temperature below absolute zero!")
        self._celsius = value

temp = Temperature(25)
print(f"   Initial: {temp.celsius}°C")

temp.celsius = 100  # Calls setter
print(f"   After setting to 100: {temp.celsius}°C")

try:
    temp.celsius = -300  # Validation fails
except ValueError as e:
    print(f"   Validation error: {e}")
print()

# 2. Property with type conversion
print("2. Setter with type conversion:")

class Person:
    def __init__(self, name, age):
        self._name = name
        self._age = age

@property
    def age(self):
        return self._age

@age.setter
    def age(self, value):
        """Convert to int and validate."""
        value = int(value)  # Convert strings, floats
        if value < 0 or value > 150:
            raise ValueError("Age must be between 0 and 150")
        self._age = value

p = Person("Alice", 30)
print(f"   Initial age: {p.age}")

p.age = "35"  # String - gets converted
print(f"   After setting '35' (string): {p.age}")

p.age = 40.9  # Float - gets converted to int
print(f"   After setting 40.9 (float): {p.age}")
print()

# 3. The setter must have the same name
print("3. Setter pattern:")
print("""
   @property
   def name(self):
       return self._name

@name.setter  # Must be @<property_name>.setter
   def name(self, value):
       self._name = value
""")

# 4. Property with deleter
print("4. Adding a deleter:")

class User:
    def __init__(self, email):
        self._email = email

@property
    def email(self):
        return self._email

@email.setter
    def email(self, value):
        if '@' not in value:
            raise ValueError("Invalid email")
        self._email = value

@email.deleter
    def email(self):
        """Called by: del user.email"""
        print("   Clearing email...")
        self._email = None

user = User("alice@example.com")
print(f"   Email: {user.email}")

del user.email  # Calls deleter
print(f"   After delete: {user.email}")
print()

# 5. Complete example with all three
print("5. Complete property (getter, setter, deleter):")

class BankAccount:
    def __init__(self, initial_balance=0):
        self._balance = initial_balance

@property
    def balance(self):
        """Get current balance."""
        return self._balance

@balance.setter
    def balance(self, value):
        """Set balance with validation."""
        if value < 0:
            raise ValueError("Balance cannot be negative")
        self._balance = value

@balance.deleter
    def balance(self):
        """Close account (reset to zero)."""
        print("   Account closed.")
        self._balance = 0

account = BankAccount(1000)
print(f"   Balance: ${account.balance}")
account.balance = 500
print(f"   New balance: ${account.balance}")

Output

Click Run to execute your code

Setter Must Have the Same Name

The setter decorator must be @property_name.setter and the method name must match the property name. The internal storage should use a different name (typically with underscore: _property_name).

Computed Properties

Properties can compute values from other attributes - like area from width and height. These are typically read-only (no setter).

# Computed Properties

print("=== Computed Properties ===\n")

# 1. Derived values as properties
print("1. Properties computed from other attributes:")

class Rectangle:
    def __init__(self, width, height):
        self.width = width
        self.height = height

@property
    def area(self):
        """Computed: width * height."""
        return self.width * self.height

@property
    def perimeter(self):
        """Computed: 2 * (width + height)."""
        return 2 * (self.width + self.height)

@property
    def is_square(self):
        """Computed: check if square."""
        return self.width == self.height

rect = Rectangle(4, 5)
print(f"   Rectangle: {rect.width} x {rect.height}")
print(f"   Area: {rect.area}")
print(f"   Perimeter: {rect.perimeter}")
print(f"   Is square? {rect.is_square}")

# Properties update when source changes
rect.width = 5
print(f"   After width=5: Area={rect.area}, Is square? {rect.is_square}")
print()

# 2. Converting between units
print("2. Unit conversion properties:")

class Temperature:
    def __init__(self, celsius):
        self._celsius = celsius

@property
    def celsius(self):
        return self._celsius

@celsius.setter
    def celsius(self, value):
        self._celsius = value

@property
    def fahrenheit(self):
        """Convert celsius to fahrenheit."""
        return self._celsius * 9/5 + 32

@fahrenheit.setter
    def fahrenheit(self, value):
        """Set via fahrenheit, store as celsius."""
        self._celsius = (value - 32) * 5/9

@property
    def kelvin(self):
        """Convert celsius to kelvin."""
        return self._celsius + 273.15

temp = Temperature(0)
print(f"   0°C = {temp.fahrenheit}°F = {temp.kelvin}K")

temp.fahrenheit = 212  # Set via fahrenheit
print(f"   212°F = {temp.celsius}°C = {temp.kelvin}K")
print()

# 3. Formatted output properties
print("3. Formatting properties:")

class Product:
    def __init__(self, name, price_cents):
        self.name = name
        self._price_cents = price_cents

@property
    def price(self):
        """Return price in dollars."""
        return self._price_cents / 100

@property
    def price_display(self):
        """Formatted price string."""
        return f"${self.price:.2f}"

@property
    def price_cents(self):
        return self._price_cents

product = Product("Widget", 1999)  # $19.99
print(f"   {product.name}: {product.price_display}")
print(f"   Raw cents: {product.price_cents}")
print()

# 4. Cached/lazy computed properties
print("4. Lazy evaluation (computed once):")

class DataAnalyzer:
    def __init__(self, data):
        self.data = data
        self._mean = None  # Cache

@property
    def mean(self):
        """Compute mean only once, then cache."""
        if self._mean is None:
            print("   (Computing mean...)")
            self._mean = sum(self.data) / len(self.data)
        return self._mean

analyzer = DataAnalyzer([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
print(f"   First access: {analyzer.mean}")   # Computes
print(f"   Second access: {analyzer.mean}")  # Uses cache
print()

# 5. Using functools.cached_property (Python 3.8+)
print("5. @cached_property (Python 3.8+):")
print("""
   from functools import cached_property

class DataAnalyzer:
       @cached_property
       def mean(self):
           # Computed only once, automatically cached
           return sum(self.data) / len(self.data)
""")

Output

Click Run to execute your code

@cached_property (Python 3.8+)

For expensive computations that don't change, use @cached_property from functools. It computes once on first access and caches the result. Unlike @property, it doesn't recompute on each access.

Practical Property Patterns

Real-world uses of properties: backward-compatible refactoring, dependent properties, lazy loading, and access tracking.

# Practical Property Patterns

print("=== Practical Property Patterns ===\n")

# 1. Backward compatible refactoring
print("1. Refactoring without breaking API:")

# BEFORE: Direct attribute access
class PersonOld:
    def __init__(self, name):
        self.name = name  # Public attribute

# AFTER: Add validation without changing interface
class Person:
    def __init__(self, name):
        self._name = None
        self.name = name  # Uses setter

@property
    def name(self):
        return self._name

@name.setter
    def name(self, value):
        if not value or not value.strip():
            raise ValueError("Name cannot be empty")
        self._name = value.strip().title()

# Same API, but now with validation!
p = Person("  alice  ")
print(f"   Name: '{p.name}'")  # Cleaned: 'Alice'
print()

# 2. Dependent properties
print("2. Dependent properties (circle example):")

import math

class Circle:
    def __init__(self, radius):
        self._radius = radius

@property
    def radius(self):
        return self._radius

@radius.setter
    def radius(self, value):
        if value <= 0:
            raise ValueError("Radius must be positive")
        self._radius = value

@property
    def diameter(self):
        """diameter = 2 * radius"""
        return self._radius * 2

@diameter.setter
    def diameter(self, value):
        """Setting diameter updates radius."""
        self.radius = value / 2  # Uses radius setter for validation

@property
    def area(self):
        return math.pi * self._radius ** 2

@property
    def circumference(self):
        return 2 * math.pi * self._radius

c = Circle(5)
print(f"   radius={c.radius}, diameter={c.diameter}")
print(f"   area={c.area:.2f}, circumference={c.circumference:.2f}")

c.diameter = 20  # Set via diameter
print(f"   After diameter=20: radius={c.radius}")
print()

# 3. Property for lazy database loading
print("3. Lazy loading pattern:")

class User:
    def __init__(self, user_id):
        self.user_id = user_id
        self._profile = None  # Not loaded yet

@property
    def profile(self):
        """Load profile only when needed."""
        if self._profile is None:
            print(f"   Loading profile for user {self.user_id}...")
            # Simulate database fetch
            self._profile = {"name": "Alice", "email": "alice@example.com"}
        return self._profile

user = User(123)
print(f"   User ID: {user.user_id}")
print(f"   Profile: {user.profile}")  # Loads now
print(f"   Profile again: {user.profile}")  # Uses cache
print()

# 4. Read-only after initialization
print("4. Write-once property (immutable after init):")

class Config:
    def __init__(self, api_key):
        self._api_key = api_key
        self._initialized = True

@property
    def api_key(self):
        return self._api_key

@api_key.setter
    def api_key(self, value):
        if hasattr(self, '_initialized'):
            raise AttributeError("api_key is read-only after initialization")
        self._api_key = value

config = Config("secret-key-123")
print(f"   API Key: {config.api_key}")

try:
    config.api_key = "new-key"
except AttributeError as e:
    print(f"   Cannot change: {e}")
print()

# 5. Property with logging/tracking
print("5. Property with access logging:")

class TrackedValue:
    def __init__(self, initial):
        self._value = initial
        self._access_count = 0
        self._change_count = 0

@property
    def value(self):
        self._access_count += 1
        return self._value

@value.setter
    def value(self, new_value):
        self._change_count += 1
        self._value = new_value

@property
    def stats(self):
        return f"Accessed {self._access_count}x, Changed {self._change_count}x"

t = TrackedValue(100)
_ = t.value  # Access
_ = t.value  # Access
t.value = 200  # Change
_ = t.value  # Access
print(f"   Current value: {t.value}")
print(f"   Stats: {t.stats}")

Output

Click Run to execute your code

Properties for API Stability

Properties let you change implementation details without changing the public interface. Users write the same obj.value whether it's stored directly, computed, validated, or lazily loaded.

Common Mistakes

1. Using the same name for property and storage

# Wrong - infinite recursion!
class Person:
    @property
    def name(self):
        return self.name  # Calls itself!

    @name.setter
    def name(self, value):
        self.name = value  # Calls itself!

# Correct - use different name for storage
class Person:
    @property
    def name(self):
        return self._name  # Underscore prefix

    @name.setter
    def name(self, value):
        self._name = value

2. Forgetting to use @property_name.setter

# Wrong - this creates a new property!
class Circle:
    @property
    def radius(self):
        return self._radius

    @property  # Wrong! Should be @radius.setter
    def radius(self, value):
        self._radius = value

# Correct
class Circle:
    @property
    def radius(self):
        return self._radius

    @radius.setter  # Correct decorator
    def radius(self, value):
        self._radius = value

3. Not using the setter in init

# Problem - validation bypassed in __init__
class Temperature:
    def __init__(self, celsius):
        self._celsius = celsius  # Bypasses validation!

    @property
    def celsius(self):
        return self._celsius

    @celsius.setter
    def celsius(self, value):
        if value < -273.15:
            raise ValueError("Below absolute zero!")
        self._celsius = value

# Better - use property in __init__ for validation
class Temperature:
    def __init__(self, celsius):
        self.celsius = celsius  # Uses setter - validates!

4. Making properties do too much work

# Bad - expensive operation on every access
class Report:
    @property
    def data(self):
        # This runs a database query EVERY time!
        return self.database.fetch_all_records()

# Better - cache expensive operations
class Report:
    @property
    def data(self):
        if self._data is None:
            self._data = self.database.fetch_all_records()
        return self._data

# Or use @cached_property (Python 3.8+)

5. Properties with side effects

# Bad - getter with surprising side effects
class Counter:
    @property
    def value(self):
        self._access_count += 1  # Side effect!
        return self._value

# Getters should be "pure" - no unexpected changes
# If you need to track access, be explicit about it

Exercise: Temperature Converter

Task: Create a Temperature class with properties for multiple units.

Requirements:

celsius property with getter and setter (validates >= -273.15)
fahrenheit property with getter and setter (converts to/from celsius)
kelvin property - read-only getter (celsius + 273.15)
__str__ showing all three units

Output

Click Run to execute your code

Show Solution

class Temperature:
    def __init__(self, celsius=0):
        self.celsius = celsius  # Uses setter

    @property
    def celsius(self):
        return self._celsius

    @celsius.setter
    def celsius(self, value):
        if value < -273.15:
            raise ValueError("Temperature below absolute zero!")
        self._celsius = value

    @property
    def fahrenheit(self):
        return self._celsius * 9/5 + 32

    @fahrenheit.setter
    def fahrenheit(self, value):
        self.celsius = (value - 32) * 5/9

    @property
    def kelvin(self):
        return self._celsius + 273.15
    # No kelvin setter - read-only!

    def __str__(self):
        return f"{self.celsius}°C / {self.fahrenheit}°F / {self.kelvin}K"


# Test
t = Temperature(0)
print(t)  # 0°C / 32.0°F / 273.15K

t.celsius = 100
print(t)  # 100°C / 212.0°F / 373.15K

t.fahrenheit = 68
print(t)  # 20.0°C / 68.0°F / 293.15K

Summary

@property creates a getter - access method like an attribute
@name.setter creates a setter with validation
@name.deleter handles del obj.name
Store internal value with underscore: _name (not same as property name!)
Computed properties derive values from other attributes
Use @cached_property for expensive one-time computations

What's Next?

Now that you understand properties, learn about Abstract Classes - using the abc module to define interfaces that subclasses must implement, ensuring consistent APIs across related classes.

Previous Special Methods

Next Abstract Classes

Why Properties?

Property Basics

Start Public, Add Properties Later

Property Setters

Setter Must Have the Same Name

Computed Properties

@cached_property (Python 3.8+)

Practical Property Patterns

Properties for API Stability

Common Mistakes

1. Using the same name for property and storage

2. Forgetting to use @property_name.setter

3. Not using the setter in __init__

4. Making properties do too much work

5. Properties with side effects

Exercise: Temperature Converter

Summary

What's Next?

Enjoying these tutorials?

3. Not using the setter in init