PAYATHON 2026

Pyright 为何不报告 Any 传给 Message 参数?

数据小陈

结论

Pyright 不报错,是因为 json.loads 的类型签名返回 Any,而 Any 在类型系统里与任何类型都兼容。调用 await handler.put(msg) 时,msg 被推断为 Any,Pyright 不会拿 Message 去严格检查它。运行时 json.loads(b'1010') 拿到的是整数 1010,并不是 Message 实例。问题出在运行时数据校验,静态类型检查发现不了。

原因

  1. typeshed 中 json.loads 的返回类型是 Any,而 Any 会绕过后续的类型检查。
  2. Message 是普通 dataclass,不会自动把 JSON 数字或字典转换成 Message 实例。
  3. Pyright/Pylance 只做静态分析,不会执行 json.loads,也不知道 b'1010' 解析后的具体 Python 类型。除非你用类型收窄或显式校验把类型信息告诉它。
  4. cast(Message, ...) 只会改变静态类型,不会做运行时检查。

解决步骤

  1. 不要把 json.loads 的结果直接传给要求 Message 的方法。
  2. 写一个解析函数,检查 JSON 结构并显式构造 Message。
  3. 让解析函数返回 Message,这样调用 put 时类型就明确了。
  4. 如果数据来自不可信输入,保留运行时校验,不要只依赖 cast。

代码示例

import asyncio
import json
from dataclasses import dataclass
from typing import Any

@dataclass(frozen=True, slots=True)
class Message:
    sender: str
    msg_type: str

def parse_message(raw: bytes) -> Message:
    data: Any = json.loads(raw)
    if not isinstance(data, dict):
        raise ValueError('Message must be a JSON object')
    sender = data.get('sender')
    msg_type = data.get('msg_type')
    if not isinstance(sender, str) or not isinstance(msg_type, str):
        raise ValueError('sender and msg_type must be strings')
    return Message(sender=sender, msg_type=msg_type)

class MessageHandler:
    _messages: asyncio.Queue[Message]

    def __init__(self) -> None:
        self._messages = asyncio.Queue()

    async def put(self, msg: Message) -> None:
        await self._messages.put(msg)

async def main() -> None:
    handler = MessageHandler()
    msg = parse_message(b'1010')
    await handler.put(msg)

asyncio.run(main())

这段代码会在 parse_message 中抛出 ValueError,因为 b'1010' 解析出来是数字,不是包含 sender 和 msg_type 的对象。要传入合法消息,应使用符合结构的 JSON 数据,或直接在代码中构造 Message。

如果只是想让类型检查器不再报错,可以写成下面这样:

from typing import cast

msg = cast(Message, json.loads(b'1010'))
await handler.put(msg)

不过运行时 msg 仍然是 1010,后面访问 msg.sender 会失败。cast 只做类型断言,修不了运行时问题。

注意事项

  • Any 是设计上的动态逃逸口,不是 Pyright 的 bug。
  • 开启更严格的类型检查有帮助,但不能替代运行时数据校验。
  • 对 JSON 输入,建议使用显式解析函数、TypedDict 加校验,或者 pydantic 这类数据校验库。
  • 类型注解只影响静态检查,不影响 Python 运行时行为。

备注:内容仅供参考。