Python描述符进阶：自定义文档与属性删除的艺术
—— 让托管属性文档更精准，实现属性删除控制
🔍 问题背景：描述符文档字符串的局限性
在实现LineItem类时（示例20-7），weight和price属性共享同一个Quantity描述符类（示例20-6）。这导致一个关键问题：
无法为不同属性单独添加文档说明（如weight需要标注单位"千克"）。而特性（property）可以轻松实现这点，因其直接绑定到单个属性。
示例20-6：原始描述符类
class Quantity:def __init__(self, storage_name):self.storage_name = storage_namedef __set__(self, instance, value):if value > 0:instance.__dict__[self.storage_name] = valueelse:raise ValueError('value must be > 0')def __get__(self, instance, owner):return instance.__dict__[self.storage_name]
💡 解决方案：为描述符实例定制文档字符串
通过重写__set_name__方法，在实例化时为每个属性单独注入文档：
class Quantity:def __init__(self, storage_name, doc=None):self.storage_name = storage_nameself.__doc__ = doc # 存储实例级文档字符串 def __set_name__(self, owner, name):# 若未提供文档，生成默认说明 if not self.__doc__:self.__doc__ = f"{name} (Quantity descriptor)"# __set__ 和 __get__ 方法保持不变class LineItem:weight = Quantity("weight", doc="物品重量（单位：千克）")price = Quantity("price", doc="物品单价（单位：元）")
实现效果：
✅ help(LineItem.weight) 输出：物品重量（单位：千克）
✅ help(LineItem.price) 输出：物品单价（单位：元）
✅ 托管类文档中清晰区分不同属性的语义
⚠️ 覆盖删除操作：实现 __delete__ 方法
当需要拦截属性删除行为时（如防止误删关键数据），需在描述符中实现__delete__方法：
class ProtectedQuantity(Quantity):def __delete__(self, instance):# 自定义删除行为示例 print(f"警告：尝试删除属性 {self.storage_name}！")# 可选：阻止删除操作 # raise AttributeError("禁止删除该属性")
应用场景：
- 防止关键属性被意外删除
- 删除时触发清理操作（如释放关联资源）
- 实现审计日志（记录删除行为）
完整实现方案
class SmartDescriptor:def __init__(self, doc=None):self.__doc__ = docdef __set_name__(self, owner, name):if not self.__doc__:self.__doc__ = f"{name} descriptor"def __get__(self, instance, owner):# 实现读取逻辑...def __set__(self, instance, value):# 实现写入逻辑...def __delete__(self, instance):# 可选：实现删除保护 raise AttributeError("受保护属性禁止删除")class Product:weight = SmartDescriptor("重量（单位：g）")price = SmartDescriptor("价格（单位：CNY）")
💎 核心价值总结
1. 文档精确性
通过__set_name__动态生成文档，解决共享描述符类的文档差异化问题
适用场景：API开发、自动文档生成工具（如Sphinx）
2. 删除安全控制
__delete__方法提供三层控制：
- 拦截删除行为
- 触发关联操作
- 实现属性保护策略
3. 架构灵活性
组合使用__get__/__set__/__delete__可实现：
- 延迟加载属性
- 属性变更审计
- 资源自动管理
最佳实践：在ORM框架（如SQLAlchemy）、配置管理库中优先使用描述符，它比特性（property）更适合复用逻辑，比元类更轻量级。掌握文档定制与删除控制，将使你的描述符具备生产级可靠性。
扩展思考：尝试实现一个@descriptor装饰器，将普通类快速转换为描述符类，支持自动文档注入和删除保护——这将是理解Python元编程的绝佳练习！