Quelle est la bonne façon de documenter un paramètre ** kwargs?
J'utilise sphinx et le plugin autodoc pour générer la documentation de l'API pour mes modules Python. Bien que je sache comment bien documenter des paramètres spécifiques, je ne trouve pas d'exemple pour documenter un paramètre **kwargs.
Quelqu'un a-t-il un bon exemple d'une manière claire de documenter ces problèmes?
Je pense que subprocess- docs du module est un bon exemple. Donne une liste exhaustive de tous les paramètres pour un top/classe parent . Ensuite, référez-vous simplement à cette liste pour toutes les autres occurrences de **kwargs.
Après avoir trouvé cette question, j’ai décidé de ce qui suit, qui est valide Sphinx 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 requis pour en faire une docstring "brute" et ainsi garder le \* intact (pour que Sphinx puisse le saisir en tant que * 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) doit simplement correspondre au formatage automatisé fourni par Sphinx.
Une fois que vous avez essayé de faire en sorte que la section "Arguments des mots clés" ressemble à la section "Paramètres" par défaut, il vous semblera peut-être plus facile de créer votre propre section de paramètres dès le début (comme dans certaines des réponses). , mais comme preuve de concept, c’est un moyen d’obtenir une bonne apparence pour un **kwargs supplémentaire si vous utilisez déjà Sphinx.
Documents de style Google analysés par Sphinx
Avertissement: non testé.
A partir de cette découpe de l'exemple exemple de sphinx docstring , les *args et **kwargs sont laissés unxpanded:
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érerais 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 que, Optional n'est pas requis pour les arguments **key.
Sinon, vous pouvez essayer de lister explicitement les * arguments sous Other Parameters et **kwargs sous le Keyword Args (voir analysé 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 de 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 demandé explicitement de sphinx , je voudrais également signaler le Guide de style Google Python . Leur exemple de docstring semble impliquer qu'ils n'appellent pas spécifiquement les 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érencer la documentation de gestion de sous-processus. Si vous importez un module, vous pouvez voir rapidement les docstrings du module via inspect.getsource.
Un exemple tiré de l'interpréteur python utilisant la recommandation de Silent Ghost:
>>> import subprocess
>>> import inspect
>>> import print inspect.getsource(subprocess)
Bien entendu, vous pouvez également consulter la documentation du module via la fonction d’aide. Par exemple, aide (sous-processus)
Je ne suis pas personnellement un fan de la docstring de sous-processus pour kwargs à titre d'exemple, mais comme dans l'exemple de Google, il ne répertorie pas les kwargs séparément, comme illustré 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 car il est intéressant de noter que vous pouvez consulter le code source ou la documentation de n'importe quel module de cette manière pour vous aider à mieux commenter votre code.
Si quelqu'un d'autre recherche une syntaxe valide .. Voici un exemple de chaîne de documentation. C’est justement ce que j’ai fait, j’espère que cela vous sera utile, mais je ne peux pas prétendre que cela soit conforme à quelque chose 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 style numpydoc , il est recommandé de documenter **kwargs en utilisant Other Parameters .
Par exemple, en suivant 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 en particulier qu'il est recommandé d'indiquer les valeurs par défaut de kwargs, celles-ci n'étant pas évidentes à partir de la signature de la fonction.