如何注释函数参数的最大限制

Posted 2023-03-22

【中文标题】如何注释函数参数的最大限制

【英文标题】：How can I annotate a maximum limit to a function parameter

【发布时间】：2020-12-10 13:23:51

【问题描述】：

例如

def function(param):
# do something
# return value

通过使用Type hints，我可以让用户知道参数param的类型和返回值value，如下所示：

def function(param : int)-> str:
# do something
# return value

有没有办法让用户知道可以传递给函数function的最大值？

【问题讨论】：

明确一点，当您说用户时，您是指开发人员？如果是这样，如果参数超出预期，您可以提前异常。

请明确定义您想要什么。 “一种让用户意识到的方式”可以是任何东西，从注释、运行时检查、文档字符串到随机博客文章。您是专门寻找受约束的类型提示，还是只是您尝试并拒绝的示例？

是的，我正在寻找类型提示。

你能添加一个支持你需要的例子吗？？

【参考方案1】：

TLDR：如果有效值很少，请使用Literal，如果需要编程验证，请使用NewType。

---

Literal 允许静态定义允许的值。

from typing import literal

def digit_name(digit: Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) -> str: ...


digit_name(6)   # valid
digit_name(12)  # invalid

请注意，虽然Literal 在技术上仅表示这些值，但各种类型检查器确实只允许这些值的实际文字。

---

NewType 是一种类型的低开销特化。将它与在运行时检查类型以拒绝无效值的网守一起使用。

from typing import NewType

# Digit is a plain `int` at runtime, but a subclass for type checking
Digit = NewType('Digit', int)


def assert_digit(candidate: int) -> Digit:
    assert 0 <= candidate <= 9  # assert can be optimised away with `-O` if the program is known to be correct
    return Digit(candidate)

def digit_name(digit: Digit) -> str: ...


a_digit = assert_digit(3)
print(a_digit, 'is', digit_name(a_digit))        # valid
print(a_digit, 'is still', digit_name(a_digit))  # valid
print(3, 'is also still', digit_name(3))         # invalid

此模式允许在“任何值”和“已验证值”之间建立边界。虽然必须显式调用网关守卫并执行运行时检查，但静态类型检查确保网关守卫必须被调用但一次就足够了。

【参考方案2】：

在设计时，编译器或预编译器可以（在一定程度上）检查参数的类型。例如，如果您使用某个变量或表达式作为参数调用函数，编译器可以检查表达式是否应该与参数的预期类型相同。

然而，参数的值只能在运行时决定——即程序运行时。因此，不，您无法获得以这种方式限制参数的类型提示。不过，您可以让一个文档字符串提供该信息，这样用户就可以知道他们是否检查过，但编译器或 IDE 将无济于事。

还有另外两种方法：

定义一个新类型，它只能具有您愿意允许的值范围 让函数在传递错误值时引发异常（在运行时）

一种新类型：

class Int0To9(int):
    def __init__(self, value):
        assert value in range(10)
        super().__init__()


def my_func(x: Int0To9):
    print(x)


# this one will work, but shows a type hint in a good IDE
my_func(1)
# this one will also work, but shows a type hint in a good IDE - this may be a problem, the value is out of range
my_func(10)
# this one works, as expected, no hints
my_func(Int0To9(2))
# this one raises an AssertionError, before the function is even called, as the Int0To9 cannot be instantiated
try:
    my_func(Int0To9(11))
except AssertionError:
    print('error, as expected (11)')


def my_safe_func(x: int):
    assert x in range(10)
    print(x)


# no problem
my_safe_func(3)
# This now raises an assertion error as well
try:
    my_safe_func(12)
except AssertionError:
    print('error, as expected (12)')
# no problem here still
my_safe_func(Int0To9(4))


def my_very_safe_func(x: Int0To9):
    assert x in range(10)
    print(x)


# this one gives a type hint and fails correctly
try:
    my_very_safe_func(13)
except AssertionError:
    print('error, as expected (13)')
# this one gives a type hint but succeeds if you run it, as expected
my_very_safe_func(5)
# only this one runs correctly without hints
my_very_safe_func(Int0To9(6))
# this one also fails, as before
try:
    my_very_safe_func(Int0To9(14))
except AssertionError:
    print('error, as expected (14)')

结果：

1
10
2
error, as expected (11)
3
error, as expected (12)
4
error, as expected (13)
5
6
error, as expected (14)

【参考方案3】：

这样做的一种方法是使用 docstring，因此当用户键入 help(function) 时，他可以看到您在 docstring 中编写的任何内容。

示例

def function(param : int)-> str:
    """
    This function does this and returns this
    :param param: integer with a maximum of 100
    :return: anything
    """
    # do something
    # return value

那么当用户输入时

help(function)

他会看到这样的帮助信息：

Help on function function in module __main__:

function(param: int) -> str
    This function does this and returns this
    :param param: integer with a maximum of 100
    :return: anything
(END)

注意

如果用户在 Pycharm 中使用该函数（不知道在其他编辑器中是否也一样），只有将鼠标悬停在函数名称上才能看到帮助菜单。