it-swarm-eu.dev

Jaký je správný způsob, jak dokumentovat parametr ** kwargs?

Používám sphinx a plugin autodoc pro generování API dokumentace pro mé moduly Python. I když vidím, jak pěkně dokumentovat specifické parametry, nemohu najít příklad, jak dokumentovat parametr **kwargs.

Má někdo dobrý příklad jasného způsobu, jak tyto dokumenty zdokumentovat?

pythondocumentationpython-sphinx
70
jkp

Myslím, že subprocess- moduly docs je dobrý příklad. Uveďte úplný seznam všech parametrů pro top/parent class . Pak stačí odkazovat na tento seznam pro všechny ostatní výskyty **kwargs.

14
SilentGhost

Po nalezení této otázky jsem se usadil na následujícím, což je platná Sfinga a funguje celkem dobře:

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"""...""" je nutné, aby se tento "surový" docstring, a tak udržet \* neporušený (pro Sphinx vyzvednout jako doslovný * a ne začátek "důrazu").

Zvolené formátování (seznam s odrážkami s typem s rodinou a popis oddělený m-pomlčkou) je jednoduše v souladu s automatizovaným formátováním, které poskytuje sfinga.

Jakmile přejdete do této snahy o to, aby sekce „Argumenty klíčových slov“ vypadala jako výchozí část „Parametry“, zdá se, že by bylo snadnější vrátit se do sekce s vlastními parametry od začátku (podle některých dalších odpovědí) , ale jako důkaz konceptu je to jeden ze způsobů, jak dosáhnout pěkného doplňku **kwargs, pokud již používáte Sphinx.

33
quornian

Dokumenty ve stylu Google analyzované sfingou

Prohlášení: není testováno.

Z tohoto výřezu příkladu sphinx docstring , *args a **kwargs jsou vlevo neexpandováno:

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.

Já bych navrhnout následující řešení pro kompaktnost:

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

Všimněte si, že Optional není vyžadováno pro argumenty **key. 

Jinak, můžete se pokusit explicitně vypsat * args pod Other Parameters a **kwargs pod Keyword Args (viz analyzované sekce ):

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

V jejich dokumentaci je příklad doctstring pro sfingu. Konkrétně zobrazují následující: 

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

I když jste se ptali na sfingu výslovně, chtěl bych také poukázat na Google Python Style Guide . Zdá se, že jejich docstring příklad naznačuje, že nevyvolávají konkrétně kwargy. (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 má otázku ohledně přijaté odpovědi odkazující na dokumentaci řízení podprocesů. Pokud importujete modul, můžete rychle zobrazit modul docstrings via inspect.getsource. 

Příklad z pythonového interpretu pomocí doporučení Silent Ghost: 

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

Samozřejmě si můžete prohlédnout dokumentaci k modulu také pomocí nápovědy. Například nápověda (podproces) 

Nejsem osobně fanouškem podprocesu docstring pro kwargs jako příklad, ale jako příklad Google to není seznam kwargs samostatně, jak je uvedeno v příkladu dokumentace 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á jsem tuto odpověď na A-B-B je otázka, protože to stojí za zmínku, že si můžete prohlédnout každý modul zdroj nebo dokumentace tímto způsobem pro postřehy a inspiraci pro komentování kódu.

6
binarysubstrate

Pokud někdo jiný hledá nějakou platnou syntaxi .. Zde je příklad docstring. Takhle jsem to udělal, doufám, že je to pro tebe užitečné, ale nemohu tvrdit, že je to v souladu s něčím zvlášť.

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

To záleží na stylu dokumentace, kterou používáte, ale pokud používáte styl numpydoc , doporučujeme dokumentovat **kwargs pomocí Other Parameters .

Například podle příkladu 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}``.
    """

Všimněte si zejména, že se doporučuje udávat výchozí hodnoty kwargs, protože tyto nejsou zřejmé z podpisu funkce.

0
Jonas Adler