[英]Formatting python docstrings for dicts
What's the recommended way of adding a docstring for a dictionary parameter?为字典参数添加文档字符串的推荐方法是什么? I can see multiple line docstring examples here .
我可以在这里看到多行文档字符串示例。
I need to document the input arguments to a function in the docstring.我需要在文档字符串中记录函数的输入参数。 If it's a simple variable, I can use something like:
如果它是一个简单的变量,我可以使用类似的东西:
def func2(a=x, b = y):
""" fun2 takes two integers
Keyword arguments:
a -- refers to age (default 18)
b -- refers to experience (default 0)
"""
If we have dict
passed as input argument to function:如果我们将
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
"""
I generally use the Google docstring style , so a dictionary parameter would look like:我通常使用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?
"""
...
A function that takes **kwargs
(note: this is not quite the same as having a dictionary parameter), would look like:这需要一个功能
**kwargs
(注:这是不是具有字典参数完全一样),看起来像:
def func(**kwargs):
"""Some function to do stuff to arbitrary keyword arguments.
Args:
**kwargs: Arbitrary keyword arguments.
Keyword Args:
<kwarg_name> int: A description
<kwarg_name_2> str: Another description
<...>
"""
...
If there are specific parameters that should be present (eg your key1
), they should be separate, not rolled into **kwargs
.如果应该存在特定的参数(例如您的
key1
),它们应该是分开的,而不是卷入**kwargs
。
In Python 3.x, you can also use function annotations :在 Python 3.x 中,您还可以使用函数注释:
def func(a_dict: dict):
"""Some function to do something to a dictionary."""
...
From Python 3.5, you can be even more explicit using typing
:从 Python 3.5 开始,您可以使用更明确的
typing
:
from typing import Mapping
def func(a_dict: Mapping[str, int]):
"""Some function to do something to a dictionary."""
...
For those using PyCharm: You can configure your default docstring formats in:对于使用 PyCharm 的用户:您可以在以下位置配置默认文档字符串格式:
Preferences -> Tools -> Python Integrated Tools -> Docstrings
as of version 2019
the allowed options are: Plain, Epytext, reStructuredText, NumPy, Google .自
2019
版起,允许的选项为: Plain、Epytext、reStructuredText、NumPy、Google 。 This functionality will automatically add a docstring skeleton once you've typed three double quotes "
and hit enter
.一旦您输入三个双引号
"
并按enter
此功能将自动添加一个文档字符串骨架。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.