如何告知类型检查器：特定read_json_file调用将返回列表？

我编写了一个读取JSON文件的函数read_json_file，其返回类型为Union[dict, list]，具体返回字典还是列表取决于文件内容：

from typing import Union
import json

def read_json_file(filename)->Union[dict, list]:
    with open(filename) as f:
        return json.load(f)

当我用该函数读取一个已知内容为列表的JSON文件，并在返回类型为list的函数get_name_list中调用它时：

def get_name_list()->list:
    return read_json_file("name_list.json")        # 存在问题的行

静态类型检查器pyright报错，提示read_json_file可能返回dict，但get_name_list必须返回list。我尝试过三种方案但都不满意：为read_json_file添加ensure_type参数（无效）、用TypeVar定义泛型返回类型（可读性差）、用#type:ignore忽略检查（不够理想）。

以下是几种更优的解决方案，能让类型检查器知晓该特定调用将返回列表：

方案1：使用类型断言（带运行时验证） #

通过assert语句在运行时验证返回类型，同时给类型检查器明确的类型提示：

def get_name_list()->list:
    data = read_json_file("name_list.json")
    assert isinstance(data, list), "name_list.json内容不是列表"
    return data

这个方案既满足静态类型检查要求，又能在实际运行时捕获类型不匹配的错误，安全性更高。

方案2：用cast显式声明类型 #

若不需要运行时验证，可使用typing.cast直接告知类型检查器返回的是列表：

from typing import cast, Union
import json

def read_json_file(filename)->Union[dict, list]:
    with open(filename) as f:
        return json.load(f)

def get_name_list()->list:
    return cast(list, read_json_file("name_list.json"))

cast仅作用于静态类型检查阶段，不会对运行时行为产生任何影响。

方案3：函数重载（针对特定文件名） #

如果已知特定文件名对应固定的返回类型，可以用typing.overload为函数定义重载签名，让类型检查器根据文件名字面量推断返回类型：

from typing import Union, overload, Literal
import json

@overload
def read_json_file(filename: Literal["name_list.json"]) -> list: ...

@overload
def read_json_file(filename: str) -> Union[dict, list]: ...

def read_json_file(filename):
    with open(filename) as f:
        return json.load(f)

def get_name_list()->list:
    return read_json_file("name_list.json")  # 类型检查器会识别为返回list

这种方式适合有明确对应关系的固定文件名场景，类型推断更精准。

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