Python 3.8+ 引入的 Literal 类型注解。它用于限定变量或参数只能取特定字面量值，如字符串、数字或布尔值，弥补了传统类型注解仅限制数据类型的不足。文章涵盖基础语法、类属性约束、与 Union/Enum 结合用法及版本兼容性。需注意 Literal 仅作用于静态检查，运行时需手动校验，且适用于取值范围固定少量的场景，大量取值建议用 Enum 替代。
在 Python 静态类型检查体系中，Literal 是实现「字面量级精确类型约束」的核心工具。它突破了传统类型注解（如 str/int）仅限定类型大类的局限，能够精准约束变量、参数或返回值只能取特定的字面量值，大幅提升代码的可读性、可维护性和静态检查能力。
Literal 是 Python 3.8 版本引入的类型注解（PEP 586 规范），隶属于 typing 模块（Python 3.9+ 可通过 typing_extensions 兼容，3.10+ 原生支持更完善）。其核心作用是：，而非仅限定为某类数据类型。
例如：
str 注解仅表示变量是字符串类型，无法限制具体值；Literal["general", "news", "finance"] 则明确要求变量只能是 "general"、"news"、"finance" 这三个字符串字面量之一。Python 作为动态类型语言，传统类型注解（如 int/str）只能约束「类型大类」，无法应对以下场景：
DEBUG/INFO/ERROR）；alipay/wechat）；mypy/Pyright）需要更精准的类型提示，提前发现非法值传入问题。Literal 的出现填补了这一空白，让类型注解从「类型级」下沉到「字面量级」，实现更细粒度的类型约束。
# Python 3.8+（标准库）
from typing import Literal
# Python 3.9+ 兼容低版本（需先安装 typing_extensions）
# pip install typing_extensions
from typing_extensions import Literal
# 变量注解：限定变量取值范围
变量名：Literal[字面量 1, 字面量 2,...] = 初始值
# 函数参数注解：限定参数只能传入指定字面量
def 函数名 (参数名：Literal[字面量 1, 字面量 2,...])-> 返回值类型:
pass
# 函数返回值注解：限定返回值只能是指定字面量
def 函数名 ()-> Literal[字面量 1, 字面量 2,...]:
pass
Literal 仅支持不可变的字面量，包括：
Literal["a", "b"]Literal[1, 2.5]Literal[True, False]Literal[None]Enum）：Literal[Color.RED, Color.BLUE]注意：不支持列表、字典等可变对象作为
Literal的参数，如Literal[[1,2]]会触发类型检查错误。
from typing import Literal
# 限定 topic 只能是 "general"/"news"/"finance" 之一
topic: Literal["general","news","finance"] = "general"
# 合法赋值
topic = "news"
# 非法赋值（mypy 等工具会报错，运行时不报错，因类型注解不影响运行）
topic = "sports"
# Error: Incompatible types (expression has type "Literal['sports']", variable has type "Literal['general', 'news', 'finance']")
from typing import Literal
def set_log_level(level: Literal["DEBUG","INFO","WARNING","ERROR"])-> Literal["success","failed"]:
"""设置日志级别，仅支持指定值，返回操作结果"""
valid_levels = {"DEBUG","INFO","WARNING","ERROR"}
if level in valid_levels:
print(f"日志级别已设置为：{level}")
return "success"
return "failed"
# 合法调用
set_log_level("INFO") # 返回 "success"
# 非法调用（静态检查报错）
set_log_level("CRITICAL")
# Error: Argument 1 to "set_log_level" has incompatible type "Literal['CRITICAL']"; expected "Literal['DEBUG', 'INFO', 'WARNING', 'ERROR']"
Literal 在类的场景中可覆盖类属性、实例属性、方法参数/返回值、类方法/静态方法等，是约束类行为的重要工具。
from typing import Literal, ClassVar
class PaymentProcessor:
# 类属性：限定支付渠道只能是指定值（ClassVar 标识类属性）
DEFAULT_CHANNEL: ClassVar[Literal["alipay","wechat","unionpay"]] = "alipay"
def __init__(self, channel: Literal["alipay","wechat","unionpay"]):
# 实例属性：限定初始化时渠道必须为指定值
self.channel: Literal["alipay","wechat","unionpay"] = channel
# 合法实例化
processor = PaymentProcessor("wechat")
print(processor.channel) # wechat
# 非法实例化（静态检查报错）
# processor = PaymentProcessor("paypal")
# Error: Argument 1 to "PaymentProcessor" has incompatible type "Literal['paypal']"; expected "Literal['alipay', 'wechat', 'unionpay']"
from typing import Literal
class OrderHandler:
def update_status(self, order_id:str, status: Literal["pending","paid","shipped","completed"])-> Literal[0,1]:
"""更新订单状态，成功返回 1，失败返回 0"""
valid_status = {"pending","paid","shipped","completed"}
if status in valid_status:
# 模拟更新逻辑
return 1
return 0
# 调用示例
handler = OrderHandler()
result = handler.update_status("123456","paid")
print(result) # 1
# 非法调用（静态检查报错）
# handler.update_status("123456","cancelled")
# Error: Argument 2 to "update_status" has incompatible type "Literal['cancelled']"; expected "Literal['pending', 'paid', 'shipped', 'completed']"
Literal 可与 Union 结合，实现「多组字面量 + 基础类型」的复合约束：
from typing import Literal, Union
# 限定值为指定字符串字面量 或 None
NullableTopic = Union[Literal["general","news"],None]
topic: NullableTopic = None # 合法
topic = "general" # 合法
topic = "finance" # 静态检查报错
# 限定值为指定数字字面量 或 布尔值
MixType = Union[Literal[1,2], Literal[True,False]]
value: MixType = True # 合法
value = 3 # 静态检查报错
Literal 可与 enum.Enum 结合，约束变量只能是枚举的特定成员，而非任意枚举成员：
from typing import Literal
from enum import Enum
class Color(Enum):
RED = 1
GREEN = 2
BLUE = 3
# 限定只能是 Color.RED 或 Color.BLUE
def print_color(color: Literal[Color.RED, Color.BLUE])->None:
print(f"Selected color: {color.name}")
# 合法调用
print_color(Color.RED)
# 非法调用（静态检查报错）
# print_color(Color.GREEN)
# Error: Argument 1 to "print_color" has incompatible type "Literal[Color.GREEN]"; expected "Literal[Color.RED, Color.BLUE]"
Python 3.11+ 引入了 LiteralString/LiteralInt 等派生类型，用于推导「任意字符串/数字字面量」，而非固定值：
from typing import LiteralString
def get_config(key: LiteralString)->str:
"""限定 key 为字符串字面量（而非变量），避免注入风险"""
config = {"host":"127.0.0.1","port":"8080"}
return config.get(key, "")
# 合法调用（传入字面量）
get_config("host") # 返回 "127.0.0.1"
# 非法调用（传入变量，静态检查报错）
key = "port"
get_config(key) # Error: Argument 1 to "get_config" has incompatible type "str"; expected "LiteralString"
Literal 是静态类型注解，仅对 mypy/Pyright/PyCharm 等工具生效，运行时不会校验值的合法性。若需运行时校验，需手动实现：
from typing import Literal
def set_topic(topic: Literal["general","news"])->None:
# 手动运行时校验
if topic not in {"general","news"}:
raise ValueError(f"Invalid topic: {topic}, must be 'general' or 'news'")
print(f"Topic set to: {topic}")
# 运行时触发异常
set_topic("sports") # ValueError: Invalid topic: sports, must be 'general' or 'news'
Literal 适用于「取值范围固定且少量」的场景，若取值范围超过 5 个，建议使用 Enum 替代，避免代码冗余：
# 不推荐：字面量过多，代码冗长
def set_role(role: Literal["admin","editor","viewer","operator","guest"])->None:
pass
# 推荐：用 Enum 替代
from enum import Enum
class Role(Enum):
ADMIN = "admin"
EDITOR = "editor"
VIEWER = "viewer"
OPERATOR = "operator"
GUEST = "guest"
def set_role(role: Role)->None:
pass
Literal 的最低支持版本，若需兼容 3.7 及以下版本，需安装 typing_extensions 并从该模块导入；Literal 与 | 运算符结合（替代 Union），如 topic: Literal["general"] | Literal["news"]。Literal 仅支持不可变字面量，以下写法均会触发静态检查错误：
from typing import Literal
# 错误：列表是可变对象
invalid1: Literal[[1,2]] = [1,2]
# 错误：字典是可变对象
invalid2: Literal[{"key":"value"}] = {"key":"value"}
| 类型注解 | 核心作用 | 适用场景 |
|---|---|---|
str/int | 限定变量为某类数据类型 | 取值范围无限制的普通变量 |
Literal | 限定变量为指定字面量值 | 固定取值范围的配置/参数 |
Enum | 定义枚举类型，限定为枚举成员 | 取值范围较多、需语义化的场景 |
Union | 限定变量为多个类型之一 | 多类型混合的变量 |
Literal 是 Python 静态类型体系中不可或缺的工具，其核心价值在于将类型约束从「类型级」下沉到「字面量级」，实现精准的取值范围限定。使用时需注意：
Literal 仅作用于静态检查，运行时需手动校验；Enum；Union/Enum 结合，扩展约束能力；typing_extensions。合理使用 Literal 可大幅提升代码的可读性和健壮性，让静态类型检查工具提前发现非法值问题，减少运行时异常，是编写高质量 Python 代码的重要实践。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online