一句话结论:@property 不是"把方法包装成属性"这么简单——它往类字典里放了一个 data descriptor(同时定义了 __get__、__set__、__delete__ 的对象)。data descriptor 的优先级高于实例字典 __dict__,所以实例永远"藏不住"一个同名的真属性;而只定义了 __get__ 的普通函数是非数据描述符,会被实例字典覆盖。这一个优先级规则,就是属性查找的全部秘密。
本文全部代码在 CPython 3.13.14 本机实测通过。
一、@property 在类字典里放了什么
class C:
@property
def x(self):
return self._x * 2
@x.setter
def x(self, v):
self._x = v
看类字典:
c = C()
c.x = 21
print(c.x) # 42
print(type(C.__dict__['x'])) # <class 'property'>
print('x' in C.__dict__) # True
实测输出:
A1 property 读写 -> 42 | type = property | 是类属性? = True
关键点:x 不是实例属性,是类属性。property 对象本身坐镇 C.__dict__,每次 c.x 都要通过它转发。
这个对象有完整的描述符三件套:
p = C.__dict__['x']
print(hasattr(p, '__get__'), hasattr(p, '__set__'), hasattr(p, '__delete__'))
# True True True
实测:
A2 描述符协议 -> True True True | fget/fset = True True
三个都齐,所以它叫 data descriptor。原始的 getter、setter 分别存在 p.fget、p.fset 上。
二、只读 property 赋值时,报错发生在哪一层
class D:
@property
def y(self):
return 1
d = D()
d.y = 2 # AttributeError!
实测:
A3 只读赋值 -> AttributeError: property 'y' of 'D' object has no setter
注意:这个 AttributeError 不是 Python "检查权限"查出来的,而是属性查找协议走到 __set__ 时,property 的默认实现直接抛的。同理删除:
A6 del 无 deleter 的 property -> AttributeError: property 'x' of 'C' object has no deleter
带 @x.deleter 的 property 才能被 del,且 del 走的是你写的 deleter(实测:deleter 被调用后 hasattr(g, '_g') 变 False)。
三、核心规则:data descriptor 压过实例字典
这是整篇文章最重要的一组对照实验。
实验 1:实例字典里塞一个同名真属性,看谁赢——
class E:
@property
def z(self):
return 'FROM_PROPERTY'
e = E()
e.__dict__['z'] = 'FROM_DICT' # 直接绕过 __setattr__ 往实例字典里塞
print(e.z)
A4 实例字典试图覆盖 property -> FROM_PROPERTY
property 赢了。实例字典里明明有 z,查找协议却优先问了类上的 data descriptor。
实验 2:普通方法(只有 __get__ 的非数据描述符)——
class F:
def m(self):
return 'FROM_CLASS'
f = F()
f.__dict__['m'] = lambda: 'FROM_DICT'
print(f.m())
A5 非 data descriptor 被实例字典覆盖 -> FROM_DICT
这次实例字典赢了。
完整优先级(obj.x 的查找顺序):
1. 类及其 MRO 上找到 data descriptor(如 property) -> 用它,且跳过实例字典
2. 实例 __dict__ 里有同名属性 -> 用实例的
3. 类及其 MRO 上找到非数据描述符(如普通函数) -> 用它(兜底给类)
4. 都没有 -> 走 __getattr__ / 抛 AttributeError
这也解释了为什么 property 可以做"只读属性":不是 Python 帮你检查,而是 data descriptor 的优先级天然让实例字典的赋值"够不着"它。
四、手写一个等价物,验证机制
property 不是语法糖,它就是上面这套协议的实现。自己写一个:
class Prop:
def __init__(self, fget):
self.fget = fget
def __get__(self, obj, objtype=None):
if obj is None: # 通过类访问时返回描述符本身
return self
return self.fget(obj)
class H:
def __init__(self):
self._v = 7
def _get(self):
return self._v + 100
v = Prop(_get)
print(H().v) # 107
A7 手写 data descriptor -> 107
和 property 行为一致。区别只在于官方版还带 __set__/__delete__,属于 data descriptor;我们这个只有 __get__,是非数据描述符——所以它其实可以被实例字典覆盖,这正是两种描述符的分界线。
五、进阶玩法:set_name 写校验字段
自定义描述符还能用 __set_name__ 在类创建时自动记住自己的名字,写出可复用的校验属性:
class Checked:
def __set_name__(self, owner, name):
self.name = '_' + name # 存到 _qty,避免递归
def __get__(self, obj, objtype=None):
if obj is None: return self
return getattr(obj, self.name)
def __set__(self, obj, val):
if val < 0:
raise ValueError('must be >= 0')
setattr(obj, self.name, val)
class Order:
qty = Checked()
def __init__(self):
self.qty = 3
o = Order()
o.qty = 10 # ok
o.qty = -1 # ValueError: must be >= 0
A8 __set_name__ -> 10 | 负数拦截: must be >= 0
@property 的 setter 里手写 if v < 0: raise,和这种描述符方案是同一件事的两种写法——前者一属性一写,后者一个描述符类管所有属性。
六、字节码与开销
读 obj.x 和调 obj.getx() 的字节码只差一个 CALL:
A9 read attr 字节码 -> ['RESUME', 'LOAD_NAME', 'LOAD_ATTR', 'RETURN_VALUE']
A9b method call 字节码 -> ['RESUME', 'LOAD_NAME', 'LOAD_ATTR', 'CALL', 'RETURN_VALUE']
20 万次访问实测:
A10 20万次 property/method/裸属性 -> 0.0239 / 0.0240 / 0.0177 s
property 比裸属性慢约 35%,但和直接调 getter 方法几乎持平——c.x 本质上就是一次函数调用。热点循环里反复读 property 时,值得先存成局部变量。
七、总结
| 问题 | 答案 |
|---|---|
@property 往类里放了什么 |
一个 property 实例,data descriptor,坐镇 __dict__ |
| 只读赋值谁报的错 | property.__set__ 的默认实现抛 AttributeError |
| 为什么实例藏不住同名属性 | data descriptor 优先级 > 实例字典 |
| 普通方法为什么能被实例字典覆盖 | 函数是非数据描述符(只有 __get__) |
| 手写等价物 | 定义 __get__(+__set__ 才算 data descriptor) |
| 批量校验属性 | 自定义描述符 + __set_name__ |
| 性能 | 约等于一次方法调用,比裸属性慢 35% |
三个常见误区:
- 以为
@property只是"语法糖"——它是完整的属性查找协议干预,搞不懂描述符优先级就解释不了"为什么我的赋值不生效"。 - 以为只读属性是 Python 做了权限检查——实际是 data descriptor 的查找优先级让赋值根本到不了实例字典。
- 给 property 起名和内部字段同名(如
x内部存self.x)——递归炸栈,内部字段记得换个名字。