python - 具有强制数据类型和维度的输入 numpy 数组的文档字符串格式

Question

为了举例，假设我有一个函数，它接受两个 numpy 数组作为输入参数。第一个数组必须是二维的并且只包含 float 。第二个数组必须是一维的并且只包含 bool 值。

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

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.

   """

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

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).
"""

请注意，如果您想进行更多说明，最好在函数描述部分也描述数据类型和维度。