python - 记录 **kwargs 参数的正确方法是什么？

Question

我正在使用Sphinx和autodoc 扩展为我的 Python 模块生成 API 文档。虽然我可以看到如何很好地记录特定参数，但我找不到如何记录**kwargs参数的示例。

有没有人有一个很好的例子来说明记录这些的清晰方法？

Answer 1

找到这个问题后，我确定了以下问题，这是有效的狮身人面像并且效果很好：

def some_function(first, second="two", **kwargs):
    r"""Fetches and returns this thing

    :param first:
        The first parameter
    :type first: ``int``
    :param second:
        The second parameter
    :type second: ``str``
    :param \**kwargs:
        See below

    :Keyword Arguments:
        * *extra* (``list``) --
          Extra stuff
        * *supplement* (``dict``) --
          Additional content

    """

需要将其r"""..."""设为“原始”文档字符串，从而保持\*原样（Sphinx 将其作为文字*而不是“强调”的开始）。

选择的格式（带有括号类型和 m-dash 分隔的描述的项目符号列表）只是为了匹配 Sphinx 提供的自动格式。

一旦您努力使“关键字参数”部分看起来像默认的“参数”部分，似乎从一开始就滚动您自己的参数部分可能会更容易（根据其他一些答案） ，但作为概念证明，**kwargs如果您已经在使用 Sphinx ，这是实现补充外观漂亮的一种方法。

Answer 2

由 Sphinx 解析的 Google Style 文档字符串

免责声明：未经测试。

从sphinx docstring example的这个 cutout 中，*argsand**kwargs未展开：

def module_level_function(param1, *args, param2=None, **kwargs):
    """
    ...

    Args:
        param1 (int): The first parameter.
        param2 (Optional[str]): The second parameter. Defaults to None.
            Second line of description should be indented.
        *args: Variable length argument list.
        **kwargs: Arbitrary keyword arguments.

我建议以下紧凑性解决方案：

    """
    Args:
        param1 (int): The first parameter.
        param2 (Optional[str]): The second parameter. Defaults to None.
            Second line of description should be indented.
        *param3 (int): description
        *param4 (str): 
        ...
        **key1 (int): description 
        **key2 (int): description 
        ...

请注意，参数Optional不需要。**key

否则，您可以尝试在下面Other Parameters和**kwargs下面显式列出 *args Keyword Args（请参阅文档字符串部分）：

    """
    Args:
        param1 (int): The first parameter.
        param2 (Optional[str]): The second parameter. Defaults to None.
            Second line of description should be indented.
    
    Other Parameters:
        param3 (int): description
        param4 (str): 
        ...

    Keyword Args:
        key1 (int): description 
        key2 (int): description 
        ...

Answer 3

在他们的文档中有一个Sphinx 的文档字符串示例。具体来说，它们显示以下内容：

def public_fn_with_googley_docstring(name, state=None):
"""This function does something.

Args:
   name (str):  The name to use.

Kwargs:
   state (bool): Current state to be in.

Returns:
   int.  The return code::

      0 -- Success!
      1 -- No good.
      2 -- Try again.

Raises:
   AttributeError, KeyError

A really great idea.  A way you might use me is

>>> print public_fn_with_googley_docstring(name='foo', state=None)
0

BTW, this always returns 0.  **NEVER** use with :class:`MyPublicClass`.

"""
return 0

尽管您明确询问了sphinx，但我也会指出Google Python Style Guide。他们的文档字符串示例似乎暗示他们没有专门调用 kwargs。(other_silly_variable=无)

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
"""Fetches rows from a Bigtable.

Retrieves rows pertaining to the given keys from the Table instance
represented by big_table.  Silly things may happen if
other_silly_variable is not None.

Args:
    big_table: An open Bigtable Table instance.
    keys: A sequence of strings representing the key of each table row
        to fetch.
    other_silly_variable: Another optional variable, that has a much
        longer name than the other args, and which does nothing.

Returns:
    A dict mapping keys to the corresponding table row data
    fetched. Each row is represented as a tuple of strings. For
    example:

    {'Serak': ('Rigel VII', 'Preparer'),
     'Zim': ('Irk', 'Invader'),
     'Lrrr': ('Omicron Persei 8', 'Emperor')}

    If a key from the keys argument is missing from the dictionary,
    then that row was not found in the table.

Raises:
    IOError: An error occurred accessing the bigtable.Table object.
"""
pass

ABB 有一个关于引用子流程管理文档的公认答案的问题。如果您导入一个模块，您可以通过 inspect.getsource 快速查看模块文档字符串。

python 解释器中使用 Silent Ghost 推荐的示例：

>>> import subprocess
>>> import inspect
>>> import print inspect.getsource(subprocess)

当然你也可以通过帮助功能查看模块文档。例如帮助（子进程）

我个人并不喜欢以 kwargs 为例的子流程文档字符串，但与 Google 示例一样，它没有单独列出 kwargs，如 Sphinx 文档示例中所示。

def call(*popenargs, **kwargs):
"""Run command with arguments.  Wait for command to complete, then
return the returncode attribute.

The arguments are the same as for the Popen constructor.  Example:

retcode = call(["ls", "-l"])
"""
return Popen(*popenargs, **kwargs).wait()

我将这个答案包含在 ABB 的问题中，因为值得注意的是，您可以通过这种方式查看任何模块的源代码或文档，以获得评论代码的见解和灵感。

Answer 4

如果您正在寻找如何以numpydoc样式执行此操作，您可以在不指定类型的情况下简单地在参数部分中提及**kwargs- 如sphinx 扩展 napolean的numpydoc 示例和pandas 文档 sprint 2018 的文档字符串指南中所示。

这是我从LSST 开发人员指南中找到的一个示例，它很好地解释了参数的描述应该是什么**kwargs：

def demoFunction(namedArg, *args, flag=False, **kwargs):
    """Demonstrate documentation for additional keyword and
    positional arguments.

    Parameters
    ----------
    namedArg : `str`
        A named argument that is documented like always.
    *args : `str`
        Additional names.

        Notice how the type is singular since the user is expected to pass individual
        `str` arguments, even though the function itself sees ``args`` as an iterable
        of `str` objects).
    flag : `bool`
        A regular keyword argument.
    **kwargs
        Additional keyword arguments passed to `otherApi`.

        Usually kwargs are used to pass parameters to other functions and
        methods. If that is the case, be sure to mention (and link) the
        API or APIs that receive the keyword arguments.

        If kwargs are being used to generate a `dict`, use the description to
        document the use of the keys and the types of the values.
    """

或者，基于@Jonas Adler 的建议，我发现最好将**kwargs其及其描述放在Other Parameters部分中- 即使matplotlib 文档指南中的这个示例也表明相同。

Answer 5

如果其他人正在寻找一些有效的语法.. 这是一个示例文档字符串。我就是这样做的，我希望它对你有用，但我不能声称它符合任何特定的要求。

def bar(x=True, y=False):
    """
    Just some silly bar function.

    :Parameters:
      - `x` (`bool`) - dummy description for x
      - `y` (`string`) - dummy description for y
    :return: (`string`) concatenation of x and y.
    """
    return str(x) + y

def foo (a, b, **kwargs):
    """
    Do foo on a, b and some other objects.

    :Parameters:
      - `a` (`int`) - A number.
      - `b` (`int`, `string`) - Another number, or maybe a string.
      - `\**kwargs` - remaining keyword arguments are passed to `bar`

    :return: Success
    :rtype: `bool`
    """
    return len(str(a) + str(b) + bar(**kwargs)) > 20

Answer 6

这取决于您使用的文档样式，但如果您使用numpydoc样式，建议**kwargs使用Other Parameters.

例如，按照 quornian 的示例：

def some_function(first, second="two", **kwargs):
    """Fetches and returns this thing

    Parameters
    ----------
    first : `int`
        The first parameter
    second : `str`, optional
        The second parameter

    Other Parameters
    ----------------
    extra : `list`, optional
        Extra stuff. Default ``[]``.
    suplement : `dict`, optional
        Additional content. Default ``{'key' : 42}``.
    """

请特别注意，建议提供 kwargs 的默认值，因为这些在函数签名中并不明显。

Answer 7

我无法找到文档的实际链接，但这有效（使用 Sphinx 3.4.3）：

class Foo:
    """A Foo implementation

    :param str foo: Foo
    :param int bar: Bar
    :keyword str key1: kwarg 1
    :keyword str key2: kwarg 2
    :keyword int key3: kwarg 3
    """

    def __init__(self, foo, bar, **kwargs):
        pass

Answer 8

我认为subprocess-module 的文档就是一个很好的例子。给出一个顶级/父类的所有参数的详尽列表。然后只需参考该列表以了解所有其他出现的**kwargs.