it-swarm.com.de

Wie dokumentiere ich einen ** kwargs-Parameter richtig?

Ich benutze sphinx und das Autodoc-Plugin, um die API-Dokumentation für meine Python-Module zu generieren. Während ich sehen kann, wie bestimmte Parameter schön dokumentiert werden, kann ich kein Beispiel finden, wie ein **kwargs-Parameter dokumentiert wird.

Hat jemand ein gutes Beispiel für eine klare Art, diese zu dokumentieren?

70
jkp

Ich denke, dass subprocess- module docs ein gutes Beispiel ist. Geben Sie eine erschöpfende Liste aller Parameter für eine top/parent-Klasse an. Dann verweisen Sie einfach auf diese Liste für alle anderen Vorkommen von **kwargs.

14
SilentGhost

Nachdem ich diese Frage gefunden hatte, entschied ich mich für Folgendes, die Sphinx gültig ist und ziemlich gut funktioniert:

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

    """

Der r"""...""" ist erforderlich, um daraus einen "rohen" Docstring zu machen und somit den \* intakt zu halten (für Sphinx als wörtlichen * und nicht als Beginn der "Hervorhebung").

Die gewählte Formatierung (Aufzählungsliste mit Klammern und m-Bindestrich getrennte Beschreibung) entspricht einfach der von Sphinx bereitgestellten automatischen Formatierung.

Nachdem Sie sich bemüht haben, den Abschnitt "Schlüsselwortargumente" wie den Standardabschnitt "Parameter" aussehen zu lassen, scheint es einfacher zu sein, Ihren eigenen Parameterabschnitt von Anfang an zu rollen (wie in den anderen Antworten angegeben). , aber als Beweis für das Konzept ist dies ein Weg, um einen Nice-Look für zusätzlichen **kwargs zu erhalten, wenn Sie bereits Sphinx verwenden.

33
quornian

Von Sphinx analysierte Google-Style-Dokumentstrings

Haftungsausschluss: nicht getestet.

Aus diesem Ausschnitt des sphinx docstring Beispiels werden der *args und **kwargsnicht erweitert gelassen:

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.

Ich würde vorschlagen die folgende Lösung für die Kompaktheit:

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

Beachten Sie, dass Optional für **key-Argumente nicht erforderlich ist. 

Andernfalls, Sie können versuchen, die * args unter Other Parameters und **kwargs unter Keyword Args explizit aufzulisten (siehe geparste abschnitte ):

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

Es gibt ein Doctstring-Beispiel für Sphinx in ihrer Dokumentation. Im Einzelnen zeigen sie Folgendes: 

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

Obwohl Sie explizit nach sphinx gefragt haben, möchte ich auch auf den Google Python Style Guide verweisen. Ihr Docstring-Beispiel scheint darauf hinzudeuten, dass sie Kwargs nicht speziell aufrufen. (other_silly_variable = keine) 

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 hat eine Frage nach der akzeptierten Antwort der Referenzierung der Unterprozessverwaltungsdokumentation. Wenn Sie ein Modul importieren, können Sie die Modul-Docstrings schnell über inspect.getsource anzeigen. 

Ein Beispiel aus dem Python-Interpreter, der die Empfehlung von Silent Ghost verwendet: 

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

Natürlich können Sie die Dokumentation des Moduls auch über die Hilfefunktion anzeigen. Zum Beispiel Hilfe (Subprozess) 

Ich bin kein Fan des Subprozess-Docstrings für Kwargs als Beispiel, aber wie das Google-Beispiel werden Kwargs nicht separat aufgeführt, wie im Sphinx-Dokumentationsbeispiel gezeigt. 

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()

Ich füge diese Antwort auf die Frage von A-B-B bei, weil es erwähnenswert ist, dass Sie die Quellen oder Dokumentation jedes Moduls auf diese Weise überprüfen können, um Einblicke und Anregungen für die Kommentierung Ihres Codes zu erhalten.

6
binarysubstrate

Wenn jemand anderes nach einer gültigen Syntax sucht .. Hier ein Beispiel für einen Docstring. So habe ich es gemacht, ich hoffe es ist nützlich für Sie, aber ich kann nicht behaupten, dass es mit irgendetwas konform ist.

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

Dies hängt vom verwendeten Dokumentationsstil ab. Wenn Sie jedoch den numpydoc -Stil verwenden, wird empfohlen, **kwargs mithilfe von Other Parameters zu dokumentieren.

Zum Beispiel das Beispiel von 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}``.
    """

Beachten Sie insbesondere, dass es empfohlen wird, die Standardwerte von Kwargs anzugeben, da diese nicht aus der Funktionssignatur ersichtlich sind.

0
Jonas Adler