函数类型和 None 类型的 NumPy 文档字符串

Question

我正在编写以下函数：

def parse_zip_file(path, handler):
    """
    Parse all files contained in a zip file (specified by the path parameter).

    Parameters
    ----------
    path : str
        The path to the zip file.
    handler: function
        When looping through all the files contained in the zip file, this method will be called every time
        a new file is found. Two arguments are passed. The first argument is the name of the discovered file
        and the second argument are the contents of the file.

    Returns
    -------
    None
        Nothing is returned.
    """
    return None

我在想，我这样做对吗？有什么方法可以检查文档字符串是否正确（我正在使用 PyCharm 作为编辑器）？更具体地说，function 是处理程序参数的正确类型吗？在哪里可以找到我可以使用的所有 NumPy 文档字符串类型的概述？如果什么都没有返回，我使用 None 是否正确？

Answer 1

我也有同样的问题。这个非常相似，接受的答案说要包括它，但并没有真正说明为什么或为什么不这样做，也没有回答您关于在哪里验证您的工作的特定问题。

验证文档字符串的高级答案是来自 NumPy 的 documentation。

这可能就足够了，但请继续阅读此问题中您的微问题的答案。第一：

I was wondering, am I doing this correctly? Is there any way I can check the docstring is correct (I am using PyCharm as an editor)?

来自 NumPy 的 page 有一个很好的验证部分。你可以用 numpydoc 来做。

To see the Restructured Text generated for an object, the numpydoc module can be called. For example, to do it for numpy.ndarray, use:

$ python -m numpydoc numpy.ndarray

其他选项，可以使用 sphinx, another package is pydocstyle - 虽然我不能说它的覆盖范围它看起来确实得到维护，支持到 Python 3.9.

More specifically, is function the right type for the handler argument?

我相信是这样，我没有看到关于哪些类型有效的特定部分，我会假设所有类型都有效，并且函数是有效的 type/class.

Where can I find an overview of all NumPy docstring types I can use?

Top level docs.

And Is it correct that I use None if nothing is returned at all?

是。文档说了以下内容，重点是我自己的：

Returns

Explanation of the returned values and their types. Similar to the Parameters section, except the name of each return value is optional. The type of each return value is always required:

函数类型和 None 类型的 NumPy 文档字符串

NumPy docstring for function type and None type

python

numpy

docstring

pycharm