代码收藏家技术教程 2025-01-27

从零开始：Python 新增的注解功能（Type Hints）

适用读者：对 Python 有一定基础，想了解 Python 注解（Type Hints）以及它在代码可读性、调试与维护方面的作用的朋友们。

一、什么是 Python 注解（Type Hints）？

简单来说，**Python 注解（Type Hints）**就是在变量或函数上标记“希望（或建议）它是某种类型”，从而帮助我们和其他开发者更好地理解代码，也让静态类型检查工具（如 mypy、pyright）对我们的代码进行更好的分析和错误提示。

在 Python 3.5 及之后的版本中，随着 PEP 484 的提出，Python 开始支持函数和变量的注解（也称“类型提示”）。虽然 Python 本身是“动态类型”的语言（执行时并不会强制类型），但这个功能极大地提高了代码的可读性和可维护性。

二、为什么要用注解？

提高可读性
在团队协作中，如果没有注解，光凭函数名或变量名并不能总是让人一眼看出它的数据类型。加上注解，代码可读性更强！
减少错误
借助类型检查工具，可以提前发现许多类型不匹配的问题，比如：本来需要字符串却不小心传了数字。
更好的开发体验
很多编辑器/IDE（如 VSCode、PyCharm）都支持通过类型注解来做自动补全或智能提示，提高开发效率。

三、变量注解

在 Python 3.6+ 中可以给变量添加注解的语法如下：

age: int = 18
name: str = "Alice"
is_student: bool = True

这里我们为变量标明了“希望是整数、字符串和布尔值”。在实际运行时，Python 并不会“强制”它的类型，而是作为一个提示信息留给开发者和工具去参考。但一般来说，既然标明了类型，最好就保持一致，避免混淆。

使用示例

from typing import List

numbers: List[int] = [1, 2, 3]
texts: List[str] = ["apple", "banana", "cherry"]

# 打印变量
print(numbers)
print(texts)

List[int] 表示该变量应该是一个由整数组成的列表。

List[str] 则是一个由字符串组成的列表。

四、函数注解

1. 函数参数注解

通过在函数定义时为参数“标注类型”，帮助其他人或自己在阅读时快速知道所需传入的类型：

def greet(name: str) -> None:
    print(f"Hello, {name}!")

这里 name: str 表示参数 name 希望传入一个字符串。
而 -> None 表示返回值的类型是 None（也就是没有实际返回值）。

2. 函数返回值注解

在函数定义的结尾处使用 -> 类型 来说明返回值期望的类型：

def add(x: int, y: int) -> int:
    return x + y

此处 -> int 清楚地表明函数 add 的返回值应该是整数。

3. 结合多种类型

可能有时函数的参数或返回值不止一种类型，比如：参数既可以是整数也可以是字符串。这种情况可以使用 Union：

from typing import Union

def process_data(data: Union[int, str]) -> str:
    if isinstance(data, int):
        return f"Data is an integer: {data}"
    else:
        return f"Data is a string: {data}"

上面 Union[int, str] 表示 data 可以是整数或字符串，但并不强制，依然是 Python 动态类型的灵活性。

五、常用的类型提示

基本类型：int, str, float, bool

内置容器类型：List[int], Dict[str, int], Set[str], Tuple[int, str]

可选类型：Optional[int]，实际上是 Union[int, None] 的简写，表示可以是整数也可以是 None

自定义类：使用类名本身来注解，例如 User 表示一个自定义 User 类对象

更多高级类型可以参考 typing 模块文档，比如 Generic, Callable, Any 等。

六、如何检查注解是否正确？

使用 mypy 工具
安装：pip install mypy
执行：mypy your_script.py
如果有类型不匹配的地方，mypy 会发出警告或错误提示。
使用编辑器内置功能
VSCode 在安装 Python 插件或 Pyright 插件后，会根据注解自动提示和检查类型。
PyCharm 也会对注解提供智能检测和提示。

七、完整示例

以下是一个简单的示例脚本 student.py，演示了变量注解和函数注解在同一个文件中使用：

from typing import List, Optional

def get_student_name(student_id: int, student_list: List[dict]) -> Optional[str]:
    """
    传入学生ID和学生信息列表，返回找到的学生名字。
    如果未找到，则返回 None。
    """
    for student in student_list:
        if student['id'] == student_id:
            return student['name']
    return None

# 示例数据
students: List[dict] = [
    {"id": 101, "name": "Alice"},
    {"id": 102, "name": "Bob"},
]

student_id: int = 101
name: Optional[str] = get_student_name(student_id, students)

if name is not None:
    print(f"找到学生：{name}")
else:
    print(f"未找到ID为 {student_id} 的学生。")

students: List[dict] 提示 students 是一个字典构成的列表。

函数 get_student_name 传入整型 student_id，以及一个“列表，元素为字典”的 student_list。

返回值可能为字符串或 None，所以用 Optional[str] 来注解。