lista - funciones en python

¿Cómo expresar varios tipos para un solo parámetro o un valor de retorno en las cadenas de documentos procesadas por Sphinx?

Question

A veces, una función en Python puede aceptar un argumento de un tipo flexible. O puede devolver un valor de un tipo flexible. Ahora no puedo recordar un buen ejemplo de tal función en este momento, por lo tanto, estoy demostrando cómo se ve esa función con un ejemplo de juguete a continuación.

Quiero saber cómo escribir cadenas de documentación para dichas funciones utilizando la notación de documentación de Sphinx. En el siguiente ejemplo, los argumentos pueden ser str o int . Del mismo modo puede devolver str o int .

He dado un ejemplo de cadenas de documentación (tanto en la notación predeterminada de Sphinx como en la notación de Google entendida por la extensión napoleón de Sphinx). No sé si esta es la forma correcta de documentar los tipos flexibles.

Notación por defecto de Sphinx:

def add(a, b):
    """Add numbers or concatenate strings.

    :param int/str a: String or integer to be added
    :param int/str b: String or integer to be added
    :return: Result
    :rtype: int/str
    """
    pass

Esfinge napoleon de notación de Google:

def add2(a, b):
    """Add numbers or concatenate strings.

    Args:
      a (int/str): String or integer to be added
      b (int/str): String or integer to be added

    Returns:
      int/str: Result
    """
    pass

¿Cuál es la forma correcta de expresar varios tipos de parámetros o valores de retorno en las cadenas de documentos que deben ser procesadas por Sphinx?

Answer 1

Consejos tipo Python 3.5 Union

https://docs.python.org/3/library/typing.html#typing.Union

Por el momento, recomiendo usar la misma sintaxis que el módulo, que:

• Facilita la portabilidad, y posiblemente se automatiza, más adelante
• Especifica una forma canónica única y bien definida para hacer las cosas.

Ejemplo:

def f(int_or_float):
    """
    :type int_or_float: Union[int, float]
    :rtype: float
    """
    return int_or_float + 1.0

Luego, cuando tengas 3.5, escribirás solo:

def f(list_of_int : Union[int, float]) -> float:
    return int_or_float + 1.0

Creo que ya tiene soporte para la generación de documentación, pero aún no lo he probado: https://github.com/sphinx-doc/sphinx/issues/1968