在NumpyDoc DocStrings中表示关键字-参数的性质？

Question

在尝试遵循DocStrings的DocStrings格式时，我似乎想不出如何告诉用户参数是关键字参数(即。指定为SomeFunc(theKeyWordArg=100)，而不是SomeFunc(100) )。

我在网上找到的文档(如这和这)只显示了一些示例，如

def somefunc(arg1, arg2):
'''
Parameters
----------
arg1, arg2 : int
    info on arg1 & arg2

对于关键词论点：

def somefunc( keyword=False ):
...

但他说，在一般情况下，这是我在许多职能中定义的：

def somefunc( *args, **kwargs):

我应该把它们写成这样：

Parameters
----------
*args
    Variable length argument list.
**kwargs
    Arbitrary keyword arguments.

我遇到的问题是，我看不到一种明确的方法来告诉用户，参数部分中的哪些参数是关键字和unkeyworded参数，所以我必须执行如下操作：

somefunc(*args, **kwargs)
'''
Parameters
----------
x : int
    Non-keyworded arg, x is an int
name : string
    keyworded arg, pass a string as the name.
'''

因此，用户将调用该函数来设置x & name，如下所示：

somefunc(10, name='gazebo')

在docstring中没有标准的方法来指示哪些参数是关键字&哪些不是呢？

例如，这难道不是一个明确的好方法吗？

somefunc(*args, **kwargs)
'''
Parameters
----------
x : int
    x is an int
y : float
    y should be a float
name = string
    Pass a string as the name
label = string
    Provide a label for this object
'''

其中:指的是非关键字(即。SomeFunc(100, 200)和=的意思是关键字(即。SomeFunc(100, 200, name="Bob", label="one and two hundred"))

Answer 1

当一个参数是Python中的关键字参数时，它就有一个默认值(撇开对**kwargs的一些不寻常的处理)。通常，只需说明缺省值就足够了(并使文档更简单)，例如：

def somefunc(keyword=False):
    """
    Parameters:
    -----------
    keyword: bool. Controls whether to delete hard drive. Defaults to False.
    ...
    """
    # ... rest of code

由此，读者必须知道，任何具有默认值的参数都是关键字参数。

这是一些大型图书馆的风格，比如熊猫。下面是一些用于pandas.ols的帮助字符串

Definition: pandas.ols(**kwargs)
Docstring:
Returns the appropriate OLS object depending on whether you need
simple or panel OLS, and a full-sample or rolling/expanding OLS.

Will be a normal linear regression or a (pooled) panel regression depending
on the type of the inputs:

y : Series, x : DataFrame -> OLS
y : Series, x : dict of DataFrame -> OLS
y : DataFrame, x : DataFrame -> PanelOLS
y : DataFrame, x : dict of DataFrame/Panel -> PanelOLS
y : Series with MultiIndex, x : Panel/DataFrame + MultiIndex -> PanelOLS

Parameters
----------
y: Series or DataFrame
    See above for types
x: Series, DataFrame, dict of Series, dict of DataFrame, Panel
weights : Series or ndarray
    The weights are presumed to be (proportional to) the inverse of the
    variance of the observations.  That is, if the variables are to be
    transformed by 1/sqrt(W) you must supply weights = 1/W
intercept: bool
    True if you want an intercept.  Defaults to True.
nw_lags: None or int
...