为何Pylance无法静态推断字典值的Literal Union类型？

我在编写to_ChatCompletionMessageParam()实例方法时，最初的实现如下：

def to_ChatCompletionMessageParam(self) -> ChatCompletionMessageParam:
    author: Literal["assistant", "user"] = self.author
    result: ChatCompletionMessageParam = {
        "role": author,
        "content": self.item.value()
    }

    ...

    return result

ChatCompletionMessageParam是多个TypedDict的联合类型，可转换为普通字典字面量，每个联合类型都包含必填的Literal类型字段role，其定义示例如下：

from typing import TypeAlias, Union, TypedDict, Required, Literal, Iterable

ChatCompletionMessageParam: TypeAlias = Union[ChatCompletionUserMessageParam, ChatCompletionAssistantMessageParam]

class ChatCompletionUserMessageParam(TypedDict, total=False):
    content: Required[Union[str, Iterable["ChatCompletionContentPartParam"]]]
    """用户消息的内容。"""

    role: Required[Literal["user"]]
    """消息作者的角色，此处为`user`。"""

    # 省略其他字段
    ...

class ChatCompletionAssistantMessageParam(TypedDict, total=False):
    role: Required[Literal["assistant"]]
    """消息作者的角色，此处为`assistant`。"""

    content: Union[str, Iterable["ContentArrayOfContentPart"], None]
    """助手消息的内容。

    除非指定了`tool_calls`或`function_call`，否则为必填项。
    """

    # 省略其他字段
    ...

目前我只能通过显式的Literal分支检查才能让类型校验通过，代码如下：

def to_ChatCompletionMessageParam(self) -> ChatCompletionMessageParam:
    author: Literal["assistant", "user"] = self.author

    if author == "assistant":
        result: ChatCompletionMessageParam = {
            "role": author,
            "content": self.item.value()
        }
    else:
        result: ChatCompletionMessageParam = {
            "role": author,
            "content": self.item.value()
        }
    return result

想问这是Pylance的bug，还是简化代码中存在它无法排除的特定边缘情况？

TL;DR：创建需要匹配包含必填Literal字段的多字典联合类型的字典字面量时，Pylance无法验证提供的值是否符合类型要求。

这不是Pylance的bug，而是静态类型检查器处理联合类型时的固有局限性。

当你直接用Literal["assistant", "user"]类型的变量author构建字典时，Pylance在静态分析阶段无法确定author的具体取值——尽管它的类型是两个字面量的联合，但类型检查器无法推断出这个变量的取值会严格匹配联合类型中某一个TypedDict的role字段要求。

具体来说，ChatCompletionMessageParam是两个TypedDict的联合，每个TypedDict的role都是固定的字面量类型。当你用一个联合类型的变量赋值给role时，类型检查器无法确认该变量的实际值恰好对应其中某一个TypedDict的role约束，因此会抛出类型不兼容的错误。

而通过显式的if/else分支检查后，类型检查器可以在每个分支中窄化author的类型：在author == "assistant"的分支里，author会被推断为Literal["assistant"]，此时构建的字典会匹配ChatCompletionAssistantMessageParam；同理，else分支会匹配ChatCompletionUserMessageParam，类型校验自然通过。

这种情况属于类型检查器处理依赖运行时值的类型匹配时的常规限制，并非Pylance的缺陷。

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