Python Union 联合类型注解详解

---

Python Union 联合类型注解详解

在 Python 中，类型注解（type hint）是用来指定变量、函数参数和返回值的类型的方式，帮助开发者在代码编写时提高代码的可读性和可维护性。在 Python 3.10 之前，typing 模块提供了 Union 类型来表示一个变量或函数参数可以是多种类型中的任意一个。自 Python 3.10 以后，Python 引入了新的语法来使用 |（管道符）代替 Union 来表示联合类型。

本文将介绍 Union 联合类型注解的用法，包括 Python 3.9 之前和 3.10 之后的写法，以及实际的应用场景。

---

1. 什么是 Union 联合类型？

联合类型（Union Type） 是指一个变量或函数参数可以接受多种类型中的任何一个。使用 Union 类型注解时，我们可以声明一个类型是多个类型的“联合”，表示它可以是多个类型中的任何一个。

语法（Python 3.9 及之前版本）：

from typing import Union

# 用法示例
variable: Union[type1, type2, type3]

语法（Python 3.10 及之后版本）：

Python 3.10 以后，你可以使用 | 操作符来表示联合类型：

# 用法示例
variable: type1 | type2 | type3

这两种写法是等效的。

---

2. Union 联合类型注解示例

(1) 使用 Union 来表示多个类型的参数

假设我们有一个函数，它可以接收整数、浮点数或者字符串作为参数，我们可以使用 Union 来进行类型注解。

# Python 3.9 及之前版本
from typing import Union

def process_data(value: Union[int, float, str]) -> str:
    return f"Processing: {value}"

print(process_data(10))       # 输出: Processing: 10
print(process_data(10.5))     # 输出: Processing: 10.5
print(process_data("Hello"))  # 输出: Processing: Hello

(2) 使用 | 来表示联合类型（Python 3.10 及之后版本）

Python 3.10 之后，你可以使用 | 来替代 Union：

def process_data(value: int | float | str) -> str:
    return f"Processing: {value}"

print(process_data(10))       # 输出: Processing: 10
print(process_data(10.5))     # 输出: Processing: 10.5
print(process_data("Hello"))  # 输出: Processing: Hello

这两种写法是等效的，只是 Python 3.10 引入的 | 语法更简洁。

---

3. 使用 Union 进行复杂类型注解

(1) 使用 Union 与列表结合

有时我们希望表示一个列表中的元素可以是不同类型的联合，例如，一个列表可以包含整数、浮动数字和字符串。

from typing import Union

# Python 3.9 及之前版本
def process_list(values: list[Union[int, float, str]]) -> str:
    return f"Values: {values}"

print(process_list([1, 2.5, "hello"]))  # 输出: Values: [1, 2.5, 'hello']

(2) 使用 | 来表示联合类型（Python 3.10 及之后版本）

def process_list(values: list[int | float | str]) -> str:
    return f"Values: {values}"

print(process_list([1, 2.5, "hello"]))  # 输出: Values: [1, 2.5, 'hello']

在这里，list[int | float | str] 表示列表中的每个元素可以是整数、浮点数或字符串。

---

4. 联合类型与 None 的结合

在许多情况下，我们需要表示一个值可能是某种类型，或者可能是 None（例如表示“无值”或“缺失的值”）。可以使用 Union 或 | 来表示这种情况。

(1) 使用 Union 与 None 结合

from typing import Union

def get_value(data: Union[int, None]) -> str:
    if data is None:
        return "No data"
    return f"Value: {data}"

print(get_value(42))    # 输出: Value: 42
print(get_value(None))  # 输出: No data

(2) 使用 | 与 None 结合（Python 3.10 及之后版本）

def get_value(data: int | None) -> str:
    if data is None:
        return "No data"
    return f"Value: {data}"

print(get_value(42))    # 输出: Value: 42
print(get_value(None))  # 输出: No data

通过这种方式，我们可以表示一个值可能是整数类型或 None，这种写法非常常见，尤其是在函数返回值为空或缺失时。

---

5. 注意事项 ⚠️

(1) 类型检查工具

使用 Union 类型注解后，可以通过静态类型检查工具如 mypy 来检查类型的一致性。静态类型检查工具有助于在开发过程中捕捉潜在的类型错误。

例如，运行以下代码：

$ mypy your_script.py

如果传递给 process_data 函数一个不符合联合类型的值，mypy 会给出警告。

(2) 可选类型的处理

如果一个值可能是多个类型之一，或者可以是 None，你可以使用联合类型来表达。例如，int | None 表示一个值可以是整数类型，也可以是 None。

在处理可选值时，建议你始终显式地检查 None，避免引发错误。

---

6. 总结

• Union 类型注解：允许你指定一个值可以是多个类型中的任何一个。你可以通过 Union 或 | 来实现联合类型注解。
• 语法：在 Python 3.9 及之前版本中，使用 Union[type1, type2]；而在 Python 3.10 及之后版本中，使用 type1 | type2。
• 常见应用：联合类型广泛应用于函数参数、返回值的注解，尤其是在需要表示多个可能类型时。
• 与 None 结合：当一个值可能是特定类型或 None 时，联合类型非常有用，表示“可选”类型。

通过使用 Union 或 | 来注解联合类型，能够让代码更清晰，帮助开发者更好地理解数据的预期类型和结构。