Pandas 2.2.0中DataFrame.query()无法通过@访问类变量的问题

为什么会报错？ #

Pandas 2.2.0对DataFrame.query()的变量解析逻辑做了收紧调整：

• 在1.4.0及更早版本，@后面的链式表达式（比如@i.j）会直接在全局/局部命名空间里完整解析——先找到类i，再取它的类变量j。
• 但2.2.0之后，@只能绑定单个直接变量（比如实例m、局部定义的普通变量）。解析器会把@后的第一个标识符（这里是i）当成要找的变量名，但类对象默认不在query()的解析作用域里，所以就抛出了KeyError: 'i'。

这个调整主要是为了减少命名冲突，同时让query()的变量解析逻辑更简单、高效。

官方文档相关说明 #

这个变化是Pandas 2.2.0针对计算模块的核心改进之一：

• 在2.2.0的发布说明里，「Computation improvements」部分明确提到，优化了query()和eval()的作用域处理规则，仅允许@引用直接可访问的变量，不再支持链式调用里直接引用类或模块级别的对象。
• 查看pandas.core.computation.scope模块的更新记录，新版本调整了变量收集逻辑，只把局部/全局命名空间里的实例、基本数据类型这类“直接可引用”的对象加入解析器，类对象默认被排除在外。

符合你需求的替代方案 #

不想实例化类或者用f-string拼查询语句的话，可以把类变量赋值给一个局部变量，再用@引用这个变量：

import seaborn as sns
tips = sns.load_dataset('tips')

class i:
    j = 5

# 把类变量转成局部变量
target_size = i.j
tips.query("size == @target_size")  # 正常运行

内容的提问来源于stack exchange，提问作者Mani