8

Is there a tool that can check if the arguments listed in the docstring match the signature of the function call? It should be able to deal with numpy-style docstrings. I am regularly using R CMD CHECK, which finds documentation/code mismatches in R and this is quite helpful. It would be very good to have something similar in Python, but I did not find anything yet.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Soeren D.
  • 312
  • 1
  • 7
  • Just to be clear, you want to check the name and type of the parameters, right? – wjandrea Sep 02 '20 at 16:24
  • 1
    Yes, exactly, it should check that the name and type of the arguments in the documentation match the ones in the code. – Soeren D. Sep 02 '20 at 16:26
  • In the case of Python the tools used for static checks of the docstrings against the signatures are [linters](https://www.google.com/search?client=firefox-b-d&q=linter+python), with [pylint](https://www.pylint.org/) being one popular choice. Each IDE has a default linter and some IDE's like PyCharm use their proprietary linter implementation. This is probably a case of you not using an IDE that's set for Python, or not having configured a linter for Python (so it's an IDE config question). Finally, docs is another matter, see [Python-Sphinx](https://stackoverflow.com/tags/python-sphinx/info). – bad_coder Sep 02 '20 at 21:22
  • What IDE are you using? – bad_coder Sep 02 '20 at 22:23
  • I am using Visual Studio Code, and I have pylint enabled. It gives me a ton of warnings, but it has never raised a docstring-code mismatch. – Soeren D. Sep 03 '20 at 05:26

3 Answers3

5

I just created a tool to achieve this, called pydoctest.

It will attempt to infer the types in your docstrings (not just lexically compare) and report back on mismatches between number of arguments, argument-names, argument-types, return-types, (optionally) throw error if lacking docstring and more.

It currently supports google, sphinx and numpy docstring format, but can rather easily be extended with other formats.

Example:

def func_type_mismatch(self, a: int) -> int:
    """[summary]

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

    Returns:
        int: [description]
    """
    pass

Running pydoctest on this function, gives this output:

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'>'

Edit (June 2021): I've started the development of a vscode-extension that uses and highlights the errors. enter image description here https://marketplace.visualstudio.com/items?itemName=JeppeRask.pydoctest

Jeppe
  • 1,830
  • 3
  • 24
  • 33
0

I was trying to find the same, so I wrote docsig

pip install docsig

then just run docsig . and it will check this for you

/path/to/project
-----------------------
def function(✖*args) -> ✓List[str]:
    """...

    :param None: ✖
    :return: ✓
    """

E103: parameters missing

There are 8 other errors so far

jshwi
  • 84
  • 1
  • 1
  • 9
0

In addition to pydoctest and docsig mentioned in other answers, there are at least these tools:

akaihola
  • 26,309
  • 7
  • 59
  • 69