Python 的类型提示（type hint）

Python 的类型提示（Type Hints）是 Python 3.5 引入的一项特性（通过 PEP 484），它允许开发者在代码中标注变量、函数参数和返回值的预期类型。这些提示不会在运行时强制执行（Python 仍是动态类型语言），而是用于静态分析工具（如 mypy、pyright）、IDE（如 PyCharm、VS Code）和代码文档化，帮助及早发现类型错误、提升代码可读性和维护性。类型提示有以下特点：

• 早期错误检测：静态类型检查器可以在运行前发现类型不匹配。
• 代码文档化：类型标注让函数签名更清晰，便于团队协作。
• IDE 支持：自动补全、重构和导航更智能。
• 重构安全：修改类型时，工具会提示受影响的地方。
• 无运行时开销：提示仅在开发阶段生效，运行时代码不

1.基本语法

fromtypingimportList,Dict,Union,Optional,...

包含以下类型”：

类型	示例
int	x: int = 5
float	y: float = 3.14
str	name: str = "Alice"
bool	flag: bool = True
None	value: None = None

（1）变量标注：使用冒号 : 指定类型。

age:int=30# age 预期为整数name:str="Alice"

(2) 容器类型提示（列表、字典、元组）

#Python 内置容器类型也可以加类型提示，需要用 typing 模块（Python 3.9+ 有些类型可直接写）。fromtypingimportList,Dict,Tuple# List[int] 表示整数列表numbers:List[int]=[1,2,3]# Dict[str, int] 表示键为 str，值为 int 的字典ages:Dict[str,int]={"Alice":25,"Bob":30}# Tuple[str, int] 表示长度为2的元组，类型分别为 str 和 intperson:Tuple[str,int]=("Alice",25)# 如果元组长度不固定，可以用 Tuple[int, ...]points:Tuple[int,...]=(1,2,3,4)#3.9简化写法---从 Python 3.9 开始，内置容器类型（如 list、dict、tuple、set 等）可以直接使用泛型语法，不需要再从 typing 模块导入 List、Dict、Tuple 等大写版本。numbers:list[int]=[1,2,3]ages:dict[str,int]={"Alice":25}

（3）可选类型（Optional）

#如果一个变量可能是某种类型，也可能是 None，用 Optional：fromtypingimportOptional age:Optional[int]=None#Optional[int] 等价于 Union[int, None]。age=20

(4) 联合类型（Union）

#一个变量可能是多种类型：fromtypingimportUnion value:Union[int,str]=5value="hello"#python3.10可以这么写value:int|str=5value="hello"

（5）函数类型提示

defgreet(name:str)->str:returnf"Hello,{name}"defadd_numbers(a:int,b:int)->int:returna+bdefprocess(items:list[int])->list[int]:return[i*2foriinitems]

(6) 高级类型提示

#Any任何类型都可以：fromtypingimportAny data:Any=123data="hello"data=[1,2,3]

#Callable表示函数类型：fromtypingimportCallabledefapply(func:Callable[[int,int],int],x:int,y:int)->int:returnfunc(x,y)defadd(a:int,b:int)->int:returna+bapply(add,2,3)# 返回 5#解释： `Callable[[int, int], int]` 表示一个接受两个 int 参数，返回 int 的函数

#TypeVar（泛型）fromtypingimportTypeVar,List T=TypeVar("T")# 声明泛型类型 #泛型就像 “占位符类型”，它不固定具体类型，而是 在使用时才确定deffirst_element(lst:List[T])->T:returnlst[0]first_element([1,2,3])# 类型推断为 intfirst_element(["a","b"])# 类型推断为 str

2.有什么用

2.1 提高代码可读性（给别人和自己看的说明书）

#类型提示就像在代码上贴标签，告诉别人“这个变量是什么类型”，不用去猜。defadd(a:int,b:int)->int:returna+b

• 不看函数实现，你就知道a、b是整数，返回值也是整数。
• 如果没有类型提示，你只能看实现或者通过测试才能确认类型：

defadd(a,b):returna+b

如果别人传了"hello"，你才会发现出错。

2.2静态检查工具能帮你找错误（提前发现 bug）

#Python 运行时才报错，但用 **类型提示 + 静态检查工具**（如 mypy、PyCharm、VS Code）可以在写代码时发现类型问题。defadd(a:int,b:int)->int:returna+b add(2,"3")# 静态检查工具会警告：b 类型错了

2.3 IDE 提供智能提示（自动补全更精准）

有了类型提示，IDE 可以：

• 自动补全方法和属性
• 提供函数参数提示
• 提前发现类型错误

示例：

defgreet(name:str)->str:returnf"Hello,{name}"greet("Alice").# IDE 会提示 str 的方法，比如 .upper(), .lower() 等

2.4方便团队协作和维护

#在大项目中，变量和函数很多，**别人看到你的函数能快速知道它要什么类型，返回什么类型**，减少沟通成本。# 没有类型提示defprocess(data):...# 有类型提示defprocess(data:list[str])->dict[str,int]:...

• 前者要看实现才能理解
• 后者一眼就知道：输入是字符串列表，输出是字符串到整数的字典

如果项目很大或者长期维护，类型提示像安全网：代码改动时，类型检查可以防止不小心把数字改成字符串导致程序崩溃，方便自动生成文档、代码分析工具、甚至部分优化