Python 描述符协议实现类型检查字段

在 Python 中，描述符（Descriptor）是一种强大但常被忽视的机制，它允许你自定义类属性的访问行为。通过实现描述符协议，你可以轻松为类的字段添加类型检查、值验证或自动转换等功能。本文将手把手教你如何用描述符实现一个带类型检查的字段，确保赋值时的数据类型符合预期。

什么是描述符协议？

描述符是实现了 __get__、__set__ 或 __delete__ 方法中任意一个的对象。当你把这样一个对象作为类的属性（而不是实例属性）时，Python 在访问该属性时会自动调用对应的描述符方法。

最常用的是 __set__ 方法——它在给属性赋值时触发。我们将利用这一点，在赋值前检查值的类型是否匹配预设类型。

步骤一：创建基础类型检查描述符

定义 一个名为 TypedField 的类，它接收一个类型参数，并在设置值时进行校验。

class TypedField:
    def __init__(self, expected_type):
        self.expected_type = expected_type
        self.name = None  # 稍后由元类或 __set_name__ 设置

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

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return instance.__dict__.get(self.name)

    def __set__(self, instance, value):
        if not isinstance(value, self.expected_type):
            raise TypeError(
                f"Expected {self.expected_type.__name__} for '{self.name}', "
                f"got {type(value).__name__}"
            )
        instance.__dict__[self.name] = value

这段代码的关键点：

• __set_name__ 是 Python 3.6+ 引入的方法，当描述符作为类属性被定义时，Python 自动调用它，传入拥有该描述符的类（owner）和属性名（name）。这让我们能知道当前字段叫什么名字，便于报错。
• __set__ 方法中使用 isinstance(value, self.expected_type) 检查 类型。如果不匹配，就抛出 TypeError。
• 值最终存入实例的 __dict__，避免无限递归（如果存回属性本身，会再次触发 __set__）。

步骤二：在数据类中使用描述符

创建 一个 Person 类，用 TypedField 定义姓名和年龄字段。

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

    def __init__(self, name, age):
        self.name = name
        self.age = age

现在尝试使用这个类：

p = Person("Alice", 30)  # 正常
p.age = 31               # 正常
p.name = "Bob"           # 正常

但如果尝试错误类型：

p.age = "thirty"  # 抛出 TypeError: Expected int for 'age', got str

步骤三：支持多个类型或可选值

有时你可能希望一个字段接受多种类型（比如 str 或 None），或者允许 None 作为合法值。修改 TypedField 以支持这些场景。

class TypedField:
    def __init__(self, *expected_types, allow_none=False):
        if not expected_types:
            raise ValueError("At least one expected type must be provided")
        self.expected_types = expected_types
        self.allow_none = allow_none
        self.name = None

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

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return instance.__dict__.get(self.name)

    def __set__(self, instance, value):
        if value is None and self.allow_none:
            instance.__dict__[self.name] = None
            return

        if not any(isinstance(value, t) for t in self.expected_types):
            type_names = ", ".join(t.__name__ for t in self.expected_types)
            raise TypeError(
                f"Expected one of ({type_names}) for '{self.name}', "
                f"got {type(value).__name__}"
            )
        instance.__dict__[self.name] = value

现在可以这样定义字段：

class Employee:
    name = TypedField(str)
    salary = TypedField(int, float, allow_none=True)

e = Employee()
e.name = "Charlie"
e.salary = 5000      # OK
e.salary = 5000.5    # OK
e.salary = None      # OK, because allow_none=True
e.salary = "high"    # TypeError

步骤四：处理继承与私有属性冲突

如果你在子类中重写字段，描述符仍然有效，因为它是绑定在类上的。但要注意：不要在 __init__ 中直接操作 __dict__ 跳过描述符，否则类型检查会失效。

始终通过属性赋值 来触发描述符：

class SafeInitPerson:
    name = TypedField(str)

    def __init__(self, name):
        self.name = name  # 正确：触发 __set__
        # 不要写成 self.__dict__['name'] = name

步骤五：性能与替代方案对比

虽然描述符功能强大，但它比普通属性稍慢，因为每次访问都要调用方法。但在绝大多数应用中，这点开销可以忽略。

作为对比，以下是其他实现类型检查的方式及其局限：

如果你只需要开发时提示，用类型注解即可；如果需要运行时强制校验，描述符是最灵活的底层方案。

实战：构建一个通用模型基类

组合 多个描述符，创建一个可复用的基类。

class BaseModel:
    def __repr__(self):
        fields = []
        for key, value in self.__class__.__dict__.items():
            if isinstance(value, TypedField):
                val = getattr(self, key, None)
                fields.append(f"{key}={repr(val)}")
        return f"{self.__class__.__name__}({', '.join(fields)})"


class Book(BaseModel):
    title = TypedField(str)
    pages = TypedField(int)
    isbn = TypedField(str, allow_none=True)

b = Book()
b.title = "Python Tricks"
b.pages = 300
print(b)  # 输出: Book(title='Python Tricks', pages=300, isbn=None)

注意事项

• 描述符必须定义在类级别，不能在 __init__ 中动态添加（否则不会触发协议）。
• 避免在 __set__ 中做耗时操作，因为它在每次赋值时都执行。
• 如果你需要更复杂的验证（如范围检查、格式匹配），可以在 __set__ 中扩展逻辑，例如检查字符串长度或数值范围。

class PositiveIntField(TypedField):
    def __init__(self, allow_zero=False):
        super().__init__(int)
        self.allow_zero = allow_zero

    def __set__(self, instance, value):
        super().__set__(instance, value)  # 先做类型检查
        if value < 0 or (value == 0 and not self.allow_zero):
            raise ValueError(f"'{self.name}' must be a positive integer")
        instance.__dict__[self.name] = value

使用它：

class Product:
    price_cents = PositiveIntField()

p = Product()
p.price_cents = 100   # OK
p.price_cents = -10   # ValueError

定义 类时合理组合这些工具，就能构建出既安全又清晰的数据模型。