Logo

Menu

ysf
ysf
Published on 2023-06-02 / 7 Visits
1

Python中的类型注解 (Type Hints)

#Python

Python 是一门动态类型语言，变量的类型由其在运行时所绑定的对象决定。这一特性为开发者提供了高度的灵活性，使得在开发过程中无需显式声明变量类型，从而提升开发效率。

然而，随着项目规模的扩大和代码量的增长，这种灵活性会带来维护上的挑战。在缺乏类型约束的情况下，开发者很难及时掌握函数参数或变量的实际类型，一旦传入错误类型的参数，由于 Python 是解释型语言，问题往往要到实际运行时才会暴露。在大型项目中，这类问题可能意味着巨大的调试成本和潜在的业务风险。

为了解决这一问题，Python 在 3.5 版本引入了类型注解 (Type Hints)，它允许开发者在代码中显式地标注变量、函数参数和返回值的预期数据类型。

需要强调的是，类型注解是可选的。Python 解释器在运行时不会对它们进行强制检查。它们的核心价值在于为开发者、静态类型检查工具（如 mypy、PyCharm 等）和集成开发环境（IDE）提供辅助信息，以增强代码的可读性、可维护性和开发效率。

为什么使用类型注解

类型注解的核心价值在于提升代码质量和开发效率，尤其在大型项目和团队协作中。

  • 提高代码可读性：类型注解让代码“自文档化”。通过 age: int 或 def greet(name: str) -> str: 的明确声明，开发者可以快速理解变量、参数的预期类型及函数的返回类型，无需深入探究实现细节。

  • 提前发现错误（静态类型检查）：配合 mypy、pyright 等静态类型检查工具，可以在代码运行前就发现潜在的类型错误。例如，当意外将字符串传给了一个期望传入整数的函数，检查工具会立即发出警告，避免程序在运行时因类型错误导致的异常。

  • 增强 IDE 支持：现代 IDE（如 PyCharm、VS Code）可以利用类型注解提供更精准的代码补全、参数提示、错误高亮，极大地提升了编码体验。

注解的基本使用

变量注解

基本语法为 variable_name: type = value

name: str = "Alice"
age: int = 30
is_active: bool = True
score: float = 98.5

# 仅声明类型，稍后赋值
count: int
count = 10

函数注解

函数注解的基本语法为：def function_name(parameter_name: type) -> return_type

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

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

Union、Optional、Any

Union

表示变量可以是定义的多种类型中的任意一种：

from typing import Union
# 表示value可以是整数或浮点数
def calculate(value: Union[int, float]):
    return value*10

Python 3.10+ 推荐写法：

def calculate(value: int | float) -> float:
    return value * 10

Optional

表示可能为 None

from typing import Optional

# 表示返回值可能为None 或类型为 str
def get_user_name(user_id: int) -> Optional[str]:
    if user_id == 1:
        return "Alice"
    return None

Python 3.10+ 推荐写法：

def get_user_name(user_id: int) -> str | None:
    if user_id == 1:
        return "Alice"
    return None

Any

表示任意类型，不做类型检查

from typing import Any

data: Any = "hello"
data = 123
data = {"key": "value"}

⚠️ 建议谨慎使用 Any，它会绕过类型检查。

容器类型注解

在 Python 3.9（PEP 585）之后，可以直接使用内置类型进行泛型标注。而在 Python 3.9 之前，如果要对列表、字典等类型进行注解，需要从 typing 模块中导入 List、Dict 等专用注解类型，代码中充斥着冗余的导入代码。

类型

Python 3.8 及以前

Python 3.9+（推荐）

列表

List[int]

list[int]

字典

Dict[str, int]

dict[str, int]

集合

Set[int]

set[int]

元组

Tuple[int, int]

tuple[int, int]

1. 列表

from typing import List, Union

# 单一类型，列表中的元素是同一类型
numbers: List[int] = [1, 2, 3]
names: List[str] = ["alice", "bob"]
# Python 3.9+
numbers: list[int] = [1, 2, 3]
names: list[str] = ["alice", "bob"]

# 混合类型，列表中元素类型可以是 int 或 str
mixed_data: List[Union[int, str]] = [1, 'hello', 2, 'world']
# Python 3.9+
mixed_data: list[Union[int, str]] = [1, 'hello', 2, 'world']
# Python 3.10+
mixed_data: list[int | str] = [1, 'hello', 2, 'world']

# 嵌套列表（二维结构）  
matrix: list[list[int]] = [  
[1, 2, 3],  
[4, 5, 6]  
]

经典应用场景：API 返回数据

def get_user_ids() -> list[int]:
    return [1001, 1002, 1003]

2. 字典

注解字典时，需要同时指定键和值的类型

from typing import Dict, List
  
# Python 3.9 之前
user_score: Dict[str, int] = {
    "Alice": 90,
    "Bob": 85
}
# 嵌套容器：键是字符串，值是字符串列表
# 例如：{"Math": ["Alice", "Bob"], "English": ["Charlie"]}
class_students: Dict[str, List[str]] = {
    "Math": ["Alice", "Bob"],
    "English": ["Charlie"]
}

#######################################

# Python 3.9+ 推荐写法
# 键是字符串，值是整数
user_scores: dict[str, int] = {
    "Alice": 90, 
    "Bob": 85
}

class_students: dict[str, list[str]] = {  
    "Math": ["Alice", "Bob"],
    "English": ["Charlie"]
}

# 函数返回字典
def get_user_info(user_id: int) -> dict[str, str | int]:  
    return {"name": "Alice", "age": 18}

3. 元组

元组通常用于表示固定结构的数据

# 固定长度 + 不同类型
user: tuple[int, str] = (1, "Alice")

# 坐标点（常见场景）
point: tuple[float, float] = (3.5, 4.2)

函数返回多个值：

def get_user() -> tuple[int, str]:
    return 1, "Alice"

不指定长度元组（元素类型相同）：

numbers: tuple[int, ...] = (1, 2, 3, 4)

4. 集合

Set 用于表示无序且不重复的元素集合

# 基础用法
unique_ids: set[int] = {1, 2, 3}

# 去重
def remove_duplicates(items: list[int]) -> set[int]:  
    return set(items)

特殊类型注解

Callable

表示可调用对象（函数、lambda、实现了 __call__ 的对象）

from typing import Callable

# Callable[[参数类型...], 返回值类型]

# 定义一个函数类型：接收两个 int，返回一个 int
func: Callable[[int, int], int] = lambda x, y: x + y

# 等价于：
def add(x: int, y: int) -> int:
    return x + y

应用场景：函数作为参数（回调函数）

from typing import Callable

def compute(a: int, b: int, op: Callable[[int, int], int]) -> int:
    return op(a, b)

result = compute(2, 3, lambda x, y: x * y)  # 6

TypeVar（泛型）

用于定义类型变量，使函数可以适用于多种类型。

from typing import TypeVar

# 定义一个类型变量 T（可以是任意类型）
T = TypeVar('T')

def first(items: list[T]) -> T:
    # items 是一个 T 类型列表
    # 返回值类型与列表元素类型一致
    return items[0]

nums = first([1, 2, 3])        # 推导为 int
names = first(["a", "b"])      # 推导为 str

为什么使用 TypeVar 而不使用 Any 呢？

# 使用 Any（类型丢失）
def first_any(items: list[Any]) -> Any:
    return items[0]

# 使用 TypeVar（类型保持一致）
def first_generic(items: list[T]) -> T:
    return items[0]

TypeVar 的核心价值：保持输入和输出类型一致

Iterable

表示可迭代对象（只要实现了迭代协议即可，例如 list、tuple、set、generator 等）

from collections.abc import Iterable

def process(items: Iterable[int]):
    # items 可以是 list / tuple / set / generator 等
    for item in items:
        print(item)
        
# process 函数可以用于多种类型
process([1, 2, 3])       # list
process((1, 2, 3))       # tuple
process({1, 2, 3})       # set
process(range(5))        # generator-like

Iterable 与 list[type] 的对比：

# 只接受 list
def process_list(items: list[int]):
    ...

# Iterable 更通用（推荐）
def process_iter(items: Iterable[int]):
    ...

  • 如果只需要遍历：使用 Iterable

  • 如果需要索引、长度：用 list[type]

Python 3.9+ 新语法总结

Python 3.9+（PEP 585）与 3.10+（PEP 604）显著简化了类型注解：

  • 使用 list[int] 替代 List[int]

  • 使用 dict[str, int] 替代 Dict[str, int]

  • 使用 | 替代 Union

如果项目使用的Python版本高于或等于3.9，推荐优先采用新语法。

注意事项

类型注解不等于类型检查，Python本身不会检查类型

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

add("1", "2")  # 不会报错（运行时拼接字符串）

类型注解的目标并不是改变 Python 的动态特性，而是在保持灵活性的前提下，引入适度的约束，从而在大型工程中提升可维护性与可读性。

curl：命令行工具
论文阅读：Attention Is...