LiteralString仅接受字符串字面量，拒绝变量、拼接或运行时构造的字符串；需mypy≥1.0.0并启用literal错误码，用于保障输入来源可信，不替代Literal[...]的精确枚举约束。
LiteralString 只接受字符串字面量，不接受变量或拼接结果
typing.LiteralString 是 Python 3.11+ 引入的类型提示工具，它的核心约束是：**仅允许在调用时传入真正的字符串字面量（如 "hello"、f"world"、r"raw"），拒绝任何运行时构造的字符串**。它不是对值内容的校验，而是对 AST 层面“是否为字面量”的静态检查。
常见错误现象包括：
- 传入变量：
s = "abc"; func(s)→ 类型检查器报错 - 传入拼接：
func("a" + "b")或func(f"{x}")（即使x是字面量）→ 多数检查器（如 mypy）仍拒绝 - 传入
str(...)转换：func(str(42))→ 不合法
myPy 对 LiteralString 的支持需开启 strict 模式
默认情况下，mypy 不启用 LiteralString 检查。必须显式启用相关标志，否则所有 LiteralString 注解都会被静默忽略。
实操建议：
- 在
mypy.ini或pyproject.toml中添加：[mypy] enable_error_code = "literal" strict = true
- 或命令行运行：
mypy --enable-error-code literal your_file.py - 注意：仅
mypy >= 1.0.0支持该特性；Pyright / Pylance 当前（v2024）对LiteralString的支持较弱，基本不报错
函数签名中正确使用 LiteralString 参数
声明函数时，把参数类型设为 LiteralString 即可触发检查。它通常用于需要确保输入“不可被用户动态控制”的场景，比如 SQL 查询模板、格式化字符串键、枚举式字段名等。
示例：
from typing import LiteralString
<p>def select_by_field(table: str, field: LiteralString) -> list:</p><h1>field 必须是字面量，防止注入或拼错</h1><pre class='brush:python;toolbar:false;'>return db.query(f"SELECT * FROM {table} WHERE {field} = ?")select_by_field("users", "email") # ✅ 合法 select_by_field("users", field_name) # ❌ field_name 是变量 select_byfield("users", "user" + "id") # ❌ 拼接不被接受（mypy 默认行为）
注意：LiteralString 本身不携带具体值信息，所以不能替代 Literal["a", "b"] 做精确枚举限制；它只管“是不是字面量”，不管“是哪个字面量”。
和 Literal[...] 的关键区别与误用风险
容易混淆的是：LiteralString ≠ Literal["foo", "bar"]。前者宽泛（任意字面量都行），后者严格（只接受指定几个）。
典型误用：
- 想限制只能传
"name"或"age"，却写了field: LiteralString→ 实际放行所有字面量，失去约束力 - 想防止拼接但又接受变量，试图用
Union[LiteralString, str]→ 失效，因为str会绕过所有字面量检查 - 在运行时试图用
isinstance(x, str)判断LiteralString→ 无意义，它只是类型提示，运行时完全擦除
真正需要值级约束时，必须用 Literal[...]；需要“来源可信”保障（如防注入、保编译期可见性）时，才用 LiteralString。两者解决的问题不在同一层。
