Python类型注解中如何清晰表达元组值的语义内容？

以下是几种能让开发者无需额外查阅文档，直接从代码中理解返回值结构与语义的实用方案：

1. 给自定义类型+属性添加详细文档字符串（Docstring） #

主流IDE（PyCharm、VS Code+Pylance）都会在智能提示或悬停时展示Docstring内容，直接把语义说明写进去，不用跳转就能看懂。

from typing import Dict, NamedTuple, ABC, abstractproperty

class Balance(NamedTuple):
    """资产持有明细
    Attributes:
        quantity: 资产的实际持有数量
        proportion: 该资产在整个投资组合中的占比（取值范围0-1）
    """
    quantity: float
    proportion: float

class Exchange(ABC):
    @abstractproperty
    def balances(self) -> Dict[str, Balance]:
        """返回账户内所有资产的持有情况
        返回结构示例：{"BTC": (0.0015, 0.30), "ETH": (0.10, 0.20), "LTC": (5, 0.50)}
        """
        ...

2. 用TypedDict替代NamedTuple（适合字典结构的直观提示） #

TypedDict的类型提示在部分IDE中会直接展开内部字段结构，不用点进定义就能看到具体的键值语义：

from typing import Dict, TypedDict, ABC, abstractproperty

class Balance(TypedDict):
    quantity: float
    proportion: float

class Exchange(ABC):
    @abstractproperty
    def balances(self) -> Dict[str, Balance]:
        ...

VS Code+Pylance这类工具会直接把返回类型提示为Dict[str, {'quantity': float, 'proportion': float}]，一目了然。

3. 直接在Tuple类型标注中加注释 #

如果不想自定义类型，直接在Tuple的每个元素后加注释，很多IDE会识别并展示这些注释：

from typing import Dict, Tuple, ABC, abstractproperty

class Exchange(ABC):
    @abstractproperty
    def balances(self) -> Dict[str, Tuple[
        float,  # 资产持有数量
        float   # 资产在组合中的占比
    ]]:
        ...

这种方式最轻量化，适合简单的Tuple结构语义说明。

4. 使用DataClass并添加字段注释 #

Python 3.7+的dataclass，配合字段级注释，部分IDE对其类型展开支持更友好，同时能保持结构的可维护性：

from dataclasses import dataclass
from typing import Dict, ABC, abstractproperty

@dataclass(frozen=True)  # 模拟NamedTuple的不可变性
class Balance:
    quantity: float
    """资产的实际持有数量"""
    proportion: float
    """资产在投资组合中的占比"""

class Exchange(ABC):
    @abstractproperty
    def balances(self) -> Dict[str, Balance]:
        ...

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