描述符与 property

# Python 3.10+

class ReadLoggingDescriptor:
    """每次读取属性时打印日志的非数据描述符"""

    def __get__(self, instance, owner):
        attr_name = getattr(self, 'attr_name', 'unknown')
        if instance is None:
            # 通过类访问：返回描述符自身
            return self
        print(f"[LOG] 读取 {owner.__name__}.{attr_name}")
        return instance.__dict__.get(attr_name, None)

    def __set_name__(self, owner, name):
        self.attr_name = name


class User:
    username = ReadLoggingDescriptor()

    def __init__(self, username: str):
        self.username = username


u = User("alice")
print(u.username)  # [LOG] 读取 User.username  ->  alice
print(User.username)  # <__main__.ReadLoggingDescriptor object at ...>

# Python 3.10+

class NonNegativeNumber:
    """确保存储的值始终为非负数"""

    def __set_name__(self, owner, name: str):
        self.private_name = f"_{name}"

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return getattr(instance, self.private_name, None)

    def __set__(self, instance, value):
        if not isinstance(value, (int, float)):
            raise TypeError(f"期望数字类型，实际为 {type(value).__name__}")
        if value < 0:
            raise ValueError(f"值不能为负数，当前为 {value}")
        instance.__dict__[self.private_name] = value


class Product:
    price = NonNegativeNumber()
    stock = NonNegativeNumber()

    def __init__(self, price: float, stock: int):
        self.price = price
        self.stock = stock


p = Product(19.99, 100)
print(p.price)   # 19.99
p.price = 29.99  # OK
# p.price = -5   # ValueError: 值不能为负数，当前为 -5

# Python 3.10+

class ProtectedAttribute:
    """防止误删关键属性"""

    def __set_name__(self, owner, name: str):
        self.private_name = f"_{name}"

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return getattr(instance, self.private_name, None)

    def __set__(self, instance, value):
        instance.__dict__[self.private_name] = value

    def __delete__(self, instance):
        raise AttributeError(f"禁止删除该属性")


class Config:
    api_key = ProtectedAttribute()

    def __init__(self, api_key: str):
        self.api_key = api_key


cfg = Config("sk-abc123")
# del cfg.api_key  # AttributeError: 禁止删除该属性

# Python 3.10+

class TypedField:
    """Python 3.5 风格：需要手动传入字段名"""

    def __init__(self, field_type, field_name):
        self.field_type = field_type
        self.field_name = field_name
        self.private_name = f"_{field_name}"

    def __set__(self, instance, value):
        if not isinstance(value, self.field_type):
            raise TypeError(
                f"期望 {self.field_type.__name__}, 实际为 {type(value).__name__}"
            )
        instance.__dict__[self.private_name] = value

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return instance.__dict__.get(self.private_name)


class OldStylePerson:
    name = TypedField(str, "name")  # 烦人！需要重复写字段名
    age = TypedField(int, "age")


# --- Python 3.6+ 风格 ---
class ModernTypedField:
    """__set_name__ 自动获知字段名"""

    def __init__(self, field_type):
        self.field_type = field_type
        # 字段名将在 __set_name__ 中自动设置

    def __set_name__(self, owner, name: str):
        self.field_name = name
        self.private_name = f"_{name}"

    def __set__(self, instance, value):
        if not isinstance(value, self.field_type):
            raise TypeError(
                f"期望 {self.field_type.__name__}, 实际为 {type(value).__name__}"
            )
        instance.__dict__[self.private_name] = value

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return instance.__dict__.get(self.private_name)


class ModernPerson:
    name = ModernTypedField(str)  # 简洁！字段名自动推断
    age = ModernTypedField(int)


p = ModernPerson()
p.name = "Bob"
p.age = 30
print(p.name, p.age)  # Bob 30

# Python 3.10+

class DataDesc:
    """数据描述符：实现了 __get__ 和 __set__"""

    def __get__(self, instance, owner):
        print("  DataDesc.__get__ 被调用")
        if instance is None:
            return self
        return instance.__dict__.get('_val', 0)

    def __set__(self, instance, value):
        print("  DataDesc.__set__ 被调用")
        instance.__dict__['_val'] = value


class Demo:
    attr = DataDesc()


d = Demo()
d.attr = 42       # DataDesc.__set__ 被调用（走描述符）
print(d.attr)     # DataDesc.__get__ 被调用 -> 42（走描述符，不会读 __dict__["attr"]）

# 尝试绕过描述符，直接写入实例字典
d.__dict__['attr'] = 100
print(d.attr)     # DataDesc.__get__ 被调用 -> 42
# 仍是 42！因为数据描述符的 __get__ 优先级高于实例 __dict__

# Python 3.10+

class NonDataDesc:
    """非数据描述符：只实现了 __get__"""

    def __get__(self, instance, owner):
        print("  NonDataDesc.__get__ 被调用")
        if instance is None:
            return self
        return "来自非数据描述符的值"


class Demo:
    attr = NonDataDesc()


d = Demo()
print(d.attr)
# 输出：
#   NonDataDesc.__get__ 被调用
#   来自非数据描述符的值

# 实例字典中的同名属性会"遮蔽"非数据描述符
d.__dict__['attr'] = "实例字典中的值"
print(d.attr)
# 输出：实例字典中的值（不再触发 __get__）

# Python 3.10+

class DataDesc:
    def __set_name__(self, owner, name):
        self.name = name

    def __get__(self, instance, owner):
        print(f"  -> DataDesc.__get__ (数据描述符)")
        return f"data_desc:{self.name}"

    def __set__(self, instance, value):
        print(f"  -> DataDesc.__set__: {value}")


class NonDataDesc:
    def __set_name__(self, owner, name):
        self.name = name

    def __get__(self, instance, owner):
        print(f"  -> NonDataDesc.__get__ (非数据描述符)")
        return f"nondata_desc:{self.name}"


def verify_lookup():
    """验证完整的属性查找优先级"""

    class Klass:
        data_attr = DataDesc()
        nondata_attr = NonDataDesc()
        class_attr = "我是类属性"

        def __init__(self):
            self.instance_attr = "我是实例属性"
            # 注意：这里不手动设置 data_attr 和 nondata_attr 的实例字典值

        def __getattr__(self, name):
            print(f"  -> __getattr__({name!r})")
            return f"fallback:{name}"

    obj = Klass()

    print("\n=== 1. 数据描述符（最高优先级） ===")
    print(obj.data_attr)  # DataDesc.__get__

    print("\n=== 2. 实例字典（次高优先级） ===")
    print(obj.instance_attr)

    print("\n=== 3. 非数据描述符（在实例字典之后） ===")
    print(obj.nondata_attr)  # NonDataDesc.__get__（实例字典中没有该 key）

    # 现在让实例字典 "遮蔽" 非数据描述符
    obj.__dict__['nondata_attr'] = "实例覆盖了非数据描述符"
    print(obj.nondata_attr)  # "实例覆盖了非数据描述符" —— 不再触发 __get__

    print("\n=== 4. 类属性（描述符之后的兜底） ===")
    print(obj.class_attr)

    print("\n=== 5. __getattr__（最后的钩子） ===")
    print(obj.no_such_attr)  # __getattr__

verify_lookup()

=== 1. 数据描述符（最高优先级） ===
  -> DataDesc.__get__ (数据描述符)
data_desc:data_attr

=== 2. 实例字典（次高优先级） ===
我是实例属性

=== 3. 非数据描述符（在实例字典之后） ===
  -> NonDataDesc.__get__ (非数据描述符)
nondata_desc:nondata_attr
实例覆盖了非数据描述符

=== 4. 类属性（描述符之后的兜底） ===
我是类属性

=== 5. __getattr__（最后的钩子） ===
  -> __getattr__('no_such_attr')
fallback:no_such_attr

# Python 3.10+

class MyProperty:
    """property 的精简实现（省略文档生成和 __delete__ 等细节）"""

    def __init__(self, fget=None, fset=None, fdel=None):
        self.fget = fget
        self.fset = fset
        self.fdel = fdel

    def __get__(self, instance, owner):
        if instance is None:
            return self
        if self.fget is None:
            raise AttributeError("unreadable attribute")
        return self.fget(instance)

    def __set__(self, instance, value):
        if self.fset is None:
            raise AttributeError("can't set attribute")
        self.fset(instance, value)

    def __delete__(self, instance):
        if self.fdel is None:
            raise AttributeError("can't delete attribute")
        self.fdel(instance)

    def setter(self, fset):
        """支持 @prop.setter 语法"""
        self.fset = fset
        return self

    def deleter(self, fdel):
        """支持 @prop.deleter 语法"""
        self.fdel = fdel
        return self

    def getter(self, fget):
        """支持 @prop.getter 语法"""
        self.fget = fget
        return self


# --- 使用自己的 MyProperty ---
class Rectangle:
    def __init__(self, width: float, height: float):
        self._width = width
        self._height = height

    @MyProperty
    def area(self):
        """计算面积"""
        return self._width * self._height

    @MyProperty
    def width(self):
        return self._width

    @width.setter
    def width(self, value: float):
        if value <= 0:
            raise ValueError("宽度必须为正数")
        self._width = value


rect = Rectangle(3.0, 4.0)
print(rect.area)   # 12.0
rect.width = 5.0
print(rect.area)   # 20.0
# rect.area = 100  # AttributeError: can't set attribute（只有 fget，无 fset）

# Python 3.10+

# 写法一：装饰器（推荐）
class User:
    def __init__(self, name: str):
        self._name = name

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

    @name.setter
    def name(self, value: str):
        if not value.strip():
            raise ValueError("名称不能为空")
        self._name = value.strip()


# 写法二：函数式构造（等价于写法一）
class UserV2:
    def __init__(self, name: str):
        self._name = name

    def get_name(self):
        return self._name

    def set_name(self, value: str):
        if not value.strip():
            raise ValueError("名称不能为空")
        self._name = value.strip()

    name = property(get_name, set_name)

# Python 3.10+

from typing import Any, Optional


class Field:
    """通用强类型字段描述符"""

    def __init__(self, field_type: type, *, nullable: bool = False):
        self.field_type = field_type
        self.nullable = nullable

    def __set_name__(self, owner, name: str):
        self.name = name
        self.private_name = f"_{name}"

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return instance.__dict__.get(self.private_name, None)

    def __set__(self, instance, value: Any):
        if value is None:
            if not self.nullable:
                raise TypeError(f"{self.name} 不允许为 None")
        elif not isinstance(value, self.field_type):
            raise TypeError(
                f"{self.name} 期望 {self.field_type.__name__}, "
                f"实际为 {type(value).__name__}"
            )
        instance.__dict__[self.private_name] = value


class Employee:
    name   = Field(str)
    age    = Field(int)
    salary = Field(float)
    email  = Field(str, nullable=True)  # 允许为空

    def __init__(self, name: str, age: int, salary: float, email: Optional[str] = None):
        self.name = name
        self.age = age
        self.salary = salary
        self.email = email


emp = Employee("Alice", 30, 80000.0)
print(emp.name, emp.age, emp.salary)  # Alice 30 80000.0
emp.email = None  # OK
# emp.age = "三十"  # TypeError: age 期望 int, 实际为 str

# Python 3.10+

from functools import wraps
from typing import Callable

class LazyAttribute:
    """惰性计算描述符：首次访问时计算，之后缓存结果"""

    def __init__(self, calculator: Callable):
        self.calculator = calculator

    def __set_name__(self, owner, name: str):
        self.name = name

    def __get__(self, instance, owner):
        if instance is None:
            return self
        # 计算并写入实例字典，后续访问直接走实例 __dict__
        print(f"[Lazy] 正在计算 {self.name}...")
        result = self.calculator(instance)
        instance.__dict__[self.name] = result
        return result


class Report:
    def __init__(self, data: list[int]):
        self.data = data

    @LazyAttribute
    def sum(self):
        """总和 —— 延迟计算"""
        return sum(self.data)

    @LazyAttribute
    def average(self):
        """平均值 —— 延迟计算"""
        return sum(self.data) / len(self.data) if self.data else 0


r = Report([1, 2, 3, 4, 5])
print("创建 Report 实例...（还未计算）")
print(r.sum)      # [Lazy] 正在计算 sum...  -> 15
print(r.sum)      # 15（从实例字典缓存读取，不再计算）
print(r.average)  # [Lazy] 正在计算 average...  -> 3.0
print(r.average)  # 3.0（缓存）

# Python 3.10+

import time

class CachedProperty:
    """可过期的缓存属性描述符"""

    def __init__(self, func: Callable, ttl: float = 60.0):
        self.func = func
        self.ttl = ttl  # 缓存有效期（秒）
        self.timestamp_key: str = ""

    def __set_name__(self, owner, name: str):
        self.name = name
        self.cache_key = f"_cached_{name}"
        self.timestamp_key = f"_cached_{name}_ts"

    def __get__(self, instance, owner):
        if instance is None:
            return self
        now = time.time()
        cached_value = instance.__dict__.get(self.cache_key)
        cached_at = instance.__dict__.get(self.timestamp_key, 0)

        if cached_value is not None and (now - cached_at) < self.ttl:
            print(f"[Cache HIT] {self.name}")
            return cached_value

        print(f"[Cache MISS] 重新计算 {self.name}...")
        result = self.func(instance)
        instance.__dict__[self.cache_key] = result
        instance.__dict__[self.timestamp_key] = now
        return result


class StockQuote:
    def __init__(self, symbol: str):
        self.symbol = symbol

    @CachedProperty
    def price(self) -> float:
        """模拟从 API 获取股价（昂贵操作）"""
        import random
        return round(random.uniform(10, 200), 2)

    @CachedProperty
    def volume(self) -> int:
        """模拟获取成交量"""
        import random
        return random.randint(1000, 1000000)


sq = StockQuote("AAPL")
print(sq.price)    # [Cache MISS] 重新计算 price...  -> 157.32
print(sq.price)    # [Cache HIT] price  -> 157.32
print(sq.volume)   # [Cache MISS] 重新计算 volume...
print(sq.volume)   # [Cache HIT] volume

# Python 3.10+
# Django ORM 字段的简化原理

class DjangoFieldMockup:
    """模拟 Django 字段的描述符行为"""

    def __init__(self, field_type, *, default=None, primary_key=False):
        self.field_type = field_type
        self.default = default
        self.primary_key = primary_key

    def __set_name__(self, owner, name: str):
        self.name = name
        self.attname = f"_{name}"

    def __get__(self, instance, owner):
        if instance is None:
            # 通过类访问：返回字段描述符本身
            # Django 中用这种方式进行 QuerySet 构建（如 User.objects.filter(username=...）
            return self
        return instance.__dict__.get(self.attname, self.default)

    def __set__(self, instance, value):
        # Django 在这里会做类型转换、验证、数据库适配等
        if value is not None and not isinstance(value, self.field_type):
            raise TypeError(
                f"字段 {self.name} 期望 {self.field_type.__name__}"
            )
        instance.__dict__[self.attname] = value


class MockModel:
    """模拟 Django Model 的元类行为"""

    def __init__(self, **kwargs):
        for name, value in kwargs.items():
            setattr(self, name, value)  # 触发描述符 __set__


class User(MockModel):
    id = DjangoFieldMockup(int, primary_key=True)
    username = DjangoFieldMockup(str)
    age = DjangoFieldMockup(int, default=18)


# 通过类访问字段（用于 QuerySet 查询）
print(User.id)        # <DjangoFieldMockup ...>
print(User.id.name)   # 'id'

# 通过实例访问字段值
u = User(username="alice", age=25)
print(u.username)     # 'alice'
print(u.age)          # 25

# Python 3.10+
# SQLAlchemy InstrumentedAttribute 简化示意

class InstrumentedAttribute:
    """模拟 SQLAlchemy 的属性描述符"""

    def __init__(self, name: str):
        self.name = name

    def __get__(self, instance, owner):
        if instance is None:
            return self  # 类级别：用于构建查询
        # 实例级别：从内部状态字典获取值
        # SQLAlchemy 实际从 instance.__dict__ 或内部的 state 对象获取
        return instance.__dict__.get(self.name)

    def __set__(self, instance, value):
        # SQLAlchemy 在这里设置值，并标记该属性为"已修改"（dirty）
        print(f"[Instrumented] 追踪属性变更: {self.name} = {value}")
        instance.__dict__[self.name] = value
        # 实际 SQLAlchemy 还会触发 session tracking 逻辑


class Base:
    pass


class Product(Base):
    name = InstrumentedAttribute("name")
    price = InstrumentedAttribute("price")


p = Product()
p.name = "Widget"   # [Instrumented] 追踪属性变更: name = Widget
p.price = 9.99      # [Instrumented] 追踪属性变更: price = 9.99

# Python 3.10+

class Dog:
    def bark(self):
        return "Woof!"

d = Dog()

# 以下两个调用是等价的：
# 1. Python 的语法糖
print(d.bark())              # Woof!

# 2. 在底层实际发生的事
from types import MethodType
bound_method = Dog.bark.__get__(d, Dog)
print(bound_method())        # Woof!
print(type(bound_method))    # <class 'method'>

# 关键：实例字典中不会存储方法
print('bark' in d.__dict__)  # False
# 方法通过非数据描述符的 __get__ 动态生成

# Python 3.10+

class SharedDescriptor:
    """错误示例：数据存储在描述符实例上"""

    def __init__(self, default=0):
        self.default = default

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return self.default  # BUG: 所有实例共享同一个 self.default

    def __set__(self, instance, value):
        self.default = value  # BUG: 修改的是类级别的共享状态


class BadExample:
    x = SharedDescriptor()


a = BadExample()
b = BadExample()

a.x = 100
print(a.x)  # 100
print(b.x)  # 100  —— b 也受到了影响！
# 原因：a.x 和 b.x 操作的是同一个 SharedDescriptor 实例的 self.default

# --- 正确做法 ---
class CorrectDescriptor:
    """正确示例：数据存储在 instance.__dict__ 中"""

    def __set_name__(self, owner, name: str):
        self.private_name = f"_{name}"

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return instance.__dict__.get(self.private_name, None)

    def __set__(self, instance, value):
        instance.__dict__[self.private_name] = value


class GoodExample:
    x = CorrectDescriptor()


c = GoodExample()
d = GoodExample()
c.x = 100
d.x = 200
print(c.x)  # 100
print(d.x)  # 200  —— 各自独立，完全隔离

# Python 3.10+

class OnlyDeleteDescriptor:
    """即使只实现了 __delete__，没有 __set__，仍是数据描述符！"""

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return instance.__dict__.get('_value', 'default')

    def __delete__(self, instance):
        print("__delete__ called")
        instance.__dict__.pop('_value', None)


class Demo:
    attr = OnlyDeleteDescriptor()


d = Demo()
# 试图用实例字典"覆盖"它？行不通！
d.__dict__['attr'] = 'should I override?'
print(d.attr)  # 'default' —— 实例字典被忽略！因为这是数据描述符