如何在Python的函数文档字符串中指定多种返回类型？

Question

我知道用于为Google样式生成文档字符串的语法，例如：

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        bool: The return value. True for success, False otherwise.

    """

但是，如果我有一个函数可以根据执行的代码分支返回多种类型，该怎么办？记录此问题的正确方法是什么？

下面是一个例子。 Returns部分应放什么？

def foo(x, y):
    """Dummy function.

    Args:
        x (int): integer
        y (int): integer

    Returns:
        list/dict: either list or a dict depending on...

    """
    if x > y:
        return [1, 2, 3]
    if x < y:
        return {1:2}

example显示了两种不同的可能的返回类型：

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

但是，我想知道提供类型和描述的最佳方法是什么，以便拿破仑能够以本机支持它，并且阅读文档也很容易。

使用int/str: %description%是处理多种返回类型的唯一方法吗？

    Returns:
      int/str: integer if a > b and a string otherwise

Answer 1

如果要使用批注来指定根据函数结果而不同类型的返回类型，则可以通过以下方式做到这一点：

from typing import Type, Dict, Optional

def function(self) -> Optional[dict, str]:
    if self.result:
        return self.result
    else:
        return "Empty result"

Here，您可以找到更多信息