理解和实现描述符

元编程赋予我们强大的手段来动态控制程序的结构和行为。其中，描述符提供了一种受控且可复用的方式来管理属性访问。Python 不仅依赖标准的属性查找，还允许我们定义实现特定方法的对象，以拦截并自定义属性被访问、设置或删除时的行为。

实质上，描述符是定义了 __get__、__set__ 或 __delete__ 方法中一个或多个的任何对象。当一个类（所有者类）的实例拥有一个属性，而该属性本身是某个描述符类的实例时，Python 的属性访问机制会自动调用这些特殊方法。这使您能够将逻辑直接嵌入 (embedding)到属性访问本身中，而不仅仅是简单的值存储。

描述符协议

描述符的行为由三个特殊方法控制：

1. __get__(self, instance, owner):

   • 当描述符的属性被访问时调用。
   • self: 描述符实例本身。
   • instance: 通过此实例访问属性。如果通过类本身访问（例如，MyClass.attribute），则 instance 将为 None。
   • owner: 所有者类（例如，MyClass）。
   • 此方法应返回计算出的属性值或引发 AttributeError。

2. __set__(self, instance, value):

   • 尝试设置描述符属性时调用。
   • self: 描述符实例。
   • instance: 正在设置属性的实例。
   • value: 赋给属性的值。
   • 此方法通常存储或处理值。它不返回任何内容。它的存在定义了一个数据描述符。

3. __delete__(self, instance):

   • 尝试使用 del 删除描述符属性时调用。
   • self: 描述符实例。
   • instance: 正在删除属性的实例。
   • 此方法处理删除逻辑。

需要了解的是，描述符实例通常在类级别创建。它们是所有者类的属性，而不是该类实例的直接属性，尽管它们管理实例特有的数据。

实现一个基本描述符

我们通过一个简单例子来说明这一点：一个确保模型超参数 (parameter) (hyperparameter)始终为正浮点数的描述符。

import logging

logging.basicConfig(level=logging.INFO)

class PositiveFloat:
    """确保属性为正浮点数的描述符。"""
    def __init__(self, name):
        # 存储实例 __dict__ 中使用的内部名称
        self.private_name = '_' + name

    def __get__(self, instance, owner):
        if instance is None:
            # 通过类访问，返回描述符本身
            return self
        # 从实例的字典中获取值
        return getattr(instance, self.private_name, None)

    def __set__(self, instance, value):
        try:
            # 尝试转换和验证
            val_float = float(value)
            if val_float <= 0:
                raise ValueError(f"值必须为正数，得到 {val_float}")
            # 将验证后的值存储到实例的字典中
            setattr(instance, self.private_name, val_float)
            logging.info(f"在 {instance} 上将 {self.private_name.lstrip('_')} 设置为 {val_float}")
        except (ValueError, TypeError) as e:
            # 处理转换错误或验证失败
            raise TypeError(f"值必须为正浮点数。{e}") from e

# 在机器学习模型配置类中的使用示例
class ModelConfig:
    learning_rate = PositiveFloat('learning_rate')
    regularization_strength = PositiveFloat('regularization_strength')

    def __init__(self, lr, reg_strength):
        # 此处会调用描述符的 __set__ 方法
        self.learning_rate = lr
        self.regularization_strength = reg_strength

    def __repr__(self):
        return (f"ModelConfig(lr={self.learning_rate}, "
                f"reg_strength={self.regularization_strength})")

# --- 尝试运行 ---
config = ModelConfig(lr=0.01, reg_strength=0.005)
print(config) # 输出: ModelConfig(lr=0.01, reg_strength=0.005)

# 访问属性会调用 __get__
print(f"当前学习率: {config.learning_rate}") # 输出: Current Learning Rate: 0.01

# 设置属性会调用 __set__
config.learning_rate = 0.008
print(config) # 输出: ModelConfig(lr=0.008, reg_strength=0.005)

# 尝试设置无效值会通过 __set__ 抛出错误
try:
    config.regularization_strength = -0.1
except TypeError as e:
    print(f"设置正则化出错: {e}")
    # 输出: Error setting regularization: Value must be a positive float. Value must be positive, got -0.1

try:
    config.learning_rate = "invalid"
except TypeError as e:
    print(f"设置学习率出错: {e}")
    # 输出: Error setting learning rate: Value must be a positive float. could not convert string to float: 'invalid'

# 通过类访问会返回描述符实例
print(ModelConfig.learning_rate) # 输出: <__main__.PositiveFloat object at 0x...>

在此示例中，PositiveFloat 是描述符类。当我们在 ModelConfig 中指定 learning_rate = PositiveFloat('learning_rate') 时，我们就让 learning_rate 成为一个与 ModelConfig 类相关的描述符实例。config.learning_rate = 0.01 这样的赋值会触发 PositiveFloat.__set__，而 config.learning_rate 这样的访问则会触发 PositiveFloat.__get__。请留意，描述符如何利用实例的 __dict__（通过 getattr 和 setattr 使用 _learning_rate 这样的私有名称）来为每个 ModelConfig 实例存储实际数据。

数据描述符与非数据描述符

__set__ 方法的存在与否，从根本上改变了描述符与实例属性的交互方式：

• 数据描述符： 定义 __get__ 和 __set__（以及可选的 __delete__）。数据描述符在属性查找顺序中具有更高的优先级。如果一个实例同时拥有一个数据描述符和 __dict__ 中同名的条目，数据描述符会优先起作用。这就是为什么我们的 PositiveFloat 描述符能稳定拦截赋值操作。
• 非数据描述符： 仅定义 __get__。非数据描述符的优先级低于实例 __dict__ 条目。如果实例字典中存在同名条目，该条目将覆盖描述符。方法是常见的非数据描述符示例（它们实现 __get__ 来绑定 self）。

在规划属性行为时，了解这一区别很关键，尤其是在考虑实例级别的赋值是否应覆盖描述符的逻辑时。

机器学习 (machine learning)库中的运用

描述符不只是简单的语法糖；它们能实现机器学习环境中复杂的有效模式：

1. 超参数 (parameter) (hyperparameter)校验： 如上所示，描述符非常适合在赋值时直接对超参数（类型、范围、允许值）施加约束，使配置更稳定。您可以为学习率、层大小、激活函数 (activation function)名称等构建描述符。

2. 资源惰性加载： 机器学习常涉及大型对象，如数据集、嵌入 (embedding)或预训练 (pre-training)模型权重 (weight)。急切加载这些可能会占用大量内存和时间。描述符可以推迟加载，直到属性首次被访问。

   import time
   
   class LazyLoader:
       """仅在首次访问时加载资源的描述符。"""
       def __init__(self, name, load_func):
           self.private_name = '_' + name
           self.load_func = load_func
           self.loaded = False
   
       def __get__(self, instance, owner):
           if instance is None:
               return self
   
           value = getattr(instance, self.private_name, None)
           if not self.loaded:
               print(f"正在加载 '{self.private_name.lstrip('_')}' 的资源...")
               start_time = time.time()
               value = self.load_func() # 执行加载函数
               setattr(instance, self.private_name, value)
               self.loaded = True # 标记为已加载（针对此描述符实例）
               end_time = time.time()
               print(f"...在 {end_time - start_time:.2f} 秒内加载完成。")
   
           return value
   
   # 示例：模拟加载大型嵌入
   def load_word_embeddings():
       # 模拟耗时加载操作
       time.sleep(2) 
       return {"word1": [0.1, 0.2], "word2": [0.3, 0.4]} 
   
   class ModelPipeline:
       embeddings = LazyLoader('embeddings', load_word_embeddings)
   
       def process(self, text):
           # 访问 self.embeddings 会触发 __get__ 并加载（如果尚未加载）
           print(f"正在访问嵌入以处理: {text}")
           emb_vector = self.embeddings.get(text, [0.0, 0.0]) 
           print(f"已使用向量 {emb_vector} 处理 '{text}'")
           # 进一步处理...
   
   pipeline = ModelPipeline()
   print("流水线已初始化。")
   # 嵌入尚未加载。
   
   pipeline.process("word1") 
   # 输出:
   # Pipeline initialized.
   # Accessing embeddings to process: word1
   # Loading resource for 'embeddings'...
   # ...loaded in 2.00 seconds. 
   # Processed 'word1' using vector [0.1, 0.2]
   
   pipeline.process("word2")
   # 输出:
   # Accessing embeddings to process: word2
   # Processed 'word2' using vector [0.3, 0.4] 
   # （此次无加载信息）
   

3. 受管属性与副作用： 描述符可在属性被设置或访问时触发动作。例如，更改模型参数可以自动使缓存的预测失效，或记录修改操作。

4. 与外部系统对接： 描述符可以管理与特征存储的通信，在属性被访问时自动获取最新的特征值，或在设置时推送更新。

与 property() 的关系

您或许会从 Python 的内置函数 property() 中看出一些类似的行为。实际上，property 是一种高级便捷的途径来构建描述符，它主要用于在一个类定义中管理单个属性的获取器、设置器和删除器。

class SimpleConfig:
    def __init__(self, initial_value):
        self._value = initial_value

    @property
    def value(self):
        """值的获取器。"""
        print("正在获取值")
        return self._value

    @value.setter
    def value(self, new_value):
        """带校验功能的值设置器。"""
        print(f"正在将值设置为 {new_value}")
        if not isinstance(new_value, (int, float)):
            raise TypeError("值必须是数值类型")
        self._value = new_value

    @value.deleter
    def value(self):
        """值的删除器。"""
        print("正在删除值")
        del self._value

# 使用方法:
conf = SimpleConfig(10)
print(conf.value)      # 调用获取器
conf.value = 20        # 调用设置器
try:
    conf.value = "bad" # 调用设置器，引发 TypeError
except TypeError as e:
    print(e)
del conf.value         # 调用删除器

在内部，property(fget, fset, fdel) 会构建一个数据描述符实例。虽然 property 对于在单个类中进行简单的属性管理表现良好，但构建一个完整的描述符类能带来更大的能力和复用性：

• 复用性： 一次定义一个描述符（如 PositiveFloat），即可在不同类的多个属性上复用。
• 状态： 描述符可以持有自己的状态（尽管需要谨慎，因为它们通常是类级别的）
• 复杂性： 对于比简单获取/设置/删除更复杂的逻辑，使用专用类会更清晰。

描述符为控制属性访问提供了强大的抽象。通过拦截获取、设置和删除操作，它们能以清晰、可复用的方式实现校验、惰性加载、日志记录及其他横切功能。这种能力在构建复杂的机器学习 (machine learning)组件、配置或库时尤其有利，因为其中需要对属性进行受控的访问和行为管理。