【类型注释】Python的Type Hints（常用做法）

Python的Type Hints常用做法主要包括变量和函数的类型标注，核心原则是通过清晰的命名减少冗余注释，同时对复杂类型或函数参数/返回值进行显式标注以提高代码可读性和可维护性。

1. 优先通过命名体现类型

   若变量名能直观反映其类型和用途（如color_ls表示颜色列表、score_dict表示成绩字典），可省略显式类型标注。

   示例：

   color_ls = [] # 无需标注为List[str]，命名已表明是字符串列表score_dict = {} # 无需标注为Dict[str, int]，命名已表明是键为字符串、值为整数的字典

2. 复杂类型或模糊命名时显式标注

   若变量名无法清晰表达类型（如data、result），或类型为自定义类、第三方库类型（如numpy.ndarray），需使用类型标注。

   示例：

   from typing import List, Dict, Optionalimport numpy as npdata: List[int] = [1, 2, 3] # 明确标注为整数列表config: Dict[str, float] = {"alpha": 0.5, "beta": 1.0} # 明确标注键值类型array: np.ndarray = np.zeros(3) # 标注为NumPy数组

3. 动态类型或不确定类型时使用Any或Optional

   若变量类型可能变化或为可选值，可使用typing.Any或Optional（需配合具体类型）。

   示例：

   from typing import Any, Optionaldynamic_var: Any = 10 # 类型不确定，可能是任意类型optional_var: Optional[str] = None # 可能是字符串或None

4. 查询变量类型的方法

   对不确定类型的变量，可通过type()函数动态查询：

   import numpy as npx = np.zeros(2)print(type(x)) # 输出：<class 'numpy.ndarray'>

1. 参数和返回值必须标注

   函数参数和返回值应显式标注类型，除非参数名能完全自解释（如x: float比temp(x)更清晰）。

   示例：

   def is_zero(x: float) -> bool: """判断输入是否为0""" return x == 0

2. 复杂参数类型标注

   若参数为容器类型（如列表、字典）或第三方库类型（如numpy.ndarray），需标注具体类型。

   示例：

   import numpy as npfrom typing import Listdef process_array(x_array: np.ndarray) -> List[float]: """处理NumPy数组并返回浮点数列表""" return x_array.tolist()

3. 多返回值或可变参数标注

   使用Tuple标注多返回值，*args和kwargs需配合Any或具体类型。

   示例：

   from typing import Tuple, Anydef get_min_max(numbers: List[int]) -> Tuple[int, int]: """返回列表中的最小值和最大值""" return min(numbers), max(numbers)def log_args(*args: Any, kwargs: Any) -> None: """打印所有参数""" print(args, kwargs)

4. 类型别名提高可读性

   对复杂类型（如嵌套字典或联合类型），可通过TypeAlias定义别名。

   示例（Python 3.10+）：

   from typing import TypeAliasVector: TypeAlias = list[float] # 浮点数列表别名Matrix: TypeAlias = list[Vector] # 二维浮点数数组别名def dot_product(v1: Vector, v2: Vector) -> float: """计算两个向量的点积""" return sum(x * y for x, y in zip(v1, v2))

1. 兼容性

   Python 3.5+支持typing模块，Python 3.9+可直接使用内置类型（如list[int]替代List[int]）。

   Python 3.10+引入TypeAlias和联合类型语法（如str | int替代Union[str, int]）。

2. 工具支持

   类型标注可被静态类型检查工具（如mypy、pyright）用于检测潜在错误。

   IDE（如PyCharm、VSCode）可基于类型标注提供自动补全和错误提示。

3. 避免过度标注

   对简单脚本或快速原型开发，可省略类型标注以减少代码量。

   对大型项目或团队协作，类型标注能显著提升代码质量。