Python 指示NumpyDoc DocStrings中参数的关键字属性？

在尝试遵循DocStrings的NumpyDoc格式时，我似乎不知道如何告诉用户参数是关键字参数（即指定为

SomeFunc（关键字arg=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.

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

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（100200）

），而

=

表示关键字的（即

SomeFunc（100200，name=“Bob”，label=“1200”）

）

当一个参数是Python中的关键字参数时，它因此有一个默认值（撇开一些异常处理

**kwargs

）。通常只需说明默认值即可（并使文档更简单），例如：

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

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

这是一些较大的库中的样式，例如pandas。下面是一些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
...

---

啊，这很有趣。但是，我有很多函数带有非关键字的参数，它们也有类似于“默认值”的东西，所以docstring中提到了很多默认值。而且，这个函数只接受kwargs，所以很明显，每个参数都应该是keyword

pandas.ols（x=[1,2,3]，y=whatever）

。我突然想到mapltolib

绘图（）

函数与我的函数非常相似-同时使用了°arg和°kwarg。查看他们的文档，他们完全避免了参数部分，只是详细地解释了整件事。在等待进一步证据之前，我怀疑没有标准的方法来简洁地告诉用户一个参数是*arg，另一个是**kwarg。替换

：

使用

=

将是一种简洁的方式……我认为这会破坏斯芬克斯的东西？事实上，对于a°°kwarg和a°arg使用

x=int

声明

y:float

，有什么不好的地方吗？这似乎是一种表示关键字的合理方式。我通常不会将matplotlib与Python中的最佳实践联系起来，但熊猫也不是最好的例子。我对你的说法感到困惑，“我有很多函数都带有非关键字的参数，它们也有类似“默认值”的东西”“…仅仅依赖常规的默认值是一种不好的做法。有没有什么好的理由不能将所有这些位置参数都转换为具有代表性默认值的关键字参数？这会更好，因为不会破坏API。如果用户从未调用

set_thisVar（x）

函数，当程序稍后向另一个软件发送命令时，if必须使用某个值，因此

get\u thisVar（）

返回一个“默认值”值。这个模块最初是用非键控参数编程的，这使得用户使用起来非常简单和快速。我不得不添加许多可选参数，我将其作为关键字参数（因为在其他情况下，有超过2或3个位置参数，在这种情况下很快就会混淆）。