Qual è lo standard di docstring della Sfinge per i tipi di strutture di dati come gli elenchi?

Question

Does Sphinx ha uno standard supportato per documentare gli argomenti oi tipi di valori restituiti che non sono un semplice oggetto singolo?

Ad esempio, nel seguito, arg1 è uno str, arg2 è un elenco di str e arg3 è uno str o int. Come si può specificare la raccolta o i tipi di compositi in Sfinge? O non esiste uno standard comune per questo?

def function(arg1, arg2, arg3): 
    """ 
    :param arg1: Argument 1 
    :type arg1: str 
    :param arg2: Argument 2 
    :type arg2: list[str] 
    :param arg3: Argument 3 
    :type arg3: str or int 
    """ 
    pass 

Answer 1

Python 3.5 tipo accenna, mentre non è ancora supportato da Sfinge, probabilmente farà Sphinx annotazioni di tipo obsoleto un giorno. https://docs.python.org/3/library/typing.html

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

• rendere i porting più facile, e forse automatizzabili, in seguito
• specifica un modo unico ben definito di fare le cose

Esempio:

def f(list_of_int): 
    """ 
    :type list_of_int: List[int] 
    :rtype: int 
    """ 
    return list_of_int[0] + list_of_int[1] 

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

def f(list_of_int : List[int]) -> int: 
    return list_of_int[0] + list_of_int[1] 

La str or int parte può essere espresso con Union: How to express multiple types for a single parameter or a return value in docstrings that are processed by Sphinx?