python在文档字符串中自动添加类型提示

Posted 2023-03-22

【中文标题】python在文档字符串中自动添加类型提示

【英文标题】：python automatically adding type hints in docstring

【发布时间】：2021-11-16 08:39:21

【问题描述】：

我正在寻找一种工具，可以将函数中已经添加的类型注释添加到 PyCharm 生成的文档字符串中。

我已经关注this issue on JetBrains很久了，这张票似乎还没有任何进展。

我也看到了this article，但它似乎太具体了，只适用于谷歌文档字符串。

我已经检查了this package on PyPI，但这与我需要的相反。我需要的是将参数中提供的类型提示添加到文档字符串中，而不是相反。

这可能与How to make PyCharm get type hints from function definition and populate type values in docstrings? 有关，但我只需要一个通用解决方案，或者至少需要一个可以与 Numpy docstring 或 reStructuredText 一起使用并且可以与 PyCharm 很好地配合使用的解决方案。

我只是看到自己回来研究这个东西，希望能得到一些东西，但找不到我需要的东西。什么工具可以解决这个问题？

【问题讨论】：

问个问题：在 dostring 中再次显示文档类型提示有什么意义，因为自动化 API 文档生成器可以直接从类型提示中读取它们？

@MikkoOhtamaa 很有趣。请问您是否可以让我知道其中一种自动化 API 文档生成器，它可以自动将类型提示合并到文档页面中，并以某种方式将它们链接到原始类型的文档？因此，如果我添加了类型提示foo(a: bar) -> bool:，它将提供某种指向bar 文档的链接。我将类型添加到文档字符串的目标是为了这个链接功能，函数中的类型提示只是为了 mypy 和更容易使用 IDE 进行调试。

Sphinx 应该已经从注释中提取类型。 PyCharm 本身似乎也在其帮助弹出窗口中正确使用注释。事实上，我会建议 not 通过将信息放入文档字符串来复制信息。

@MisterMiyagi 感谢您提供此信息，我将研究 sphinx 并尝试看看它是否能满足我的需求，是的，如果您手动输入两次，复制信息似乎没有用。跨度>

Sphinx 已经提取了此信息，请在此处查看示例：tradingstrategy.ai/docs/programming/api/candle.html

【参考方案1】：

几个月前我在搜索时，找不到任何可用的解决方案。现在，我正在使用带有 this 扩展名的 VS Code，它提供了很好的 Docstring：

def foo(a: int, b: str) -> bool:
    """[summary]

    Args:
        a (int): [description]
        b (str): [description]

    Returns:
        bool: [description]
    """

【讨论】：

如果你有一个已经注释的函数，扩展是否可以工作，例如foo(a: int, b: str) -> bool: 它会为参数生成模板并返回正确的类型？尽管回购中的问题数量并不确定，但该扩展似乎很酷。如果这意味着更好的文档体验，我可能会切换到 VS 代码

是的，一旦你点击"""，它就会为 args 生成模板并返回正确的类型。我通常不关心问题的数量，但自 3 月以来它没有任何新的提交，这不能保证。