Python 类型提示：Literal 类型
概述
Literal 类型是 Python 类型提示系统中的一个特殊形式，用于定义字面量类型（也称为值类型）。它允许开发者指定一个变量或函数参数必须等于特定的字面量值（或几个可能的值之一）。
Literal 类型为 Python 的类型系统提供了更精细的控制能力，特别是在需要精确指定允许的特定值时非常有用。
导入
from typing import Literal
基本用法
1. 单个字面量值
def always_true() -> Literal[True]:return Truedef open_read_only(file: str) -> str:# 返回值只能是特定的字符串字面量return "success"def process_status(code: Literal[200, 404, 500]) -> str:if code == 200:return "OK"elif code == 404:return "Not Found"else:return "Server Error"
2. 多个字面量值
# 定义文件模式类型
FileMode = Literal['r', 'rb', 'w', 'wb', 'a', 'ab']def open_file(filepath: str, mode: FileMode) -> str:# 实现文件打开逻辑return f"File {filepath} opened with mode {mode}"# 正确的用法
open_file("data.txt", "r") # 通过类型检查
open_file("data.bin", "rb") # 通过类型检查# 错误的用法（类型检查器会报错）
open_file("data.txt", "read") # 错误：'read' 不是有效的字面量
- 在pycharm中能直接提醒
3. 布尔值和数字字面量
# 布尔值字面量
def toggle_switch(state: Literal[True, False]) -> Literal[True, False]:return not state# 数字字面量
Direction = Literal[0, 90, 180, 270]def rotate_sprite(angle: Direction) -> None:print(f"Rotating to {angle} degrees")# 混合类型字面量
ResponseType = Literal["success", "error", 200, 404]
高级用法
1. 与联合类型结合使用
from typing import Union, Literal# 更灵活的类型定义
StatusCode = Union[Literal[200], Literal[404], Literal[500]]
ApiResponse = Union[dict, Literal["timeout"], Literal["error"]]
2. 枚举的替代方案
# 使用 Literal 代替简单的枚举
Color = Literal["red", "green", "blue", "yellow"]def set_traffic_light(color: Color) -> None:if color == "red":print("Stop")elif color == "green":print("Go")elif color == "yellow":print("Caution")# 类型检查会捕获拼写错误
set_traffic_light("red") # 正确
set_traffic_light("reed") # 类型检查错误
3. 在类和方法中使用
from typing import Literal, ClassVarclass DatabaseConnection:# 类常量使用 Literal 类型SUPPORTED_VERSIONS: ClassVar[Literal["1.0", "2.0", "3.0"]] = ["1.0", "2.0", "3.0"]def __init__(self, version: Literal["1.0", "2.0", "3.0"]):self.version = version@classmethoddef get_status(cls) -> Literal["connected", "disconnected", "error"]:return "connected"
实际应用场景
1. API 响应处理
from typing import Literal, TypedDictclass ApiResponse(TypedDict):status: Literal["success", "error"]data: dictmessage: strdef handle_response(response: ApiResponse) -> None:if response["status"] == "success":process_data(response["data"])else:log_error(response["message"])
2. 配置验证
from typing import Literal, TypedDictclass AppConfig(TypedDict):environment: Literal["development", "staging", "production"]log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR"]database: Literal["mysql", "postgresql", "sqlite"]def validate_config(config: AppConfig) -> bool:# 配置验证逻辑return True
3. 状态机实现
from typing import LiteralOrderState = Literal["pending", "confirmed", "shipped", "delivered", "cancelled"]class Order:def __init__(self):self.state: OrderState = "pending"def transition(self, new_state: OrderState) -> None:# 状态转换逻辑valid_transitions = {"pending": ["confirmed", "cancelled"],"confirmed": ["shipped", "cancelled"],"shipped": ["delivered"],}if new_state in valid_transitions.get(self.state, []):self.state = new_stateelse:raise ValueError(f"Invalid transition from {self.state} to {new_state}")
限制和注意事项
- 不可子类化:
Literal[...]不能被继承 - 运行时限制: 在运行时，
Literal接受任意值作为参数，但类型检查器可能会施加限制 - 哈希性要求: 字面量参数应该是可哈希的
- 类型检查器支持: 不同的类型检查器（如 mypy、pyright）可能对
Literal有不同的支持程度
最佳实践
- 使用有意义的字面量: 选择能够清晰表达意图的字面量值
- 避免过度使用: 只在确实需要限制为特定值时使用
Literal - 与枚举比较: 对于固定的值集合，考虑使用
Enum是否更合适 - 文档化: 为使用
Literal的复杂类型添加适当的文档
示例总结
from typing import Literal, Union# 各种使用场景的完整示例
HttpMethod = Literal["GET", "POST", "PUT", "DELETE", "PATCH"]
StatusCode = Literal[200, 201, 400, 401, 403, 404, 500]
ApiResponse = Union[dict, list, Literal["error", "timeout", "unauthorized"]]def make_api_request(method: HttpMethod,endpoint: str,expected_status: StatusCode = 200
) -> ApiResponse:"""发起 API 请求Args:method: HTTP 方法，必须是预定义的字面量值endpoint: API 端点expected_status: 期望的 HTTP 状态码Returns:API 响应数据或错误字面量"""# 实现请求逻辑if method == "GET":return {"data": "sample response"}else:return "error"
Literal 类型为 Python 的类型系统提供了更精细的控制能力，特别是在需要精确指定允许的特定值时非常有用。