Python Literal[] 类型提示详解

Python Literal\[\] 类型提示详解

一、什么是 Literal

Literal 是 typing 模块提供的类型提示，用于限定变量或参数只能取指定的字面值。

python 复制代码

from typing import Literal

二、基本用法

1. 限定变量值

python 复制代码

status: Literal["active", "inactive"] = "active"  # ✅
status: Literal["active", "inactive"] = "pending"  # ❌ 类型检查报错

2. 限定函数参数

python 复制代码

def set_mode(mode: Literal["read", "write", "append"]) -> None:
    ...

set_mode("read")   # ✅
set_mode("delete") # ❌ 类型检查报错

3. 限定返回值

python 复制代码

def get_direction() -> Literal["left", "right"]:
    return "left"  # ✅

三、常见使用场景

1. API 请求方法

python 复制代码

import requests
from typing import Literal

def request(url: str, method: Literal["GET", "POST", "PUT", "DELETE"] = "GET"):
    return requests.request(method, url)

2. 配置选项

python 复制代码

def configure(debug: Literal[True, False] = False):
    if debug:
        print("调试模式")

3. 状态机

python 复制代码

OrderStatus = Literal["pending", "paid", "shipped", "delivered", "cancelled"]

def update_status(status: OrderStatus) -> None:
    print(f"状态更新为: {status}")

4. 与 Enum 结合

python 复制代码

from enum import Enum

class Color(Enum):
    RED = "red"
    GREEN = "green"
    BLUE = "blue"

def paint(color: Literal[Color.RED, Color.GREEN, Color.BLUE]):
    ...

四、类型检查工具支持

工具	支持情况
Mypy	✅ 完全支持
Pyright	✅ 完全支持
PyCharm	✅ 完全支持
VS Code	✅ 完全支持

bash 复制代码

# 使用 mypy 检查
pip install mypy
mypy your_script.py

五、进阶用法

1. 与 Union 组合

python 复制代码

from typing import Union

def process(value: Union[int, Literal["auto", "manual"]]):
    ...

2. 嵌套使用

python 复制代码

Config = Literal[
    {"debug": True},
    {"debug": False}
]

3. 在数据类中使用

python 复制代码

from dataclasses import dataclass

@dataclass
class User:
    name: str
    role: Literal["admin", "user", "guest"]

六、注意事项

事项	说明
运行时无约束	`Literal` 仅在静态检查时生效，运行时可赋任意值
仅限字面值	只能是字符串、数字、布尔、`None` 等字面量
不支持变量	`x = "a"; Literal[x]` 无效
类型擦除	运行时无法获取 `Literal` 的具体值

python 复制代码

# 运行时不会报错
status: Literal["active"] = "invalid"  # 类型检查报错，但运行正常

七、对比其他方案

python 复制代码

# ❌ 不推荐：用 Enum
class Status(Enum):
    ACTIVE = "active"
    INACTIVE = "inactive"

# ✅ 推荐：用 Literal（更简洁）
Status = Literal["active", "inactive"]

# ❌ 不推荐：用 Union
Mode = Union[str, int]  # 太宽泛

# ✅ 推荐：用 Literal（更精确）
Mode = Literal["read", "write"]  # 更明确

总结：Literal[] 是 Python 类型系统中实现字面量类型约束的利器，让代码更安全、可读性更强、IDE 补全更精准。