Python typing模块常用类型注解的正确写法

类型注解为Python代码提供了清晰的“路标”，明确指出变量应是什么类型、函数期望接收什么参数以及会返回什么。typing模块是实现这一目标的核心工具。掌握其常用类型的正确写法，能显著提升代码的可读性和可维护性，并为静态类型检查工具（如mypy）打下基础。

第一部分：基础类型注解

最基础的注解直接使用Python内置类型名称。

1. 导入 typing 模块。

   import typing
   # 为了方便，通常使用 from typing import ... 的形式导入具体类型
   from typing import List, Dict, Any, Optional, Union

2. 为变量添加类型注解。
   在变量名后添加一个冒号 :，然后跟上类型。

   name: str = "Alice"
   age: int = 30
   is_student: bool = False

3. 使用特殊类型 Any。
   Any 表示任意类型，相当于禁用了类型检查。仅在类型确实无法确定时使用。

   def process(data: Any) -> None:
       # 可以对 `data` 进行任何操作，类型检查器不会报错
       pass

第二部分：容器类型与嵌套

处理列表、字典等容器时，需要精确描述其内部元素的类型。

1. 使用 List 注解列表。
   从 typing 导入 List，并用方括号 [] 指定元素类型。

   from typing import List
   scores: List[int] = [90, 85, 92]
   names: List[str] = ["Bob", "Charlie"]

2. 使用 Dict 注解字典。
   用 Dict 注解，并在方括号内依次指定键和值的类型，用逗号分隔。

   from typing import Dict
   user_info: Dict[str, str] = {"username": "dave", "email": "dave@example.com"}
   # 一个键为字符串，值为整数列表的字典
   grade_book: Dict[str, List[int]] = {"Math": [90, 85], "Science": [88, 92]}

3. 使用 Set 和 Tuple 注解集合与元组。
   Set 的注解方式与 List 类似。Tuple 需要指定每个位置元素的确切类型，或者使用 ... 表示任意长度的同构元组。

   from typing import Set, Tuple
   unique_ids: Set[int] = {1, 2, 3}
   # 一个包含特定类型顺序的元组
   point: Tuple[float, float] = (1.0, 2.5)
   # 一个任意长度、全为字符串的元组（等价于 Tuple[str, ...]）
   aliases: Tuple[str, ...] = ("alias1", "alias2", "alias3")

第三部分：函数注解

函数注解是最强大的部分，能明确函数的输入输出契约。

1. 注解函数参数与返回值。
   在参数名后加 : 类型，在函数声明末尾加 -> 返回类型。

   def add(a: int, b: int) -> int:
       return a + b
   
   def greet(name: str) -> str:
       return f"Hello, {name}!"

2. 处理可选参数与 None 返回值。
   当一个参数可以接受 None，或者函数可能不返回任何有效值（即返回 None）时，使用 Optional。Optional[X] 等价于 Union[X, None]。

   from typing import Optional
   def find_user(user_id: int) -> Optional[str]:
       # 可能根据ID找到用户并返回名字，也可能找不到，返回None
       if user_id == 1:
           return "Alice"
       return None
   
   def log_message(message: str, prefix: Optional[str] = None) -> None:
       # `prefix` 参数可以传字符串，也可以不传（默认为None）
       if prefix:
           print(f"{prefix}: {message}")
       else:
           print(message)

3. 使用联合类型 Union。
   当一个变量或参数可以是多种类型之一时，使用 Union[type1, type2, ...]。在Python 3.10+中，可以用 type1 | type2 语法代替。

   from typing import Union
   # 支持整数或字符串ID
   def get_record(id: Union[int, str]) -> dict:
       pass
   # Python 3.10+ 写法
   # def get_record(id: int | str) -> dict:
   #     pass

第四部分：高级与常用类型

一些在实际项目中频繁使用的高级类型。

1. 使用 TypeAlias 创建类型别名。
   为复杂的类型组合创建一个简洁的别名，提高可读性。Python 3.10+ 推荐使用 TypeAlias 进行显式声明。

   from typing import TypeAlias, Dict, List
   # Python 3.10+ 使用 TypeAlias
   UserId: TypeAlias = int
   Users: TypeAlias = Dict[UserId, str]  # 假设用户ID映射到用户名
   Vector: TypeAlias = List[float]       # 一个数字向量
   # 使用别名进行注解
   def scale_vector(v: Vector, factor: float) -> Vector:
       return [x * factor for x in v]

2. 使用 Callable 注解可调用对象。
   用于注解函数、lambda 表达式等可以被调用的对象。Callable[[参数类型列表], 返回类型]。

   from typing import Callable
   # `callback` 是一个函数，它接受两个整数并返回一个字符串
   def execute_callback(callback: Callable[[int, int], str], x: int, y: int) -> str:
       return callback(x, y)
   
   # 一个简单的函数作为callback
   def my_formatter(a: int, b: int) -> str:
       return f"Result: {a + b}"

3. 使用 TypeVar 创建泛型。
   TypeVar 用于定义泛型函数或类，表示一个“待定”的类型，在具体使用时会被实例化为某个具体类型。这是实现类型安全容器或函数的关键。

   from typing import TypeVar, List
   T = TypeVar('T')  # 声明一个类型变量
   
   def first_element(lst: List[T]) -> T:
       # 返回类型与输入列表的元素类型相同
       return lst[0]
   
   # 调用时，类型推断会生效
   int_first = first_element([1, 2, 3])       # int_first 被推断为 int
   str_first = first_element(["a", "b"])      # str_first 被推断为 str