Форматирование строк документации python для dicts

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

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

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

python dictionary docstring
person webminal.org    schedule 03.11.2014    source источник
comment
Не могли бы вы объяснить, что именно вы имеете в виду? Вы имеете в виду, как документировать параметр, который должен быть словарем?   -  person jonrsharpe    schedule 03.11.2014
comment
Да, как документировать параметр, который является словарем.   -  person webminal.org    schedule 03.11.2014

Ответы (2)


arrow_upward
24
arrow_downward

Обычно я использую стиль строки документации 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.

    Keyword Args:
        <kwarg_name> int: A description
        <kwarg_name_2> str: Another description
        <...>

    """
    ...

Если есть определенные параметры, которые должны присутствовать (например, ваш 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."""
    ...
person jonrsharpe    schedule 03.11.2014
comment
Что, если вы хотите явно ввести ключи и значения словаря? В словаре есть class_ids с типом, masks с типом... и т.д. - person CMCDragonkai; 09.05.2018
comment
@CMCDragonkai Я не знаю никаких соглашений для этого; если это то, что вы хотите, вам лучше использовать что-то вроде namedtuple с этими атрибутами. - person jonrsharpe; 09.05.2018
comment
Строка документации, которую вы предлагаете Намгьялу, dict of str: int, хороша. Но я не вижу его описания по вашей ссылке на sphinxcontrib-napoleon. readthedocs.io/en/latest/ - person Arthur; 30.10.2020

arrow_upward
4
arrow_downward

Для тех, кто использует PyCharm: вы можете настроить форматы строк документации по умолчанию в:

Preferences -> Tools -> Python Integrated Tools -> Docstrings

начиная с версии 2019 разрешены следующие варианты: Обычный, Epytext, reStructuredText, NumPy, Google. Эта функция автоматически добавит скелет строки документации после того, как вы наберете три двойных кавычки " и нажмете enter.

person Tomasz Bartkowiak    schedule 12.03.2020