当前位置：首页 > news >正文

Effective Python 第50条：用__set_name__给类属性加注解

news 2025/11/13 10:06:03

Effective Python 第50条：用__set_name__给类属性加注解

描述符基础
实践示例：带验证的属性
高级应用：自动生成文档
实际应用场景
注意事项
结论

在Python编程中，描述符(descriptor)是一种强大的特性，它允许我们自定义属性访问的行为。__set_name__方法是描述符协议的一部分，它在Python 3.6中引入，用于在类创建时自动调用，以便描述符可以获取它所描述的属性名称。本文将深入探讨如何使用__set_name__来为类属性添加注解，实现更优雅的代码结构。

描述符基础

描述符是一个实现了至少三个方法之一（__get__、__set__、__delete__）的对象。当一个类中的属性使用了描述符时，Python会自动调用这些方法来获取、设置或删除属性值。

__set_name__方法在描述符被赋值给类属性时调用，它接收两个参数：所有者类(owner)和属性名(name)。这使得描述符可以知道它所描述的属性名称，从而可以更灵活地处理属性。

实践示例：带验证的属性

让我们创建一个带验证功能的描述符，使用__set_name__来存储属性名称：

class Validated:def __init__(self, validation_function):self.validation_function = validation_functionself.name = None  # 将在__set_name__中设置def __set_name__(self, owner, name):self.name = namedef __get__(self, instance, owner):if instance is None:return selfreturn instance.__dict__.get(self.name, None)def __set__(self, instance, value):if not self.validation_function(value):raise ValueError(f"Invalid value for {self.name}: {value}")instance.__dict__[self.name] = value

现在我们可以创建特定类型的验证描述符：

class PositiveInteger(Validated):def __init__(self):super().__init__(self.validate)@staticmethoddef validate(value):return isinstance(value, int) and value > 0class NonEmptyString(Validated):def __init__(self):super().__init__(self.validate)@staticmethoddef validate(value):return isinstance(value, str) and len(value.strip()) > 0

在类中使用这些描述符：

class Person:age = PositiveInteger()name = NonEmptyString()def __init__(self, name, age):self.name = name  # 调用NonEmptyString的__set__self.age = age    # 调用PositiveInteger的__set__p = Person("Alice", 30)
print(p.age)  # 输出: 30
p.age = -5    # 抛出ValueError: Invalid value for age: -5

高级应用：自动生成文档

__set_name__还可以用于自动生成文档。我们可以创建一个描述符，在类创建时自动为属性添加文档字符串：

class Documented:def __init__(self, docstring=None):self.docstring = docstringself.name = Nonedef __set_name__(self, owner, name):self.name = nameif self.docstring is None:self.docstring = f"属性 {name} 的文档"def __get__(self, instance, owner):if instance is None:return selfreturn instance.__dict__.get(self.name, None)def __set__(self, instance, value):instance.__dict__[self.name] = valueclass Product:price = Documented("产品的价格，必须为正数")quantity = Documented("库存数量，必须为非负整数")def __init__(self, price, quantity):self.price = priceself.quantity = quantity