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

Question

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

5

我想使用Python docstring来更好地记录我的代码。

在下面的函数中，它以列表作为输入，并将文件写入磁盘。我想知道如何在docstring中记录函数输出，因为函数的返回类型为None。它是否有一个约定？

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

- masoud

我会省略“返回”部分，尽管我认为这并没有普遍的标准。 - Dennis

这可能取决于您用什么工具来创建文档。例如，使用重构文本的Sphinx？ - hiro protagonist

@hiroprotagonist 我使用numpy风格的文档。 - masoud

1

numpy使用sphinx。我不知道他们是否使用retext或markdown（或其他）。你可以尝试找出来（或简要查看源代码）。但无论如何，请查看sphinx。 - hiro protagonist

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- bad_coder · Accepted Answer

关于类型提示，Python 唯一的约定是：

非目标, PEP 484

需要强调的是，Python 将保持动态类型语言的特性，作者们也没有任何意愿通过约定或其他方式使类型提示成为必须的。

考虑到这一点，有3种写 docstrings 的语法。其中两种语法有自己的风格指南，请参见numpydoc docstring guide和Google Python Style Guide - 3.8 Comments and Docstrings。（相比之下，PEP 8和PEP 257 不太具体）。

仅返回None的函数情况在numpydoc样式指南中没有特别提到，需要注意它只涉及到返回值的函数的情况：

Sections - numpydoc docstring guide

Returns

返回值及其类型的解释。与参数部分类似，每个返回值的名称是可选的。每个返回值的类型始终是必需的。

因此，在正式的Python术语中，返回None的函数不返回任何值，因为在这种情况下，None表示没有值，因此numpydoc指南没有提到这种特殊情况：

3.2. 标准类型层次结构，数据模型

无

这种类型只有一个值(...) 在许多情况下用于表示没有值，例如从不显式返回任何内容的函数返回该值。

由于样式指南是被省略的，因此我们可以尝试搜索 numpy 文档以查找一个返回 None 的函数，看看应该如何操作。一个很好的例子是 numpy.copyto，确实与 Return 相对应的文档字符串部分是不存在的。

一个方法的详细文档和它的docstring不应该与简要的文本描述混淆。将上述numpy.copyto示例的详细文档与逻辑函数-比较中的列表进行比较，后者在文本上描述了返回值，但省略了所有签名中的类型提示。

为了完整起见，我们可以引用Google样式指南中的这种情况：

3.8.3 函数和方法，Google Python样式指南

返回：（或生成器的产出）（...）如果函数只返回None，则不需要此部分。

最后，问题中的示例可以使用NumPy样式docstrings编写为：

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

或者使用Google风格的文档字符串：

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