python内置模块typing里Literal函数的基本用法和总结--快速学习掌握Literal函数的用法

Literal 是 Python typing 模块中提供的一种类型注解，用于指定变量或函数的参数只能取特定的字面量值（常量）。它允许你将变量的取值严格限制在指定的一组值内，确保程序只接受特定的常量值，从而减少错误的发生。

一、基本概念

在 Python 中，通常我们会使用常见的类型注解来限制变量的类型，例如 int, str, bool 等。然而，有时我们想要进一步限制一个变量只能取某些特定的值，而不仅仅是某个类型。例如，假设我们有一个变量 color，并且我们希望它只能是 “red”、“green” 或 “blue”，这时我们就可以使用 Literal 来实现这种约束。

二、基本用法

from typing import Literal

def set_color(color: Literal["red", "green", "blue"]) -> None:
    print(f"The color is {color}")

在这个例子中，函数 set_color 的参数 color 被限制为只能取 “red”、“green” 或 “blue” 这三个值。任何其他值都会引发类型错误。

set_color("red")   # 输出: The color is red
set_color("green") # 输出: The color is green
set_color("yellow")  # 类型检查工具会报错：Argument 1 to "set_color" has incompatible type "str"; expected "Literal['red', 'green', 'blue']"

在上述错误示例中，“yellow” 虽然是字符串类型，但因为它不在 Literal 的定义范围之内，所以类型检查工具会抛出错误。

三、常见用法

限制函数参数：使用 Literal 可以限制传递给函数的参数只能是某些固定的值。例如某个函数需要接收特定的命令或选项。

def open_file(mode: Literal["r", "w", "a"]) -> None:
    pass

在这里，mode 参数只能是 “r”（读）、“w”（写）或 “a”（追加）。

配置项或状态：有时候在某些配置或状态管理中，我们希望某个属性只支持一些固定的状态值。

class Connection:
    def __init__(self, state: Literal["open", "closed", "error"]):
        self.state = state

这样可以明确地表达状态，并避免使用不合法的状态值。

四、Literal 的优点

• 提高代码的可读性和安全性：通过使用 Literal，我们可以清楚地表达某个值的有效取值范围，代码的意图更加明确。
• 防止错误：类型检查器会在编译时捕获不合法的值，减少运行时的潜在错误。
• 自动补全和类型提示：许多 IDE（如 PyCharm、VSCode）支持 Literal 的自动补全功能，开发时更方便。

from typing import Literal

def set_mode(mode: Literal["auto", "manual"]) -> str:
    if mode == "auto":
        return "Automatic mode selected"
    else:
        return "Manual mode selected"
      

set_mode("a")  # 自动提示："auto", "manual"

五、高级用法

组合字面量类型： 你可以使用不同类型的字面量组合，例如同时限制字符串和数字：

from typing import Literal

def process(value: Literal["low", "medium", "high", 1, 2, 3]) -> None:
    pass

布尔值字面量： 可以限制一个变量只能为 True 或 False：

def toggle(state: Literal[True, False]) -> None:
    pass

None 作为字面量： 如果你想让参数的默认值为 None，也可以通过 Literal 实现：

def example(option: Literal[None, "option1", "option2"] = None):
    pass

六、总结

Literal 限定一个变量只能取特定的值（字面量），而不仅仅是类型。
通过 Literal，可以在类型注解中指定函数的参数或类的属性只能接受一组有限的常量值。
它提高了代码的安全性，减少了潜在的运行时错误，尤其适用于函数参数、配置项、状态管理等场景。