本文深入探讨了在使用 polars 的 `register_expr_namespace` 注册自定义命名空间时遇到的类型检查器错误问题。核心挑战在于 polars 的动态属性访问机制与 python 静态类型系统的冲突。文章提出了多种解决方案，包括建议 polars 官方添加 `__getattr__` 方法以改善类型提示，讨论了 pyright 的局限性，并详细展示了如何通过开发 mypy 插件实现对动态命名空间的全面静态类型检查，从而在保持代码严谨性的同时提升开发效率。
在使用 Polars 提供的 pl.api.register_expr_namespace 装饰器注册自定义表达式命名空间时，开发者常常会遇到来自 mypy 或 pyright 等静态类型检查器的错误提示。这些错误通常表现为 "Expr" has no attribute "your_namespace" 或 "Cannot access member 'your_namespace' for type 'Expr'"。
以下是一个典型的示例，展示了问题出现的情景：
import polars as pl
@pl.api.register_expr_namespace("greetings")
class Greetings:
def __init__(self, expr: pl.Expr):
self._expr = expr
def hello(self) -> pl.Expr:
return (pl.lit("Hello ") + self._expr).alias("hi there")
def goodbye(self) -> pl.Expr:
return (pl.lit("Sayōnara ") + self._expr).alias("bye")
# 在这里，类型检查器会报错
print(pl.DataFrame(data=["world", "world!", "world!!"]).select(
[
pl.all().greetings.hello(), # mypy/pyright: "Expr" has no attribute "greetings"
pl.all().greetings.goodbye(),
]
))运行 mypy checker.py 或 pyright checker.py 会得到类似的错误输出：
% mypy checker.py checker.py:19: error: "Expr" has no attribute "greetings" [attr-defined] Found 1 error in 1 file (checked 1 source file) % pyright checker.py /path/to/checker.py:19:18 - error: Cannot access member "greetings" for type "Expr" Member "greetings" is unknown (reportGeneralTypeIssues) 1 error, 0 warnings, 0 informations
这些错误迫使开发者不得不频繁使用 # type: ignore[attr-defined] 或其他抑制指令，这降低了类型检查的价值，并可能掩盖真正的类型问题。
Polars 的 API 注册机制本质上是一种动态属性访问。当您通过 @pl.api.register_expr_namespace("greetings") 注册一个命名空间时，pl.Expr 实例上会动态地添加一个名为 greetings 的属性。然而，Python 的静态类型系统和类型检查器在编译时无法预知这些动态添加的属性。
解决此问题的关键在于 Polars 内部的 polars.expr.expr.Expr 类需要显式地为类型检查器提供动态属性访问的提示。具体来说，在 TYPE_CHECKING 上下文中定义一个 __getattr__ 方法足以让类型检查器理解该类支持动态属性访问，从而抑制不必要的错误。
一个理想的解决方案是 Polars 库本身在 Expr 类中添加如下结构：
import typing
class Expr:
# ... 其他方法和属性 ...
if typing.TYPE_CHECKING:
def __getattr__(self, attr_name: str, /) -> typing.Any: ...这种模式在 mypy 和 pyright 中都有效，它告诉类型检查器，当访问一个未在类定义中显式声明的属性时，__getattr__ 方法会被调用，并且其返回值可以是 Any 类型。这可以有效解决因动态属性访问导致的 attr-defined 错误。我们建议向 Polars 开发者提交一个问题，请求他们在 Expr 类中为类型检查目的添加一个动态的 __getattr__ 定义。
对于 Pyright 而言，除了上述建议 Polars 官方修改 __getattr__ 外，目前没有像 Mypy 那样灵活的插件机制来处理此类动态行为。Pyright 社区的领导者此前曾表示对插件支持的保留态度。
这意味着在 Polars 官方未修改的情况下，Pyright 用户只能通过以下方式来抑制错误：
由于 Pyright 缺乏插件支持，目前无法实现像 Mypy 那样对动态注册命名空间进行静态类型检查的完整解决方案。
Mypy 提供了强大的插件机制，允许开发者扩展其类型检查能力，以适应复杂的动态代码模式。通过编写一个 Mypy 插件，我们可以实现对 Polars 动态注册命名空间的完全静态类型检查，不仅消除误报，还能捕获实际的类型错误。
通过 Mypy 插件，我们可以达到以下理想的类型检查效果：
import polars as pl
@pl.api.register_expr_namespace("greetings")
class Greetings:
def __init__(self, expr: pl.Expr):
self._expr = expr
def hello(self) -> pl.Expr:
return (pl.lit("Hello ") + self._expr).alias("hi there")
def goodbye(self) -> pl.Expr:
return (pl.lit("Sayōnara ") + self._expr).alias("bye")
# 经过插件处理后，以下代码将能正确识别类型错误
print(
pl.DataFrame(data=["world", "world!", "world!!"]).select(
[
pl.all().greetings.hello(),
pl.all().greetings.goodbye(1), # mypy: Too many arguments for "goodbye" of "Greetings" [call-arg]
pl.all().asdfjkl # mypy: `polars.expr.expr.Expr` object has no attribute `asdfjkl` [misc]
]
)
)在这个示例中，插件不仅允许 pl.all().greetings.hello() 通过类型检查，还能准确地指出 goodbye(1) 调用参数过多，以及 asdfjkl 这个不存在的属性。
为了实现 Mypy 插件，我们需要以下项目结构：
project/ mypy.ini # Mypy 配置文件，指定插件路径 mypy_polars_plugin.py # Mypy 插件的实现代码 test.py # 包含 Polars 代码的测试文件
1. mypy.ini 配置
在 mypy.ini 文件中，我们需要告诉 Mypy 加载我们的插件：
[mypy] plugins = mypy_polars_plugin.py
2. mypy_polars_plugin.py 插件代码
这个插件的核心思想是：
from __future__ import annotations
import typing_extensions as t
import mypy.nodes
import mypy.plugin
import mypy.plugins.common
if t.TYPE_CHECKING:
import collections.abc as cx
import mypy.options
import mypy.types
STR___GETATTR___NAME: t.Final = "__getattr__"
STR_POLARS_EXPR_MODULE_NAME: t.Final = "polars.expr.expr"
STR_POLARS_EXPR_FULLNAME: t.Final = f"{STR_POLARS_EXPR_MODULE_NAME}.Expr"
STR_POLARS_EXPR_REGISTER_EXPR_NAMESPACE_FULLNAME: t.Final = "polars.api.register_expr_namespace"
def plugin(version: str) -> type[PolarsPlugin]:
"""Mypy 插件的入口点。"""
return PolarsPlugin
class PolarsPlugin(mypy.plugin.Plugin):
"""Mypy 插件类，用于处理 Polars 动态命名空间注册。"""
_polars_expr_namespace_name_to_type_dict: dict[str, mypy.types.Type]
def __init__(self, options: mypy.options.Options) -> None:
super().__init__(options)
self._polars_expr_namespace_name_to_type_dict = {}
@t.override
def get_customize_class_mro_hook(
self, fullname: str
) -> cx.Callable[[mypy.plugin.ClassDefContext], None] | None:
"""
Mypy 要求 `__getattr__` 或 `__getattribute__` 存在，以便 `get_attribute_hook`
在动态属性上工作。此钩子为 `polars.expr.expr.Expr` 的类定义添加 `__getattr__`。
"""
if fullname == STR_POLARS_EXPR_FULLNAME:
return add_getattr
return None
@t.override
def get_class_decorator_hook_2(
self, fullname: str
) -> cx.Callable[[mypy.plugin.ClassDefContext], bool] | None:
"""
使 Mypy 识别 `@polars.api.register_expr_namespace(...)` 类装饰器工厂。
它积累了一个映射，其中包含 `polars.expr.expr.Expr` 实例上可访问的动态属性。
映射条目形如 `<namespace name>: <Namespace>`。
"""
if fullname == STR_POLARS_EXPR_REGISTER_EXPR_NAMESPACE_FULLNAME:
return self.polars_expr_namespace_registering_hook
return None
@t.override
def get_attribute_hook(
self, fullname: str
) -> cx.Callable[[mypy.plugin.AttributeContext], mypy.types.Type] | None:
"""
使 Mypy 理解，当从 `polars.expr.expr.Expr` 实例访问属性且该属性不存在时，
应查找通过 `get_class_decorator_hook_2` 积累的映射中的属性。
"""
if fullname.startswith(f"{STR_POLARS_EXPR_FULLNAME}."):
return self.polars_expr_attribute_hook
return None
def polars_expr_namespace_registering_hook(
self, ctx: mypy.plugin.ClassDefContext
) -> bool:
"""
使用装饰器工厂 `polars.api.register_expr_namespace(<namespace name>)`
注册稍后从 `polars.expr.expr.Expr` 实例访问的可用动态属性。
返回该类是否包含足够的信息以被视为语义分析。
"""
# 确保类装饰器表达式形如 `@polars.api.register_expr_namespace(<namespace name>)`
namespace_arg: str | None
if (
(not isinstance(ctx.reason, mypy.nodes.CallExpr))
or (len(ctx.reason.args) != 1)
or (
(namespace_arg := ctx.api.parse_str_literal(ctx.reason.args[0])) is None
)
):
# 如果装饰器工厂表达式无效，则提前返回。
return True
self._polars_expr_namespace_name_to_type_dict[
namespace_arg
] = ctx.api.named_type(ctx.cls.fullname)
return True
def polars_expr_attribute_hook(
self, ctx: mypy.plugin.AttributeContext
) -> mypy.types.Type:
"""
当访问 `polars.expr.expr.Expr` 实例上的属性时，查找已注册的命名空间。
如果属性不存在，则显示错误。
"""
assert isinstance(ctx.context, mypy.nodes.MemberExpr)
attr_name: str = ctx.context.name
namespace_type: mypy.types.Type | None = (
self._polars_expr_namespace_name_to_type_dict.get(attr_name)
)
if namespace_type is not None:
return namespace_type
else:
ctx.api.fail(
f"`{STR_POLARS_EXPR_FULLNAME}` object has no attribute `{attr_name}`",
ctx.context,
)
return mypy.types.AnyType(mypy.types.TypeOfAny.from_error)
def add_getattr(ctx: mypy.plugin.ClassDefContext) -> None:
"""
向给定的类定义添加一个 `__getattr__` 方法的类型提示。
"""
mypy.plugins.common.add_method_to_class(
ctx.api,
cls=ctx.cls,
name=STR___GETATTR___NAME,
args=[
mypy.nodes.Argument(
variable=mypy.nodes.Var(
name="attr_name", type=ctx.api.named_type("builtins.str")
),
type_annotation=ctx.api.named_type("builtins.str"),
initializer=None,
kind=mypy.nodes.ArgKind.ARG_POS,
pos_only=True,
)
],
return_type=mypy.types.AnyType(mypy.types.TypeOfAny.implementation_artifact),
self_type=ctx.api.named_type(STR_POLARS_EXPR_FULLNAME),
)3. test.py 测试文件
这个文件就是之前展示的 Polars 代码示例，用于验证插件是否按预期工作。
import polars as pl
@pl.api.register_expr_namespace("greetings")
class Greetings:
def __init__(self, expr: pl.Expr):
self._expr = expr
def hello(self) -> pl.Expr:
return (pl.lit("Hello ") + self._expr).alias("hi there")
def goodbye(self) -> pl.Expr:
return (pl.lit("Sayōnara ") + self._expr).alias("bye")
print(
pl.DataFrame(data=["world", "world!", "world!!"]).select(
[
pl.all().greetings.hello(),
pl.all().greetings.goodbye(1), # 此处 Mypy 会报错
pl.all().asdfjkl # 此处 Mypy 会报错
]
)
)运行 mypy test.py (确保在 project 目录下执行，或者 mypy --config-file mypy.ini test.py)，您将看到 Mypy 能够正确地识别 goodbye 方法的参数错误和 asdfjkl 属性的不存在，同时允许 greetings.hello() 通过。
处理 Polars 动态命名空间注册与类型检查器之间的冲突，需要理解动态属性访问的本质及其与静态类型系统的交互。
通过采取这些策略，开发者可以在享受 Polars 强大功能的同时，维护代码的类型安全性，提升开发体验和代码质量。
以上就是解决 Polars 动态命名空间注册的类型检查挑战的详细内容，更多请关注php中文网其它相关文章！
每个人都需要一台速度更快、更稳定的 PC。随着时间的推移，垃圾文件、旧注册表数据和不必要的后台进程会占用资源并降低性能。幸运的是，许多工具可以让 Windows 保持平稳运行。
广告Copyright 2014-2025 https://www.php.cn/ All Rights Reserved | php.cn | 湘ICP备2023035733号
211
收藏
