如何为自定义namedtuple设置函数返回类型？

我有一个可能包含任意数量参数的sample_config.json文件，示例内容如下：

{
  "tableA_ID": "tableA.csv",
  "tableB_ID": "tableB.csv",
  "time_period" : 10,
  "start_date": "2024-07-01",
  "optimization_metric": "L1",
  "id": 353
}

目前示例中有6个键值对，但实际可能包含更多。我编写了一个辅助函数读取该JSON文件，并将其转换为名为ConfigTuple的自定义namedtuple：

import json
from collections import namedtuple
from pathlib import Path

def get_config_namedtuple(config_path: str | Path) -> ConfigTuple:
    config_path = Path(config_path)
    with open(f"{config_path}") as f:
        config = json.load(f)
        ConfigTuple = namedtuple("ConfigTuple", config)
    return ConfigTuple(**config)

该函数可以正常使用，示例代码如下：

config_path = Path("sample_config.json")
config = get_config_namedtuple(config_path=config_path)
# 使用namedtuple
print(f"{config.tableB_ID=}")

运行后会输出tableB.csv，但函数签名中的返回类型标注-> ConfigTuple会触发LSP错误，提示“ConfigTuple未定义”。这是因为该类型定义在函数体内而非全局作用域。我需要优雅的修复方案，让返回类型ConfigTuple被正确识别，同时适配任意键数量的JSON对象，且希望返回类型能被正确解析，而非忽略类型错误。

方法1：使用TypedDict结合SimpleNamespace（推荐） #

TypedDict可以动态生成匹配JSON结构的类型注解，配合SimpleNamespace实现点访问，同时让LSP正确识别类型：

import json
from pathlib import Path
from typing import TypedDict
from types import SimpleNamespace

def get_config(config_path: str | Path) -> SimpleNamespace:
    config_path = Path(config_path)
    with open(config_path) as f:
        config = json.load(f)
    
    # 动态生成对应JSON结构的TypedDict，辅助静态类型检查
    ConfigDict = TypedDict("ConfigDict", {k: type(v) for k, v in config.items()})
    # 转换为SimpleNamespace支持点访问
    return SimpleNamespace(**config)

这种方式既保留了点访问的便利性，又能让静态检查工具识别配置字段的类型，同时避免了类型未定义的错误。

方法2：用Protocol定义动态访问协议 #

通过Protocol定义一个支持任意属性访问的类型协议，让LSP识别返回值的访问特性：

import json
from collections import namedtuple
from pathlib import Path
from typing import Protocol, Any

class ConfigProtocol(Protocol):
    def __getattr__(self, name: str) -> Any: ...

def get_config_namedtuple(config_path: str | Path) -> ConfigProtocol:
    config_path = Path(config_path)
    with open(config_path) as f:
        config = json.load(f)
        ConfigTuple = namedtuple("ConfigTuple", config)
    return ConfigTuple(**config)

该方案保留了namedtuple的不可变特性，同时让LSP不再报错，且能识别返回值支持任意属性的点访问。

方法3：全局占位类型配合TYPE_CHECKING #

如果坚持使用namedtuple，可以在全局作用域为类型检查工具声明占位类型，运行时使用函数体内生成的真实类型：

import json
from collections import namedtuple
from pathlib import Path
from typing import TYPE_CHECKING

# 仅在静态类型检查阶段生效的占位类型
if TYPE_CHECKING:
    ConfigTuple = namedtuple("ConfigTuple", [])

def get_config_namedtuple(config_path: str | Path) -> "ConfigTuple":
    config_path = Path(config_path)
    with open(config_path) as f:
        config = json.load(f)
        ConfigTuple = namedtuple("ConfigTuple", config)
    return ConfigTuple(**config)

这种方式既解决了LSP的类型未定义错误，又不影响运行时的实际逻辑。

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