Formatting python docstrings for dicts
Solution 1
I generally use the Google docstring style, so a dictionary parameter would look like:
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:
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 (e.g. your key1
), they should be separate, not rolled into **kwargs
.
In Python 3.x, you can also use function annotations:
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
:
from typing import Mapping
def func(a_dict: Mapping[str, int]):
"""Some function to do something to a dictionary."""
...
Solution 2
For those using PyCharm: You can configure your default docstring formats in:
Preferences -> Tools -> Python Integrated Tools -> Docstrings
as of version 2019
the allowed options are: Plain, Epytext, reStructuredText, NumPy, Google. This functionality will automatically add a docstring skeleton once you've typed three double quotes "
and hit enter
.
Related videos on Youtube
![webminal.org](https://i.stack.imgur.com/Mx7jx.jpg?s=256&g=1)
webminal.org
Free and Open Source programmer. Projects include: FileSystem Projects and Free Online Linux Terminal
Updated on March 13, 2020Comments
-
webminal.org over 4 years
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:def func3(**kwargs): """ takes dictionary as input <Here how to explain them - Is it like?> kwargs['key1'] -- takes value1 <or simply> key1 -- takes value1 """
-
jonrsharpe over 9 yearsCould you please explain what exactly you mean? Do you mean how to document a parameter that should be a dictionary?
-
webminal.org over 9 yearsYes, how to document a parameter which is a dictionary.
-
-
CMCDragonkai about 6 yearsWhat if you wanted to explicitly type out the dictionary's keys and values? The dictionary has
class_ids
which has a type,masks
which has a type... etc. -
jonrsharpe about 6 years@CMCDragonkai I'm not aware of any convention for that; if that's what you want you'd be better with something like a
namedtuple
with those as attributes. -
Arthur over 3 yearsThe docstring you propose Namgyal,
dict of str: int
, is fine. But I don't see any description of it at your link to sphinxcontrib-napoleon.readthedocs.io/en/latest/…