如何为Python只读模块添加对应返回类型的全局类型提示？

假设get_current_payment_settings()返回的是一个PaymentSettings类实例（比如用dataclass定义的配置类），可以通过以下几种方式实现模块级的类型提示：

方法1：模块级别声明属性类型 #

直接在payment_settings.py中，针对PaymentSettings的每个字段添加类型注解，配合TYPE_CHECKING避免运行时导入问题：

# src/payment_settings.py
from typing import TYPE_CHECKING, Any
from utils.payment import get_current_payment_settings

if TYPE_CHECKING:
    from utils.payment import PaymentSettings

def __getattr__(name: str) -> Any:
    settings = get_current_payment_settings()
    return getattr(settings, name)

def __setattr__(name: str) -> None:
    raise NotImplementedError("payment_settings is read-only")

# 声明与PaymentSettings一致的属性类型
if TYPE_CHECKING:
    something: str
    # 这里添加PaymentSettings的所有其他字段及其类型

这种方式简单直接，类型检查器（如mypy、Pyright）会识别这些模块级属性，在使用payment_settings.something时提供正确的类型提示。

方法2：复用PaymentSettings的注解 #

如果PaymentSettings的字段较多，手动复制类型太繁琐，可以直接复用类的__annotations__：

# src/payment_settings.py
from typing import TYPE_CHECKING, Any
from utils.payment import get_current_payment_settings

def __getattr__(name: str) -> Any:
    settings = get_current_payment_settings()
    return getattr(settings, name)

def __setattr__(name: str) -> None:
    raise NotImplementedError("payment_settings is read-only")

if TYPE_CHECKING:
    from utils.payment import PaymentSettings
    # 复制PaymentSettings的字段注解到模块
    __annotations__.update(PaymentSettings.__annotations__)

这样模块会自动继承PaymentSettings的所有字段类型，无需手动维护。

方法3：用类型断言告知检查器模块类型 #

通过cast告诉类型检查器，当前模块的类型等价于PaymentSettings：

# src/payment_settings.py
from typing import TYPE_CHECKING, cast
from utils.payment import get_current_payment_settings

if TYPE_CHECKING:
    from utils.payment import PaymentSettings
    # 让类型检查器将模块视为PaymentSettings实例
    __getattr__ = cast(PaymentSettings, lambda name: ...)

def __getattr__(name: str):
    settings = get_current_payment_settings()
    return getattr(settings, name)

def __setattr__(name: str) -> None:
    raise NotImplementedError("payment_settings is read-only")

这种方式无需声明每个字段，适合希望完全复用PaymentSettings类型的场景。

注意事项 #

• 确保get_current_payment_settings()的返回值已经有明确的类型注解（比如-> PaymentSettings）。
• 以上方法仅作用于静态类型检查，运行时不会影响模块的实际行为。

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