Python高级技术之：`Python`的类型提示：`mypy`和`typing`模块在大型项目中的应用。

各位观众，大家好！我是今天的主讲人，很高兴能和大家一起聊聊Python类型提示这个话题。别担心，今天咱们不搞那种让人昏昏欲睡的学院派理论，就来点实在的，说说在大型项目中，mypy和typing模块到底能帮我们解决什么问题，以及怎么用它们让我们的代码更健壮、更易维护。

开场白：类型提示，你的代码“体检报告”

想象一下，你写了一个非常复杂的函数，经过几个月的迭代，你已经忘了当初设计它的初衷。现在，你要修改这个函数，但又害怕改坏了。这时候，如果你的代码有详细的“体检报告”——也就是类型提示，是不是就能心里更有底了？

类型提示就像是给你的Python代码加上了静态类型检查的“超能力”。虽然Python本身是动态类型语言，但这并不意味着我们不能给它加上类型信息。typing模块提供了定义类型提示的标准方式，而mypy则是一个静态类型检查器，可以根据这些类型提示来检查你的代码是否存在类型错误。

第一部分：typing模块：类型提示的“百宝箱”

typing模块是Python 3.5引入的标准库，它提供了各种类型构造器，让我们能更精确地描述变量、函数参数和返回值的类型。

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

这几个是最常用的类型，就不多说了，直接上代码：

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

name: str = "Alice"
age: int = 30
price: float = 9.99
is_valid: bool = True

2. 容器类型：List, Tuple, Dict, Set

typing模块提供了泛型版本的容器类型，可以指定容器内元素的类型。

from typing import List, Tuple, Dict, Set

numbers: List[int] = [1, 2, 3, 4, 5]
coordinates: Tuple[float, float] = (3.14, 2.71)
user_data: Dict[str, str] = {"name": "Bob", "email": "[email protected]"}
unique_numbers: Set[int] = {1, 2, 3}

3. Optional：可选项类型

Optional[T] 等价于 Union[T, None]，表示变量可能为 T 类型，也可能为 None。

from typing import Optional

def get_user_name(user_id: int) -> Optional[str]:
  # 假设从数据库中获取用户信息
  if user_id == 1:
    return "Charlie"
  else:
    return None

name: Optional[str] = get_user_name(2)
if name:
  print(f"User name: {name}")
else:
  print("User not found.")

4. Union：联合类型

Union[T1, T2, ...] 表示变量可以是 T1, T2 等类型中的任何一种。

from typing import Union

def process_data(data: Union[int, str]) -> str:
  if isinstance(data, int):
    return f"Integer: {data}"
  elif isinstance(data, str):
    return f"String: {data}"
  else:
    return "Unknown type"

print(process_data(123))
print(process_data("Hello"))

5. Any：任意类型

Any 表示变量可以是任何类型。尽量避免使用 Any，因为它会失去类型检查的意义。

from typing import Any

def do_something(x: Any) -> None:
  print(x)

do_something(123)
do_something("World")

6. Callable：可调用类型

Callable[[Arg1Type, Arg2Type, ...], ReturnType] 用于描述函数类型。

from typing import Callable

def apply_function(func: Callable[[int, int], int], x: int, y: int) -> int:
  return func(x, y)

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

result: int = apply_function(add, 5, 3)
print(result)

7. TypeVar：类型变量

TypeVar 允许你定义泛型函数或类。

from typing import TypeVar, List

T = TypeVar('T')  # 定义一个类型变量 T

def first_element(items: List[T]) -> T:
  return items[0]

numbers: List[int] = [1, 2, 3]
first_number: int = first_element(numbers)  # mypy 会推断 first_number 的类型为 int

strings: List[str] = ["a", "b", "c"]
first_string: str = first_element(strings)  # mypy 会推断 first_string 的类型为 str

8. Generic：泛型类

Generic 用于定义泛型类。

from typing import TypeVar, Generic

T = TypeVar('T')

class Box(Generic[T]):
  def __init__(self, content: T):
    self.content = content

  def get_content(self) -> T:
    return self.content

integer_box: Box[int] = Box(10)
integer_content: int = integer_box.get_content()

string_box: Box[str] = Box("Hello")
string_content: str = string_box.get_content()

9. Literal：字面量类型

Literal 允许你限制变量只能取某些特定的字面量值。Python 3.8 新增。

from typing import Literal

def set_log_level(level: Literal["debug", "info", "warning", "error"]) -> None:
  print(f"Setting log level to: {level}")

set_log_level("info")  # 正确
# set_log_level("verbose")  # mypy 会报错，因为 "verbose" 不在允许的字面量值中

10. Final：最终变量

Final 用于声明一个变量为常量，即一旦赋值后就不能再修改。Python 3.8 新增。

from typing import Final

MAX_CONNECTIONS: Final[int] = 100
# MAX_CONNECTIONS = 200  # mypy 会报错，因为 MAX_CONNECTIONS 是 Final 类型的变量

11. NewType：创建新类型

NewType 用于创建一个新的类型，但它仅仅是类型别名，在运行时不会创建新的类。

from typing import NewType

UserID = NewType('UserID', int)

def get_user_name(user_id: UserID) -> str:
  # 假设从数据库中获取用户信息
  return f"User with ID: {user_id}"

user_id: UserID = UserID(123)
user_name: str = get_user_name(user_id)
print(user_name)

# 即使传入一个普通的 int 值，mypy 也不会报错，因为 UserID 只是类型别名
user_name2: str = get_user_name(456)
print(user_name2)

12. Protocol：协议类型

Protocol 用于定义接口，可以用来进行静态类型检查。它类似于其他语言中的接口，但更加灵活。Python 3.8 新增。

from typing import Protocol

class SupportsRead(Protocol):
  def read(self, size: int) -> str:
    ...

def read_data(reader: SupportsRead, size: int) -> str:
  return reader.read(size)

class FileReader:
  def read(self, size: int) -> str:
    return "File content"

class NetworkReader:
  def read(self, size: int) -> str:
    return "Network data"

file_reader = FileReader()
network_reader = NetworkReader()

print(read_data(file_reader, 10))
print(read_data(network_reader, 20))

# 如果一个类没有实现 read 方法，mypy 会报错
# class InvalidReader:
#   def get_data(self) -> str:
#     return "Invalid data"

# invalid_reader = InvalidReader()
# print(read_data(invalid_reader, 30))  # mypy 报错

第二部分：mypy：类型检查的“火眼金睛”

mypy 是一个静态类型检查器，它可以根据你在代码中添加的类型提示来检查代码是否存在类型错误。

1. 安装 mypy

pip install mypy

2. 运行 mypy

在你的项目根目录下，运行 mypy 命令，加上要检查的文件或目录。

mypy your_module.py
mypy your_package/

3. mypy 的配置

mypy 允许你通过配置文件 mypy.ini 来定制类型检查的行为。

例如：

[mypy]
python_version = 3.8
ignore_missing_imports = True
strict = True  # 开启严格模式

• python_version: 指定 Python 版本。
• ignore_missing_imports: 忽略找不到的模块导入。
• strict: 开启严格模式，启用所有严格的类型检查选项。强烈建议在大型项目中开启此选项。

4. 示例：使用 mypy 检查类型错误

# example.py
def greet(name: str) -> str:
  return "Hello, " + name

# greeting: int = greet("World")  # mypy 会报错，因为 greet 返回的是 str，而这里赋值给了一个 int 类型的变量
greeting: str = greet("World")
print(greeting)

def calculate_average(numbers: List[int]) -> float:
  if not numbers:
    return 0.0
  return sum(numbers) / len(numbers)

# average: int = calculate_average([1, 2, 3])  # mypy 会报错，因为 calculate_average 返回的是 float，而这里赋值给了一个 int 类型的变量
average: float = calculate_average([1, 2, 3])
print(average)

运行 mypy example.py，你会看到 mypy 报告的类型错误。

第三部分：在大型项目中应用类型提示的最佳实践

在大型项目中，类型提示的作用更加明显。它可以帮助你：

• 减少运行时错误： 类型提示可以在开发阶段发现潜在的类型错误，避免在生产环境中出现意外的崩溃。
• 提高代码可读性和可维护性： 类型提示可以清晰地表达代码的意图，方便其他开发者理解和修改代码。
• 改善代码重构体验： 类型提示可以帮助你在重构代码时更准确地了解代码的依赖关系，减少引入错误的风险。
• 提升开发效率： 类型提示可以为 IDE 提供更好的代码补全和错误提示，提升开发效率。

1. 循序渐进地引入类型提示

不要试图一次性给整个项目添加类型提示。可以先从核心模块或者新开发的模块开始，逐步扩大类型提示的覆盖范围。

2. 团队协作：统一类型提示风格

为了保证代码的一致性和可读性，团队应该制定统一的类型提示风格指南，例如：

• 使用一致的命名规范。
• 尽量使用精确的类型提示，避免使用 Any。
• 为所有公共函数和类的参数和返回值添加类型提示。
• 使用 mypy 的严格模式，并解决所有类型错误。

3. 利用 IDE 的类型检查功能

许多 IDE（例如 PyCharm、VS Code）都支持 mypy 集成，可以在你编写代码时实时检查类型错误。配置好 IDE，可以大大提高开发效率。

4. 编写可测试的代码

类型提示只是静态类型检查，不能完全替代单元测试。编写充分的单元测试，可以保证代码的正确性和健壮性。

5. 处理第三方库的类型提示

有些第三方库可能没有提供类型提示，或者类型提示不完整。你可以：

• 使用 stub 文件（.pyi 文件）为第三方库添加类型提示。
• 向第三方库的作者提交 PR，贡献你的类型提示。
• 暂时使用 Any 类型，并添加注释说明。

6. 表格：类型提示与传统测试方法的对比

特性	类型提示 (Mypy)	单元测试	集成测试
检查类型	静态	动态	动态
发现问题时机	编译时	运行时	运行时
覆盖范围	基于声明的类型	基于测试用例的代码路径	基于测试用例的系统交互
反馈速度	快	慢	非常慢
所需资源	相对较少	较多	非常多
主要优点	早期发现类型错误，提高代码可读性	验证代码行为的正确性	验证系统组件间的协同工作
主要缺点	需要额外配置和学习，无法覆盖所有运行时错误	无法早期发现类型错误，覆盖范围受限	难以隔离问题，维护成本高

7. 真实案例：利用类型提示优化数据处理管道

假设我们有一个数据处理管道，从文件中读取数据，经过一系列的转换操作，最后写入数据库。

# data_pipeline.py
from typing import List, Dict, Union

def read_data(file_path: str) -> List[Dict[str, Union[str, int]]]:
  """
  从文件中读取数据，返回一个包含字典的列表。
  """
  # 省略文件读取逻辑
  data = [
      {"name": "Alice", "age": 30, "city": "New York"},
      {"name": "Bob", "age": 25, "city": "London"},
  ]
  return data

def transform_data(data: List[Dict[str, Union[str, int]]]) -> List[Dict[str, Union[str, int, float]]]:
  """
  对数据进行转换，例如计算平均年龄。
  """
  total_age = sum(item["age"] for item in data)
  average_age: float = total_age / len(data)
  for item in data:
    item["average_age"] = average_age
  return data

def write_data(data: List[Dict[str, Union[str, int, float]]], db_connection: object) -> None:
  """
  将数据写入数据库。
  """
  # 省略数据库写入逻辑
  print("Writing data to database...")
  for item in data:
    print(item)

# 模拟数据库连接
class MockDBConnection:
    pass

def main():
  file_path: str = "data.txt"
  data: List[Dict[str, Union[str, int]]] = read_data(file_path)
  transformed_data: List[Dict[str, Union[str, int, float]]] = transform_data(data)
  db_connection: MockDBConnection = MockDBConnection()
  write_data(transformed_data, db_connection)

if __name__ == "__main__":
  main()

通过添加类型提示，我们可以清晰地了解每个函数输入和输出的数据类型，方便我们进行代码维护和重构。mypy 可以在编译时检查类型错误，避免在运行时出现意外的错误。

总结：类型提示，让你的 Python 代码更上一层楼

类型提示是 Python 代码现代化的重要一步。虽然它不能完全替代单元测试，但它可以帮助你在开发阶段发现潜在的类型错误，提高代码的可读性和可维护性，最终提升开发效率。

希望今天的讲座对大家有所帮助。记住，拥抱类型提示，让你的 Python 代码更上一层楼！ 感谢大家的收听！