1. 1. 函数类型提示的基础概念
1.1 什么是类型提示
在现代 Python 编程中，类型提示（Type Hints）并不会改变程序的运行行为，但会为代码提供明确的类型信息，便于静态分析与自动补全。通过使用 PEP 484 提出的语法约定，开发者可以在函数参数和返回值处标注类型，从而提升代码可读性和维护性。
类型提示的核心是让解释器在运行时保持原样，而在静态阶段由工具进行检查。类型信息可以来自 Python 内置的类型，也可以来自第三方模块的 typing 子模块定义的类型。这样的设计使得 Python 仍然保持动态特性，同时获得静态检查的好处。
1.2 静态类型检查的角色
静态类型检查工具（如 mypy、pyright）会在代码编写阶段对类型提示进行核对，发现潜在的类型不匹配与错误路径。通过集成到 CI/CD 流程，开发者可以在合并前捕捉到常见的类型错误，从而降低运行时异常的风险。
在嵌入式或硬件相关的项目中，静态检查同样有价值，因为它们往往涉及对外部设备接口的 API 调用和数据结构传输。采用一致的类型标注，可以使驱动程序、协议解析、以及外设通信层的代码更稳定、更易于重构。
2. 2. 基本语法与实用写法
2.1 基本语法
最常见的类型标注方式是在函数参数和返回值处添加提示。简单标注的形式是将类型写在参数名后，用 -> 指定返回类型。
常用写法示例包括为整型、字符串等基本类型标注，以及为复杂类型声明容器。
def add(a: int, b: int) -> int:return a + b
标注不仅限于数字和字符串，组合类型也很常见，例如 List、Dict 等。通过引入 typing 模块，可以表达更丰富的语义。
在一个函数的定义中，所有参数和返回值均可带有类型提示，且默认值与可选类型也可以结合使用，形成更精确的接口描述。
2.2 注解与默认值
当参数具备默认值时，类型提示仍然有效。若某个参数是可选的，可以用 Optional 来表示，即可能返回 None。这与运行时的实际值无关，只作为静态检查的约束。
将类型注解与默认值结合使用，可以让函数在不触发错误的情况下被灵活调用，同时保持清晰的 API 语义。
3. 3. 常用容器类型和泛型
3.1 List、Dict、Tuple 标注
容器类型标注是 Python 函数类型提示中最常见的场景。通过从 typing 模块引入泛型类型，例如 List[int]、Dict[str, float]、Tuple[str, int]，可以明确容器中元素的类型约束。
这样的标注有助于静态分析工具快速推断数据结构的形状，并在代码中提供更准确的自动补全信息。
from typing import List, Dict, Tupledef scale_values(values: List[float], factor: float) -> List[float]:return [v * factor for v in values]def office_map() -> Dict[str, float]:return {"Alice": 3.7, "Bob": 4.2}def first_pair(items: Tuple[str, int, float]) -> str:return items[0]
3.2 Optional、Union 与 Any 的使用
当一个参数可能具有多种类型时，可以使用 Union，例如 Union[str, int] 表示该值可能是字符串或整数。若某个值可能为 None，可以用 Optional 简化写法，即 Optional[int] 等价于 Union[int, None]。
对于某些场景，若不对类型作精确限定，使用 Any 可以绕过类型检查，但应谨慎使用，因为这会降低静态分析的效果。
4. 4. 函数高级类型：Callable、Protocol 与 TypedDict
4.1 Callable 的签名
Callable 用于描述可调用对象的参数类型与返回值类型。它常用于将函数作为参数传递给其他函数，或将回调签名进行严格约束。
通过明确输入输出签名，可以在尝试传入不兼容的回调时提前发现问题。
from typing import Callabledef apply(fn: Callable[[int, int], int], x: int, y: int) -> int:return fn(x, y)def add(a: int, b: int) -> int:return a + bresult = apply(add, 2, 3) # 5
4.2 Protocol 与结构化类型
Protocol 提供一种结构化类型的方式，强调对象的行为而非具体实现。遵循某个 Protocol 的对象，只要实现了其方法签名，就被视为符合该协议。
这在需要对不同实现进行互操作时非常有用，尤其是在大型系统或需要替换实现的场景中，减少了耦合。
from typing import Protocolclass SupportsLen(Protocol):def __len__(self) -> int: ...def len_of(x: SupportsLen) -> int:return len(x)class MyContainer:def __len__(self) -> int:return 42assert len_of(MyContainer()) == 42
4.3 TypedDict 的字典结构定义
TypedDict 允许用字典来表达固定的键集合及对应的值类型，适合描述配置信息、接口交换的数据结构等场景。
与常规 dict 相比，TypedDict 在静态检查阶段能够发现键名拼写错误或类型不符的问题。
from typing import TypedDictclass User(TypedDict):id: intname: stremail: strdef greet(u: User) -> str:return f"Hello {u['name']}"u: User = {"id": 1, "name": "Alice", "email": "alice@example.com"}
print(greet(u))
5. 5. 实战应用：静态检查、运行时校验与嵌入式场景
5.1 使用 mypy 做静态检查
在实际开发中，将类型提示与静态分析工具结合使用，可以显著提升代码质量。常见做法是将 mypy 集成到本地开发或持续集成流程中，通过对标注进行逐行检查，定位潜在的类型不一致。
执行静态检查时，工具会读取你的代码并对标注进行推断，若发现类型冲突会给出具体的错误位置与原因，从而帮助你在运行前修正问题。
# mypy 示例：假设保存为 script.py
# 运行命令：
# mypy script.pydef inc(x: int) -> int:return x + 1print(inc("1")) # 这里会在 mypy 检查时报错：Argument 1 to "inc" has incompatible type "str"
5.2 运行时类型校验的方法
尽管类型提示主要用于静态分析，但在某些应用场景下也需要运行时校验。TypeGuard 等工具可以在运行时进行类型判断，帮助分支逻辑更加健壮。
另一种常见做法是借助第三方库实现数据结构的运行时校验，如 Pydantic、schema 等。它们可以在实例化阶段对输入数据进行校验并抛出清晰的错误信息。
from typing import TypeGuarddef is_int(value: object) -> TypeGuard[int]:return isinstance(value, int)def process(value: object) -> int:if is_int(value):return value * 2raise ValueError("Expected int")print(process(5)) # 10
#print(process("5")) # 将运行时报错
5.3 嵌入式场景中的类型提示
在嵌入式开发中，诸如 MicroPython、CircuitPython 等运行环境也逐渐支持类型提示。通过在控制外设、寄存器访问、协议解析等关键路径上使用类型注解，可以提升代码的可读性并帮助后续移植与调试。
稳定的类型提示语义在硬件驱动层变得尤为重要，因为它们往往涉及时间敏感的接口与错误处理路径。
在嵌入式项目中，结合静态检查与单元测试，可以更早地发现接口不一致或数据格式错误，从而降低硬件调试成本。
