Python类型提示中如何要求含无效标识符键的键值对？

问题背景 #

处理JSON传递的字典载荷时，常会遇到1req、class这类不符合Python标识符规则的键。需要通过类型提示让mypy、pyright等静态分析工具及IDE识别这些键为必填项，同时满足额外属性、已知可选键的类型约束——普通TypedDict或Mapping无法覆盖全部需求。

核心需求 #

• 必填有效标识符键a，类型为int；
• 必填无效标识符键1req，类型为str；
• 允许传入其他字符串键作为额外属性，值必须为list；
• 支持n个含无效标识符的必填键；
• 支持已知可选键（如b，类型为float），这类键值类型固定且为已知字面量；
• 静态分析工具需对无效输入（如缺少必填键、额外属性类型错误）抛出明确错误。

解决方案实现 #

利用Python 3.11+（或typing_extensions库）的TypedDict特性，结合字符串字面量定义无效标识符键、NotRequired标记可选键、__extra_items__约束额外属性类型，完全满足所有需求：

from typing import TypedDict, NotRequired, Any

class Payload(TypedDict):
    # 必填有效标识符键
    a: int
    # 必填无效标识符键：用字符串字面量直接定义
    '1req': str
    # 已知可选键：用NotRequired标记，值类型固定
    b: NotRequired[float]
    # 额外属性约束：所有未显式定义的键必须是字符串类型，值必须为list
    __extra_items__: str, list[Any]

def process_payload(payload: Payload) -> None:
    # 业务处理逻辑示例
    print(f"必填键a: {payload['a']}, 必填键1req: {payload['1req']}")
    if 'b' in payload:
        print(f"可选键b: {payload['b']}")

版本兼容说明 #

若使用Python 3.10及以下版本，需安装typing_extensions库，并导入对应类型：

from typing_extensions import TypedDict, NotRequired, Any

class Payload(TypedDict, extra='allow'):
    a: int
    '1req': str
    b: NotRequired[float]
    # 额外属性类型约束需结合Mapping做交叉类型
    __extra_items__: str, list[Any]

验证示例 #

合法调用（无错误） #

process_payload({
    'a': 1,
    '1req': 'blah',
    'someAdditionalProp': [],
    'b': 3.14
})

无效调用（静态分析报错） #

1. 额外属性值类型错误

process_payload({
    'a': 1,
    '1req': 'blah',
    'someAdditionalProp': None  # 静态检查提示：None无法赋值给list[Any]
})

预期错误提示（pyright）：

Argument of type "dict[str, int | str | None]" cannot be assigned to parameter "payload" of type "Payload"
  Type "None" cannot be assigned to type "list[Any]" for key "someAdditionalProp"

2. 缺少必填无效标识符键

process_payload({
    'a': 1,
    'someAdditionalProp': []  # 静态检查提示：缺少必填键'1req'
})

预期错误提示（mypy）：

Argument 1 to "process_payload" has incompatible type "dict[str, int | list[Any]]"; expected "Payload"
  "dict[str, int | list[Any]]" is missing required key "'1req'"

方案优势 #

• 直接支持无效标识符的必填键定义，无需额外绕路；
• 精确约束额外属性的类型，避免宽泛的Union导致的类型不安全；
• 清晰区分已知可选键与任意额外属性；
• 完全兼容主流静态分析工具（mypy、pyright）及IDE类型检查。

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