Python中的__set__与__set_name__的具体使用

在Python的元编程工具箱里，有两个名字相似但职责分明的方法：__set__和__set_name__。它们都属于描述符协议（Descriptor Protocol），是构建高级、可复用属性系统的基石。理解它们，才算真正摸到了Python动态特性的门道。

一、描述符协议基础

简单来说，描述符就是一个实现了特定方法的类。这些方法构成了一个协议，当你的类属性被访问、赋值或删除时，Python解释器就会调用它们。

这里有个关键点：一个描述符如果只实现了__get__，它就是个“非数据描述符”；如果它还实现了__set__或__delete__，就升级为“数据描述符”。这个分类直接决定了它在属性查找链中的优先级。

二、__set__详解

签名与机制

先看它的标准签名：

def __set__(self, obj, value):
    ...

• self：描述符实例本身。
• obj：拥有该描述符的类的实例。
• value：被赋予的值。

当你在一个实例上对描述符属性进行赋值操作时（比如obj.attr = 42），__set__方法就会被调用。它的核心任务就是处理这个赋值行为。

class Descriptor:
    def __get__(self, obj, objtype=None):
        print(f"__get__ called, obj={obj}")
        return obj.__dict__.get('_value')

    def __set__(self, obj, value):
        print(f"__set__ called, value={value}")
        obj.__dict__['_value'] = value   # 注意：不能用 obj.attr = value，会无限递归！


class MyClass:
    attr = Descriptor()


m = MyClass()
m.attr = 42    # 触发 __set__
print(m.attr)  # 触发 __get__

输出结果清晰地展示了调用顺序：

__set__ called, value=42

__get__ called, obj=<__main__.MyClass object>

42

这里有个至关重要的细节：在__set__内部存储值时，必须直接操作obj.__dict__或者使用setattr(obj, ‘_internal_name’, value)。如果写成obj.attr = value，就会再次触发__set__，导致无限递归。

数据描述符 vs 非数据描述符：优先级之争

这是描述符机制里最需要厘清的一个概念。Python的属性查找遵循一条明确的优先级链（在方法解析顺序MRO之后）：

数据描述符 > 实例 __dict__ > 非数据描述符

什么意思？看个例子就明白了：

class NonData:
    """只有 __get__，非数据描述符"""
    def __get__(self, obj, objtype=None):
        return "from descriptor"

class Data:
    """有 __set__，数据描述符"""
    def __get__(self, obj, objtype=None):
        return "from descriptor"
    def __set__(self, obj, value):
        pass

class A:
    x = NonData()
    y = Data()

a = A()
a.__dict__['x'] = "from instance"
a.__dict__['y'] = "from instance"

print(a.x)  # 输出："from instance"   ← 实例 __dict__ 胜出
print(a.y)  # 输出："from descriptor" ← 数据描述符胜出！

看到了吗？对于非数据描述符x，实例的__dict__优先级更高。而对于实现了__set__的数据描述符y，它的__get__方法会优先被调用，完全绕过实例字典。这就是__set__方法赋予描述符的“特权”。

实战：构建类型验证描述符

理解了机制，我们就能用它来做点有用的事，比如实现一个类型验证器：

class TypedField:
    def __init__(self, expected_type):
        self.expected_type = expected_type
        self.storage_name = None  # 后面由 __set_name__ 填充

    def __set__(self, obj, value):
        if not isinstance(value, self.expected_type):
            raise TypeError(
                f"'{self.storage_name}' 期望 {self.expected_type.__name__}，"
                f"得到 {type(value).__name__}"
            )
        obj.__dict__[self.storage_name] = value

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        return obj.__dict__.get(self.storage_name)


class Person:
    name = TypedField(str)
    age  = TypedField(int)

p = Person()
p.name = "Alice"   # ✅ 通过
p.age  = 30        # ✅ 通过
p.age  = "thirty"  # ❌ 触发 TypeError

这个描述符在赋值时拦截值并进行类型检查，只有类型匹配才允许存储。不过，你可能会注意到代码里有个self.storage_name = None，并且注释说“由__set_name__填充”。这就引出了我们今天要讲的另一个主角。

三、__set_name__详解（Python 3.6+）

它解决了什么问题？

在__set_name__出现之前，描述符有个很尴尬的问题：它不知道自己被定义在宿主类里时叫什么名字。这就导致我们不得不手动传入属性名，既繁琐又容易出错：

# 旧方式（繁琐且容易出错）
class Person:
    name = TypedField(str, 'name')  # 必须手动重复写名字
    age  = TypedField(int, 'age')

__set_name__就是为了自动化这个过程而生的。

签名与触发时机

它的签名如下：

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

• self：描述符实例。
• owner：拥有该描述符的类（注意，是类对象，不是实例）。
• name：该描述符在类中的属性名。

关键点在于它的触发时机：__set_name__在类定义完成时，由元类type.__new__自动调用。这个时间点远早于任何实例的创建。

class Descriptor:
    def __set_name__(self, owner, name):
        print(f"__set_name__ 被调用: owner={owner.__name__}, name='{name}'")
        self.name = name

class MyClass:
    foo = Descriptor()  # 类定义时立即触发
    bar = Descriptor()

# 输出：
# __set_name__ 被调用: owner=MyClass, name='foo'
# __set_name__ 被调用: owner=MyClass, name='bar'

与__set__联动：构建完整的自感知描述符

现在，我们可以把__set_name__和__set__结合起来，创建一个既知道“自己叫什么”，又能验证数据的完整描述符：

class Validated:
    """通用验证描述符，自动感知自身名称"""

    def __set_name__(self, owner, name):
        self.public_name  = name           # 外部访问名，如 'age'
        self.private_name = '_' + name     # 内部存储名，如 '_age'

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        return getattr(obj, self.private_name, None)

    def __set__(self, obj, value):
        value = self.validate(value)
        setattr(obj, self.private_name, value)

    def validate(self, value):
        raise NotImplementedError


class PositiveInt(Validated):
    def validate(self, value):
        if not isinstance(value, int) or value <= 0:
            raise ValueError(f"必须是正整数，得到: {value!r}")
        return value


class NonEmptyStr(Validated):
    def validate(self, value):
        if not isinstance(value, str) or not value.strip():
            raise ValueError(f"不能为空字符串，得到: {value!r}")
        return value


class Product:
    name  = NonEmptyStr()
    price = PositiveInt()
    stock = PositiveInt()

p = Product()
p.name  = "Python Book"
p.price = 99
p.stock = 10

print(p.name, p.price, p.stock)  # 输出：Python Book 99 10
print(p.__dict__)                 # 输出：{'_name': 'Python Book', '_price': 99, '_stock': 10}

这样一来，描述符就能自动知道自己在类中的名字（name, price），并据此生成一个内部存储名（_name, _price），代码变得非常简洁和优雅。

四、__set_name__的高级用法

1. 感知宿主类（owner）进行元数据收集

__set_name__不仅能拿到自己的名字，还能拿到宿主类（owner）的引用。这为一些高级用法打开了大门，比如自动注册所有字段：

class LoggedField:
    def __set_name__(self, owner, name):
        self.name = name
        # 在宿主类上注册所有被追踪的字段
        if not hasattr(owner, '_tracked_fields'):
            owner._tracked_fields = []
        owner._tracked_fields.append(name)

    def __set__(self, obj, value):
        print(f"[LOG] {type(obj).__name__}.{self.name} = {value!r}")
        obj.__dict__[self.name] = value

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        return obj.__dict__.get(self.name)


class Config:
    host    = LoggedField()
    port    = LoggedField()
    timeout = LoggedField()

print(Config._tracked_fields)  # 输出：['host', 'port', 'timeout']

c = Config()
c.host = "localhost"   # 输出：[LOG] Config.host = 'localhost'
c.port = 8080          # 输出：[LOG] Config.port = 8080

通过这种方式，宿主类Config可以轻松知道它有哪些被LoggedField装饰的属性，这在构建框架时非常有用。

2. 动态添加描述符（需手动调用）

需要注意的是，__set_name__只在类定义时由元类自动调用。如果你在类定义之后才动态地添加一个描述符，就必须手动调用它：

class MyDesc:
    def __set_name__(self, owner, name):
        self.name = name
    def __set__(self, obj, value):
        obj.__dict__[self.name] = value * 2
    def __get__(self, obj, objtype=None):
        return obj.__dict__.get(self.name) if obj else self

# 动态挂载
desc = MyDesc()
MyClass.new_attr = desc
desc.__set_name__(MyClass, 'new_attr')  # ⬅ 必须手动调用！

m = MyClass()
m.new_attr = 10
print(m.new_attr)  # 输出：20

五、与property的对比

你可能会问，这和@property装饰器有什么区别？property本身就是一个描述符的实现，但它通常用于单个类的特定属性。而自定义描述符的优势在于可复用性。

# 使用property：每个类属性都要写一遍getter和setter
class Circle:
    @property
    def radius(self):
        return self._radius
    @radius.setter
    def radius(self, v):
        if v < 0: raise ValueError
        self._radius = v

# 使用描述符：一次定义，到处复用
class PositiveNumber:
    def __set_name__(self, owner, name):
        self.name = name
    def __set__(self, obj, value):
        if value < 0: raise ValueError(f"{self.name} 不能为负")
        obj.__dict__[self.name] = value
    def __get__(self, obj, objtype=None):
        return obj.__dict__.get(self.name) if obj else self

class Circle:
    radius = PositiveNumber()  # 直接复用

class Rectangle:
    width  = PositiveNumber()  # 直接复用
    height = PositiveNumber()  # 直接复用

描述符将验证逻辑封装在一个独立的、可复用的类中，让业务类（如Circle, Rectangle）的代码保持干净。

六、总结

我们来梳理一下这两个核心方法的分工：

__set__(self, obj, value)

• 在实例赋值时触发（obj.attr = value）。
• 它的存在使描述符成为“数据描述符”，在属性查找时拥有最高优先级。
• 负责实现赋值时的核心逻辑，如验证、转换、日志记录等。
• 存储值时需操作obj.__dict__或使用setattr，避免递归。

__set_name__(self, owner, name)

• 在类定义完成时由元类自动调用（一次性）。
• 为描述符提供它在类中的名称，解决了描述符的“自我认知”问题。
• 可以感知宿主类，用于字段注册、元数据收集等高级模式。
• 动态挂载描述符时需要手动调用。

将两者配合使用，是构建可复用、类型安全、自省能力强的属性系统的标准模式。这也是dataclasses、SQLAlchemy、Django ORM等众多流行框架底层依赖的核心机制。掌握它们，你就能更深入地理解Python的优雅与强大。