Type Hint是 Python 3.5 新增的支持，中文可以译为 类型提示。屏幕前的你或许听过，又或许没有。所以今天，让我们一起了解了解。
本文基于 Python 3.10.4，部分代码需要在 Python 3.10.0 及以上运行，原因在后续文章中会有说明
本文的代码编辑器为 VS Code ，您可以选择其他现代编辑器/IDE以体验

为什么需要 Type Hint

简而言之，按我的理解，type hint的目的是写给“别人”看。这个“别人”，就包括代码编辑器、其他阅读代码的人和几天后的你自己。
废话不多说，Show You My Code!

开始写代码

现在我们假设，你想写一个函数，用处是统计给定字符串中某个字符出现的次数，于是你大手一挥，写下了这样的代码：

1
2
def count_char(text, char):
    return text.啥来着？？？

尴尬的是，你记得str类有这个方法，但却忘记了这个方法叫啥了，看看编辑器的自动提示？

image.png
遗憾的是，编辑器不知道你的text是啥类型的，自然没法帮你补全。那我们能不能告诉它：这是个str呢？可以，给参数名后面加个: str就好了
（这个空格不是必须的，只是为了好看）

image.png
这就是Type Hint的作用，通过显示指明类型告诉调用者和编辑器：我需要什么类型。这能帮助你充分利用现代编辑器的自动提示功能，并让你写出的代码更加易于阅读和维护。

一个注意点

在继续下面内容之前，我们得明确一件事：Type Hint只是手动指明我们需要的类型，但它不是强制的。举个栗子，对于这个函数，正确的使用如下：

1
2
3
4
5
def count_char(text: str, char):
    return text.count(char)

# text 参数为 str
print(count_char("Hello World", "e"))

但如果我们给text传了个别的类型，比如int，会发生什么？答案是仍然能编译通过，只是执行时报错而已。

编辑器并不报错
这就是为什么它叫Type Hint：只是提示，并非强制。
当然，我们也可以借助其他手段来实现强制的类型限定，比如借助 mypy

mypy

安装mypy很容易，只需要pip install mypy即可。之后就可以用mypy filename.py检测此类错误

image.png
当然，能在vscode中直接用更好。我们可以按ctrl+shift+p打开设置（工作区or全局，看你想法）
image.png

配置如下：

1
2
3
{
    "python.linting.mypyEnabled": true
}

即可在vscode中实时用mypy检查

image.png

基本使用

对于普通类型，用法就像刚刚说的，在名字后面加个: 类型即可

1
2
3
4
5
6
7
8
9
10
11
12
# 变量
num: int = 10
f: float = 0.7

# 自定义的类也差不多
class Node:
    def __init__(self):
        pass
        
# 函数参数
def visit_node(n: Node):
    pass

对于集合类型，我们可以使用[]指定里面元素的类型

1
2
3
4
5
6
# 列表，每个元素应该为`str`
def join_to_str(arr: list[str]):
    return "".join(arr)

join_to_str(["Funny", "SaltyFish"]) # 正确的
join_to_str([1, 2, 3]) # 错误 List item 2 has incompatible type "int"; expected "str"

Tuple用法也类似

1
2
3
4
# 值为 int，str的二元组
two_tuple: tuple[int, str] = 200, "哈哈哈"
# 值为 int 的不定长元组
t: tuple[int, ...] = (1, 2, 3, 4)

字典可以分别指定key、value的类型

1
2
3
4
5
6
7
# 指定键为`str`，值为`int`
def dict_example(d: dict[str, int]):
    pass

dict_example({"github": 1, "juejin": 2}) # 合法的
# Dict entry 0 has incompatible type "str": "str"; expected "str": "int"
dict_example({"github": "github.com/FunnySaltyFish", "juejin": 2})

注意的是，上面两个list和dict的例子在较早期的Python版本是会报错的，需要先from typing import List，再用List[str]标注类型。不过，如果你的程序希望支持到较多的Python版本，那么用List或许是更好的选择；反之就用list吧。

如果你希望此参数既可以传List，又可以传Tuple，或者传生成器，那么可以写成Iterable，它表示可迭代的。

1
2
3
4
5
6
7
8
from typing import Iterable
def iter_print(arr: Iterable):
    for each in arr:
        print(each)

iter_print(["你好","我好","她也好"])    # 列表
iter_print(("Funny", "Salty", "Fish")) # 元组
iter_print((i*2 for i in range(10)))   # 生成器

类似的更广泛类型还有Sequence和Mapping，可以自行了解

标注函数

标注函数包括几个方面：标注函数的返回类型，和标注函数类型的参数

标注函数的返回值类型

实际上，如果你把鼠标放到刚刚我们写的count_char函数上，你能看到这样的提示

image.png
智能的编辑器通过分析函数内容已经推断出了函数会返回一个int，标了个-> int，而这就是函数的返回值标注方式

1
2
3
# 返回值int
def count_char(text: str, char: str) -> int:
    return text.count(char)

如果函数没有return语句，则返回值为None

1
2
3
# 没有返回值，默认为None
def print_n() -> None:
    print("n")

如果函数是拿来抛异常，或者更极端，运行完之后程序直接退了，那可以标NoReturn

1
2
3
4
5
6
from typing import NoReturn
def exit_app() -> NoReturn:
    exit(0)
    
def exception_func() -> NoReturn:
    raise Exception("异常退出")

这样做的好处之一是，编辑器可以识别到函数调用处后面的代码不会被执行，标灰并给出Unreachable的提示

image.png

标注函数类型

如果一个参数，它要求传入的为一个函数，则可以使用Callable描述。比如下面的函数，可以对另一个函数计时

1
2
3
4
5
6
7
8
9
import time
from typing import Callable
def calc_time(func: Callable):
    start = time.time()
    func()
    end = time.time()
    print(f"此函数花费了{end-start}s")

calc_time(lambda : sum(range(10000000)))

Callable也可以指定更具体的类型，Callable[[int, int], str] 就表示参数为两个int，返回值为str的函数

更复杂的类型

接下来我们看一些更复杂的类型。
问题一： 如果一个参数可以接受所有类型，可以标成啥？
你可以不标，或者标成typing下的Any，它俩是一样的，标了类似于没标。

问题二： 如果一个参数可以接受几种不同的类型，怎么标？
这个问题在Python 3.10前有些麻烦，你需要引入Union。比如，假设这个参数可以接受int和float

1
2
3
4
5
6
7
from typing import Union
def f2(a: Union[int, float]):
    pass

f2(1)   # ok
f2(3.4) # ok
f2("s") # 错误

不过,3.10简化了这个操作。现在可以用|并列多个类型

1
2
def f2(a: int|float):
    pass

二者是等价的

1
print(Union[int, float] == int|float) # True

如果需要了解Py3.10的新特性，可以参考我的这篇文章 Python3.10正式版发布！新特性速览 - 掘金 (juejin.cn)

问题三： 如果参数可以为None呢？
使用|，比如int|None，或者使用Optional

1
2
3
4
from typing import Optional
a: Optional[int]
a = 1
a = None

问题四： 如果这个类型还没被定义，咋整？
这个情景来自类的构造函数，如果需要用到它自己，就会碰到这个问题（或者某些方法需要返回自己）。比如说定义链表的节点：

image.png
这时候可以””包围，避免循环引用

image.png

或者可以用TypeVar

1
2
3
4
5
6
7
TListNode  = TypeVar("TListNode", bound="ListNode")

class ListNode:
    def __init__(self, prev_node: TListNode|None) -> None:
        pass

node = ListNode(ListNode(None))

不过，目前仍在预览版（估计不久后就有正式版了）的Python 3.11.0加入了typing.Self，用来指自己。到时候可以这样写

1
2
3
4
from typing import Self
class ListNode:
    def __init__(self, prev_node: Self|None) -> None:
        pass

问题五： 有些类型名太长了，我打多了心累，咋办？
比如说，写http接口的响应函数，然后都处理成(状态码, 数据字典)的类型，就会是这样

1
2
def http_response():
    return 200, {"code": "0", "data": "https://juejin.cn/user/2673613109214333", "message": "https://github.com/FunnySaltyFish"}

那它的类型就得写成：

1
tuple[int, dict[str, Any]]

写多了确实麻烦。所以我们可以给这个类型起个别名：

1
2
3
4
5
from typing import TypeAlias, Any
ResponseType: TypeAlias = tuple[int, dict[str, Any]]

def http_response() -> ResponseType:
    pass

这样就统一、简洁多了
注意的是，TypeAlias是Python3.10强制的，此前的版本可以去掉。但我觉得有TypeAlias的版本比较清晰，能指明这是个类型别名。

问题六： 如果某个变量只能取特定值，怎么写？
比如sex，你想让对方只传入男、女和其他三种字符串，可以这么写

1
2
sex: Literal["男", "女", "其他"]
sex = "未知" # 错误

当然这需要import。Literal就是字面量的意思。

除上面写到的，可以用typing.Final创建一个“常量”，告知此值不可被更改

image.png

typing包下还有其他一些东东，此处就不赘述了。感兴趣的同学可以翻阅 官方文档 以了解更多。

最后

现在，你已经掌握了Type Hint的基本用法，或许可以开始使用它了。即使不是全部，但从一部分开始也是个不错的选择。毕竟代码最终是给人看的，你也不希望几个月后看着自己曾经写过的代码默默骂一句： “chao，这里应该传个啥类型来着？”

参考