Python __set__与__set_name__方法使用详解

在Python元编程中，__set__和__set_name__是两个名称相似但功能不同的方法。它们都属于描述符协议，是构建高级、可复用属性系统的关键。理解它们有助于深入掌握Python的动态特性。

描述符协议基础

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

方法	触发时机	类型
__get__	读取属性	非数据描述符（若单独使用）
__set__	设置属性	数据描述符（含此方法）
__delete__	删除属性	数据描述符（含此方法）
__set_name__	类定义时	辅助方法（Python 3.6+）

关键点在于：仅实现__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__，导致无限递归。

数据描述符与非数据描述符的优先级

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__的高级用法

感知宿主类进行元数据收集

__set_name__可获取宿主类引用，支持高级用法如自动注册字段：

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装饰，这在构建框架时非常有用。

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

注意：__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):
        retun 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：每个类属性都要写一遍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的优雅与强大。