python - 在文档字符串中使用 typing 模块

Question

假设我有一个带有文档字符串的函数，我在其中将返回类型声明为具有两个字符串的元组:

def foo():
    """
    Returns:
        Tuple[str, str]: Tuple of first name and last name
    """

如果我不在除文档字符串之外的任何地方使用它，我是否应该从 typing 导入 Tuple？

Answer 1

PyCharm 对类型提示的文档字符串支持实际上并不使用typing。您不需要导入该模块。

typing 模块只是为了支持注释在运行时执行的事实；对于以 def foo() -> Tuple[str, str]: 开头的语句，Python 实际上会计算表达式 Tuple[str, str] 所以期望能够解析名称。 (从 Python 3.7 开始，您可以使用 from __future__ import annotations 禁用(或者更确切地说，推迟)评估)。

但文档字符串通常不会被评估，并且预计不会包含可运行的 Python 代码。

除非您硬性要求将类型信息放入文档字符串中，否则我会坚持使用实际注释:

from typing import Tuple


# type aliases
firstname = str
lastname = str


def foo() -> Tuple[firstname, lastname]:
    """Descriptive line documenting this function's purpose"""
    # ...