1. 为什么我们需要理解描述符协议在Python开发中我们每天都在使用描述符只是大多数人没有意识到这一点。当你使用property装饰器时当你调用实例方法时甚至当你访问类属性时描述符协议都在幕后默默工作。理解这个协议就像拿到了Python对象模型的万能钥匙。我曾在项目中遇到过这样一个问题需要动态控制某些属性的访问权限常规的property写法会导致代码臃肿。直到深入理解描述符协议后我才发现可以用一个通用的权限控制描述符来优雅地解决这个问题代码量减少了70%。2. 描述符协议的核心机制2.1 什么是描述符描述符是实现了特定协议的Python类这个协议包含以下三个方法中的一个或多个__get__(self, obj, objtypeNone) - object __set__(self, obj, value) - None __delete__(self, obj) - None当你的类实现了这些方法它就成为了一个描述符。根据实现的方法不同描述符可以分为数据描述符实现__set__或__delete__非数据描述符仅实现__get__2.2 属性访问的优先级规则Python的属性查找遵循一套严格的优先级规则数据描述符最高优先级实例属性非数据描述符类属性getattr最后兜底这个顺序解释了为什么实例方法非数据描述符可以被实例属性覆盖而property数据描述符则不能被直接覆盖。3. 手把手实现各种描述符3.1 基础描述符示例让我们实现一个最简单的描述符记录属性访问class LoggedAccess: def __init__(self, name): self.name name def __get__(self, obj, objtypeNone): value obj.__dict__.get(self.name) print(fAccessing {self.name} with value {value}) return value def __set__(self, obj, value): print(fUpdating {self.name} to {value}) obj.__dict__[self.name] value class Person: name LoggedAccess(name) def __init__(self, name): self.name name p Person(Alice) p.name # 输出: Accessing name with value Alice p.name Bob # 输出: Updating name to Bob3.2 延迟初始化描述符有些属性计算成本高我们可以实现延迟初始化class LazyProperty: def __init__(self, func): self.func func self.name func.__name__ def __get__(self, obj, objtypeNone): if obj is None: return self value self.func(obj) obj.__dict__[self.name] value return value class Circle: def __init__(self, radius): self.radius radius LazyProperty def area(self): print(Calculating area...) return 3.14 * self.radius ** 2 c Circle(5) print(c.area) # 第一次访问会计算 print(c.area) # 第二次直接返回缓存值3.3 类型检查描述符我们可以用描述符实现运行时类型检查class Typed: def __init__(self, name, expected_type): self.name name self.expected_type expected_type def __get__(self, obj, objtypeNone): if obj is None: return self return obj.__dict__.get(self.name) def __set__(self, obj, value): if not isinstance(value, self.expected_type): raise TypeError(fExpected {self.expected_type}) obj.__dict__[self.name] value class Person: name Typed(name, str) age Typed(age, int) def __init__(self, name, age): self.name name self.age age p Person(Alice, 30) # 正常 p.age thirty # 抛出TypeError4. 描述符的高级应用场景4.1 实现ORM映射描述符是Python ORM框架的核心技术。下面是一个简化版的ORM实现class Field: def __init__(self, column_type): self.column_type column_type def __set_name__(self, owner, name): self.name name def __get__(self, obj, objtypeNone): if obj is None: return self return obj.__dict__.get(self.name) def __set__(self, obj, value): if not isinstance(value, self.column_type): raise ValueError(fExpected {self.column_type}) obj.__dict__[self.name] value class IntegerField(Field): def __init__(self): super().__init__(int) class StringField(Field): def __init__(self): super().__init__(str) class Model: def __init__(self, **kwargs): for name, value in kwargs.items(): setattr(self, name, value) def save(self): fields [] values [] for name, field in self.__class__.__dict__.items(): if isinstance(field, Field): fields.append(name) values.append(getattr(self, name)) print(fINSERT INTO {self.__class__.__name__} ({,.join(fields)}) VALUES ({,.join(map(repr, values))})) class User(Model): id IntegerField() name StringField() user User(id1, nameAlice) user.save() # 输出: INSERT INTO User (id,name) VALUES (1,Alice)4.2 方法绑定机制Python的方法绑定实际上也是通过描述符实现的。理解这一点可以帮助我们创建自定义的方法装饰器class MethodLogger: def __init__(self, method): self.method method def __get__(self, obj, objtypeNone): if obj is None: return self.method def logged_method(*args, **kwargs): print(fCalling {self.method.__name__} with {args}, {kwargs}) return self.method(obj, *args, **kwargs) return logged_method class Calculator: MethodLogger def add(self, a, b): return a b calc Calculator() calc.add(2, 3) # 输出: Calling add with (2, 3), {}5. 描述符的陷阱与最佳实践5.1 常见错误模式描述符实例共享问题class BrokenDescriptor: def __init__(self): self.value None def __get__(self, obj, objtypeNone): return self.value def __set__(self, obj, value): self.value value class MyClass: attr BrokenDescriptor() a MyClass() b MyClass() a.attr 42 print(b.attr) # 也输出42所有实例共享同一个值解决方法总是将值存储在实例字典中def __set__(self, obj, value): obj.__dict__[self.name] value描述符与继承的交互 子类中的描述符会覆盖父类的同名描述符这可能导致意外的行为。5.2 性能考量描述符会增加属性访问的开销。在性能关键路径上可以考虑以下优化使用__slots__减少字典查找对于只读描述符考虑使用__dict__直接访问在__get__中避免不必要的计算5.3 调试技巧当描述符行为不符合预期时检查obj.__dict__确认实例状态使用inspect.getmro查看方法解析顺序临时添加打印语句跟踪描述符方法调用6. 描述符与相关技术的对比6.1 描述符 vs propertyproperty实际上是创建了一个数据描述符的语法糖。两者主要区别特性描述符property复用性高可复用类低每个属性单独定义灵活性高完全控制中等受限语法代码量多需要完整类少装饰器语法动态性高运行时修改低定义时固定6.2 描述符 vsgetattr/getattribute描述符提供了更细粒度的属性控制描述符针对单个属性getattr处理所有未定义属性getattribute拦截所有属性访问在性能上描述符通常更高效因为它们不参与每次属性访问。7. Python内置描述符实例分析7.1 classmethod和staticmethod这两个装饰器实际上都是通过描述符实现的class my_classmethod: def __init__(self, method): self.method method def __get__(self, obj, objtypeNone): if objtype is None: objtype type(obj) def new_method(*args, **kwargs): return self.method(objtype, *args, **kwargs) return new_method class my_staticmethod: def __init__(self, method): self.method method def __get__(self, obj, objtypeNone): return self.method7.2 函数与方法普通函数在类中自动变成方法这也是描述符的功劳 def func(self): ... return self ... class A: ... method func ... a A() a.method # 自动绑定到实例 bound method func of __main__.A object at 0x... func.__get__(a, A) # 等价于上面的访问 bound method func of __main__.A object at 0x...8. 现代Python中的描述符改进8.1 __set_name__方法Python 3.6引入了__set_name__让描述符能自动知道自己的属性名class AutoNamedDescriptor: def __set_name__(self, owner, name): self.name name def __get__(self, obj, objtypeNone): if obj is None: return self return obj.__dict__.get(self.name)8.2 描述符协议扩展Python 3.8为描述符协议添加了__set_name__和__objclass__支持使得描述符能更好地与类型系统和inspect模块协作。9. 实际项目中的描述符应用9.1 配置管理系统在大型项目中我们可以用描述符实现类型安全的配置管理class ConfigMeta(type): def __new__(mcls, name, bases, namespace): cls super().__new__(mcls, name, bases, namespace) for name, attr in cls.__dict__.items(): if isinstance(attr, Field): attr.name name return cls class Field: def __init__(self, type_, defaultNone): self.type type_ self.default default def __get__(self, obj, objtypeNone): if obj is None: return self return obj.__dict__.get(self.name, self.default) def __set__(self, obj, value): if not isinstance(value, self.type): raise ValueError(fExpected {self.type}) obj.__dict__[self.name] value class AppConfig(metaclassConfigMeta): host Field(str, localhost) port Field(int, 8080) debug Field(bool, False) config AppConfig() config.port 8000 # 正常 config.host 123 # 抛出ValueError9.2 数据验证框架结合描述符和装饰器可以构建强大的验证框架class Validator: def __init__(self, validator_func): self.validator validator_func def __set_name__(self, owner, name): self.name name def __get__(self, obj, objtypeNone): if obj is None: return self return obj.__dict__.get(self.name) def __set__(self, obj, value): if not self.validator(value): raise ValueError(fInvalid value for {self.name}) obj.__dict__[self.name] value def range_validator(min_, max_): def validator(value): return min_ value max_ return validator class Temperature: celsius Validator(range_validator(-273.15, 1000)) temp Temperature() temp.celsius 25 # 正常 temp.celsius -300 # 抛出ValueError10. 从源码看描述符实现要真正理解描述符我们需要看看CPython是如何实现的。在Objects/descrobject.c中描述符协议的核心逻辑如下static PyObject * descr_get(PyObject *self, PyObject *obj, PyObject *type) { PyObject *get PyObject_GetAttrString(self, __get__); if (get NULL) { if (PyErr_ExceptionMatches(PyExc_AttributeError)) { PyErr_Clear(); return self; } return NULL; } PyObject *res PyObject_CallFunctionObjArgs(get, obj, type, NULL); Py_DECREF(get); return res; }这段C代码展示了Python如何查找并调用__get__方法。类似的逻辑也适用于__set__和__delete__。理解这一点很重要因为它解释了为什么描述符方法需要特定的签名Python会严格按照(self, obj, objtype)的参数格式来调用它们。 
长河君 · 2026/10/28 7:26:48 · 阅读 1.2k Python描述符协议详解与应用实践
1. 为什么我们需要理解描述符协议在Python开发中我们每天都在使用描述符只是大多数人没有意识到这一点。当你使用property装饰器时当你调用实例方法时甚至当你访问类属性时描述符协议都在幕后默默工作。理解这个协议就像拿到了Python对象模型的万能钥匙。我曾在项目中遇到过这样一个问题需要动态控制某些属性的访问权限常规的property写法会导致代码臃肿。直到深入理解描述符协议后我才发现可以用一个通用的权限控制描述符来优雅地解决这个问题代码量减少了70%。2. 描述符协议的核心机制2.1 什么是描述符描述符是实现了特定协议的Python类这个协议包含以下三个方法中的一个或多个__get__(self, obj, objtypeNone) - object __set__(self, obj, value) - None __delete__(self, obj) - None当你的类实现了这些方法它就成为了一个描述符。根据实现的方法不同描述符可以分为数据描述符实现__set__或__delete__非数据描述符仅实现__get__2.2 属性访问的优先级规则Python的属性查找遵循一套严格的优先级规则数据描述符最高优先级实例属性非数据描述符类属性getattr最后兜底这个顺序解释了为什么实例方法非数据描述符可以被实例属性覆盖而property数据描述符则不能被直接覆盖。3. 手把手实现各种描述符3.1 基础描述符示例让我们实现一个最简单的描述符记录属性访问class LoggedAccess: def __init__(self, name): self.name name def __get__(self, obj, objtypeNone): value obj.__dict__.get(self.name) print(fAccessing {self.name} with value {value}) return value def __set__(self, obj, value): print(fUpdating {self.name} to {value}) obj.__dict__[self.name] value class Person: name LoggedAccess(name) def __init__(self, name): self.name name p Person(Alice) p.name # 输出: Accessing name with value Alice p.name Bob # 输出: Updating name to Bob3.2 延迟初始化描述符有些属性计算成本高我们可以实现延迟初始化class LazyProperty: def __init__(self, func): self.func func self.name func.__name__ def __get__(self, obj, objtypeNone): if obj is None: return self value self.func(obj) obj.__dict__[self.name] value return value class Circle: def __init__(self, radius): self.radius radius LazyProperty def area(self): print(Calculating area...) return 3.14 * self.radius ** 2 c Circle(5) print(c.area) # 第一次访问会计算 print(c.area) # 第二次直接返回缓存值3.3 类型检查描述符我们可以用描述符实现运行时类型检查class Typed: def __init__(self, name, expected_type): self.name name self.expected_type expected_type def __get__(self, obj, objtypeNone): if obj is None: return self return obj.__dict__.get(self.name) def __set__(self, obj, value): if not isinstance(value, self.expected_type): raise TypeError(fExpected {self.expected_type}) obj.__dict__[self.name] value class Person: name Typed(name, str) age Typed(age, int) def __init__(self, name, age): self.name name self.age age p Person(Alice, 30) # 正常 p.age thirty # 抛出TypeError4. 描述符的高级应用场景4.1 实现ORM映射描述符是Python ORM框架的核心技术。下面是一个简化版的ORM实现class Field: def __init__(self, column_type): self.column_type column_type def __set_name__(self, owner, name): self.name name def __get__(self, obj, objtypeNone): if obj is None: return self return obj.__dict__.get(self.name) def __set__(self, obj, value): if not isinstance(value, self.column_type): raise ValueError(fExpected {self.column_type}) obj.__dict__[self.name] value class IntegerField(Field): def __init__(self): super().__init__(int) class StringField(Field): def __init__(self): super().__init__(str) class Model: def __init__(self, **kwargs): for name, value in kwargs.items(): setattr(self, name, value) def save(self): fields [] values [] for name, field in self.__class__.__dict__.items(): if isinstance(field, Field): fields.append(name) values.append(getattr(self, name)) print(fINSERT INTO {self.__class__.__name__} ({,.join(fields)}) VALUES ({,.join(map(repr, values))})) class User(Model): id IntegerField() name StringField() user User(id1, nameAlice) user.save() # 输出: INSERT INTO User (id,name) VALUES (1,Alice)4.2 方法绑定机制Python的方法绑定实际上也是通过描述符实现的。理解这一点可以帮助我们创建自定义的方法装饰器class MethodLogger: def __init__(self, method): self.method method def __get__(self, obj, objtypeNone): if obj is None: return self.method def logged_method(*args, **kwargs): print(fCalling {self.method.__name__} with {args}, {kwargs}) return self.method(obj, *args, **kwargs) return logged_method class Calculator: MethodLogger def add(self, a, b): return a b calc Calculator() calc.add(2, 3) # 输出: Calling add with (2, 3), {}5. 描述符的陷阱与最佳实践5.1 常见错误模式描述符实例共享问题class BrokenDescriptor: def __init__(self): self.value None def __get__(self, obj, objtypeNone): return self.value def __set__(self, obj, value): self.value value class MyClass: attr BrokenDescriptor() a MyClass() b MyClass() a.attr 42 print(b.attr) # 也输出42所有实例共享同一个值解决方法总是将值存储在实例字典中def __set__(self, obj, value): obj.__dict__[self.name] value描述符与继承的交互 子类中的描述符会覆盖父类的同名描述符这可能导致意外的行为。5.2 性能考量描述符会增加属性访问的开销。在性能关键路径上可以考虑以下优化使用__slots__减少字典查找对于只读描述符考虑使用__dict__直接访问在__get__中避免不必要的计算5.3 调试技巧当描述符行为不符合预期时检查obj.__dict__确认实例状态使用inspect.getmro查看方法解析顺序临时添加打印语句跟踪描述符方法调用6. 描述符与相关技术的对比6.1 描述符 vs propertyproperty实际上是创建了一个数据描述符的语法糖。两者主要区别特性描述符property复用性高可复用类低每个属性单独定义灵活性高完全控制中等受限语法代码量多需要完整类少装饰器语法动态性高运行时修改低定义时固定6.2 描述符 vsgetattr/getattribute描述符提供了更细粒度的属性控制描述符针对单个属性getattr处理所有未定义属性getattribute拦截所有属性访问在性能上描述符通常更高效因为它们不参与每次属性访问。7. Python内置描述符实例分析7.1 classmethod和staticmethod这两个装饰器实际上都是通过描述符实现的class my_classmethod: def __init__(self, method): self.method method def __get__(self, obj, objtypeNone): if objtype is None: objtype type(obj) def new_method(*args, **kwargs): return self.method(objtype, *args, **kwargs) return new_method class my_staticmethod: def __init__(self, method): self.method method def __get__(self, obj, objtypeNone): return self.method7.2 函数与方法普通函数在类中自动变成方法这也是描述符的功劳 def func(self): ... return self ... class A: ... method func ... a A() a.method # 自动绑定到实例 bound method func of __main__.A object at 0x... func.__get__(a, A) # 等价于上面的访问 bound method func of __main__.A object at 0x...8. 现代Python中的描述符改进8.1 __set_name__方法Python 3.6引入了__set_name__让描述符能自动知道自己的属性名class AutoNamedDescriptor: def __set_name__(self, owner, name): self.name name def __get__(self, obj, objtypeNone): if obj is None: return self return obj.__dict__.get(self.name)8.2 描述符协议扩展Python 3.8为描述符协议添加了__set_name__和__objclass__支持使得描述符能更好地与类型系统和inspect模块协作。9. 实际项目中的描述符应用9.1 配置管理系统在大型项目中我们可以用描述符实现类型安全的配置管理class ConfigMeta(type): def __new__(mcls, name, bases, namespace): cls super().__new__(mcls, name, bases, namespace) for name, attr in cls.__dict__.items(): if isinstance(attr, Field): attr.name name return cls class Field: def __init__(self, type_, defaultNone): self.type type_ self.default default def __get__(self, obj, objtypeNone): if obj is None: return self return obj.__dict__.get(self.name, self.default) def __set__(self, obj, value): if not isinstance(value, self.type): raise ValueError(fExpected {self.type}) obj.__dict__[self.name] value class AppConfig(metaclassConfigMeta): host Field(str, localhost) port Field(int, 8080) debug Field(bool, False) config AppConfig() config.port 8000 # 正常 config.host 123 # 抛出ValueError9.2 数据验证框架结合描述符和装饰器可以构建强大的验证框架class Validator: def __init__(self, validator_func): self.validator validator_func def __set_name__(self, owner, name): self.name name def __get__(self, obj, objtypeNone): if obj is None: return self return obj.__dict__.get(self.name) def __set__(self, obj, value): if not self.validator(value): raise ValueError(fInvalid value for {self.name}) obj.__dict__[self.name] value def range_validator(min_, max_): def validator(value): return min_ value max_ return validator class Temperature: celsius Validator(range_validator(-273.15, 1000)) temp Temperature() temp.celsius 25 # 正常 temp.celsius -300 # 抛出ValueError10. 从源码看描述符实现要真正理解描述符我们需要看看CPython是如何实现的。在Objects/descrobject.c中描述符协议的核心逻辑如下static PyObject * descr_get(PyObject *self, PyObject *obj, PyObject *type) { PyObject *get PyObject_GetAttrString(self, __get__); if (get NULL) { if (PyErr_ExceptionMatches(PyExc_AttributeError)) { PyErr_Clear(); return self; } return NULL; } PyObject *res PyObject_CallFunctionObjArgs(get, obj, type, NULL); Py_DECREF(get); return res; }这段C代码展示了Python如何查找并调用__get__方法。类似的逻辑也适用于__set__和__delete__。理解这一点很重要因为它解释了为什么描述符方法需要特定的签名Python会严格按照(self, obj, objtype)的参数格式来调用它们。