Python函数文档字符串是否需重复类型提示？PEP规范疑问

假设有如下函数：

def do_product(a: int, b: int) -> int:
    return a * b

我对该函数进行文档编写：

def do_product(a: int, b: int) -> int:
    """该函数接收两个整数并返回它们的乘积

    :param a: 第一个整数 
    :param b: 第二个整数

    :return: 返回a和b的乘积"""
    return a * b

我使用Sphinx时，通过sphinx-autodoc-typehints扩展可将代码中的类型提示导入到API文档中，这样只需在代码中声明一次类型，避免文档与函数声明出现歧义。但目前我在处理一个PR时，被要求在文档字符串中再次声明类型，修改后如下：

def do_product(a: int, b: int) -> int:
    """该函数接收两个整数并返回它们的乘积

    :param int a: 第一个整数 
    :param int b: 第二个整数

    :return int: 返回a和b的乘积"""
    return a * b

这看起来是重复定义，我认为这样做并无意义。

1. 编写文档字符串时，是否需要定义类型？
2. Python中记录类型提示的最佳实践是什么？
3. 针对此是否有对应的PEP标准？我尚未找到合适的规范。

1. 编写文档字符串时是否需要定义类型？ #

不需要——至少在已经通过Python原生类型提示声明过参数和返回值类型的情况下，完全没必要在文档字符串里重复写类型。重复定义不仅增加维护成本（后续修改类型时要改两处），还可能引发不一致风险，和你提到的用sphinx-autodoc-typehints扩展的场景冲突，完全违背了"一次定义，多处复用"的初衷。

当然，如果你的项目还在使用不支持类型提示的旧Python版本（比如Python 3.5之前），那文档字符串里的类型标注是必要的，但现在这种情况已经很少见了。

2. Python中记录类型提示的最佳实践 #

• 优先使用原生类型提示：直接在函数签名里声明a: int、-> int这种形式，这是最标准、最易被工具识别的方式，IDE、类型检查器（比如mypy）、文档生成工具都能直接读取。
• 文档字符串聚焦逻辑说明：文档字符串里只写参数的业务含义、函数的功能、返回值的解释，不用重复类型信息。比如:param a: 用于计算乘积的第一个整数，而不是:param int a: ...。
• 利用工具自动同步：像你用的sphinx-autodoc-typehints这类扩展，能自动把代码里的类型提示同步到生成的API文档中，既保证一致性，又减少手动维护的工作量。
• 复杂类型用标准模块：如果涉及泛型、可选类型、联合类型等，用Python 3.10+支持的list[int]、str | None，或旧版本的typing.List[int]、typing.Optional[str]这类原生类型标注，不要在文档字符串里手写复杂类型说明。

3. 对应的PEP标准 #

有明确的PEP规范：

• PEP 484：Python类型提示的核心规范，定义了函数签名中类型提示的语法和使用方式，明确推荐在函数参数和返回值处直接声明类型，而非依赖文档字符串。
• PEP 257：文档字符串规范，它并没有要求在文档字符串里写类型信息，只是规定了文档字符串的格式（单行/多行写法），强调文档字符串要清晰说明功能，而非重复代码里已有的信息。
• PEP 8：代码风格规范，提到类型提示的使用要简洁，避免冗余，和PEP 484的要求一致。

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