Python Type Hints 完全教學：從基礎到 mypy 靜態型別檢查實戰

容器型別

Python 3.9 以後可以直接用小寫的內建型別當泛型，不用再從 typing 匯入了：

# Python 3.9+ 寫法（推薦）
names: list[str] = ["Alice", "Bob"]
ages: dict[str, int] = {"Alice": 30, "Bob": 25}
coordinates: tuple[float, float] = (25.03, 121.56)
unique_ids: set[int] = {1, 2, 3}

# 巢狀容器也沒問題
matrix: list[list[int]] = [[1, 2], [3, 4]]
config: dict[str, list[str]] = {"admins": ["alice", "bob"]}

Optional 與 Union

當一個值可能是某個型別或 None 時，用 Optional。Python 3.10 以後可以用更簡潔的 | 語法：

# Python 3.10+ 用 | 語法
def find_user(user_id: int) -> dict | None:
    """找不到使用者時回傳 None"""
    ...

# 多型別聯合
def process(value: str | int | float) -> str:
    return str(value)

# Python 3.9 以前的寫法
from typing import Optional, Union
def find_user_old(user_id: int) -> Optional[dict]:
    ...

TypeVar 與 Generics

當你寫一個函式要處理「任意型別但要保持一致」的情況，就需要泛型。Python 3.12 引入了全新的語法，寫起來超級乾淨：

# Python 3.12+ 新語法
def first[T](items: list[T]) -> T:
    return items[0]

# 泛型 class
class Stack[T]:
    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()

# 使用時型別會自動推斷
stack = Stack[int]()
stack.push(42)
value: int = stack.pop()  # mypy 知道這是 int

Protocol 結構化型別

Protocol 是 Python 版的「鴨子型別」正式化。不需要繼承，只要物件有對應的方法就算符合：

from typing import Protocol

class Drawable(Protocol):
    def draw(self) -> None: ...

class Circle:
    def draw(self) -> None:
        print("畫圓形")

class Square:
    def draw(self) -> None:
        print("畫方形")

def render(shape: Drawable) -> None:
    shape.draw()

# Circle 和 Square 都沒有繼承 Drawable，但因為有 draw 方法就能用
render(Circle())  # OK
render(Square())  # OK

這在寫 plugin 架構或依賴注入時特別好用，如果你對設計模式有興趣，可以參考 Python 裝飾器教學 了解更多進階用法。

TypedDict

對於那些用 dict 當作結構體在傳的場景，TypedDict 可以幫你精確定義每個 key 的型別：

from typing import TypedDict

class UserProfile(TypedDict):
    name: str
    age: int
    email: str
    is_premium: bool

def get_display_name(user: UserProfile) -> str:
    prefix = "⭐ " if user["is_premium"] else ""
    return f"{prefix}{user['name']}"

user: UserProfile = {
    "name": "Alice",
    "age": 30,
    "email": "[email protected]",
    "is_premium": True
}

mypy.ini 設定建議

在專案根目錄放一個 mypy.ini，統一團隊的檢查標準：

[mypy]
python_version = 3.12
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = True
check_untyped_defs = True
no_implicit_optional = True

# 第三方套件若沒有型別 stub，先忽略
[mypy-requests.*]
ignore_missing_imports = True

[mypy-celery.*]
ignore_missing_imports = True

mypy strict mode

如果你想用最嚴格的標準來檢查，可以開啟 strict mode：

mypy --strict src/

strict mode 會開啟所有嚴格檢查，包括禁止 Any 型別、要求所有函式都有型別標註等。建議新專案從一開始就用 strict mode，舊專案則慢慢遷移。