时间戳

首页 > 解决方案 > 如何根据 Numpy 风格的文档字符串记录 kwargs？

python - 如何根据 Numpy 风格的文档字符串记录 kwargs？

问题描述

因此，我发现了与其他样式相关的帖子，并且我知道有关文档的NumPy 页面，但我很困惑。我不明白如何将每个 kwargs 添加到方法的参数部分。这是来自给定的网页：

def foo(var1, var2, *args, long_var_name='hi', **kwargs):
    r"""Summarize the function in one line.

    Several sentences providing an extended description. Refer to
    variables using back-ticks, e.g. `var`.

    Parameters
    ----------
    var1 : array_like
        Array_like means all those objects -- lists, nested lists, etc. --
        that can be converted to an array.  We can also refer to
        variables like `var1`.
    var2 : int
        The type above can either refer to an actual Python type
        (e.g. ``int``), or describe the type of the variable in more
        detail, e.g. ``(N,) ndarray`` or ``array_like``.
    *args : iterable
        Other arguments.
    long_var_name : {'hi', 'ho'}, optional
        Choices in brackets, default first when optional.
    **kwargs : dict
        Keyword arguments.

目前尚不清楚如何在此处添加每个 kwargs。我还看到了这个 sphinx 页面“Example NumPy Style Python Docstring”，这是关于 kwargs 的部分：

def module_level_function(param1, param2=None, *args, **kwargs):
    """This is an example of a module level function.

    Function parameters should be documented in the ``Parameters`` section.
    The name of each parameter is required. The type and description of each
    parameter is optional, but should be included if not obvious.

    If \*args or \*\*kwargs are accepted,
    they should be listed as ``*args`` and ``**kwargs``.

    The format for a parameter is::

        name : type
            description

            The description may span multiple lines. Following lines
            should be indented to match the first line of the description.
            The ": type" is optional.

            Multiple paragraphs are supported in parameter
            descriptions.

    Parameters
    ----------
    param1 : int
        The first parameter.
    param2 : :obj:`str`, optional
        The second parameter.
    *args
        Variable length argument list.
    **kwargs
        Arbitrary keyword arguments.

不，我还是一头雾水。是这样的吗？

"""
Dummy docstring.

Parameters
----------
**kwargs: dict
    first_kwarg: int
        This is an integer
    second_kwarg: str
        This is a string
"""

标签： pythonpython-3.xnumpydocstring

解决方案

通常需要在本Parameters节中描述的 kwargs 通常会像其他命名参数一样处理，并且不展开**kwargs。但是，numpy 样式指南也有一个Other Parameters部分可用于提供 kwargs 的描述，而不会使该Parameters部分混乱。风格指南将其描述为：

用于描述不经常使用的参数的可选部分。仅当函数具有大量关键字参数时才应使用它，以防止参数部分混乱。

numpydoc repo 给出了这个例子：

"""

    Other Parameters
    ----------------
    only_seldom_used_keyword : int, optional
        Infrequently used parameters can be described under this optional
        section to prevent cluttering the Parameters section.
    **kwargs : dict
        Other infrequently used keyword arguments. Note that all keyword
        arguments appearing after the first parameter specified under the
        Other Parameters section, should also be described under this
        section.

"""

因此，额外的 kwargs 可以添加为

"""

    Other Parameters
    ----------------
    first_kwarg: int
        This is an integer
    second_kwarg: str
        This is a string
    **kwargs : dict
        Other infrequently used keyword arguments.

"""

推荐阅读