具有强制数据类型和维度的输入numpy数组的Docstring格式

Question

为了举例,假设我有一个函数,它将两个numpy数组作为输入参数.第一个数组必须是2维的,并且只包含浮点数.第二个数组必须是1维的,并且只包含布尔值.

到目前为止,我还没有真正找到在docstring中指定输入数组数据类型和维度的现有约定.我想到的一种可能的格式(以numpy docstring约定为基础)是这样的:

def example_function(arr1, arr2):
    """This is an example function.

    Parameters
    ----------
    arr1 : ndarray(dtype=float, ndim=2)
        Array containing some kind of data.
    arr2 : ndarray(dtype=bool, ndim=1)
        Array containing some kind of mask.

   """

这可以被认为是"正确的"文档字符串格式吗？(即它是否违反了现有docstring约定的任何规则？)

Answer 1

维度和项目类型是有关作为函数参数的数组的额外信息。因此，根据文档，您需要一种如下样式：

"""
x : type
    Description of parameter `x`.
"""

在这种情况下应为：

"""
Parameters
----------
arr1 : ndarray
    2D array containing data with `float` type.
arr2 : ndarray
    1D mask array(containing data with boolean type).
"""

并请注意，如果要进一步说明，最好在函数描述部分中描述数据类型和维。