Как правильно документировать параметр * * kwargs? [закрытый]

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

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

    """

The r"""...""" требуется, чтобы сделать это "сырой" docstring и таким образом сохранить \* неповрежденный (для Сфинкса, чтобы забрать как литерал * и не начало "акцента").

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

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

Google Style docstrings разбираются Сфинксом

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

из этого выреза sphinx docstring example на *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 аргументов.

иначе, вы можете попробовать явно перечислить * args под 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 
        ...

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

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

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

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)

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

Я лично не поклонник подпроцесса docstring для 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, потому что стоит отметить, что вы можете просмотреть источник или документацию любого модуля таким образом для понимания и вдохновения для комментирования вашего кода.

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

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

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

например, следуя примеру кворниана:

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, поскольку они не очевидны из сигнатуры функции.