为 returns 只有一组特定值的函数键入提示

Question

我有一个函数只能returna、b或c，都是T类型。我想在签名中包含这个事实，因为它们在函数上下文中具有特殊含义。我该怎么做？

目前我用这个

def fun(...) -> "a or b or c":
    #briefly explain the meaning of a, b and c in its docstring

这是正确的吗？

我知道我能做到

def fun(...) -> T:
    # briefly explain the meaning of a, b and c in its docstring

但正如我所说，我想在签名中表达该函数仅 return 那些特定值。

Answer 1

如果所有类型都完全相同，只需 将其添加为 return 类型:

def func(...) -> T: # or int or whatever else

I want to express in the signature that the function only return those specific values

类型提示不指定名称或值，它们只指定类型；类型检查器尝试 act 提供的 type。

如果您只是出于文档目的这样做，请根据需要添加 'a or b or c'；用户会理解它，但类型检查器不会而且他们肯定不会对此采取行动。

Answer 2

您不能单独使用类型提示来指定您的函数 return 只是类型值的一个子集。顾名思义，类型提示是关于类型而不是值。

但是，您可以创建一个新的 enum.Enum 子类型，它只包含您要 return 的值，并在函数中使用它。然后你可以输入提示你正在 return枚举类型。

import enum

class cmp_results(enum.IntEnum):
    less = -1
    equal = 0
    greater = 1

def my_cmp_function(x, y) -> cmp_results:
    if x < y: return cmp_results.less
    elif x == y: return cmp_results.equal
    else: return cmp_results.greater

这可能有点矫枉过正。只是暗示 int 作为 return 类型（并记录具体值）可能就足够了。

Answer 3

你可以用 literal types 来做到这一点。

from typing_extensions import Literal
# from typing import Literal  # Python 3.8 or higher

def fun(b: int) -> Literal["a", "b", "c"]:
    if b == 0:
        return "a"
    if b == 1:
        return "b"
    return "d"

mypy 能够将 return "d" 检测为无效语句：

error: Incompatible return value type (got "Literal['d']",
expected "Union[Literal['a'], Literal['b'], Literal['c']]")

Python 3.8

感谢 Python 3.8 typing 模块中默认的 PEP 586, the Literal is already included。

为 returns 只有一组特定值的函数键入提示

Type hint for a function that returns only a specific set of values

python

literals

type-hinting

python-3.x

python-typing

你可以用 literal types 来做到这一点。

Python 3.8