如何结合Python类型注解编写DRY文档字符串并兼容各类工具？

Python支持类型注解后，要写出无重复（DRY）的代码文档，核心原则就是用函数签名里的类型注解替代文档字符串中的类型声明，只保留参数和返回值的语义描述，这样既避免冗余，又能兼容各类工具。

核心写法示例 #

直接去掉文档字符串里的:type:和:rtype:，只保留描述部分：

def my_function(db: Session, name: str) -> str:
    """Some function

    :param db: a database connection
    :param name: some name
    :return: return something
    """

如果偏好Google/NumPy风格的文档字符串，同样只保留描述：

def my_function(db: Session, name: str) -> str:
    """Some function

    Args:
        db: a database connection
        name: some name

    Returns:
        return something
    """

兼容各类工具的关键 #

• VSCode等IDE：主流IDE会自动读取函数签名中的类型注解，在代码提示时将类型信息和文档字符串的描述结合展示，完全不需要文档里重复写类型。
• mypy等代码检查器：这类工具只关注函数签名里的类型注解，文档字符串中的类型声明对它们无效，去掉后反而能避免类型信息不一致的问题。
• Sphinx自动文档生成：需要搭配sphinx_autodoc_typehints扩展（配合默认的sphinx.ext.autodoc），它会自动从类型注解中提取类型信息，和文档字符串的描述合并生成规范的文档，无需手动维护:type:标签。

注意事项 #

• 确保类型注解的准确性：现在所有工具都依赖签名里的类型信息，写错会导致IDE提示、类型检查和文档生成出错。
• 复杂类型补充说明：如果使用Optional[Session]、Union[str, int]这类复杂类型，可在文档字符串的描述里补充适用场景，比如db: optional database connection, defaults to None。
• 老项目迁移：逐步替换文档字符串中重复的:type:和:rtype:，避免新旧写法混合导致的混乱。

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