Python 的类型提示（type hint）

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

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

1.基本语法

python 复制代码

from typing import List, 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）变量标注：使用冒号 : 指定类型。

python 复制代码

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

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

python 复制代码

#Python 内置容器类型也可以加类型提示，需要用 typing 模块（Python 3.9+ 有些类型可直接写）。
from typing import List, 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 和 int
person: 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）

python 复制代码

#如果一个变量可能是某种类型，也可能是 None，用 Optional：

from typing import Optional

age: Optional[int] = None  #Optional[int] 等价于 Union[int, None]。
age = 20

(4) 联合类型（Union）

python 复制代码

#一个变量可能是多种类型：
from typing import Union

value: Union[int, str] = 5
value = "hello"


#python3.10可以这么写
value: int | str = 5
value = "hello"

（5）函数类型提示

python 复制代码

def greet(name: str) -> str:
    return f"Hello, {name}"

def add_numbers(a: int, b: int) -> int:
    return a + b

def process(items: list[int]) -> list[int]:
    return [i*2 for i in items]

(6) 高级类型提示

python 复制代码

#Any任何类型都可以：
from typing import Any

data: Any = 123
data = "hello"
data = [1,2,3]

python 复制代码

 #Callable表示函数类型：
from typing import Callable

def apply(func: Callable[[int, int], int], x: int, y: int) -> int:
    return func(x, y)

def add(a: int, b: int) -> int:
    return a + b

apply(add, 2, 3)  # 返回 5

#解释： `Callable[[int, int], int]` 表示一个接受两个 int 参数，返回 int 的函数

python 复制代码

#TypeVar（泛型）
from typing import TypeVar, List

T = TypeVar("T")  # 声明泛型类型   #泛型就像 "占位符类型"，它不固定具体类型，而是 在使用时才确定
def first_element(lst: List[T]) -> T:
    return lst[0]

first_element([1,2,3])   # 类型推断为 int
first_element(["a","b"]) # 类型推断为 str

2.有什么用

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

python 复制代码

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

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

python 复制代码

def add(a, b):
    return a + b

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

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

python 复制代码

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

add(2, "3")  # 静态检查工具会警告：b 类型错了

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

有了类型提示，IDE 可以：

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

示例：

python 复制代码

def greet(name: str) -> str:
    return f"Hello, {name}"

greet("Alice").   # IDE 会提示 str 的方法，比如 .upper(), .lower() 等

2.4方便团队协作和维护

python 复制代码

#在大项目中，变量和函数很多，**别人看到你的函数能快速知道它要什么类型，返回什么类型**，减少沟通成本。

# 没有类型提示
def process(data):
    ...

# 有类型提示
def process(data: list[str]) -> dict[str, int]:
    ...

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

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