如何在Sphinx處理的文檔字符串中爲單個參數或返回值表示多種類型？

Question

有時Python中的函數可以接受一個靈活的類型的參數。或者它可能會返回一個靈活類型的值。現在我不記得現在這樣一個功能的好例子，因此我正在演示下面的一個玩具例子，這個功能可能是什麼樣子。

我想知道如何編寫使用獅身人面像文檔批註等功能的文檔字符串。在下面的例子中，參數可以是str或int。同樣，它可能會返回str或int。

我給一個例子文檔字符串（無論是在默認的獅身人面像的符號，以及谷歌將通過符號獅身人面像的拿破崙擴展理解）。我不知道這是否是記錄靈活類型的正確方法。

獅身人面像默認符號：

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 

獅身人面像拿破崙谷歌表示法：

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 

什麼是表達多種類型的參數或在旨在通過處理文檔字符串返回值的正確方法獅身人面像？

Answer 1

的Python 3.5 Union型現在暗示

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

因爲，我建議使用完全相同的語法爲模塊，這將：

• 使移植更容易，並且可能自動化，後來
• 指定唯一明確的規範的方式來做事

例子：

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

然後，當你有3.5，你會這樣寫：

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

我認爲它已經生成文檔的支持，但我還沒有測試它尚未： https://github.com/sphinx-doc/sphinx/issues/1968