Was ist der richtige Weg, um einen ** KWARGS -Parameter zu dokumentieren?

Question

Ich benutze Sphinx und das Autodoc -Plugin, um API -Dokumentation für meine Python -Module zu generieren. Während ich sehen kann, wie ich spezifische Parameter gut dokumentieren kann, kann ich kein Beispiel dafür finden, wie man a dokumentiert **kwargs Parameter.

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

Answer 1

Ich finde subprocess-modules docs ist ein gutes Beispiel. Geben Sie eine umfassende Liste aller Parameter für a Top/Elternklasse. Dann beziehen Sie sich einfach auf diese Liste für alle anderen Ereignisse von **kwargs.

Answer 2

Nachdem ich diese Frage gefunden hatte, habe ich mich für Folgendes entschieden, was 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

    """

Das r"""...""" ist erforderlich, um dies zu einem "rohen" Docstring zu machen und damit die \* intakt (für Sphinx als wörtlicher Aufnahme * und nicht der Beginn der "Betonung").

Die ausgewählte Formatierung (kugele Liste mit mit Klammern und mit M-Durchschichtung getrennter Beschreibung) kann lediglich mit der von Sphinx bereitgestellten automatisierten Formatierung übereinstimmen.

Sobald Sie diesen Abschnitt "Keyword -Argumente" wie den Abschnitt "Standard -" -Parameter "aussehen, scheint es, als wäre es möglicherweise einfacher, Ihren eigenen Parameter von Anfang an zu rollen (nach einigen anderen Antworten). Aber als Beweis für das Konzept ist dies eine Möglichkeit, einen schönen Look für ergänzende Ergänzung zu erreichen **kwargs Wenn Sie bereits Sphinx verwenden.

Answer 3

Google Style Docstrings analysiert von Sphinx

Haftungsausschluss: Nicht getestet.

Aus diesem Ausschnitt der Sphinx docstring Beispiel, das *args und **kwargs sind übrig nicht übertroffen:

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

Beachte wie, Optional ist nicht erforderlich für **key Argumente.

Andernfalls, Sie können versuchen, die *args unter explizit aufzulisten Other Parameters und **kwargs unter dem Keyword Args (Siehe Parsen 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 
        ...

Answer 4

Da ist ein Doctstring -Beispiel für Sphinx in ihrer Dokumentation. Insbesondere 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 nach gefragt haben Sphinx explizit würde ich auch auf die verweisen Google Python Style Guide. Ihr docString -Beispiel scheint zu implizieren, dass sie KWARGS nicht speziell aufrufen. (OTERE_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

ABB hat eine Frage zur akzeptierten Antwort auf die Referenzierung der Unterprozess -Management -Dokumentation. Wenn Sie ein Modul importieren, können Sie die Moduldocstrings über inspect.getSource schnell sehen.

Ein Beispiel aus dem Python -Dolmetscher unter Verwendung der Empfehlung des Silent Ghost:

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

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

Ich persönlich bin nicht persönlich ein Fan der Subprozess -Docstring für KWARGS als Beispiel, aber wie im Google -Beispiel wird KWARGs nicht separat aufgelistet, wie im Beispiel für die Sphinx -Dokumentation 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 in die Frage von ABB hinzu, da es erwähnenswert ist, dass Sie die Quelle oder Dokumentation eines Moduls auf diese Weise überprüfen können, um Einblicke und Inspiration für das Kommentieren Ihres Codes zu erhalten.

Answer 5

Wenn jemand anderes nach einer gültigen Syntax sucht, ist hier ein Beispiel docstring. So habe ich es gemacht, ich hoffe es ist für Sie nützlich, aber ich kann nicht behaupten, dass es mit etwas Besonderem entspricht.

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

Answer 6

Dies hängt vom Dokumentationsstil ab, den Sie verwenden, aber wenn Sie die verwenden Numpydoc Stil Es wird empfohlen, zu dokumentieren **kwargs Verwendung Other Parameters.

Zum Beispiel folgen Sie Quornians Beispiel:

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 Standardeinstellungen von KWARGs anzugeben, da diese nicht aus der Funktionssignatur ersichtlich sind.