Python Type Hints
類型提示

Python 支持動態類型（Dynamic Typing），宣告變數時無需指定其數據類型，變數的類型也可以在程式運行時隨時改變。這種靈活性讓 Python 的語法非常簡潔，開發速度也很快。

然而，在大型或複雜的專案中，動態類型可能會引發一些難以追蹤的問題。由於變數類型的不確定性，你可能會不小心將錯誤類型的數據傳遞給函數，這類錯誤通常只有在程式運行到該行代碼時才會被發現，導致所謂的「運行時錯誤」（Runtime Error）。這不僅增加了除錯的難度，也降低了代碼的可靠性。

為了解決這個問題，Python 3.5 引入了「類型提示」（Type Hints）功能。它允許開發者為變數、函數參數和返回值「提示」期望的數據類型，在不改變 Python 動態本質的前提下，提供靜態分析（Static Analysis）的能力，從而提升代碼質量和開發體驗。

🤔 什麼是 Python Type Hints？

Type Hints 是一種在代碼中標註變數、函數參數和返回值期望類型的語法。它就像是給代碼加上一層註解，告訴閱讀代碼的人或其他工具（如 IDE 或靜態分析器）這裡應該是什麼類型。

讓我們看一個簡單的例子。這是一個沒有 Type Hints 的函數：

# Before: No Type Hints
def add(a, b):
    return a + b

這個 add 函數的意圖很明顯是將兩個數字相加。但如果有人不小心傳入了兩個字串，例如 add("hello", " world")，程式不但不會報錯，還會返回 "hello world"，這可能不是你預期的結果。

現在，我們為這個函數加上 Type Hints：

# After: With Type Hints
def add(a: int, b: int) -> int:
    return a + b

語法很直觀：

• a: int 表示參數 a 期望是 int 類型。
• -> int 表示這個函數期望返回 int 類型。

加上 Type Hints 後，代碼的意圖變得更加清晰。更重要的是，開發工具可以利用這些信息來幫助你。

👍 使用 Type Hints 的好處

引入 Type Hints 雖然增加了一點點語法，但它帶來的好處遠大於此。

1. 提早發現錯誤

這是 Type Hints 最核心的價值。當你使用了 Type Hints，像 Visual Studio Code、PyCharm 這樣的現代 IDE，或是其他靜態類型檢查工具，就可以在你不運行程式的情況下分析你的代碼。

如果它們發現類型不匹配，就會立即標示出警告。例如，對於前面定義的 add(a: int, b: int) 函數，如果你嘗試這樣調用：

add("hello", "world")

你的 IDE 很可能會在 add("hello", "world") 這行代碼下劃上波浪線，並提示你：Argument of type "str" cannot be assigned to parameter "a" of type "int"。這讓你在編寫代碼的階段就能發現並修正潛在的 bug，而不是等到程式運行時才崩潰。

2. 提升代碼可讀性和可維護性

Type Hints 本身就是一種極佳的文檔。當你幾個月後回頭看自己的代碼，或者當團隊新成員接手你的專案時，他們可以透過 Type Hints 快速理解一個函數期望接收什麼樣的數據，以及它會返回什麼。

這大大降低了理解和維護代碼的成本，尤其是在處理複雜的數據結構時，例如 Dict[str, List[User]] 這樣的提示遠比閱讀大段的文檔或代碼來得快。

3. 增強開發工具的智能提示 (Autocomplete)

當 IDE 知道一個變數的確切類型時，它就能提供精準的自動完成建議。

假設你有一個 User class：

class User:
    def __init__(self, name: str, email: str):
        self.name = name
        self.email = email

    def get_profile_summary(self) -> str:
        return f"User: {self.name}, Email: {self.email}"

def send_welcome_email(user: User):
    # 當你在這裡輸入 user. 時
    # IDE 會自動提示 name, email, get_profile_summary() 等屬性和方法
    print(f"Sending email to {user.email}...")

在 send_welcome_email 函數中，因為你標註了 user 參數的類型是 User，所以當你輸入 user. 時，編輯器會立刻彈出 User object 擁有的屬性（name, email）和方法（get_profile_summary），讓你寫代碼更快更準確。如果沒有 Type Hints，編輯器就無法提供這些有用的建議，因為你可以傳入任何類型的 Object。

使用 Type Hints 是完全可選的。你可以選擇只在專案的關鍵部分使用，或是在新代碼中開始使用，而無需修改所有舊代碼。

👎 Type Hints 的潛在缺點

當然，沒有任何技術是完美的，Type Hints 也有一些需要考量的方面。

1. 增加代碼的複雜度：最直接的影響是代碼看起來更長、更「囉嗦」。對於習慣了 Python 簡潔風格的開發者來說，可能需要一些時間來適應。對於複雜的類型，例如 Callable[[int, str], bool]，提示本身也可能變得難以閱讀。

2. 可能失去靈活性：Python 的動態特性允許函數處理任何具備特定行為（例如 .send() 方法）的物件，Type hints 可能會限制其靈活性。

⚠️ 重要提醒：Type Hints 不影響程式運行

這一點非常重要，必須再三強調：Python 解譯器在執行代碼時會完全忽略 Type Hints。

Type Hints 的作用域僅限於「靜態分析」階段，也就是由 IDE 或其他分析工具進行的代碼檢查。它不會為你的程式帶來任何運行時的類型檢查。

讓我們看看這個例子：

def greet(name: str):
    print(f"Hello, {name}")

# 儘管 'name' 被提示為 str，但傳入 int 類型
# 程式依然可以正常運行，不會報錯！
greet(123)

當你運行這段代碼時，它會順利執行並輸出 Hello, 123。Python 解譯器不會因為 123 不是 str 而拋出異常。

真正的警告來自你的開發工具。你的 IDE 會在你寫下 greet(123) 的那一刻就提醒你類型不匹配。這意味著 Type Hints 是一個幫助開發者在開發階段預防錯誤的工具，而不是一個在運行階段強制執行規則的機制。

🚀 建議使用 Type Hints 的時機

雖然 Type Hints 是可選的，但在以下情況下建議你使用它：

• 大型專案與團隊協作：在多人協作的環境中，清晰的類型定義是溝通的橋樑，可以有效避免因誤解函數接口而導致的錯誤。
• 開發 Library 或 API：當你寫的代碼是給別人使用時，Type Hints 是最好的文檔。它能幫助使用者正確地調用你的 API。
• 處理複雜的數據結構：當你的函數需要接收或返回嵌套的字典或列表時，使用 Type Hints 可以讓數據結構一目了然。

Type Hints 是一個強大的現代化工具，引入了靜態語言的嚴謹性和可靠性，讓你的代碼更健壯、更易於維護。

📚 參考資料

• Python Official Documentation - typing — Support for type hints
• PEP 484 – Type Hints