Python Property Decorators Explained — @property, Getters, Setters and Real-World Patterns

# The problem: no validation on a plain attribute
class BankAccount:
    def __init__(self, owner: str, initial_balance: float):
        self.owner = owner
        self.balance = initial_balance  # Anyone can set this to anything

# --- Calling code ---
account = BankAccount("Alice", 500.00)
print(f"Initial balance: ${account.balance}")

# Nothing stops this nonsense:
account.balance = -99999
print(f"After bad assignment: ${account.balance}")

# Or this:
account.balance = "oops"
print(f"After string assignment: ${account.balance}")

class Employee:
    def __init__(self, first_name: str, last_name: str, annual_salary: float):
        self.first_name = first_name
        self.last_name = last_name
        self.annual_salary = annual_salary

    @property
    def full_name(self) -> str:
        # Computed fresh each time — never out of sync
        return f"{self.first_name} {self.last_name}"

    @property
    def monthly_salary(self) -> float:
        # Derived from annual_salary — only one source of truth
        return round(self.annual_salary / 12, 2)

    def __repr__(self) -> str:
        return f"Employee({self.full_name}, ${self.annual_salary:,.2f}/yr)"


# --- Calling code ---
emp = Employee("Sarah", "Connor", 96000.00)

print(emp.full_name)        # Accessed like an attribute, NOT full_name()
print(emp.monthly_salary)   # Always accurate — no stale cached value

# Update the source data
emp.last_name = "Reese"
print(emp.full_name)        # Automatically reflects the change

# Attempting to SET a read-only property raises an error:
try:
    emp.full_name = "John Connor"  # No setter defined — this should fail
except AttributeError as error:
    print(f"Caught expected error: {error}")

class Thermostat:
    # Celsius limits for a home thermostat
    MIN_TEMP_CELSIUS = 5
    MAX_TEMP_CELSIUS = 35

    def __init__(self, initial_temp_celsius: float):
        # Call the setter here so validation runs even on construction
        self.temperature = initial_temp_celsius

    @property
    def temperature(self) -> float:
        # Getter: simply return the internal value
        return self._temperature

    @temperature.setter
    def temperature(self, value: float) -> None:
        # Setter: validate BEFORE storing — reject bad data at the gate
        if not isinstance(value, (int, float)):
            raise TypeError(f"Temperature must be a number, got {type(value).__name__}")
        if value < self.MIN_TEMP_CELSIUS or value > self.MAX_TEMP_CELSIUS:
            raise ValueError(
                f"Temperature {value}°C is out of range "
                f"({self.MIN_TEMP_CELSIUS}–{self.MAX_TEMP_CELSIUS}°C)"
            )
        # Store in the private backing attribute — NOT self.temperature!
        self._temperature = float(value)

    @property
    def temperature_fahrenheit(self) -> float:
        # A read-only computed property derived from the validated Celsius value
        return round(self._temperature * 9 / 5 + 32, 2)

    def __repr__(self) -> str:
        return f"Thermostat({self._temperature}°C / {self.temperature_fahrenheit}°F)"


# --- Calling code ---
thermostat = Thermostat(20)  # Setter runs during __init__ too
print(thermostat)

thermostat.temperature = 22  # Clean setter call
print(thermostat)

# The interface hasn't changed — still looks like plain attribute access
print(f"Current temp: {thermostat.temperature}°C")

# Validation in action:
try:
    thermostat.temperature = 100  # Too hot — invalid
except ValueError as error:
    print(f"ValueError: {error}")

try:
    thermostat.temperature = "warm"  # Wrong type
except TypeError as error:
    print(f"TypeError: {error}")

from functools import cached_property


class Document:
    def __init__(self, title: str, content: str):
        self.title = title
        self.content = content
        self._word_count_cache = None  # Sentinel: means 'not yet computed'

    # --- Manual lazy-caching pattern (educational — see cached_property below) ---
    @property
    def word_count(self) -> int:
        if self._word_count_cache is None:
            print("  [Computing word count for the first time...]")
            # Simulate an expensive operation by doing real work
            self._word_count_cache = len(
                [word for word in self.content.split() if word.strip()]
            )
        return self._word_count_cache

    @word_count.deleter
    def word_count(self) -> None:
        # Called when content changes — invalidate the stale cache
        print("  [Cache cleared — word count will recompute next access]")
        self._word_count_cache = None

    def update_content(self, new_content: str) -> None:
        self.content = new_content
        del self.word_count  # Explicitly invalidate cache via the deleter


# --- Python 3.8+ built-in solution for simple cases ---
class ReportCard:
    def __init__(self, student_name: str, scores: list):
        self.student_name = student_name
        self.scores = scores

    @cached_property
    def grade_average(self) -> float:
        # cached_property computes once and stores in instance.__dict__
        # After first access it bypasses the descriptor entirely — very fast
        print("  [Calculating grade average...]")
        return round(sum(self.scores) / len(self.scores), 2)


# --- Calling code ---
doc = Document("Python Tips", "Python is great and properties are useful")

print(f"Word count: {doc.word_count}")  # Triggers computation
print(f"Word count: {doc.word_count}")  # Uses cache — no recompute

doc.update_content("Short doc")          # Invalidates cache via deleter
print(f"Word count: {doc.word_count}")  # Recomputes with new content

print()

report = ReportCard("Maya", [88, 92, 79, 95, 83])
print(f"Average: {report.grade_average}")  # Computed once
print(f"Average: {report.grade_average}")  # Returned from instance dict