python - how - ¿Cuál es la forma correcta de documentar un parámetro de** kwargs?

sphinx python

Question

Estoy usando sphinx y el complemento autodoc para generar documentación API para mis módulos de Python. Aunque puedo ver cómo se pueden documentar parámetros específicos, no puedo encontrar un ejemplo de cómo documentar un parámetro **kwargs .

¿Alguien tiene un buen ejemplo de una forma clara de documentar esto?

Answer 1

Creo que los documentos del subprocess -module son un buen ejemplo. Proporcione una lista exhaustiva de todos los parámetros para una clase superior / principal . Luego solo consulte esa lista para todas las demás ocurrencias de **kwargs .

Answer 2

Después de encontrar esta pregunta, decidí lo siguiente, que es válido para Sphinx y funciona bastante 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

    """

El r"""...""" es necesario para hacer de este un docstring "en bruto" y así mantener el /* intacto (para Sphinx recoger como literal * y no como el comienzo de "énfasis").

El formato elegido (lista con viñetas con tipo entre paréntesis y descripción separada por m-dash) es simplemente para que coincida con el formato automático proporcionado por Sphinx.

Una vez que ha realizado este esfuerzo de hacer que la sección "Argumentos de las palabras clave" se parezca a la sección "Parámetros" predeterminada, parece que podría ser más fácil rodar su propia sección de parámetros desde el principio (según algunas de las otras respuestas) , pero como una prueba de concepto, esta es una forma de lograr un aspecto agradable para **kwargs suplementarios si ya está usando Sphinx.

Answer 3

Esto depende del estilo de la documentación que use, pero si usa el estilo numpydoc , se recomienda documentar **kwargs utilizando Other Parameters .

Por ejemplo, siguiendo el ejemplo 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}``.
    """

Tenga en cuenta especialmente que se recomienda dar los valores predeterminados de kwargs, ya que estos no son evidentes a partir de la firma de la función.

Answer 4

Hay un ejemplo de doctstring para Sphinx en su documentación. Específicamente muestran lo siguiente:

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

Aunque me preguntó acerca de sphinx explícitamente, también apuntaría a la Guía de estilo de Google Python . Su ejemplo de docstring parece implicar que no llaman kwargs específicamente. (other_silly_variable = Ninguna)

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 tiene una pregunta sobre la respuesta aceptada al hacer referencia a la documentación de gestión del subproceso. Si importa un módulo, puede ver rápidamente las cadenas de documentos del módulo a través de inspect.getsource.

Un ejemplo del intérprete de Python que usa la recomendación de Silent Ghost:

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

Por supuesto, también puede ver la documentación del módulo a través de la función de ayuda. Por ejemplo ayuda (subproceso)

Personalmente, no soy partidario del subproceso docstring para kwargs como ejemplo, pero al igual que el ejemplo de Google, no incluye los kwargs por separado, como se muestra en el ejemplo de documentación de 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()

Incluyo esta respuesta a la pregunta de ABB porque vale la pena señalar que puede revisar la fuente o la documentación de cualquier módulo de esta manera en busca de ideas e inspiración para comentar su código.

Answer 5

Si alguien más está buscando una sintaxis válida ... Aquí hay un ejemplo de docstring. Así es como lo hice, espero que sea útil para ti, pero no puedo afirmar que cumple con nada en particular.

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

Docstrings de Google Style analizados por Sphinx

Descargo de responsabilidad: no probado.

Desde este corte del ejemplo de docstring de sphinx , los *args y **kwargs quedan sin expandir :

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.

Sugeriría la siguiente solución para compactibilidad:

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

Observe cómo, Optional no es necesario para **key argumentos **key .

De lo contrario , puede intentar hacer una lista explícita de * args en Other Parameters y **kwargs en Keyword Args (ver sections analizadas):

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