python - software - ¿Puede la esfingola Napoleón la función de documento devolver múltiples argumentos?

sphinx tutorial

Question

Estoy tratando de usar el estilo del código de Google para documentar una función para la que luego uso la esfinge con la extensión napoleón para crear documentación. La función es inusual ya que devuelve dos argumentos. No creo que Napoleón maneje esto. Si es así, ¿podría alguien decirme cómo lo manejan?

def foo(a):
''''''one line summary

longer explanation

Args:
  a (int): parameter description

Returns:
  servers (list): list of servers to use
  msg (str): logging message string 
''''''
pass

Tal vez recibo un mensaje de que no es un gran estilo de codificación para devolver múltiples argumentos, pero ¿puedes hacer esto? El html generado trata esas dos líneas como parte de una descripción para un argumento. Si coloco una nueva línea entre los servidores y la línea de mensajes, esto ayuda, pero todavía está documentando un argumento.

Answer 1

El estilo de Google no admite múltiples valores de retorno. Como solución puede utilizar:

Returns:
        2-element tuple containing

        - **rates** (*array*): the unnormalized rates (just the sum of the
          exponential kernels). To obtain rates in Hz divide the
          array by `2*tau` (or other conventional `x*tau` duration).
        - **nph** (*array*): number of photons in -5*tau..5*tau window
          for each timestamp. Proportional to the rate computed
          with KDE and rectangular kernel.

Esto da como resultado un buen resultado incluso con una descripción de varias líneas para cada artículo devuelto.

Answer 2

Python solo devuelve un solo objeto. Si llamas

serv,msg = foo(myinput)

Entonces está expandiendo explícitamente la tupla de lista de expresión que se genera cuando la función regresa con este código

return servers,msg

Usted debe leer algo como esto (con el estilo de Google de Napoleón)

"""
one line summary

longer explanation

Args:
    a (int): parameter description

Returns:
    (tuple): tuple containing:

        servers(list) servers to use
        msg (str): logging message string 
"""

O con el estilo Napoleon NumPy:

"""
one line summary

longer explanation

Parameters
----------
a : int
    parameter description

Returns
-------
servers : list
    servers to use
msg : str
    logging message string 
"""

Echa un vistazo a los documentos de Python para el return y quizás expression_list