如何在Python中使用typing.Literal限制变量取值范围-Python教程-PHP中文网

literal是python类型注解工具，用于限定变量或参数只能取指定的字符串、数字、布尔值或none等字面量值，仅在类型检查阶段生效，不参与运行时校验。

如何在python中使用typing.literal限制变量取值范围

Literal 是什么，它能限制哪些值

typing.Literal 不是运行时校验工具，它只在类型检查阶段起作用（比如 mypy、pyright、IDE 类型提示），对 Python 解释器实际执行完全无影响。它用来声明一个变量或参数**只能取几个明确的字面量值**，比如 "red"、42、True，而不是任意 str 或 int。

支持的字面量类型有限：字符串、数字（int/float）、布尔值、None，以及它们的组合（用 | 联合）。不支持变量、表达式、枚举成员（除非显式写成字面量）、列表或字典等复合结构。

怎么写 Literal 类型注解

语法很简单：Literal[值1, 值2, ...]。多个可选值之间用逗号分隔，整个类型用方括号包裹。

常见写法示例：

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 artxards">
											<div class="artcardd flexRow">
												<a class="aritcle_card_img" rel="nofollow" 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 rel="nofollow" href="/xiazai/skill6591" title="Li Python Sec Check" class="overflowclass">Li Python Sec Check</a>
													<p class="overflowclass">Python 安全规范检查工具：基于 CloudBase 规范、腾讯安全指南，LLM 智能分析（默认禁用，优先本地执行）</p>
												</div>
												<a rel="nofollow" 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"
</p>

字符串必须加引号，写成 "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")
</p>