it-swarm.xyz

Как правильно документировать параметр ** kwargs?

Я использую sphinx и плагин autodoc для генерации документации API для моих модулей Python. Хотя я вижу, как правильно задокументировать определенные параметры, я не могу найти пример того, как задокументировать параметр **kwargs.

У кого-нибудь есть хороший пример ясного способа документировать это?

70
jkp

Я думаю subprocess- документы модуля является хорошим примером. Дайте исчерпывающий список всех параметров для top/parent class . Затем просто обратитесь к этому списку для всех других вхождений **kwargs.

14
SilentGhost

После нахождения этого вопроса я остановился на следующем, который является действительным Sphinx и работает довольно хорошо:

def some_function(first, second="two", **kwargs):
    r"""Fetches and returns this thing

    :param first:
        The first parameter
    :type first: ``int``
    :param second:
        The second parameter
    :type second: ``str``
    :param \**kwargs:
        See below

    :Keyword Arguments:
        * *extra* (``list``) --
          Extra stuff
        * *supplement* (``dict``) --
          Additional content

    """

r"""...""" требуется для того, чтобы сделать эту строку «сырой» и, таким образом, сохранить \* нетронутым (чтобы Sphinx воспринимал ее как литерал *, а не как начало «упора»).

Выбранное форматирование (маркированный список с типом в скобках и описанием, разделенным m-тире) просто соответствует автоматическому форматированию, предоставляемому Sphinx.

После того, как вы попытались сделать так, чтобы раздел «Аргументы ключевых слов» выглядел как раздел «Параметры» по умолчанию, может показаться, что с самого начала проще свернуть свой собственный раздел параметров (согласно некоторым другим ответам) , но в качестве доказательства концепции это один из способов добиться приятного внешнего вида дополнительного **kwargs, если вы уже используете Sphinx.

33
quornian

Строки документов в стиле Google, проанализированные Sphinx

Отказ от ответственности: не проверено.

Из этого выреза из примера sphinx docstring , *args и **kwargs оставлены не расширены:

def module_level_function(param1, param2=None, *args, **kwargs):
    """
    ...

    Args:
        param1 (int): The first parameter.
        param2 (Optional[str]): The second parameter. Defaults to None.
            Second line of description should be indented.
        *args: Variable length argument list.
        **kwargs: Arbitrary keyword arguments.

Я бы предложил следующее решение для компактности:

    """
    Args:
        param1 (int): The first parameter.
        param2 (Optional[str]): The second parameter. Defaults to None.
            Second line of description should be indented.
        *param3 (int): description
        *param4 (str): 
        ...
        **key1 (int): description 
        **key2 (int): description 
        ...

Обратите внимание, что Optional не требуется для аргументов **key

В противном случае, вы можете попытаться явно перечислить * аргументы в Other Parameters и **kwargs в Keyword Args (см. Раздел разделы ):

    """
    Args:
        param1 (int): The first parameter.
        param2 (Optional[str]): The second parameter. Defaults to None.
            Second line of description should be indented.

    Other Parameters:
        param3 (int): description
        param4 (str): 
        ...

    Keyword Args:
        key1 (int): description 
        key2 (int): description 
        ...
14
Oleg

В их документации есть doctstring пример для Sphinx. В частности, они показывают следующее: 

def public_fn_with_googley_docstring(name, state=None):
"""This function does something.

Args:
   name (str):  The name to use.

Kwargs:
   state (bool): Current state to be in.

Returns:
   int.  The return code::

      0 -- Success!
      1 -- No good.
      2 -- Try again.

Raises:
   AttributeError, KeyError

A really great idea.  A way you might use me is

>>> print public_fn_with_googley_docstring(name='foo', state=None)
0

BTW, this always returns 0.  **NEVER** use with :class:`MyPublicClass`.

"""
return 0

Хотя вы спрашивали о sphinx явно, я бы также указал на Руководство по стилю Google Python . Их пример документирования подразумевает, что они специально не вызывают кваргов. (Не other_silly_variable = None) 

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
"""Fetches rows from a Bigtable.

Retrieves rows pertaining to the given keys from the Table instance
represented by big_table.  Silly things may happen if
other_silly_variable is not None.

Args:
    big_table: An open Bigtable Table instance.
    keys: A sequence of strings representing the key of each table row
        to fetch.
    other_silly_variable: Another optional variable, that has a much
        longer name than the other args, and which does nothing.

Returns:
    A dict mapping keys to the corresponding table row data
    fetched. Each row is represented as a Tuple of strings. For
    example:

    {'Serak': ('Rigel VII', 'Preparer'),
     'Zim': ('Irk', 'Invader'),
     'Lrrr': ('Omicron Persei 8', 'Emperor')}

    If a key from the keys argument is missing from the dictionary,
    then that row was not found in the table.

Raises:
    IOError: An error occurred accessing the bigtable.Table object.
"""
pass

У A-B-B есть вопрос о принятом ответе на ссылку на документацию по управлению подпроцессом. Если вы импортируете модуль, вы можете быстро просмотреть строки документации модуля через inspect.getsource. 

Пример из интерпретатора Python, использующего рекомендацию Silent Ghost: 

>>> import subprocess
>>> import inspect
>>> import print inspect.getsource(subprocess)

Конечно, вы также можете просмотреть документацию модуля через функцию справки. Например, помощь (подпроцесс) 

Лично я не являюсь поклонником строки документации подпроцесса для kwargs в качестве примера, но, как и в примере с Google, он не перечисляет kwargs отдельно, как показано в примере документации Sphinx. 

def call(*popenargs, **kwargs):
"""Run command with arguments.  Wait for command to complete, then
return the returncode attribute.

The arguments are the same as for the Popen constructor.  Example:

retcode = call(["ls", "-l"])
"""
return Popen(*popenargs, **kwargs).wait()

Я включил этот ответ на вопрос A-B-B, потому что стоит отметить, что вы можете просмотреть исходный код или документацию любого модуля таким образом, чтобы получить представление и вдохновение для комментирования вашего кода.

6
binarysubstrate

Если кто-то еще ищет какой-то правильный синтаксис ... Вот пример строки документации. Это то, как я это сделал, я надеюсь, что это полезно для вас, но я не могу утверждать, что это соответствует чему-то конкретному.

def bar(x=True, y=False):
    """
    Just some silly bar function.

    :Parameters:
      - `x` (`bool`) - dummy description for x
      - `y` (`string`) - dummy description for y
    :return: (`string`) concatenation of x and y.
    """
    return str(x) + y

def foo (a, b, **kwargs):
    """
    Do foo on a, b and some other objects.

    :Parameters:
      - `a` (`int`) - A number.
      - `b` (`int`, `string`) - Another number, or maybe a string.
      - `\**kwargs` - remaining keyword arguments are passed to `bar`

    :return: Success
    :rtype: `bool`
    """
    return len(str(a) + str(b) + bar(**kwargs)) > 20
4
m01

Это зависит от стиля используемой вами документации, но если вы используете стиль numpydoc , рекомендуется документировать **kwargs, используя Other Parameters .

Например, следующий пример quornian:

def some_function(first, second="two", **kwargs):
    """Fetches and returns this thing

    Parameters
    ----------
    first : `int`
        The first parameter
    second : `str`, optional
        The second parameter

    Other Parameters
    ----------------
    extra : `list`, optional
        Extra stuff. Default ``[]``.
    suplement : `dict`, optional
        Additional content. Default ``{'key' : 42}``.
    """

Обратите особое внимание на то, что рекомендуется указывать значения по умолчанию для kwargs, поскольку они не очевидны из сигнатуры функции.

0
Jonas Adler