一天一个冷知识:Python 类体里的名字,能被"凭空造出来"
摘要:在类体里写 total = GLOBAL + missing,GLOBAL 明明是 999,结果却是 0,而且不报错。谜底藏在三个地方:类体作用域、LOAD_NAME 的回退规则、元类的 __prepare__。本文先复现这个反直觉现象,再拆开字节码和命名空间,最后用它做一个正经功能:让字段声明支持自引用与前向引用,并附上四个必须知道的坑。
验证环境:CPython 3.12.3。文中所有输出都是实际运行结果。
一、一个不该成立的类
先看一段奇奇怪怪的代码,但按常识不该跑的代码:
class Zero(dict):
def __missing__(self, key):
return 0
class ZeroMeta(type):
@classmethod
def __prepare__(mcls, name, bases, **kwds):
return Zero()
GLOBAL = 999
class C(metaclass=ZeroMeta):
total = GLOBAL + missing
print(C.total) # 0
print(C.__module__) # 0
两个地方不对:
GLOBAL是 999,missing压根没定义。按常识,这行要么抛NameError,要么至少用上 999。结果是 0。C.__module__不是"__main__",也是 0。
原因不复杂,但需要把类体的执行方式拆开看:
- 类体里读名字时,解释器先问"类体自己的命名空间"。
Zero.__missing__对任何键都返回 0,于是GLOBAL和missing都拿到了 0,模块全局变量根本没被查询。 - 类体的第一条语句是
__module__ = __name__。__name__同样被 0 截胡,所以C.__module__是 0。
也就是说,命名空间不仅能在名字不存在时"补一个值",它的优先级还高于 globals。这不是 bug,而是 LOAD_NAME 的规则决定的。
二、类体不是函数:LOAD_NAME 的三级回退
把类体单独编译出来看字节码:
python
import dis, types
src = "class C:\n x = 1\n y = x + 1\n"
module = compile(src, "demo.py", "exec")
class_code = next(c for c in module.co_consts if isinstance(c, types.CodeType)) dis.dis(class_code)
输出:
text
1 0 RESUME 0 2 LOAD_NAME 0 (__name__) 4 STORE_NAME 1 (__module__) 6 LOAD_CONST 0 ('C') 8 STORE_NAME 2 (__qualname__) 2 10 LOAD_CONST 1 (1) 12 STORE_NAME 3 (x) 3 14 LOAD_NAME 3 (x) 16 LOAD_CONST 1 (1) 18 BINARY_OP 0 (+) 22 STORE_NAME 4 (y) 24 RETURN_CONST 2 (None)
关键在
LOAD_NAME / STORE_NAME 这对指令:类体没有用函数里的 LOAD_FAST,也没有用 LOAD_GLOBAL,而是走"按名字查命名空间"的路径。规则可以概括成三步:
- 先查类体的命名空间(一个 mapping),命中就返回;
- 只有查不到、并且抛出的异常是
KeyError时,才去查模块 globals; - globals 也没有,再查 builtins。
如果第 1 步抛出的是别的异常,解释器不会回退,而是直接把异常交给调用方:
python
class Boom(dict):
def __getitem__(self, key):
if key == "trap":
raise ValueError("不是 KeyError")
return super().__getitem__(key)
class BoomMeta(type):
@classmethod
def __prepare__(mcls, name, bases, **kwds):
return Boom()
try:
class Bad(metaclass=BoomMeta):
v = trap
except ValueError as e:
print(type(e).__name__, e) # ValueError 不是 KeyError
这个细节很重要:KeyError 是"这个名字不存在"的唯一信号。所以只要在命名空间里让缺失的键返回一个值(__missing__ 或自定义 __getitem__ 都行),就等于告诉解释器"这个名字存在",globals 和 builtins 都不会再查。第一节里的 0 就是这么来的。
顺带对比一下函数作用域,差异更清楚:
python
X = 5
class D:
x = X # 类体:命名空间没有 x,回退到 globals,拿到 5
try:
class E:
y = y # 类体:NameError,而不是 UnboundLocalError
except NameError as e:
print(e) # name 'y' is not defined
def f():
z = z # 函数:UnboundLocalError
try:
f()
except UnboundLocalError as e:
print(e)
函数里,名字被赋值就意味着它是局部变量,读之前必须先绑定;类体没有这个约束,它只是一段在临时 mapping 里执行的代码。
同一个原因还导致另一个常见现象:类体里的推导式看不到类命名空间。
python
try:
class F:
a = 1
b = [a for _ in range(1)]
except NameError as e:
print(e) # name 'a' is not defined
推导式有自己的作用域,类作用域不参与闭包,所以元素表达式里的 a 只能去 globals / builtins 找。
三、命名空间是谁给的:__prepare__
类体的那个 mapping 不是凭空来的,它由元类的 __prepare__ 提供;没有定义就用一个空 dict。整个类的创建顺序可以直接打印出来:
python
class Spy(dict):
def __getitem__(self, key):
print(" read ", key)
return super().__getitem__(key)
def __setitem__(self, key, value):
print(" write", key)
super().__setitem__(key, value)
def __delitem__(self, key):
print(" del ", key)
super().__delitem__(key)
class Meta(type):
@classmethod
def __prepare__(mcls, name, bases, **kwds):
print("prepare:", name, kwds)
return Spy()
def __new__(mcls, name, bases, ns, **kwds):
print("new:", kwds)
return super().__new__(mcls, name, bases, ns)
def __init__(cls, name, bases, ns, **kwds):
print("init:", kwds)
super().__init__(name, bases, ns)
class X(metaclass=Meta, flag=1):
a = 1
b = a + len("hi")
del b
print("X.a =", X.a, "| has b?", hasattr(X, "b"))
输出:
text
prepare: X {'flag': 1} read __name__ write __module__ write __qualname__ write a read a read len write b del b new: {'flag': 1} init: {'flag': 1} X.a = 1 | has b? False
从输出可以确认几件事:
__prepare__在类体执行之前调用,此时name、bases、类关键字参数都已经确定,但类对象还不存在。- 类体的每一步读写都走 mapping 协议:赋值是
STORE_NAME→__setitem__,读取是LOAD_NAME→__getitem__,del是DELETE_NAME→__delitem__。这些名字不是通过setattr加到类上的——类还没创建。 len在命名空间里不存在,__getitem__抛KeyError,于是回退到 builtins。- 类体执行完,才轮到元类的
__new__和__init__。
三个契约细节,实测比文档写得更严格:
python
import collections
class MetaPlain(type):
def __prepare__(mcls, name, bases, **kwds): # 少了 @classmethod
return {}
try:
class A(metaclass=MetaPlain):
pass
except TypeError as e:
print(e) # MetaPlain.__prepare__() missing 1 required positional argument: 'bases'
class MetaMap(type):
@classmethod
def __prepare__(mcls, name, bases, **kwds):
return collections.UserDict() # 是 mapping,但不是 dict
try:
class B(metaclass=MetaMap):
pass
except TypeError as e:
print(e) # type.__new__() argument 3 must be dict, not UserDict
__prepare__必须写成@classmethod(或@staticmethod并自己处理参数)。普通方法会因参数错位直接报错。- 文档把返回值描述为 mapping,但 CPython 3.12.3 的
type.__new__实际只接受 dict 及其子类。稳妥做法:继承dict。 - 类关键字参数不是免费的。
__prepare__收到之后,__new__/__init__/__init_subclass__里必须有人消费;都不接就会报X.__init_subclass__() takes no keyword arguments。
另外,__annotations__ 和方法里用到的 __classcell__ 也是通过 STORE_NAME 写进这个命名空间的。这决定了下一节的坑:自定义命名空间不能乱改键。
四、正经用法:让字段声明支持前向引用
声明式模型里经常有"字段引用字段"的需求:自引用(boss 指向自己)、前向引用(引用后面才定义的字段)。常见写法是塞字符串,比如 Field(ref="boss")。字符串没有补全、没有重命名支持,拼错了只能等运行时。既然类体的名字查找可以被介入,就可以直接写名字:
python
class Ref:
"""占位符:只记住名字,等类体执行完再解析。"""
__slots__ = ("name",)
def __init__(self, name):
self.name = name
class LazyNamespace(dict):
def __init__(self):
super().__init__()
self.refs = {}
def __missing__(self, key):
# 双下划线名字要回退到模块全局
if key.startswith("__"):
raise KeyError(key)
# 模块全局里已有的名字(Field、Ref……)也要回退
if key in globals():
raise KeyError(key)
if key not in self.refs:
self.refs[key] = Ref(key)
return self.refs[key]
class ModelMeta(type):
@classmethod
def __prepare__(mcls, name, bases, **kwds):
return LazyNamespace()
class Model(metaclass=ModelMeta):
pass
class Field:
def __init__(self, ref=None):
self.ref = ref
self.name = None
def __set_name__(self, owner, name):
self.name = name
if not isinstance(self.ref, Ref):
return
try:
target = owner.__dict__[self.ref.name]
except KeyError:
raise TypeError(f"{owner.__name__}.{name}: 未知字段 {self.ref.name!r}") from None
if not isinstance(target, Field):
raise TypeError(f"{owner.__name__}.{name}: {self.ref.name!r} 不是字段")
self.ref = target
def __repr__(self):
return f"<Field {self.name} ref={getattr(self.ref, 'name', None)}>"
class User(Model):
id = Field()
name = Field()
boss = Field(ref=boss) # 自引用:boss 还没赋值
mentor = Field(ref=name) # 后向引用:name 已经定义
print(User.id, User.name, User.boss, User.mentor)
print(User.boss.ref is User.boss, User.mentor.ref is User.name)
输出:
text
<Field id ref=None> <Field name ref=None> <Field boss ref=boss> <Field mentor ref=name> True True
这段代码的关键只有三处:
__missing__只在"命名空间没有、不是双下划线、也不在模块 globals"时造一个Ref。后两个条件都是为了不破坏正常回退:双下划线名字要能落到模块全局,Field、Ref这些全局名字也必须还能被找到。Ref存在独立的refs表里,不写回命名空间。这一点不是洁癖:如果写回self[key] = ref,占位符会跟着变成类属性,后面__set_name__去owner.__dict__里查时反而能"查到",拼写检查直接失效。- 解析放在
Field.__set_name__里。__set_name__是type.__new__内部调用的,此时owner.__dict__已经包含类体定义的全部名字,所以后向引用也能解析。
拼错名字和引用错对象都会在类创建阶段报出来,而不是运行时才发现:
python
try:
class Bad(User):
friend = Field(ref=nmae)
except TypeError as e:
print(e) # Bad.friend: 未知字段 'nmae'
try:
class Bad2(User):
friend = Field(ref=later)
def later(self):
return 1
except TypeError as e:
print(e) # Bad2.friend: 'later' 不是字段
这段代码本身不值得拿去造 ORM,它的价值在于说明:类体命名空间是类体执行期间唯一可介入的钩子。字段收集、定义顺序记录、重复定义检查、DSL 语法支持,都可以在这个阶段做。
五、四个坑
1. 双下划线名字必须放过
第一节已经看到后果:__name__ 被截胡,C.__module__ 变成 0。更严重的是 __classcell__。如果命名空间的 __setitem__ 把双下划线键丢掉,方法里的零参 super() 会直接崩:
python
class DropDunder(dict):
def __setitem__(self, key, value):
if key.startswith("__"):
return
super().__setitem__(key, value)
class DunderMeta(type):
@classmethod
def __prepare__(mcls, name, bases, **kwds):
return DropDunder()
try:
class Z(metaclass=DunderMeta):
def hello(self):
return super().hello()
except RuntimeError as e:
print(e)
# __class__ not set defining 'Z' as <class '__main__.Z'>.
# Was __classcell__ propagated to type.__new__?
__classcell__ 是编译器生成的 cell 对象,type.__new__ 靠它把 __class__ 绑定到新类上。丢掉它,零参 super() 就失去了类上下文。
2. 模块全局名字必须放过
__missing__ 一旦对任意键都返回值,globals 回退就被短路了。下面的元类看起来无害,实际连"调用一个全局函数"都做不到:
python
class LooseNS(dict):
def __missing__(self, key):
return "PLACEHOLDER"
class LooseMeta(type):
@classmethod
def __prepare__(mcls, name, bases, **kwds):
return LooseNS()
def make_field():
return lambda: "field"
try:
class W(metaclass=LooseMeta):
f = make_field()
except TypeError as e:
print(e) # 'str' object is not callable
make_field 在 globals 里,但命名空间先回答了 "PLACEHOLDER",于是它变成了一个字符串,再加括号就报 'str' object is not callable。这也是第四节里必须写 key in globals() 的原因。
3. 命名空间会被复制,不是类字典
__prepare__ 返回的对象只在类体执行期间充当 locals。类创建完成后,类属性被放进一份新的 dict,类的 __dict__ 只是它的只读视图:
python
class Keep(type):
@classmethod
def __prepare__(mcls, name, bases, **kwds):
ns = {}
Keep.ns = ns
return ns
class K(metaclass=Keep):
a = 1
Keep.ns["b"] = 2
print(K.__dict__ is Keep.ns) # False
print(hasattr(K, "b")) # False
print(type(K.__dict__)) # <class 'mappingproxy'>
需要保留的信息(字段顺序、占位符表、读取记录)要在 __new__ / __init__ 里主动取走,不能指望事后改命名空间还能影响类。
4. 占位符会掩盖拼写错误
这是最容易被忽略的一条。__missing__ 的副作用是"任何未知名字都合法",如果没有收尾校验,拼错的字段名会安静地变成一个 Ref,错误被推迟到很远的地方。第四节的写法之所以可靠,是因为 __set_name__ 会对每个 Ref 做一次解析,并且区分"未知字段"和"不是字段"两种错误。
换句话说:这个机制的能力和风险是同一个东西。它让"未定义"变成"已定义",你就必须自己补上"什么时候算真的未定义"。
六、什么时候该用
- 写框架、写声明式 DSL、写代码生成工具:这是合理工具。类体命名空间是标准化钩子,比改 AST 便宜得多。
- 普通业务代码:不要为了少写一对引号去动
__missing__。它会把NameError变成静默行为,调试成本远高于收益。 - 真要用:像第四节那样,把"造名字"限制在明确的语法位置(只在类体里、只对非全局名),并且在类创建结束前做全量校验。
最后回到开头那个 0:它不是解释器抽风,而是三条规则叠加的必然结果——类体用 LOAD_NAME 查一个可替换的 mapping;只有 KeyError 才算未命中;而 __prepare__ 允许你换掉这个 mapping。把这三件事串起来,__prepare__、__set_name__、__init_subclass__ 这些钩子的行为就不再神秘了。