Question

为词典参数添加docstring的推荐方法是什么？我可以看到多行文档字符串示例here。

我需要在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
      """

Answer 1

我通常使用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的函数（注意：这是不与拥有字典参数完全相同），如下所示：

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."""
    ...

Answer 2

对于使用PyCharm的用户：您可以在以下位置配置默认文档字符串格式：

Preferences -> Tools -> Python Integrated Tools -> Docstrings

自2019版开始，允许的选项为：纯文本，Epytext，reStructuredText，NumPy，Google 。键入三个双引号"并按enter后，此功能将自动添加文档字符串框架。

如何为dict添加python docstring

2 个答案: