Quelle est la bonne façon de documenter un paramètre **kwargs? [fermé]

après avoir trouvé cette question j'ai réglé sur le suivant, qui est Sphinx valide et fonctionne assez bien:

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

    """

le r"""...""" est nécessaire pour en faire un "raw" docstring et donc garder le \* intact (pour Sphinx à ramasser comme un littéral * et non le début de "emphasis").

le formatage choisi (liste à puces avec Type entre parenthèses et description séparée par un tiret) est simplement pour correspondre à l'automatique formatage fourni par Sphinx.

une fois que vous êtes allé à cet effort de faire la section" Mots clés Arguments "ressembler à la section par défaut" Paramètres", il semble qu'il pourrait être plus facile de lancer votre propre section de paramètres dès le début (comme par certaines des autres réponses), mais comme une preuve de concept c'est une façon d'obtenir un bon look pour" supplémentaire 151940920 " si vous utilisez déjà Sphinx.

Google Style docstrings parsed by Sphinx

Avertissement: pas testé.

de ce découpage du sphinx docstring example , le *args et **kwargs sont laissés Non agrandi :

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.

je suggèrent la solution suivante pour la compacité:

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

Notez comment, Optional n'est pas requise pour les **key arguments.

sinon , vous pouvez essayer d'énumérer explicitement les * args sous Other Parameters et **kwargs sous le Keyword Args (voir parsed sections ):

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

il y a un exemple doctstring pour Sphinx dans leur documentation. Plus précisément, ils montrent ce qui suit:

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

bien que vous ayez posé des questions sur sphinx explicitement, je voudrais aussi pointer vers le Guide de style de Google Python . Leur exemple de docstring semble impliquer qu'ils n'appellent pas spécifiquement kwargs. (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 a une question sur la réponse acceptée de référencement de la documentation de gestion de sous-processus. Si vous importez un module, vous pouvez rapidement voir les docstrings du module via inspect.getsource.

un exemple de l'interpréteur python utilisant la recommandation de Silent Ghost:

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

bien sûr, vous pouvez également voir la documentation du module via la fonction d'aide. Par exemple de l'aide(sous-processus)

Je ne suis pas personnellement un fan de la subprocess docstring pour kwargs comme exemple, mais comme L'exemple de Google, il ne Liste pas kwargs séparément comme indiqué dans L'exemple de documentation 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()

j'inclus cette réponse à la question de A-B-B parce qu'il vaut la peine de noter que vous pouvez passer en revue la source ou la documentation de n'importe quel module de cette façon pour les idées et l'inspiration pour commenter votre code.

si quelqu'un d'autre cherche une syntaxe valide.. Voici un exemple de cordage. C'est exactement comme ça que je l'ai fait, j'espère que c'est utile pour vous, mais je ne peux pas prétendre que c'est compatible avec quoi que ce soit en particulier.

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

cela dépend du style de documentation que vous utilisez, mais si vous utilisez le numpydoc style, il est recommandé de documenter **kwargs en utilisant Other Parameters .

par exemple, à l'exemple de 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}``.
    """

notez surtout qu'il est recommandé de donner les valeurs par défaut de kwargs, car elles ne sont pas évidentes à partir de la signature de la fonction.