# Python 3.8+（標(biāo)準(zhǔn)庫(kù)）
from typing import Literal

# Python 3.9+ 兼容低版本（需先安裝 typing_extensions）
# pip install typing_extensions
from typing_extensions import Literal

# 變量注解：限定變量取值范圍
變量名: Literal[字面量1, 字面量2, ...] = 初始值

# 函數(shù)參數(shù)注解：限定參數(shù)只能傳入指定字面量
def 函數(shù)名(參數(shù)名: Literal[字面量1, 字面量2, ...]) -> 返回值類型:
    pass

# 函數(shù)返回值注解：限定返回值只能是指定字面量
def 函數(shù)名() -> Literal[字面量1, 字面量2, ...]:
    pass

from typing import Literal

# 限定 topic 只能是 "general"/"news"/"finance" 之一
topic: Literal["general", "news", "finance"] = "general"

# 合法賦值
topic = "news"

# 非法賦值（mypy 等工具會(huì)報(bào)錯(cuò)，運(yùn)行時(shí)不報(bào)錯(cuò)，因類型注解不影響運(yùn)行）
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"]:
    """設(shè)置日志級(jí)別，僅支持指定值，返回操作結(jié)果"""
    valid_levels = {"DEBUG", "INFO", "WARNING", "ERROR"}
    if level in valid_levels:
        print(f"日志級(jí)別已設(shè)置為：{level}")
        return "success"
    return "failed"

# 合法調(diào)用
set_log_level("INFO")  # 返回 "success"

# 非法調(diào)用（靜態(tài)檢查報(bào)錯(cuò)）
set_log_level("CRITICAL")  # Error: Argument 1 to "set_log_level" has incompatible type "Literal['CRITICAL']"; expected "Literal['DEBUG', 'INFO', 'WARNING', 'ERROR']"

from typing import Literal, ClassVar

class PaymentProcessor:
    # 類屬性：限定支付渠道只能是指定值（ClassVar 標(biāo)識(shí)類屬性）
    DEFAULT_CHANNEL: ClassVar[Literal["alipay", "wechat", "unionpay"]] = "alipay"
    
    def __init__(self, channel: Literal["alipay", "wechat", "unionpay"]):
        # 實(shí)例屬性：限定初始化時(shí)渠道必須為指定值
        self.channel: Literal["alipay", "wechat", "unionpay"] = channel

# 合法實(shí)例化
processor = PaymentProcessor("wechat")
print(processor.channel)  # wechat

# 非法實(shí)例化（靜態(tài)檢查報(bào)錯(cuò)）
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]:
        """更新訂單狀態(tài)，成功返回 1，失敗返回 0"""
        valid_status = {"pending", "paid", "shipped", "completed"}
        if status in valid_status:
            # 模擬更新邏輯
            return 1
        return 0

# 調(diào)用示例
handler = OrderHandler()
result = handler.update_status("123456", "paid")
print(result)  # 1

# 非法調(diào)用（靜態(tài)檢查報(bào)錯(cuò)）
handler.update_status("123456", "cancelled")  # Error: Argument 2 to "update_status" has incompatible type "Literal['cancelled']"; expected "Literal['pending', 'paid', 'shipped', 'completed']"

from typing import Literal, Union

# 限定值為指定字符串字面量 或 None
NullableTopic = Union[Literal["general", "news"], None]
topic: NullableTopic = None  # 合法
topic = "general"  # 合法
topic = "finance"  # 靜態(tài)檢查報(bào)錯(cuò)

# 限定值為指定數(shù)字字面量 或 布爾值
MixType = Union[Literal[1, 2], Literal[True, False]]
value: MixType = True  # 合法
value = 3  # 靜態(tài)檢查報(bào)錯(cuò)

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}")

# 合法調(diào)用
print_color(Color.RED)

# 非法調(diào)用（靜態(tài)檢查報(bào)錯(cuò)）
print_color(Color.GREEN)  # Error: Argument 1 to "print_color" has incompatible type "Literal[Color.GREEN]"; expected "Literal[Color.RED, Color.BLUE]"

from typing import LiteralString

def get_config(key: LiteralString) -> str:
    """限定 key 為字符串字面量（而非變量），避免注入風(fēng)險(xiǎn)"""
    config = {"host": "127.0.0.1", "port": "8080"}
    return config.get(key, "")

# 合法調(diào)用（傳入字面量）
get_config("host")  # 返回 "127.0.0.1"

# 非法調(diào)用（傳入變量，靜態(tài)檢查報(bào)錯(cuò)）
key = "port"
get_config(key)  # Error: Argument 1 to "get_config" has incompatible type "str"; expected "LiteralString"

from typing import Literal

def set_topic(topic: Literal["general", "news"]) -> None:
    # 手動(dòng)運(yùn)行時(shí)校驗(yàn)
    if topic not in {"general", "news"}:
        raise ValueError(f"Invalid topic: {topic}, must be 'general' or 'news'")
    print(f"Topic set to: {topic}")

# 運(yùn)行時(shí)觸發(fā)異常
set_topic("sports")  # ValueError: Invalid topic: sports, must be 'general' or 'news'

# 不推薦：字面量過(guò)多，代碼冗長(zhǎng)
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

from typing import Literal

# 錯(cuò)誤：列表是可變對(duì)象
invalid1: Literal[[1, 2]] = [1, 2]

# 錯(cuò)誤：字典是可變對(duì)象
invalid2: Literal[{"key": "value"}] = {"key": "value"}