Python `typing.NamedTuple` (`collections.namedtuple`) 與 `typing.Literal` 教學 — 用型別「防止錯配」; StripRule = NamedTuple(“StripRule”, [(“regex”, re.Pattern), (“flag”, str)]) vs StripRule = namedtuple(“StripRule”, [“regex”, “flag”])

from typing import Any, Literal, NamedTuple

from collections import namedtuple   # 注意:小寫、是「函式」

from collections import namedtuple

# 傳「類別名字串」+「欄位名清單」,回傳一個新的類別
StripRule = namedtuple("StripRule", ["regex", "flag"])

rule = StripRule(regex="(?i)processstep(_\\d+)?$", flag="is_class_name_rm_processstep")

print(rule.regex)   # 具名存取:比 rule[0] 好讀
print(rule.flag)    # is_class_name_rm_processstep
print(rule[0])      # 仍可用索引 (它是 tuple)

import re
from typing import NamedTuple

class StripRule(NamedTuple):
    regex: re.Pattern[str]   # 欄位 + 型別
    flag: str                # 欄位 + 型別

rule = StripRule(re.compile(r"(?i)processstep(_\d+)?$"), "is_class_name_rm_processstep")

print(rule.regex)   # re.compile('(?i)processstep(_\\d+)?$', re.IGNORECASE)  <- (?i) 會讓 repr 帶出 re.IGNORECASE
print(rule.flag)    # is_class_name_rm_processstep

class StripRule(NamedTuple):
    """一條去尾規則:正則 + 對應旗標。"""
    regex: re.Pattern[str]
    flag: str = "is_class_name_rm_step"   # 預設值

    def apply(self, name: str) -> str:     # 也能加方法
        return self.regex.sub("", name)

import re
from collections import namedtuple
from typing import NamedTuple

# (A) collections:欄位只給「名字字串」,不帶型別 —— 合法
StripRule = namedtuple("StripRule", ["regex", "flag"])

# (B) typing 的「函式寫法」:欄位要給 (名字, 型別) 的 tuple —— 合法
StripRule = NamedTuple("StripRule", [("regex", re.Pattern), ("flag", str)])

# (C) typing 的「class 寫法」:本專案採用 —— 合法,最好讀
class StripRule(NamedTuple):
    regex: re.Pattern[str]
    flag: str

from typing import NamedTuple

StripRule = NamedTuple("StripRule", ["regex", "flag"])   
# ❌ 每個欄位不是 (name, type)
# ValueError: too many values to unpack (expected 2)
#   (typing 內部 _make_nmtuple 會對每個欄位做 `for n, t in types` 解包;
#    把字串 "regex" 當可迭代物拆開就爆掉 —— Python 3.11 實測)

from collections import namedtuple
from typing import NamedTuple

class A(NamedTuple):
    x: int

B = namedtuple("B", ["x"])

a = A(1)
print(isinstance(a, tuple))   # True  <- NamedTuple 產物也是 tuple
print(a._fields)              # ('x',) <- 具備 namedtuple 的 API
print(A.__annotations__)      # {'x': <class 'int'>} <- 有型別資訊
print(B.__annotations__)      # {}                   <- collections 版是「空的」(沒有型別資訊,但屬性本身存在)

class StripRule(NamedTuple):
    regex: re.Pattern[str]   # 比對「關鍵字 + 選擇性的 _數字 尾綴」
    flag: RmFlagName         # 命中此規則時要打的旗標名

PROCESSSTEP_RULE = StripRule(re.compile(r"(?i)processstep(_\d+)?$"), "is_class_name_rm_processstep")
MELTANSTEP_RULE  = StripRule(re.compile(r"(?i)meltanstep(_\d+)?$"),  "is_class_name_rm_meltanstep")
STEP_RULE        = StripRule(re.compile(r"(?i)step(_\d+)?$"),        "is_class_name_rm_step")

def build_aliases(tokens, strip_regex, flag_name, ...):   # 舊寫法
    ...

# 呼叫端:regex 與 flag 是「各自獨立」的兩個參數
build_aliases(tokens, re.compile(r"(?i)step(_\d+)?$"), "is_class_name_rm_processstep")
#                     ^^^^^ step 的 regex               ^^^^^ 卻配了 processstep 的 flag  → 配錯也沒人擋!

from typing import Literal

RmFlagName = Literal[
    "is_class_name_rm_processstep",
    "is_class_name_rm_meltanstep",
    "is_class_name_rm_step",
]

def mark(flag: str): ...            # 任何字串都算合法,打錯字不會被抓
def mark(flag: RmFlagName): ...     # 只有那三個字串合法,打錯字型別檢查器立刻標紅

mark("is_class_name_rm_processstep")   # OK
mark("is_class_name_rm_stepp")         # 多打一個 p:僅「型別檢查器開啟時」才標紅波浪;執行期不報錯,純 str 更完全不抓

import re
from typing import Literal, NamedTuple

# (1) 用 Literal 限縮旗標名的合法值
RmFlagName = Literal[
    "is_class_name_rm_processstep",
    "is_class_name_rm_meltanstep",
    "is_class_name_rm_step",
]

# (2) 用 NamedTuple 把 regex 與 flag 綁成一顆規則,且 flag 的型別就是 RmFlagName
class StripRule(NamedTuple):
    regex: re.Pattern[str]
    flag: RmFlagName          # <- 只接受那三個字串,否則型別檢查器報錯

# (3) 定義三顆規則:配對在此一次釘死,之後不可能拆錯
PROCESSSTEP_RULE = StripRule(re.compile(r"(?i)processstep(_\d+)?$"), "is_class_name_rm_processstep")
MELTANSTEP_RULE  = StripRule(re.compile(r"(?i)meltanstep(_\d+)?$"),  "is_class_name_rm_meltanstep")
STEP_RULE        = StripRule(re.compile(r"(?i)step(_\d+)?$"),        "is_class_name_rm_step")

BAD_RULE = StripRule(re.compile(r"(?i)step(_\d+)?$"), "is_class_name_rm_stepX")
#                                                      ^^^^^^^^^^^^^^^^^^^^^^^ 型別檢查器 (開啟時) 標紅,執行期不報錯:
#   Argument of type "Literal['is_class_name_rm_stepX']" cannot be assigned to
#   parameter "flag" of type "RmFlagName"

# ── collections.namedtuple:快速、無型別 ─────────────────
from collections import namedtuple
StripRule = namedtuple("StripRule", ["regex", "flag"])

# ── typing.NamedTuple:class 語法 + 型別 (本專案採用) ────
from typing import NamedTuple
class StripRule(NamedTuple):
    regex: "re.Pattern[str]"
    flag: str = "is_class_name_rm_step"   # 可給預設值
    def apply(self, name): ...             # 可加方法

r = StripRule(re.compile(r"(?i)step$"), "is_class_name_rm_step")
r.regex          # 具名存取
r[0]             # 仍可索引 (是 tuple)
r._fields        # ('regex', 'flag')
r._replace(flag="is_class_name_rm_processstep")   # 產生新的一顆 (原本不可變)

# ── Literal:限縮合法值 (型別檢查期生效,執行期不強制) ───
from typing import Literal
RmFlagName = Literal["is_class_name_rm_processstep",
                     "is_class_name_rm_meltanstep",
                     "is_class_name_rm_step"]