Python 描述器（Descriptor）深度解析：从原理到 ORM 实战 | Python 进阶核心知识

1
class SimpleDescriptor:
2
    """最简单的描述器示例"""
3

4
    def __get__(self, instance, owner):
5
        print(f"__get__ 被调用: instance={instance}, owner={owner}")
6
        return self._value if hasattr(self, '_value') else None
7

8
    def __set__(self, instance, value):
9
        print(f"__set__ 被调用: instance={instance}, value={value}")
10
        self._value = value
11

12
class MyClass:
13
    attribute = SimpleDescriptor()
14

15
# 使用
16
obj = MyClass()
17
obj.attribute = 42        # __set__ 被调用
18
print(obj.attribute)      # __get__ 被调用，输出: 42

1
class Descriptor:
2
    def __get__(self, instance, owner):
3
        """
4
        参数说明：
5
        - self: 描述器实例
6
        - instance: 拥有该描述器的类实例（如果是类访问则为 None）
7
        - owner: 拥有该描述器的类
8
        """
9
        if instance is None:
10
            # 通过类访问时（MyClass.attr）
11
            return self
12
        # 通过实例访问时（obj.attr）
13
        return f"来自实例 {instance}"
14

15
class MyClass:
16
    attr = Descriptor()
17

18
# 通过类访问
19
print(MyClass.attr)  # 返回描述器对象本身
20

21
# 通过实例访问
22
obj = MyClass()
23
print(obj.attr)      # 返回 "来自实例..."

1
# 1. 数据描述器（如果存在）
2
# 2. 实例 __dict__
3
# 3. 非数据描述器
4
# 4. 类 __dict__
5
# 5. 父类链（MRO）
6
# 6. __getattr__（如果定义）

1
# 数据描述器（实现 __set__）
2
class DataDescriptor:
3
    def __get__(self, instance, owner):
4
        return "数据描述器"
5

6
    def __set__(self, instance, value):
7
        pass  # 只要实现就成为数据描述器
8

9
# 非数据描述器（仅实现 __get__）
10
class NonDataDescriptor:
11
    def __get__(self, instance, owner):
12
        return "非数据描述器"
13

14
class MyClass:
15
    data = DataDescriptor()
16
    non_data = NonDataDescriptor()
17

18
obj = MyClass()
19

20
# 数据描述器：无法被实例属性覆盖
21
obj.data = "尝试覆盖"
22
print(obj.data)  # 输出: "数据描述器"（仍然是描述器）
23

24
# 非数据描述器：可以被实例属性覆盖
25
obj.non_data = "已覆盖"
26
print(obj.non_data)  # 输出: "已覆盖"（实例属性）
27

28
# 删除实例属性后，描述器生效
29
del obj.non_data
30
print(obj.non_data)  # 输出: "非数据描述器"

1
# property 是数据描述器的实现
2
class MyProperty:
3
    def __init__(self, fget=None, fset=None, fdel=None, doc=None):
4
        self.fget = fget
5
        self.fset = fset
6
        self.fdel = fdel
7
        self.__doc__ = doc
8

9
    def __get__(self, instance, owner):
10
        if instance is None:
11
            return self
12
        if self.fget is None:
13
            raise AttributeError("unreadable attribute")
14
        return self.fget(instance)
15

16
    def __set__(self, instance, value):
17
        if self.fset is None:
18
            raise AttributeError("can't set attribute")
19
        self.fset(instance, value)
20

21
    def __delete__(self, instance):
22
        if self.fdel is None:
23
            raise AttributeError("can't delete attribute")
24
        self.fdel(instance)
25

26
    # 装饰器方法
27
    def getter(self, fget):
28
        return type(self)(fget, self.fset, self.fdel, self.__doc__)
29

30
    def setter(self, fset):
31
        return type(self)(self.fget, fset, self.fdel, self.__doc__)
32

33
    def deleter(self, fdel):
34
        return type(self)(self.fget, self.fset, fdel, self.__doc__)
35

36
# 使用自定义 property
37
class Person:
38
    def __init__(self, name):
39
        self._name = name
40

41
    @MyProperty
42
    def name(self):
43
        return self._name
44

45
    @name.setter
46
    def name(self, value):
47
        if not isinstance(value, str):
48
            raise TypeError("name must be a string")
49
        self._name = value
50

51
p = Person("Alice")
52
print(p.name)     # "Alice"
53
p.name = "Bob"    # 调用 setter
54
print(p.name)     # "Bob"

1
# classmethod 是非数据描述器
2
class MyClassMethod:
3
    def __init__(self, func):
4
        self.func = func
5

6
    def __get__(self, instance, owner):
7
        # 返回绑定到类的函数
8
        return lambda *args, **kwargs: self.func(owner, *args, **kwargs)
9

10
class MyClass:
11
    @MyClassMethod
12
    def greet(cls):
13
        return f"Hello from {cls.__name__}"
14

15
# 使用
16
print(MyClass.greet())  # "Hello from MyClass"
17
obj = MyClass()
18
print(obj.greet())      # "Hello from MyClass"（仍然绑定到类）

1
# staticmethod 是非数据描述器
2
class MyStaticMethod:
3
    def __init__(self, func):
4
        self.func = func
5

6
    def __get__(self, instance, owner):
7
        # 直接返回原始函数，不绑定
8
        return self.func
9

10
class MyClass:
11
    @MyStaticMethod
12
    def greet():
13
        return "Hello!"
14

15
# 使用
16
print(MyClass.greet())  # "Hello!"
17
obj = MyClass()
18
print(obj.greet())      # "Hello!"（不绑定到任何对象）

1
class Field:
2
    """ORM 字段基类"""
3

4
    def __init__(self, name=None, primary_key=False, nullable=False):
5
        self.name = name
6
        self.primary_key = primary_key
7
        self.nullable = nullable
8

9
    def __set_name__(self, owner, name):
10
        """Python 3.6+ 新增：在类定义时调用，自动获取字段名"""
11
        if self.name is None:
12
            self.name = name
13

14
    def __get__(self, instance, owner):
15
        if instance is None:
16
            return self
17
        # 从实例字典获取值（如果存在）
18
        return instance.__dict__.get(self.name)
19

20
    def __set__(self, instance, value):
21
        # 类型验证（在子类中实现）
22
        self.validate(value)
23
        instance.__dict__[self.name] = value
24

25
    def validate(self, value):
26
        """子类实现验证逻辑"""
27
        pass
28

29
class IntegerField(Field):
30
    """整型字段"""
31

32
    def __init__(self, min_value=None, max_value=None, **kwargs):
33
        super().__init__(**kwargs)
34
        self.min_value = min_value
35
        self.max_value = max_value
36

37
    def validate(self, value):
38
        if value is None:
39
            if not self.nullable:
40
                raise ValueError(f"{self.name} cannot be null")
41
            return
42

43
        if not isinstance(value, int):
44
            raise TypeError(f"{self.name} must be an integer")
45

46
        if self.min_value is not None and value < self.min_value:
47
            raise ValueError(f"{self.name} must be >= {self.min_value}")
48

49
        if self.max_value is not None and value > self.max_value:
50
            raise ValueError(f"{self.name} must be <= {self.max_value}")
51

52
class StringField(Field):
53
    """字符串字段"""
54

55
    def __init__(self, max_length=None, **kwargs):
56
        super().__init__(**kwargs)
57
        self.max_length = max_length
58

59
    def validate(self, value):
60
        if value is None:
61
            if not self.nullable:
62
                raise ValueError(f"{self.name} cannot be null")
63
            return
64

65
        if not isinstance(value, str):
66
            raise TypeError(f"{self.name} must be a string")
67

68
        if self.max_length is not None and len(value) > self.max_length:
69
            raise ValueError(f"{self.name} length must be <= {self.max_length}")

1
class ModelMeta(type):
2
    """模型元类：收集字段信息"""
3

4
    def __new__(mcs, name, bases, namespace):
5
        fields = {}
6

7
        # 收集所有 Field 实例
8
        for key, value in namespace.items():
9
            if isinstance(value, Field):
10
                fields[key] = value
11

12
        # 存储字段信息
13
        namespace['_fields'] = fields
14

15
        return super().__new__(mcs, name, bases, namespace)
16

17
class Model(metaclass=ModelMeta):
18
    """模型基类"""
19

20
    def __init__(self, **kwargs):
21
        for field_name, field in self._fields.items():
22
            if field_name in kwargs:
23
                setattr(self, field_name, kwargs[field_name])
24
            elif not field.nullable:
25
                raise ValueError(f"{field_name} is required")
26

27
    def save(self):
28
        """模拟保存到数据库"""
29
        data = {}
30
        for field_name, field in self._fields.items():
31
            data[field_name] = getattr(self, field_name)
32

33
        print(f"Saving {self.__class__.__name__}: {data}")
34

35
    @classmethod
36
    def get_fields(cls):
37
        return cls._fields
38

39
# 使用示例
40
class User(Model):
41
    id = IntegerField(primary_key=True)
42
    name = StringField(max_length=100)
43
    age = IntegerField(min_value=0, max_value=120)
44
    email = StringField(max_length=255)
45

46
# 创建实例
47
user = User(id=1, name="Alice", age=30, email="alice@example.com")
48
user.save()  # Saving User: {'id': 1, 'name': 'Alice', 'age': 30, 'email': 'alice@example.com'}
49

50
# 验证失败示例
51
try:
52
    user2 = User(id=2, name="Bob", age="invalid", email="bob@example.com")
53
except TypeError as e:
54
    print(e)  # age must be an integer

1
class ValidatorDescriptor:
2
    """通用验证器描述器"""
3

4
    def __init__(self, validator=None, default=None):
5
        self.validator = validator
6
        self.default = default
7
        self.name = None
8

9
    def __set_name__(self, owner, name):
10
        self.name = name
11

12
    def __get__(self, instance, owner):
13
        if instance is None:
14
            return self
15
        return instance.__dict__.get(self.name, self.default)
16

17
    def __set__(self, instance, value):
18
        if self.validator is not None:
19
            if not self.validator(value):
20
                raise ValueError(f"Invalid value for {self.name}")
21
        instance.__dict__[self.name] = value
22

23
# 使用验证器
24
def is_positive(x):
25
    return x > 0
26

27
def is_email(x):
28
    return isinstance(x, str) and '@' in x
29

30
class Product:
31
    price = ValidatorDescriptor(validator=is_positive)
32
    email = ValidatorDescriptor(validator=is_email)
33

34
p = Product()
35
p.price = 100    # 正常
36
p.email = "test@example.com"  # 正常
37

38
try:
39
    p.price = -10  # 验证失败
40
except ValueError as e:
41
    print(e)  # Invalid value for price

1
class CachedDescriptor:
2
    """缓存描述器：延迟计算并缓存结果"""
3

4
    def __init__(self, func):
5
        self.func = func
6
        self.name = None
7

8
    def __set_name__(self, owner, name):
9
        self.name = name
10

11
    def __get__(self, instance, owner):
12
        if instance is None:
13
            return self
14

15
        # 检查缓存
16
        if self.name not in instance.__dict__:
17
            # 计算并缓存
18
            result = self.func(instance)
19
            instance.__dict__[self.name] = result
20

21
        return instance.__dict__[self.name]
22

23
    def __set__(self, instance, value):
24
        # 允许手动设置缓存值
25
        instance.__dict__[self.name] = value
26

27
class DataProcessor:
28
    def __init__(self, data):
29
        self.data = data
30

31
    @CachedDescriptor
32
    def processed_data(self):
33
        """模拟耗时计算"""
34
        print("Processing data...")
35
        # 模拟耗时操作
36
        import time
37
        time.sleep(1)
38
        return [x * 2 for x in self.data]
39

40
# 使用
41
processor = DataProcessor([1, 2, 3, 4, 5])
42

43
# 第一次访问：计算并缓存
44
print(processor.processed_data)  # 输出 "Processing data..."，然后 [2, 4, 6, 8, 10]
45

46
# 第二次访问：直接返回缓存
47
print(processor.processed_data)  # 直接返回 [2, 4, 6, 8, 10]

1
class LazyLoadDescriptor:
2
    """懒加载描述器：按需加载资源"""
3

4
    def __init__(self, loader):
5
        """
6
        loader: 一个函数，接受实例作为参数，返回加载的值
7
        """
8
        self.loader = loader
9
        self.name = None
10

11
    def __set_name__(self, owner, name):
12
        self.name = name
13

14
    def __get__(self, instance, owner):
15
        if instance is None:
16
            return self
17

18
        # 检查是否已加载
19
        if self.name not in instance.__dict__:
20
            # 懒加载
21
            instance.__dict__[self.name] = self.loader(instance)
22

23
        return instance.__dict__[self.name]
24

25
    def __set__(self, instance, value):
26
        instance.__dict__[self.name] = value
27

28
# 使用示例
29
def load_large_file(instance):
30
    """模拟加载大文件"""
31
    print(f"Loading large file: {instance.filename}")
32
    return f"Content of {instance.filename}"
33

34
class Document:
35
    def __init__(self, filename):
36
        self.filename = filename
37

38
    content = LazyLoadDescriptor(loader=load_large_file)
39

40
# 创建文档（不立即加载）
41
doc = Document("large_data.txt")
42

43
# 访问 content 时才加载
44
print(doc.content)  # 输出 "Loading large file: large_data.txt"，然后 "Content of large_data.txt"
45

46
# 再次访问（已缓存）
47
print(doc.content)  # 直接返回缓存内容

1
class LoggingDescriptor:
2
    """日志描述器：记录属性访问"""
3

4
    def __init__(self, wrapped):
5
        self.wrapped = wrapped
6

7
    def __get__(self, instance, owner):
8
        print(f"Accessing {self.wrapped.name}")
9
        return self.wrapped.__get__(instance, owner)
10

11
    def __set__(self, instance, value):
12
        print(f"Setting {self.wrapped.name} = {value}")
13
        self.wrapped.__set__(instance, value)
14

15
class ValidatedField:
16
    """验证字段"""
17

18
    def __init__(self, name=None):
19
        self.name = name
20

21
    def __set_name__(self, owner, name):
22
        if self.name is None:
23
            self.name = name
24

25
    def __get__(self, instance, owner):
26
        if instance is None:
27
            return self
28
        return instance.__dict__.get(self.name)
29

30
    def __set__(self, instance, value):
31
        if not isinstance(value, int):
32
            raise TypeError(f"{self.name} must be int")
33
        instance.__dict__[self.name] = value
34

35
# 创建带日志的验证字段
36
class MyClass:
37
    # 组合描述器
38
    count = LoggingDescriptor(ValidatedField())
39

40
obj = MyClass()
41
obj.count = 42        # 输出 "Setting count = 42"
42
print(obj.count)      # 输出 "Accessing count"，然后 42

1
def field_factory(validator=None, default=None, cached=False):
2
    """描述器工厂：根据参数创建不同类型的描述器"""
3

4
    if cached:
5
        # 创建带缓存的描述器
6
        class CachedField:
7
            def __init__(self):
8
                self.validator = validator
9
                self.default = default
10
                self.name = None
11

12
            def __set_name__(self, owner, name):
13
                self.name = name
14

15
            def __get__(self, instance, owner):
16
                if instance is None:
17
                    return self
18
                if self.name not in instance.__dict__:
19
                    instance.__dict__[self.name] = self.default
20
                return instance.__dict__[self.name]
21

22
            def __set__(self, instance, value):
23
                if self.validator and not self.validator(value):
24
                    raise ValueError(f"Invalid value")
25
                instance.__dict__[self.name] = value
26

27
        return CachedField()
28
    else:
29
        # 创建普通描述器
30
        class SimpleField:
31
            def __init__(self):
32
                self.validator = validator
33
                self.default = default
34
                self.name = None
35

36
            def __set_name__(self, owner, name):
37
                self.name = name
38

39
            def __get__(self, instance, owner):
40
                if instance is None:
41
                    return self
42
                return instance.__dict__.get(self.name, self.default)
43

44
            def __set__(self, instance, value):
45
                if self.validator and not self.validator(value):
46
                    raise ValueError(f"Invalid value")
47
                instance.__dict__[self.name] = value
48

49
        return SimpleField()
50

51
# 使用工厂
52
class Config:
53
    timeout = field_factory(validator=lambda x: x > 0, default=30)
54
    cache_size = field_factory(validator=lambda x: x >= 0, cached=True)
55

56
cfg = Config()
57
print(cfg.timeout)    # 30（默认值）
58
cfg.timeout = 60      # 设置值

1
# ❌ 错误：每次访问都修改状态
2
class BadDescriptor:
3
    def __get__(self, instance, owner):
4
        instance.__dict__['counter'] = instance.__dict__.get('counter', 0) + 1
5
        return instance.__dict__['counter']
6

7
# ✅ 正确：只读取，不修改
8
class GoodDescriptor:
9
    def __get__(self, instance, owner):
10
        return instance.__dict__.get('counter', 0)

1
# ❌ 错误：通过类访问时崩溃
2
class BadDescriptor:
3
    def __get__(self, instance, owner):
4
        return instance.__dict__['value']  # instance 可能是 None
5

6
# ✅ 正确：检查 instance
7
class GoodDescriptor:
8
    def __get__(self, instance, owner):
9
        if instance is None:
10
            return self  # 通过类访问返回描述器本身
11
        return instance.__dict__.get('value')

1
# ❌ 错误：__set_name__ 被调用时类还未完全创建
2
class BadDescriptor:
3
    def __set_name__(self, owner, name):
4
        # owner 是正在创建的类，但可能不完整
5
        owner.some_class_attr = True  # 可能导致问题
6

7
# ✅ 正确：只存储字段名
8
class GoodDescriptor:
9
    def __set_name__(self, owner, name):
10
        self.name = name  # 只存储字段名，不修改类