我如何为以下Python函数编写文档字符串?

问题描述 投票:0回答:1

假设我具有以下功能:

def get_matrix(*args, arbitrary=True):
    if arbitrary == True:
        return np.random.randint(-10,10, size=[args[0],args[1]])
    else:
        return np.array(args[0])

所以函数也可以

  1. 生成矩阵(如果任意== True);在这种情况下,它需要两个int参数。

  1. 将数组(如果任意== False)(由元组或列表表示)转换为numpy的数组

如何为此功能编写简洁易读的剂量? (最好保留numpy's docstring style。)Numpy对于如何记录* args和** kwargs没有什么可说的。 (或者也许是,但是到目前为止我还没有发现任何东西)

python docstring
1个回答
1
投票

对您的项目有意义的一切。 *args的通用术语是“位置参数”,通常您会希望将它们分别称为“第n个位置参数”。关键字参数**kwargs通常应根据具体情况分别使用可接受的键和值进行提及,除非您的方法中的kwarg充当其他人方法中的kwarg的代理,在这种情况下,您也可以编写“关键字参数与[other方法]相同,请参见文档以获取更多详细信息”。


在这种情况下,您给出的示例很困难,主要是因为这是一种不好的做法-一种方法应该做一件事;如果您有一个方法根据标志的值执行两种不同的操作,那么为什么不仅仅拥有两种方法并使调用者显式调用其中一种方法呢? (进一步阅读:PEP 20

Numpy的文档标准似乎走得更远,通常完全避开通用的**kwargs(支持显式命名的关键字),而更喜欢可以在文档字符串中引用的命名位置参数。您链接的文档没有提供关于该主题的明确建议,但我倾向于*args作为“变量名称”(在其中保留星号,以表示它们是位置参数),并以integers作为值(请注意复数),然后在说明中明确指出它代表位置参数。另外,我在下面所做的只是将其明确地列为“位置参数”(毕竟,这种docstring格式对于类型提示毫无用处)。

这主要是个人喜好,但我会这样记录您的功能:

def get_matrix(*args, arbitrary=True):
    """
    If `arbitrary` is True (default), generates a random matrix, 
    with x and y bounds represented by the first two given 
    positional args, and returns it.

    If `arbitrary` is False, then instead coerces the first positional
    argument into a np.array, and returns that.

    parameters
    ----------
    positional args: ints
        purpose depends on the value of arbitrary (see above)
    arbitrary: bool
        determines the behavior of the function (see above)

    returns
    -------
    if arbitrary is true, a random 2D array of defined size.
    otherwise, the first positional argument coerced to a np.array
    """
    if arbitrary == True:
        return np.random.randint(-10,10, size=[args[0],args[1]])
    else:
        return np.array(args[0])
© www.soinside.com 2019 - 2024. All rights reserved.