如何在 Python 中为返回 None 但在磁盘中写入文件的函数编写文档字符串？

Question

I want to use Python docstring to better document my code.

In the function below, it takes a list as input and write a file into disk. I want to know how to document the output of function in docstring as the function return type in None. Does it have a convention?

def foo(list_of_items: list) -> None :
    """Simple function.

    Parameters
    ----------
        list_of_items : list of str
        list of some texts    

    Returns
    -------
        what is the best way to write this section?
    """

    file = open('/path/output.txt')
    file.write(list_of_items[1])
    file.close()

Answer 1

The only Python convention regarding type hints would be:

Non-goals , PEP 484

It should also be emphasized that Python will remain a dynamically typed language, and the authors have no desire to ever make type hints mandatory, even by convention.

Considering this, there are 3 syntax for writing docstrings . Two syntaxes have their own style guide, see numpydoc docstring guide and Google Python Style Guide - 3.8 Comments and Docstrings . (By comparison PEP 8 and PEP 257 are not as specific).

The case of functions that only return None is not specifically mentioned by numpydoc style guide, carefully notice that it only addressess the case of functions that return values :

Sections - numpydoc docstring guide

5. 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

Thus In formal Python terms, a function that returns None returns no value, because in this situation None signifies the absence of a value , and so the numpydoc guideline does not mention this special case:

3.2. The standard type hierarchy, Data Model

None

• This type has a single value(...) It is used to signify the absence of a value in many situations, eg, it is returned from functions that don't explicitly return anything.

Since the style guide is omiss, so we can try to search the numpy documentation for a function that returns None to see how it's done. A good example is numpy.copyto and indeed the docstring section corresponding to Return is absent.

The detailed documentation of a method and its docstring should not to be confused with a listing where a brief textual description might be given. Compare the detailed documentation of the above numpy.copyto example with the list in Logic functions - comparison which does textually describe the returns but omits all type hints from the signatures.

For completeness we can quote the Google style guide on this case:

3.8.3 Functions and Methods, Google Python Style Guide

Returns: (or Yields: for generators) (...) If the function only returns None, this section is not required.

Finally, the example in the question can be written with NumPy style docstrings as:

def foo(list_of_items: list, the_path: str) -> None:
    """Simple function writes list_of_items to the_path.

    Parameters
    ----------
        list_of_items : list of str
            Describes list_of_items.
        the_path : str
            Describes the_path.
    """

    file = open(the_path)
    file.write(list_of_items[1])
    file.close()

Or with Google style docstrings as:

def foo2(list_of_items: list[str], the_path: str) -> None:
    """Simple function writes list_of_items to the_path.

    Params:
        list_of_items (list[str]): Describes list_of_items.
        the_path (str): Describes the_path.
    """

    file = open(the_path)
    file.write(list_of_items[1])
    file.close()