如何在Python中为一个只返回磁盘中的写入文件的函数编写docstring？

我想使用PythonDocString更好地记录我的代码

在下面的函数中，它接受一个列表作为输入，并将一个文件写入磁盘。我想知道如何将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()

---

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

，政治公众人物484

还应该强调的是，Python将仍然是一种动态类型化的语言，作者不希望强制使用类型提示，即使按照惯例也是如此

考虑到这一点，有两个问题。两个语法都有自己的样式指南，请参见和。（相比之下，它们没有那么具体）

numpydoc style guide没有特别提到只返回

None

的函数的情况，请注意，它只针对返回值的函数的情况：

返回

返回值及其类型的说明。与参数部分类似，只是每个返回值的名称是可选的。每个返回值的类型总是必需的

因此，在正式的Python术语中，返回

None

的函数不返回任何值，因为在这种情况下

None

表示没有值，因此numpydoc指南没有提到这种特殊情况：

没有

• 此类型具有单个值（…）它用于表示在许多情况下没有值，例如，它是从不显式返回任何内容的函数返回的。

因为样式指南是OMIS，所以我们可以尝试在numpy文档中搜索一个返回

None

的函数，看看它是如何完成的。一个很好的例子是，实际上与

Return

相对应的docstring部分不存在

方法及其docstring的详细文档不应与可能给出简短文本描述的列表混淆。将上述

numpy.copyto

示例的详细文档与列表进行比较，在该列表中，文本描述了返回，但忽略了签名中的所有类型提示

为完整起见，我们可以引用本案例的谷歌风格指南：

收益：（或收益率：发电机） （…）如果函数仅返回None，则不需要此部分

最后，问题中的示例可以使用NumPy样式的docstring编写，如下所示：

def foo（项目列表：列表，路径：str）->None:
“”“简单函数将\u项的列表写入\u路径。”。
参数
----------
项目列表：str列表
描述\u项的列表。
路径：str
描述_路径。
"""
文件=打开（_路径）
file.write（列出\u项[1]）
file.close（）文件

或使用谷歌风格的docstring作为：

def foo2（项目列表：list[str]，路径：str）->None:
“”“简单函数将\u项的列表写入\u路径。”。
参数：
项目列表（list[str]）：描述项目列表。
_路径（str）：描述_路径。
"""
文件=打开（_路径）
file.write（列出\u项[1]）
file.close（）文件

我将省略“返回”部分，尽管我认为没有通用标准。这可能取决于您创建文档时使用的内容。e、 g.带重组文本的斯芬克斯？@HiroProtator我使用numpy风格的文档numpy使用斯芬克斯。我不知道他们使用的是复述还是降价（或其他）。您可以尝试找出答案（或者简单地看一下源代码）。但无论如何，请看一看，