Come esprimere più tipi per un singolo parametro o un valore di ritorno in docstrings elaborati da Sphinx?

Question

A volte una funzione in Python può accettare un argomento di un tipo flessibile. Oppure può restituire un valore di un tipo flessibile. Ora non riesco a ricordare un buon esempio di tale funzione in questo momento, quindi sto dimostrando che aspetto può avere una simile funzione con un esempio di giocattolo qui sotto.

Voglio sapere come scrivere le didascalie per tali funzioni utilizzando la notazione della documentazione Sphinx. Nell'esempio seguente, gli argomenti possono essere sia str o int. Allo stesso modo può restituire sia str o int.

Ho dato un esempio di docstring (sia nella notazione Sphinx di default sia nella notazione di Google compresa dall'estensione di Napoleone di Sphinx). Non so se questo è il modo giusto per documentare i tipi flessibili.

Sfinge notazione di default:

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 

Sfinge napoleon Google notazione:

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 

Qual è il modo giusto per esprimere più tipi per i parametri o restituire i valori in docstring che sono destinate ad essere trattati da Sfinge?

Answer 1

Python 3.5 Union tipo accenna

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

Per ora, mi consiglia di utilizzare la stessa sintassi quel modulo, che sarà:

• make porting facile, e possibilmente automatizzabile , più avanti il ​​
• specifica un modo canonico unico e ben definito per fare le cose

Esempio:

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

Poi, quando si dispone di 3,5, si scriverà semplicemente:

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

penso che abbia già il supporto generazione di documentazione, ma non ho ancora testato: https://github.com/sphinx-doc/sphinx/issues/1968