Używam sphinx i wtyczki autodoc do generowania dokumentacji API dla moich modułów Pythona. Chociaż mogę zobaczyć, jak dobrze udokumentować określone parametry, nie mogę znaleźć przykładu, jak udokumentować parametr **kwargs.Jaki jest poprawny sposób udokumentowania parametru ** kwargs?
Czy ktoś ma dobry przykład jasnego sposobu na udokumentowanie tych?
Myślę, że subprocess-module's docs jest dobrym przykładem. Podaj pełną listę wszystkich parametrów dla top/parent class. Następnie odnieś się do tej listy dla wszystkich innych wystąpień **kwargs.
Czy jestem jedynym, dla którego ta odpowiedź nie ma sensu? Nie mogłem znaleźć konkretnego przykładu. –
Przykładem jest prawdopodobnie 'subprocess.call (* popenargs, ** kwargs)'. Jest to udokumentowane jako 'subprocess.call (args, *, stdin = None, stdout = None, stderr = None, shell = False)' gdzie wszystko po '*' jest rozpoznawanym kluczem w '** kwargs' (lub w najmniej często używane) – nos
Najbardziej znaczącą kontynuacją tego jest teraz ['subprocess.Popen'] (https://docs.python.org/3/library/subprocess.html#subprocess.Popen) i nie jestem z pewnością jest to szczególnie dobry przykład. –
Jeśli ktoś jeszcze szuka jakiejś poprawnej składni .. Oto przykład docstringu. Tak właśnie to zrobiłem, mam nadzieję, że ci się przyda, ale nie mogę twierdzić, że jest zgodny z niczym konkretnym.
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
Istnieje doctstring example dla Sphinx w ich dokumentacji. W szczególności wykazują one następujące:
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
Choć poprosił o sphinx wyraźnie, chciałbym również wskazać na Google Python Style Guide. Ich przykład docstrujący wydaje się sugerować, że nie wywołują one specyficznie kwargów. (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 ma pytanie dotyczące przyjętej odpowiedzi na przedstawieniu dokumentacji zarządzania podproces. Jeśli importujesz moduł, możesz szybko zobaczyć dokumentację modułu przez inspect.getsource.
Przykład z interpretera Pythona z wykorzystaniem zalecenia SilentblokiSpółka Ghost:
>>> import subprocess
>>> import inspect
>>> import print inspect.getsource(subprocess)
Oczywiście można również przeglądać dokumentację modułu za pomocą funkcji pomocy. Na przykład help (podproces):
Nie jestem osobiście fanem podprocesowego docstringu dla kwargs jako przykładu, ale tak jak w przypadku przykładu Google, nie wyświetla ona kwargs oddzielnie, jak pokazano w przykładzie dokumentacji 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()
jestem tym to odpowiedź na A-B-B pytanie, bo warto zauważyć, że można przejrzeć źródła lub Documentation dowolny moduł w ten sposób do spostrzeżeń i inspiracji do komentowania kodu.
Po znalezieniu to pytanie zdecydowałem się na następujących, co jest ważne Sphinx i działa dość dobrze:
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"""...""" jest wymagane, aby ten „raw” docstring a tym samym zachować \* nienaruszone (na Sfinks podchwycić jako literalny *, a nie początek "nacisku").
Wybrane formatowanie (lista wypunktowana z nawiasami i opisem rozdzielonym m-dash) jest po prostu dopasowane do automatycznego formatowania dostarczanego przez Sphinx.
Po przejściu do tego wysiłku, aby sekcja "Argumenty słów kluczowych" wyglądała jak domyślna sekcja "Parametry", wydaje się, że od samego początku może być łatwiej przewracać sekcję z własnymi parametrami (jak w przypadku niektórych inne odpowiedzi), ale jako dowód koncepcji jest to jeden ze sposobów uzyskania ładnego wyglądu uzupełniającego **kwargs, jeśli już używasz Sphinx.
docstrings Google Styl przetwarzane przez Sfinksa
Disclaimer: nie testowane.
Od tego wycięcia na sphinx docstring example, *args i **kwargs pozostają niespienione:
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.
bym sugerują następujące rozwiązanie dla zwartości:
"""
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
...
Zauważ, Optional nie jest wymagane dla argumentów **key.
Inaczej, można spróbować wyraźnie notować * args pod Other Parameters i **kwargs pod Keyword Args (patrz analizowany 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
...
To zależy od stylu dokumentacji używanego, ale jeśli używają stylu numpydoc, zaleca się dokumentowanie **kwargs przy użyciu Other Parameters.
Na przykład, następujący przykład quornian za:
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}``.
"""
Uwaga szczególnie, że zaleca się dać domyślnych kwargs, ponieważ nie są one w sposób oczywisty z podpisem funkcji.
To zależy całkowicie od tego, z jakiej metody docletu korzystasz. (reStructuredText, Sphinx, Google) –