Python - 函數註解：初學者指南

您好，有志於成為 Python 程式設計師的朋友們！今天，我們將深入探究函數註解的迷人世界。如果您是编程新手，也請不必擔心——我將一步一步引導您了解這個概念，就像我過去幾年教學中對無數學生所做的那樣。所以，拿著您最喜歡的飲料，放鬆心情，讓我們一起踏上這場 Python 的冒險之旅！

Python - Function Annotations

什麼是函數註解？

函數註解是 Python 的一個功能，允許我們為函數參數和返回值添加元數據。可以把它們想成是我們附加在函數上的小筆記，用於提供額外的資訊。它們不會影響函數的運作方式，但對於文檔和類型檢查來說非常有幫助。

讓我們從一個簡單的例子開始：

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

在這個例子中，name 之後的 : str 是一個註解，表示 name 應該是一個字符串。結尾的 -> str 表示該函數將返回一個字符串。

為什麼使用函數註解？

它們使您的代碼更具可讀性。
它們幫助其他開發者（以及未來的您！）更好地理解您的代碼。
它們可以被類型檢查工具使用，以捕捉潛在的錯誤。

現在，讓我們更深入地了解不同類型的註解！

帶參數的函數註解

我們可以註解函數參數，以指示我們期望的數據類型。這裡有一個例子：

def calculate_area(length: float, width: float) -> float:
return length * width

在這個函數中，我們表示 length 和 width 都應該是浮點數（小數），而函數將返回一個浮點數。

讓我們試著使用它：

area = calculate_area(5.5, 3.2)
print(f"The area is: {area}")

輸出：

The area is: 17.6

請記住，這些註解不會強制類型——您仍然可以調用 calculate_area("hello", "world")，但它並沒有多大意義！

帶返回類型的函數註解

我們已經看到了 -> float 返回類型的註解，但讓我們看看一個更複雜的例子：

def get_user_info(user_id: int) -> dict:
# 設想這個函數從數據庫中獲取用戶數據
return {
"id": user_id,
"name": "Alice",
"age": 30,
"email": "[email protected]"
}

user = get_user_info(12345)
print(f"User name: {user['name']}")

輸出：

User name: Alice

在這裡，我們表示該函數接受一個整數 user_id 並返回一個字典。

帶表達式的函數註解

註解不一定是簡單的類型——它們也可以是更複雜的表達式。這裡有一個例子：

from typing import List, Union

def process_items(items: List[Union[int, str]]) -> List[str]:
return [str(item).upper() for item in items]

result = process_items([1, "hello", 42, "world"])
print(result)

輸出：

['1', 'HELLO', '42', 'WORLD']

在這個例子中，List[Union[int, str]] 表示函數期望一個列表，其中每個項目可以是整數或字符串。

帶默認參數的函數註解

我們可以將註解與默認參數結合使用。這裡是怎麼做的：

def greet_user(name: str = "Guest") -> str:
return f"Welcome, {name}!"

print(greet_user())
print(greet_user("Alice"))

輸出：

Welcome, Guest!
Welcome, Alice!

在這個函數中，我們表示 name 應該是一個字符串，如果沒有提供名稱，則默認為 "Guest"。

將所有知識結合在一起

現在，讓我們看看一個結合了各種註解技術的更複雜的例子：

from typing import List, Dict, Union

def analyze_sales(data: List[Dict[str, Union[str, float]]]) -> Dict[str, float]:
total_sales = 0.0
items_sold = 0

for transaction in data:
total_sales += transaction['amount']
items_sold += 1

return {
"total_sales": total_sales,
"average_sale": total_sales / items_sold if items_sold > 0 else 0
}

sales_data = [
{"item": "Widget A", "amount": 10.99},
{"item": "Widget B", "amount": 5.99},
{"item": "Widget C", "amount": 15.99}
]

result = analyze_sales(sales_data)
print(f"Total sales: ${result['total_sales']:.2f}")
print(f"Average sale: ${result['average_sale']:.2f}")

輸出：

Total sales: $32.97
Average sale: $10.99

這個例子展示了如何使用複雜的註解來描述我們的輸入數據和返回值的結構。

函數註解方法摘要

以下是不同函數註解方式的摘要表：

方法	示例	描述
參數註解	`def func(x: int):`	建議參數的類型
返回類型註解	`def func() -> str:`	建議函數的返回類型
帶註解的默認值	`def func(x: int = 0):`	將類型建議與默認值結合
複雜類型註解	`def func(x: List[int]):`	使用 `typing` 模塊中的類型以提供更特定的類型提示
多個類型（Union）	`def func(x: Union[int, str]):`	表示參數可以是多個類型之一

請記住，這些註解是提示，而不是嚴格的規則。Python 並不會阻止您使用不同的類型，但像 mypy 這樣的工具可以使用這些註解來在運行代碼之前捕捉潛在的錯誤。

以上就是了，我親愛的學生們！我們已經走過了 Python 函數註解的土地。我希望這本指南能為您照亮這個概念。請記住，學習的最佳方式是通過實踐，所以不要猶豫在您自己的代碼中嘗試這些註解。快樂編程，願您的函數永遠都有良好的註解！

Credits: Image by storyset