全方位指南：初學者學習 Python 類型註解 (Type Annotations)

更新日期： 2025 年 3 月 8 日

在 Python 的世界裡，靈活和動態是它的標誌之一，但這同時也可能帶來一些困惑。

例如，當你看到一個函數 def add(a, b): return a + b 時，你無法直觀地知道 a 和 b 期望的數據類型。

在大型專案中，這種不確定性更容易引發錯誤和難以維護的代碼。

因此，Python 引入了「類型註解」（Type Annotations），讓我們能夠明確告訴自己和他人（甚至是 IDE 和靜態分析工具），每個變數和函數應該處理的數據類型。

本篇文章將詳細介紹 Python 類型註解的基礎概念、使用方法，以及常見的應用場景，幫助初學者快速掌握這項有力的工具。

什麼是類型註解 (Type Annotations)？

類型註解是一種在 Python 中標示變數、函數參數和返回值期望數據類型的語法。

它不會影響程式的執行（Python 依然是動態語言），但能提高代碼的可讀性和可靠性。

類型註解的作用

• 提高可讀性：讓代碼更容易理解。
• 協助開發工具：IDE（如 PyCharm、VS Code）可以基於類型註解提供更好的自動補全和錯誤提示。
• 幫助靜態檢查：使用工具（如 mypy）可以在程式運行前發現潛在的類型錯誤。

基本的類型註解語法

變數的類型註解

在變數名稱後使用冒號 : 指定類型：

name: str = "Alice"
age: int = 25
is_student: bool = True
scores: list = [85, 90, 78]

函數參數和返回值的類型註解

可以使用箭頭 -> 來標示函數的返回值類型：

def greet(name: str) -> str:
    return f"Hello, {name}!"

print(greet("Alice"))  
# 輸出: Hello, Alice!

在這個例子中，name: str 表示 name 參數應該是 str 字串類型，而 -> str 表示這個函數會返回一個 str 類型的數據。

常見的類型提示 (Type Hints)

Python 標準庫中的 typing 模組提供了豐富的類型提示工具。

基本類型

• int：整數，例如 42。
• float：浮點數，例如 3.14。
• str：字串，例如 "Hello"。
• bool：布林值，例如 True 或 False。
• None：無值，例如在沒有返回值的函數中使用 -> None。

容器類型

• list[int]：整數列表，例如 [1, 2, 3]。
• dict[str, int]：字典，鍵為字串，值為整數，例如 {"apple": 1, "banana": 2}。
• tuple[str, int]：元組，包含特定順序和類型的元素，例如 ("age", 30)。
• set[str]：字串集合，例如 {"apple", "banana"}。

from typing import List, Dict, Tuple, Set

names: List[str] = ["Alice", "Bob", "Charlie"]
scores: Dict[str, int] = {"Math": 95, "English": 88}
person: Tuple[str, int] = ("John", 30)
unique_items: Set[str] = {"apple", "banana"}

特殊類型

• Any：可以是任何類型，相當於不限制類型。
• Union：允許多種類型，例如 Union[int, str]。
• Optional：類型可以是指定類型或 None，例如 Optional[int] 等價於 Union[int, None]。

from typing import Any, Union, Optional

data: Any = "Anything goes"
number_or_text: Union[int, str] = 42
maybe_number: Optional[int] = None

高級用法：泛型 (Generics) 與 Callable

泛型 (Generics)

當我們創建自定義類別或函數時，可以使用泛型來適應多種類型。例如 list[T] 可以是任何類型的列表：

from typing import TypeVar, List

T = TypeVar('T')

def get_first_element(elements: List[T]) -> T:
    return elements[0]

print(get_first_element([1, 2, 3]))  
# 輸出: 1
print(get_first_element(["a", "b", "c"]))  
# 輸出: "a"

Callable (可調用物件)

用於標示可以像函數一樣調用的物件：

from typing import Callable

def operate(a: int, b: int, func: Callable[[int, int], int]) -> int:
    return func(a, b)

result = operate(2, 3, lambda x, y: x + y)
print(result)  
# 輸出: 5

Callable[[int, int], int] 表示 func 是一個接收兩個 int 並返回一個 int 的函數。

使用靜態檢查工具 (mypy)

Python 本身不會強制檢查類型，但你可以使用 mypy 這樣的工具進行靜態檢查：

安裝 mypy

pip install mypy

使用 mypy 進行類型檢查

建立一個檔案 example.py：

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

print(add(10, "20"))  # 類型錯誤

在命令列運行：

mypy example.py

輸出將會顯示類型錯誤：

error: Argument 2 to "add" has incompatible type "str"; expected "int"

總結

1. 類型註解的好處：提升代碼的可讀性、易於維護，並有助於早期錯誤檢測。
2. 基本語法：變數、函數參數和返回值都可以使用類型註解標示。
3. 常見類型提示：包括基本類型（int、str）、容器類型（list、dict）、特殊類型（Any、Optional）。
4. 高級應用：泛型（TypeVar）、可調用物件（Callable）進一步增強代碼的靈活性。
5. 靜態類型檢查：使用 mypy 等工具，在程式運行前發現潛在錯誤。

初學者可以從簡單的類型註解開始，逐步深入學習高級用法，這將對你的 Python 開發之路帶來巨大的幫助！