Formatting documentation strings for python

Question

What is the recommended way to add a documentation string for a dictionary parameter? I can see a few lines of documentation here .

I need to document the input arguments of a function in the documentation line. If this is 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 passed dict as an input argument to a 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 """ 

Answer 1

I usually use the line style of a Google document , so the dictionary option will look like this:

 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 accepts **kwargs (note: this is not quite the same as having a dictionary parameter) would look like this:

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

If there are certain parameters that should be present (for example, your key1 ), they should be separate and not minimized to **kwargs .

---

In Python 3.x, you can also use function annotations :

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

---

Starting with Python 3.5, you can be even more understandable by typing :

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