Как добавить строку документации Python для dict

Question

Каков рекомендуемый способ добавления строки документации для параметра словаря? Я могу увидеть несколько строк документации doc-string здесь.

Мне нужно документировать входные аргументы функции в строке документации. Если это простая переменная, я могу использовать что-то вроде:

 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, поэтому параметр словаря будет выглядеть следующим образом:

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 вы также можете использовать аннотации функций:

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допустимые варианты: Plain, Epytext, reStructuredText, NumPy, Google. Эта функция автоматически добавит скелет строки документации после ввода трех двойных кавычек." и ударил enter.