Literal是Python类型注解工具，用于限定变量或参数只能取指定的字符串、数字、布尔值或None等字面量值，仅在类型检查阶段生效，不参与运行时校验。
Literal 是什么，它能限制哪些值
typing.Literal 不是运行时校验工具，它只在类型检查阶段起作用（比如 mypy、pyright、IDE 类型提示），对 Python 解释器实际执行完全无影响。它用来声明一个变量或参数**只能取几个明确的字面量值**，比如 "red"、42、True，而不是任意 str 或 int。
支持的字面量类型有限：字符串、数字（int/float）、布尔值、None，以及它们的组合（用 | 联合）。不支持变量、表达式、枚举成员（除非显式写成字面量）、列表或字典等复合结构。
怎么写 Literal 类型注解
语法很简单：Literal[值1, 值2, ...]。多个可选值之间用逗号分隔，整个类型用方括号包裹。
常见写法示例：
立即学习“Python免费学习笔记（深入）”；
from typing import Literal
<h1>只能是 "start" 或 "stop"</h1><p>status: Literal["start", "stop"] = "start"</p><h1>支持数字和布尔</h1><p>mode: Literal[0, 1, True, False] = 1</p><h1>混合类型（注意：mypy 默认允许，但某些旧版本可能报错）</h1><p>priority: Literal["low", "high", 1, 2] = "high"</p><div class="aritcle_card flexRow">
<div class="artcardd flexRow">
<a class="aritcle_card_img" href="/xiazai/skill6591" title="Li Python Sec Check"><img
src="https://img.php.cn/upload/skill/000/000/081/179102166033725.jpg" alt="Li Python Sec Check" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
<div class="aritcle_card_info flexColumn">
<a href="/xiazai/skill6591" title="Li Python Sec Check">Li Python Sec Check</a>
<p>Python 安全规范检查工具：基于 CloudBase 规范、腾讯安全指南，LLM 智能分析（默认禁用，优先本地执行）</p>
</div>
<a href="/xiazai/skill6591" title="Li Python Sec Check" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a>
</div>
</div><h1>和 Union 配合（Python 3.10+ 更推荐用 |）</h1><p>from typing import Union
kind: Union[Literal["file"], Literal["dir"]] = "file"</p><h1>等价于（更简洁）：</h1><p>kind2: Literal["file"] | Literal["dir"] = "dir"
- 字符串必须加引号，写成
"red"，不能写red（那会被当成变量名） - 大小写敏感：
Literal["UP", "down"]中"Up"会触发类型错误 - 空字符串
""、单字符如"a"、带空格的" ok "都合法，只要它是字面量
为什么赋值或传参时提示“incompatible type”
这是最常遇到的报错，典型信息：error: Incompatible type "str"; expected "Literal['on', 'off']"。根本原因：你用了运行时才确定的值（比如用户输入、配置读取、函数返回），而 Literal 要求编译期就能确认具体字面量。
常见踩坑场景：
- 从
input()或sys.argv读的字符串 —— 类型检查器无法知道用户输的是不是"on" - 用变量间接赋值：
x = "on"; status: Literal["on", "off"] = x→ 报错，因为x的类型是str，不是Literal - 字典取值：
config.get("mode")返回Any或str，不能直接赋给Literal变量 - 拼接字符串：
"o" + "n"不算字面量，即使结果是"on"
解决思路不是绕过类型检查，而是明确告诉检查器“我保证这个值安全”——用 cast 或显式注解：
from typing import Literal, cast
<p>user_input = input("Enter mode: ") # 类型是 str</p><h1>✅ 安全做法：先校验，再 cast</h1><p>if user_input in ("on", "off"):
mode: Literal["on", "off"] = cast(Literal["on", "off"], user_input)
else:
raise ValueError("Invalid mode")
和 Enum、TypedDict、LiteralString 有什么区别
Literal 最容易和 Enum 混淆，但它俩定位不同：
-
Enum是运行时存在的类，有属性、方法、迭代能力；Literal只是类型提示，运行时不存在 - 想用
.name或.value？必须用Enum；只想要 IDE 提示 + mypy 报错？Literal更轻量 -
TypedDict描述键名固定的字典结构，和值的枚举无关；Literal不描述结构，只约束单个值 -
LiteralString（Python 3.11+）是另一个类型：表示“这个字符串必须是字面量”，但不指定具体是哪个，比Literal更宽泛
性能上毫无差异 —— 所有这些类型注解都在导入时被丢弃，不影响运行速度或内存占用。选哪个取决于你要解决的问题：需要运行时行为？选 Enum。只要静态约束？Literal 更直接。
最容易被忽略的一点：Literal 的联合类型（比如 Literal["a"] | Literal["b"]）在 mypy 中等价于 Literal["a", "b"]，但某些老版本或配置下解析逻辑不同，建议统一用多值写法，避免嵌套联合。
