将函数签名与文档字符串进行比较的工具

Question

是否有工具可以检查文档字符串中列出的参数是否与函数调用的签名匹配？它应该能够处理 numpy 风格的文档字符串。我经常使用 R CMD CHECK，它可以发现 R 中的文档/代码不匹配，这非常有帮助。如果 Python 中有类似的东西那就太好了，但我还没有找到任何东西。

Answer 1

我刚刚创建了一个工具来实现这一目标，称为pydoctest.

它将尝试推断文档字符串中的类型（不仅仅是词法比较）并报告参数数量、参数名称、参数类型、返回类型之间的不匹配，（可选）如果缺少文档字符串等则抛出错误。

它目前支持 google、sphinx 和 numpy 文档字符串格式，但可以很容易地使用其他格式进行扩展。

例子：

def func_type_mismatch(self, a: int) -> int:

    """[summary]

    Args:

        a (float): [description]        <-- float is not int

    Returns:

        int: [description]

    """

    pass

在此函数上运行 pydoctest 会给出以下输出：

Function: <function IncorrectTestClass.func_type_mismatch at 0x7f9a8b52c8c8> FAIL | Argument type differ. Argument 'a' was expected (from signature) to have type '<class 'int'>', but has (in docs) type '<class 'float'>'


Answer 2

pip install docsig

然后运行docsig .它就会为你检查这一点

/path/to/project

-----------------------

def function(✖*args) -> ✓List[str]:

    """...

    :param None: ✖

    :return: ✓

    """

E103: parameters missing

目前还有8个错误

Answer 3

除了其他答案中提到的pydoctest和docsig之外，至少还有这些工具：

• pydoclint与 pydocstyle或ruff一起使用

• Pylint 的docparams 扩展

• flake8-文档字符串-完整

• darglit2（对于大型项目来说速度慢得惊人）