如何为函数参数标注最大限制

Question

比如说

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

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

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

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

Answer 1

参数的类型可以在设计时由编译器（或预编译器）检查（到某一点）。例如，如果使用参数的某个变量或表达式调用函数，编译器可以检查该表达式是否应具有与参数预期的相同类型

但是，参数的值只能在运行时确定，即程序运行时。因此，不，您无法获得以这种方式限制参数的类型提示。您可以让docstring提供这些信息，这样用户就可以知道他们是否检查了，但是编译器或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)

Answer 2

TLDR：如果有效值很少，则使用^{}；如果需要编程验证，则使用^{}

---

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在技术上仅表示这些值，但各种类型检查器只允许这些值的实际文本

---

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

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

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

Answer 3

一种方法是使用docstring，这样当用户键入help（函数）时，他可以看到您在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中使用该函数（我不知道它在其他编辑器中是否工作相同），他只能通过将鼠标悬停在函数名称上来查看帮助菜单