@propertyの使い方まとめ(Python) ゲッター・セッターを簡潔に

class Person:
    def __init__(self, first_name: str, last_name: str) -> None:
        # バッキングフィールドに実データを保持
        self._first_name = first_name
        self._last_name = last_name

    @property
    def full_name(self) -> str:
        """名と姓から表示用の氏名を返します(読み取り専用)。"""
        # 取得時に計算して返す(計算プロパティ)
        return f"{self._first_name} {self._last_name}"

p = Person("Taro", "Yamada")
print(p.full_name)   # 読み取りは可能
# p.full_name = "X"  # 書き込みはエラー(AttributeError)

class Temperature:
    def __init__(self, celsius: float) -> None:
        self._celsius = float(celsius)  # バッキングフィールド

    @property
    def celsius(self) -> float:
        """摂氏温度を返します。"""
        return self._celsius

    @celsius.setter
    def celsius(self, value: float) -> None:
        """摂氏温度を設定します。絶対零度未満は不可です。"""
        # バリデーションを実施
        if not isinstance(value, (int, float)):
            raise TypeError("celsiusは数値で指定してください")
        if value < -273.15:
            raise ValueError("celsiusは-273.15以上である必要があります")
        self._celsius = float(value)

t = Temperature(0)
print(t.celsius)
t.celsius = 100
print(t.celsius)

class CacheHolder:
    def __init__(self) -> None:
        self._data = [1, 2, 3]
        self._sum_cache = None  # 計算結果のキャッシュ

    @property
    def total(self) -> int:
        """配列の合計値(キャッシュあり)。"""
        if self._sum_cache is None:
            # 高コスト計算を想定
            self._sum_cache = sum(self._data)
        return self._sum_cache

    @total.deleter
    def total(self) -> None:
        """キャッシュを破棄します。"""
        self._sum_cache = None  # 後片付け

c = CacheHolder()
print(c.total)  # 初回は計算
print(c.total)  # 2回目はキャッシュ
del c.total     # キャッシュ破棄
print(c.total)  # 再計算

class Meter:
    def __init__(self, value: float) -> None:
        self._value = float(value)

    @property
    def value(self) -> float:
        """メートル(m)単位の長さ。0以上の数値。"""
        return self._value

print(Meter.value.__doc__)  # プロパティのdocstringにアクセス
help(Meter)                 # クラスのヘルプにプロパティ説明が含まれる

class User:
    def __init__(self, name: str, age: int) -> None:
        self._name = name
        self._age = None
        self.age = age  # セッター経由で検証

    @property
    def age(self) -> int:
        """年齢は0以上の整数。"""
        return self._age

    @age.setter
    def age(self, value: int) -> None:
        if not isinstance(value, int):
            raise TypeError("ageはintで指定してください。例: user.age = 20")
        if value < 0:
            raise ValueError("ageは0以上である必要があります。例: user.age = 0")
        self._age = value

u = User("A", 18)
print(u.age)
# u.age = -1  # ValueError

class Rectangle:
    def __init__(self, width: float, height: float) -> None:
        self._width = float(width)
        self._height = float(height)

    @property
    def area(self) -> float:
        """面積(読み取り専用の計算プロパティ)。"""
        return self._width * self._height

r = Rectangle(3, 4)
print(r.area)  # 3×4=12

# 初期版(公開属性)
class ProductV1:
    def __init__(self, price: float) -> None:
        self.price = price  # 直接代入

# 改訂版(プロパティ化して検証追加)
class ProductV2:
    def __init__(self, price: float) -> None:
        self._price = 0.0
        self.price = price  # 既存コードを壊さない

    @property
    def price(self) -> float:
        """価格。0以上の数値。"""
        return self._price

    @price.setter
    def price(self, value: float) -> None:
        if not isinstance(value, (int, float)):
            raise TypeError("priceは数値で指定してください")
        if value < 0:
            raise ValueError("priceは0以上である必要があります")
        self._price = float(value)

p = ProductV2(1200)
print(p.price)
p.price = 1500
print(p.price)

class Percentage:
    def __init__(self, value: float) -> None:
        self._value = 0.0
        self.value = value

    @property
    def value(self) -> float:
        """0.0〜1.0の割合。例: 25%は0.25"""
        return self._value

    @value.setter
    def value(self, v: float) -> None:
        if not isinstance(v, (int, float)):
            raise TypeError("valueは数値で指定してください。例: pct.value = 0.25")
        if not (0.0 <= v <= 1.0):
            raise ValueError("valueは0.0〜1.0の範囲で指定してください。例: pct.value = 0.75")
        self._value = float(v)

pct = Percentage(0.3)
print(pct.value)

class Bad:
    @property
    def x(self) -> int:
        return self._x

    @x.setter
    def x(self, v: int) -> None:
        # self.x = v  # これは無限再帰になるのでNG
        self._x = v  # OK: バッキングフィールドに代入

from functools import cached_property

class Dataset:
    def __init__(self, path: str) -> None:
        self._path = path

    @cached_property
    def data(self) -> list[str]:
        """初回のみ読み込み、以後はキャッシュしたリストを返す。"""
        # 実際にはファイル読み込みなどを行う想定
        return ["row1", "row2"]

d = Dataset("data.csv")
print(d.data)   # 初回は読み込み
print(d.data)   # 2回目以降はキャッシュ

class Account:
    def __init__(self, balance: float) -> None:
        self._balance = float(balance)

    @property
    def balance(self) -> float:
        """口座残高。負の値は不可。"""
        return self._balance

    @balance.setter
    def balance(self, value: float) -> None:  # value: float で型を明示
        if value < 0:
            raise ValueError("balanceは0以上である必要があります")
        self._balance = float(value)

class Base:
    def __init__(self) -> None:
        self._x = 0

    @property
    def x(self) -> int:
        """基底のx。"""
        return self._x

    @x.setter
    def x(self, v: int) -> None:
        self._x = int(v)

class Sub(Base):
    # 取得だけロギングを追加し、設定は親のまま使う例
    @Base.x.getter
    def x(self) -> int:  # type: ignore[override]
        val = super().x  # 親のゲッターを使う
        print(f"debug: x -> {val}")
        return val

s = Sub()
s.x = 10
print(s.x)  # 取得時にログが出る