Formatting python docstrings for dicts

Question

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

Could you please explain what exactly you mean? Do you mean how to document a parameter that should be a dictionary? — jonrsharpe, Nov 03 '14 at 10:46

score 23 · Accepted Answer · edited Mar 12 '20 at 14:15

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

What 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. — CMCDragonkai, May 09 '18 at 04:21
@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*. — jonrsharpe, May 09 '18 at 07:11
The docstring you propose Namgyal, `dict of str: int`, is fine. But I don't see any description of it at your link to https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html — Arthur, Oct 30 '20 at 19:04

score 4 · Answer 2 · answered Mar 12 '20 at 14:25

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.

Formatting python docstrings for dicts

2 Answers2

Linked