Python Type Hints 教學 — 型別註記、Optional 與 mypy 檢查

Python Type Hints（型別提示）

這篇 Python type hints 教學將帶你認識型別註記：在程式碼上標明「這個變數／參數／回傳值應該是什麼型別」。Python 仍然是動態型別語言，型別提示不影響執行，但它讓 IDE 自動補全更準、錯誤在寫程式時就被指出，現代 Python 專案幾乎都在用。

基本語法

變數用 名稱: 型別，函式參數同理、回傳值用 ->：

name: str = "小明"
age: int = 25
height: float = 175.5
is_student: bool = True

def greet(name: str, times: int = 1) -> str:
    return f"你好，{name}！" * times

print(greet("小明", 2))

執行輸出：

你好，小明！你好，小明！

沒有回傳值的函式標 -> None。

容器的型別寫法

容器可以進一步標明「裡面裝什麼」：

寫法	意義
`list[int]`	裝 int 的 List
`dict[str, float]`	key 是 str、value 是 float 的字典
`tuple[str, int]`	第一個元素 str、第二個 int 的 Tuple
`set[str]`	裝 str 的集合

scores: dict[str, list[int]] = {
    "小明": [85, 90],
    "小華": [92],
}

def average(nums: list[int]) -> float:
    return sum(nums) / len(nums)

print(average(scores["小明"]))

執行輸出：

87.5

Optional：可能是 None 的值

「找不到就回傳 None」是常見模式，型別寫成 型別 | None：

def find_student(students: dict[str, int], name: str) -> int | None:
    return students.get(name)     # 找不到回傳 None

students = {"小明": 85}
result = find_student(students, "小華")

if result is not None:           # 用之前先檢查
    print(f"成績：{result}")
else:
    print("查無此人")

執行輸出：

查無此人

int | None 是現代寫法；舊程式碼裡的 Optional[int]（來自 typing 模組）意思完全相同。

重點觀念：提示不會強制執行

這是最大的誤解來源——型別寫錯，程式照樣跑：

def add(a: int, b: int) -> int:
    return a + b

print(add("哈", "囉"))    # 跟註記不符，但完全不會報錯

執行輸出：

哈囉

要真的檢查，靠外部工具 mypy（用 uv 安裝：uv add --dev mypy）：

uv run mypy main.py

執行輸出：

main.py:4: error: Argument 1 to "add" has incompatible type "str"; expected "int"
Found 1 error in 1 file (checked 1 source file)

VS Code 的 Python 擴充套件也會根據型別提示即時畫紅線，這是日常開發中最有感的好處。

常見錯誤

1. 以為型別提示會自動驗證

如上節，執行期完全不檢查。需要執行期驗證（例如 API 輸入），用 Pydantic 這類套件。

2. 回傳值可能是 None 卻沒標

標了 -> int 但某個分支沒 return（實際回傳 None），mypy 會抓出來。誠實標成 -> int | None，呼叫端才知道要檢查。

3. 想太多、標太細

一開始不用追求完美：先從「函式的參數與回傳值」標起，內部區域變數通常讓 IDE 自己推導即可。

總結

型別提示語法：變數 x: int、函式 def f(a: str) -> bool、容器 list[int]、可能為 None 用 int | None；它不影響執行，價值在 IDE 提示與 mypy 靜態檢查。從函式簽名開始標就好。下一篇進入檔案讀寫，正式跟外部世界打交道。

延伸閱讀

ㄚ槌