Wie können mehrere Typen für einen einzelnen Parameter oder einen Rückgabewert in DocStrings ausgedrückt werden, die von Sphinx verarbeitet werden?

Question

Manchmal akzeptiert eine Funktion in Python ein Argument eines flexiblen Typs. Oder es kann einen Wert eines flexiblen Typs zurückgeben. Jetzt kann ich mich an kein gutes Beispiel für eine solche Funktion erinnern, deshalb zeige ich, wie eine solche Funktion mit einem Spielzeugbeispiel aussehen könnte.

Ich möchte wissen, wie man Docstrings für solche Funktionen mit der Sphinx-Dokumentation Notation schreiben. Im folgenden Beispiel können die Argumente entweder str oder int lauten. Ebenso kann es entweder str oder int zurückgeben.

Ich habe ein Beispiel Docstrings (sowohl in der Standard-Sphinx-Notation sowie die Google-Notation von Sphinx Napoleon-Erweiterung verstanden). Ich weiß nicht, ob dies der richtige Weg ist, um die flexiblen Typen zu dokumentieren.

Sphinx Standardnotation:

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 

Sphinx napoleon Google Notation:

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 

Was ist der richtige Weg mehrere Typen für Parameter oder Rückgabewerte in Docstrings auszudrücken, die verarbeitet werden sollen durch Sphinx?

Answer 1

Python 3.5 Union Typ Hinweise

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

Vorerst empfehle ich die exakt gleiche Syntax wie dieses Modul verwenden, das wird:

• erleichtern die Portierung und möglicherweise automatisierbare , später
• spezifiziert eine einzigartige gut definierte kanonische Art, Dinge zu tun

Beispiel:

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

Dann, wenn Sie 3.5 haben, schreiben Sie einfach:

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

ich denke, es bereits Dokumentation Generation Unterstützung hat, aber ich habe es noch nicht getestet: https://github.com/sphinx-doc/sphinx/issues/1968