NumPy docstring for function type and None type

Question

I am writing the following function:

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

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)? More specifically, is function the right type for the handler argument? Where can I find an overview of all NumPy docstring types I can use? And Is it correct that I use None if nothing is returned at all?

score 2 · Accepted Answer · answered Apr 21 '21 at 04:09

I had this same question. This question is really similar, and the accepted answer says to include it, but doesn't really make a claim about why or why not to do it, nor does it answer your particular question about where to validate your work.

A high level answer to validating your docstrings is the documentation from NumPy.

That may be enough, but keep reading for answers to your micro-questions within this question. First:

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)?

This page from NumPy has a good section on validation. You can do it with 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

Other options, could use sphinx, another package is pydocstyle - though I can't speak for its coverage it does look to be maintained, supporting through Python 3.9.

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

I believe so, I don't see a specific part on which types are valid, I would assume all are valid, and, function is a valid 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?

Yes. The docs say the following, emphasis is my own:

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:

NumPy docstring for function type and None type

1 Answers1