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

Question

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

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

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

Answer 1

你不知道。文档字符串只是注释。它们被解释器忽略。所以，不要导入它，否则代码检查工具（例如 pylint）会抱怨未使用的导入。

但是，对于实际代码部分，在文档字符串中使用 反引号 可能会更好。例如

"""
Returns:
    `Tuple[str, str]`: Tuple of first name and last name
"""

这样，文档生成工具就知道它是实际代码，并且可以正确地格式化它。

Answer 2

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"""
    # ...

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

Using typing module in docstring

python

docstring

typing

pycharm