如何让Python ForwardRef支持含美元符号键的循环依赖类型提示？

要实现支持带美元符号键（如$and、$or）和循环依赖的MongoDB查询类型提示，可通过TypedDict构造函数+字符串形式的ForwardRef实现，搭配Pylance的类型检查配置即可正常工作。

方案1：Python 3.10+ 简化写法 #

利用Python 3.10引入的延迟类型注解特性（无需显式导入ForwardRef），直接用字符串引用自身类型：

from typing import TypedDict, Union, List

# 定义基础字段过滤规则（匹配普通键值对，如 {"name": "Alice"}）
FieldFilter = TypedDict("FieldFilter", {
    "name": str,
    "age": int,
    # 添加你的业务字段...
}, total=False)

# 定义包含MongoDB操作符的过滤规则，用字符串"Filter"实现循环引用
Filter = TypedDict("Filter", {
    "$and": List[Union['Filter', FieldFilter]],
    "$or": List[Union['Filter', FieldFilter]],
    "$eq": Union[str, int],
    "$gt": int,
    "$lt": int,
    # 添加其他MongoDB操作符...
}, total=False)

关键说明 #

• total=False：所有键均为可选，符合MongoDB查询的灵活结构。
• 字符串'Filter'：相当于隐式的ForwardRef，Pylance会自动解析为当前定义的Filter类型，完美处理循环依赖。
• 结合FieldFilter：同时支持普通字段匹配和操作符嵌套查询。

方案2：Python 3.7-3.9 兼容写法 #

对于旧版本Python，需显式使用ForwardRef并手动解析类型：

from typing import Union, List, ForwardRef
from typing_extensions import TypedDict

# 提前声明ForwardRef
FilterRef = ForwardRef("Filter")

# 基础字段过滤规则
FieldFilter = TypedDict("FieldFilter", {
    "name": str,
    "age": int,
}, total=False)

# 定义带操作符的Filter类型
Filter = TypedDict("Filter", {
    "$and": List[Union[FilterRef, FieldFilter]],
    "$or": List[Union[FilterRef, FieldFilter]],
    "$eq": Union[str, int],
}, total=False)

# 手动解析ForwardRef，让Pylance识别循环类型
Filter.__annotations__["$and"] = List[Union[Filter, FieldFilter]]
Filter.__annotations__["$or"] = List[Union[Filter, FieldFilter]]

Pylance配置要求 #

确保VS Code的settings.json中启用类型检查：

{
    "python.analysis.typeCheckingMode": "strict"
}

设为"basic"也能生效，但"strict"会提供更完整的类型提示和检查。

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