外观
10 - 访问属性为什么会执行代码:属性查找、property 与 descriptor
摘要
一次看似普通的 report.limit 读取可能触发函数,赋值也可能先校验再保存。本文从属性校验与方法遮蔽的教学场景出发,解释描述符、属性查找优先级及访问钩子,帮助你定位隐藏副作用。
版本范围:Python 3.14,普通 Python 类与默认属性访问为主;扩展类型或覆盖钩子的类可以改变行为。独立示例已在 Windows 上使用 CPython 3.14.0 与 3.13.7 执行通过。
1. 场景:字段已经改成 -1,读出来为什么仍是 10
假设日志查询接口有一个 limit,要求它是正整数。你给类添加了属性校验,测试时为了模拟坏数据直接写入 report.__dict__["limit"] = -1,然后读取 report.limit。令人意外的是,读取结果仍是原来的合法值。另一边,同样给实例字典写入 title,却成功覆盖了原本的 title() 方法。 可进一步阅读SpringAOP代理创建流程:代理切面与Python属性入口机制不同。
这不是字典没有更新,而是属性访问并非简单的字典查询。Python 允许类上的对象参与访问规则:有些对象可以优先接管同名属性的读取与赋值,有些只在实例没有同名值时参与读取。这套机制将方法绑定、property 和很多框架字段组织到共同的协议中。
把一次 obj.x 分成“选中候选”和“执行候选”:先按访问协议确定谁有优先权,再确认它从哪份状态取值、是否产生副作用。 默认属性访问下,数据描述符、实例值、非数据描述符的顺序不同;自定义钩子和特殊类型另有边界。只打印实例字典看不到整条访问链。
先预测同样往字典写入 limit 和 title,为什么一个读出十、一个读出字符串。limit 的数据描述符先接管,读取 _limit;title 的普通函数是非数据描述符,实例字符串抢先返回,之后调用才失败。条件只改变候选协议,就能解释两种同名覆盖结果。
2. descriptor 是参与属性访问的一组协议
descriptor(描述符)指其类型定义了 __get__、__set__ 或 __delete__ 等方法的对象。当这个对象放在另一个类的属性位置,默认属性机制能够调用这些方法。协议不是要求继承一个特定基类,而是约定若干方法的含义。
__get__(instance, owner) 负责读取;__set__(instance, value) 负责赋值;__delete__(instance) 负责删除。实例读取时传入具体实例,类读取时通常传入 None 作为实例。owner 提供所属或访问涉及的类。只有读接口的是 non-data descriptor(非数据描述符);定义设置或删除接口的是 data descriptor(数据描述符)。一个只读属性也可以是数据描述符:它的设置接口拒绝赋值,拒绝同样是一种接管。
这里“数据”与“非数据”不表示对象里是否存有业务数据,而是区分协议和查找优先级。普通函数提供读协议,因此属于非数据描述符,能够生成上一篇的绑定方法。property 提供接管读写的接口,即使没有 setter,也不会因此变成可随意遮蔽的普通属性。
描述符通常是类级对象,却为不同实例管理不同值。这需要把实际业务状态存到实例或者另一个明确的存储系统,不能简单把每次赋值都保存在描述符的 self.value 上。那样所有实例又会共享同一个值,复现第 9 篇的状态污染。描述符对象的身份与它管理的每个实例状态,应当画成两层。
官方 数据模型的描述符调用规则明确区分数据描述符、实例字典和非数据描述符的顺序。本文所有优先级结论都建立在默认属性访问机制上。
3. 从 obj.x 走完整条读取链
3.1 先找类候选,再比较优先级
粗略说“先查实例,后查类”只适用于一部分属性。默认的 object.__getattribute__ 会沿实例类型的 MRO 查找类上的候选属性,判断候选是否是数据描述符。若是,并提供读取接口,调用它的读取逻辑;否则再考虑实例中的同名值。实例也没有时,若类候选有读协议则调用它,否则返回普通类属性。
如果这些路径都没有找到可用值,通常抛出 AttributeError。通过普通属性语法访问时,类定义的 __getattr__ 可以在这个失败后补充结果。它不是每次访问都执行的入口。直接调用 object.__getattribute__ 则不会自动提供同一层语法触发的补救路径,调试时不能把两者当完全等价。
图表将在阅读到此处时加载…
图里没有画出所有特殊类型的存储形式,也没有覆盖自定义访问钩子主动改写规则的情况。它表达的是本篇普通类的机制主线,不是适用于所有 Python 对象的固定内存算法。
3.2 数据描述符为何要优先
如果实例同名值总能绕过描述符,属性校验就无法可靠接管访问。数据描述符优先,使对象可以要求调用方通过统一规则读取和设置特定属性。示例的 Positive 将值存到 _limit,即使字典里另外存在 limit,属性读取仍通过 Positive.__get__ 取 _limit。
这只是接口一致性,并非防篡改保障。调用方仍能直接改 _limit,或通过其他手段修改对象。应用中不应允许不可信代码随意持有对象后依靠描述符实现安全隔离。描述符适合表达对象内部协议和减少误用;真正的数据权限要在服务和存储边界落实。
3.3 方法为什么能被实例值遮蔽
类上的普通函数是非数据描述符,所以实例同名值可以优先。写入 report.title = "instance value" 后,report.title 返回字符串,再调用 report.title() 就会报字符串不可调用。这个失败发生在读取成功之后的调用阶段,区别于找不到属性。
在线上排查“对象不可调用”时,除了检查类定义,也要检查实例是否被配置加载、动态赋值或测试替换写入了同名值。盲目改函数签名解决不了遮蔽问题。对公共方法名称和业务数据字段保持明确命名边界,可以减少这类冲突。
4. 用 property 把普通访问语法连接到函数
下面先阅读完整示例的 Positive、Report 和主入口:字典出现 limit=-1 不应改变 report.limit 的十;写入 title 则应遮蔽绑定方法。再看缓存部分,静态观察应保持计算次数零,首次动态读增加到一,缓存遮蔽后的后续读不再增加;删除缓存关联才重新计算。每次都先找被选中的候选,再看真正执行了哪段代码。
property 是内置的描述符工具。读方法返回值,setter 执行赋值规则,deleter 管理删除。只有读取需求时,使用 @property 即可;需要写入时通过对应的 .setter 添加方法。下面的完整示例同时包含校验、遮蔽与缓存观测。先按本节读取路径理解 Positive,再继续查看后面的静态与动态访问对比:
python
"""独立示例:属性优先级、无副作用观测与缓存失效。"""
from functools import cached_property
import inspect
class Positive:
def __set_name__(self, owner, name):
self.storage_name = "_" + name
def __get__(self, instance, owner=None):
if instance is None:
return self
return vars(instance)[self.storage_name]
def __set__(self, instance, value):
if type(value) is not int or value <= 0:
raise ValueError("limit must be a positive integer")
vars(instance)[self.storage_name] = value
class Report:
limit = Positive()
def __init__(self, limit):
self.limit = limit
def title(self):
return "report"
def __getattr__(self, name):
if name == "optional":
return "fallback"
raise AttributeError(name)
if __name__ == "__main__":
report = Report(10)
report.__dict__["limit"] = -1 # 反例:试图遮蔽数据描述符。
assert report.limit == 10
print("validated:", report.limit)
try:
report.limit = 0
except ValueError as exc:
print("rejected:", str(exc))
report.title = "instance value" # 函数是非数据描述符,可以被遮蔽。
assert report.title == "instance value"
print("shadow:", report.title)
print("fallback:", report.optional)
class CachedReport:
def __init__(self):
self.rows = ["ok"]
self.calls = 0
@cached_property
def count(self):
self.calls += 1
return len(self.rows)
cached = CachedReport()
candidate = inspect.getattr_static(cached, "count")
assert isinstance(candidate, cached_property) and cached.calls == 0
assert getattr(cached, "count") == 1 and cached.calls == 1
cached.rows.append("error")
assert cached.count == 1 and cached.calls == 1 # 反例:底层变了,缓存未失效。
del cached.count # 正例:明确删除缓存;下一次读取重新计算。
assert cached.count == 2 and cached.calls == 2
print("static read calls:", 0, "after invalidation:", cached.count, cached.calls)
class MissingReport:
limit = Positive()
try:
MissingReport().limit
except KeyError:
print("missing storage:", "KeyError (minimal descriptor boundary)")
class RequiredPositive(Positive):
def __get__(self, instance, owner=None):
if instance is None:
return self
try:
return super().__get__(instance, owner)
except KeyError as error:
raise AttributeError("required field not initialized") from error
class RequiredReport:
limit = RequiredPositive()
assert not hasattr(RequiredReport(), "limit")
print("missing field:", "AttributeError preserved")保存名用 _limit 而非 limit,因为 setter 中执行 self.limit = value 会再次进入同一个 setter,造成递归。读取方法也不能通过 return self.limit 获取自己的值。同名语法会重新启动属性访问链,不会因为正在该方法内部就自动变成原始存储读取。
少量属性规则优先使用 property,它比自写通用描述符更容易理解。多个字段需要同一套校验、转换或懒加载规则时,再提取描述符。提取后要明确命名、存储位置、未初始化行为和继承复用,而不只是把重复函数藏到另一个类里。
属性还承担调用成本的表达责任。返回本地缓存的简单计算通常容易接受;属性读取若执行网络请求,调用方却难以从语法判断超时和失败。框架中确有延迟加载属性,但接口应说明其成本,并提供批量读取或预取方式。业务代码也可以用明确命名的方法表达昂贵操作。
5. 最小实验:优先级与校验完整复现
保存为 examples/10_descriptors.py,执行:
powershell
python docs/python/examples/10_descriptors.pypython
"""独立示例:数据描述符优先级与非数据描述符遮蔽。"""
class Positive:
def __set_name__(self, owner, name):
self.storage_name = "_" + name
def __get__(self, instance, owner=None):
if instance is None:
return self
return vars(instance)[self.storage_name]
def __set__(self, instance, value):
if type(value) is not int or value <= 0:
raise ValueError("limit must be a positive integer")
vars(instance)[self.storage_name] = value
class Report:
limit = Positive()
def __init__(self, limit):
self.limit = limit
def title(self):
return "report"
def __getattr__(self, name):
if name == "optional":
return "fallback"
raise AttributeError(name)
if __name__ == "__main__":
report = Report(10)
report.__dict__["limit"] = -1 # 反例:试图遮蔽数据描述符。
assert report.limit == 10
print("validated:", report.limit)
try:
report.limit = 0
except ValueError as exc:
print("rejected:", str(exc))
report.title = "instance value" # 函数是非数据描述符,可以被遮蔽。
assert report.title == "instance value"
print("shadow:", report.title)
print("fallback:", report.optional)确定性预期为 validated: 10、拒绝零值的错误说明、shadow: instance value 和 fallback: fallback。测试没有试图靠直接写入实例字典实现校验,而是有意构造冲突,以比较两个属性的规则。
__set_name__ 在类创建过程中通知描述符所属类和属性名。这样校验器不需要在声明时重复写 "limit"。但类创建后再动态加入描述符,并不自动重复整个通知过程;需要维护这条约定的代码,应显式完成必要的设置。一个描述符对象也不应随意重复用于不同名称,否则简单实现中的 storage_name 会被后一次通知覆盖。
示例故意保持最小:未初始化时从实例字典读取会报错。生产实现可以把缺值转换成清晰的 AttributeError,或要求构造阶段完成初始化。选择哪一种由状态模型决定,不能通过静默返回 None 掩盖不完整对象。
6. getattribute 与 getattr 的边界
__getattribute__ 是实例属性访问的主要入口,重写它会影响几乎每次普通属性读取。__getattr__ 是失败之后的补救钩子,更适合少量动态名称。官方 自定义属性访问区分了两个接口触发条件。
常见反例是 return self.__dict__[name] 写在 __getattribute__ 里。为了获得 self.__dict__,又需要执行 __getattribute__,递归不断重复。若只是增加观测,应该调用 object.__getattribute__(self, name) 获得默认机制的结果;若确实要替换规则,也要明确保留什么属性以及怎样避免自我访问。
另一个坑是 __getattr__ 对任何名称都返回默认值。这样拼写错误不再报错,hasattr 可能对本不存在的属性返回真,协议判断和配置校验受到影响。补救应只覆盖明确支持的名称,其余抛出 AttributeError。示例只处理 optional,就是为了保留对象的真实缺失语义。
钩子里的异常类型也影响行为。一个 property 的 getter 若内部抛出 AttributeError,普通属性访问可能进入 __getattr__,让真实的内部缺陷被误认为属性缺失。因此,不要将任意内部错误改写成 AttributeError;动态补救也不应无条件吞掉错误。定位时可以临时在隔离环境中直接调用默认读取入口,比较异常路径,但不要把调试技巧改成业务实现。
特殊方法还有一条边界:len(obj) 等隐式特殊方法调用通常从类型查找相应方法,不等价于任意一次 obj.__len__ 属性读取。给实例临时塞入 __len__ 往往不能改变 len(obj)。这服务于语言协议的稳定处理路径,也提醒我们不能把普通属性链泛化到所有语法操作。
7. 工程排查:观察访问,而不是反复打印对象
遇到属性值与字典不一致,先确认类型及 MRO,然后查看类上是否有描述符、property 或访问钩子。调试时直接执行 getattr 可能触发你正在排查的副作用;repr(obj) 也可能访问属性。对具有懒加载行为的对象,一次“打印看看”甚至可能发出数据库请求。
inspect.getattr_static 提供不触发常规动态查找的静态观察方式,可以帮助找到原始描述符。但它返回的可能是描述符对象,而不是业务值;它不是更快的业务属性读取替代品。工具的价值在于辨别存放位置和协议类型,不在于绕开对象规则取值。
缓存属性也要考虑失效。把计算结果写入实例字典,通常意味着后续可能不再执行原计算;输入状态更新时如果忘记删除缓存,读到的值会过时。数据描述符强制每次接管、非数据描述符允许缓存遮蔽,体现的是不同接口取舍,并不存在对所有属性都最优的策略。
当描述符持有外部状态映射时,强引用实例作为键可能延长实例生命周期。使用弱引用需要对象支持弱引用,而且不自动解决并发、容量或异常清理。这些问题应在第 18 篇的保留链模型中继续分析,不能把“换成弱引用”当通用修复。
7.1 setter 与 setattr 怎样配合
读取之外还要检查设置路径。普通赋值 obj.x = value 进入属性设置机制,类上若有相应数据描述符,就由它接管;否则通常写入实例的存储。重写 __setattr__ 的类可能在此前实施自己的策略。如果钩子直接写 vars(obj)[name] = value,它就可能绕过原本希望触发的 setter,造成“构造时校验、后续写入不校验”的不一致。
只是增加记录的钩子可以调用 object.__setattr__(self, name, value) 继续默认设置机制。描述符自身存储 _limit 时,若也调用普通设置语法,则又可能进入外层钩子;这是否合理取决于你的规则。示例直接使用实例字典,是为了明确将底层存储与对外 limit 接口区分。真实对象若没有实例字典,必须改用其支持的存储方式,不能把这个实现当成所有类型的通用模板。
删除也不是把字典键删掉这么简单。del obj.x 可以进入描述符的删除接口,或由 __delattr__ 调整行为;只读属性可能拒绝删除。若业务允许“恢复到默认值”,应设计明确方法或删除语义,不要通过删除内部键偶然触发未初始化错误。
7.2 slots 改变存储,不取代对象协议
__slots__ 允许类为指定属性声明存储,某些类因而不再有普通实例字典。它常用于限制意外字段并调整实例内存,但具体收益取决于字段、继承与实现。不给出真实测量就不能宣称每个对象节省固定字节,也不能认为所有派生实例都没有 __dict__。
槽属性本身通过相应描述符连接到存储。因此描述符并非只适用于框架的动态计算,它也能参与语言提供的字段访问。若某个基类或子类又引入实例字典,限制效果会改变;多重继承的实例布局也可能不兼容。选择 slots 前先明确是否需要动态字段、弱引用与序列化,再用目标类的实验验证。
由于本篇 Positive 依赖 vars(instance),它不能直接用于一个完全没有实例字典的 slots 类。这是示例的重要边界。把可复用校验器推广到所有类之前,要明确适用存储协议或设计独立的后端适配,而不是等到生产对象报错才补一串类型分支。
7.3 一次实际定位应该获得什么证据
可以在隔离环境中先使用静态观察找到类候选,记录候选类型是否提供设置或删除协议,再记录实例是否有同名项,最后用一次受控读取验证实际值。四项证据一起解释来源;仅输出 __dict__,或仅打印业务属性,都只显示链条的一端。
若 getter 触发数据库查询,应进一步记录查询次数与输入状态,比较首次和后续访问是否一致。缓存命中会改变执行路径,因此需要分别验证缓存空、缓存有值和底层状态更新三种情况。修复不能只证明“现在返回正确值”,还要证明更新与失效规则成立,异常不会被补救钩子误吞。
静态诊断也有边界:对象代理可能把属性转发给另一个目标,原始描述符不是最终存储的完整地图。此时需要继续追踪代理持有的目标与它的类型。不要通过猜测属性名称层层调用,优先查看代理公开协议和构造过程;每次动态读取都应意识到可能执行代码。这样才能将“值不在字典里”的现象解释成具体来源,而不是归为 Python 动态特性的笼统结果。
8. 进阶与面试
为什么 property 不能被同名实例字典值覆盖? 它通过数据描述符协议接管访问,默认读取优先于实例字典。没有 setter 表示拒绝设置,不代表降级成普通属性。
为什么方法可以被字符串覆盖? 普通函数是非数据描述符;实例同名值优先,绑定过程因此没有机会执行。下一步调用字符串才报错。
描述符必须存储实际数据吗? 不必,它可以计算、转发或从实例读取。管理多个实例时要明确状态归属;共享描述符里保存单一业务值会污染实例。
进一步读 CPython 的属性访问实现时,应带着顺序问题进入源码:类候选如何搜索、候选类型是否提供设置槽、实例存储何时读取、失败怎样传播。源码细节随版本改变,本文不把特定结构字段当作语言级保证。先用实验验证现象,再对照固定标签的实现,可以避免把函数名记忆误当成机制理解。
静态属性检查与缓存失效的边界
将候选优先级迁移到缓存与诊断副作用
把 Positive 换成 cached_property,共同结构仍是类候选与实例同名项竞争,变化的是候选协议与缓存回写。静态诊断用于看候选,动态读取用于取业务值,二者不应交换用途。第十二篇缓存改变函数调用路径,本篇缓存改变属性读取路径;在各自边界追踪被跳过的计算,才能解释命中后的副作用变化。
缓存失效实验用 inspect.getattr_static(不触发描述符的静态属性检查)读 cached_property,计算次数保持零;普通 getattr 后次数为一。修改底层列表后,缓存值仍为一,删除实例里的缓存属性后才重新计算为二。它不是缓存库替你跟踪了依赖,而是第一次计算后保存了结果。这里 getter 的计数是诊断副作用的直接证据,不能只凭“访问了一次属性”推断没有工作发生。Python inspect 文档也说明静态读取可能返回描述符对象而非最终值。
未初始化的描述符反例抛 KeyError,不是属性协议里的 AttributeError;hasattr 不会替你吞掉任意异常。修复类将“没有这项属性”转换成 AttributeError 后,hasattr 才返回假。独立能力任务:让底层数据更新后主动删除缓存,验收计算次数恰好增加一次;再证明静态检查不会增加次数。需要缓存请求结果时,继续对照装饰器与函数包装里的键与失效责任,二者解决的缓存生命周期不同。
9. 结尾
属性访问是一条可执行的协议链,查清描述符、实例值和访问钩子的优先级,才能判断值的来源及副作用。
- 数据描述符优先于实例同名值,普通函数属于可被遮蔽的非数据描述符。
- 校验逻辑与业务存储要分开,描述符共享不代表实例状态应该共享。
- 自定义钩子必须保留缺失语义并避免递归,昂贵属性应明确成本。