python - 格式化dicts的python docstrings

为字典参数添加docstring的建议方法是什么？我可以看到多行docstring示例。
我需要将输入参数记录到docstring中的函数中。如果它是一个简单的变量，我可以使用如下内容：

 def func2(a=x, b = y):
 """ fun2 takes two integers

 Keyword arguments:
 a -- refers to age (default 18)
 b -- refers to experience (default 0)
 """

如果我们将dict作为输入参数传递给函数：

 def func3(**kwargs):
     """ takes dictionary as input

      <Here how to explain them - Is it like?>
      kwargs['key1'] -- takes value1

      <or simply>
      key1 -- takes value1
      """

最佳答案

我通常使用Google docstring style，因此字典参数如下所示：

def func(a_dict):
    """Some function to do something to a dictionary.

    Args:
      a_dict (dict of str: int): Some mapping, I guess?

    """
    ...

采用**kwargs的函数（注意：这与使用dictionary参数不同），如下所示：

def func(**kwargs):
    """Some function to do stuff to arbitrary keyword arguments.

    Args:
      **kwargs: Arbitrary keyword arguments.

    """
    ...

如果有特定的参数应该存在（例如您的key1），它们应该是单独的，而不是滚动到**kwargs中。
在python 3.x中，还可以使用function annotations：

def func(a_dict: dict):
    """Some function to do something to a dictionary."""
    ...

从python 3.5中，您可以使用typing更加明确：

from typing import Mapping

def func(a_dict: Mapping[str, int]):
    """Some function to do something to a dictionary."""
    ...