544 lines
13 KiB
Markdown
544 lines
13 KiB
Markdown
---
|
||
name: python-patterns
|
||
description: Pythonic 語法習慣、PEP 8 標準、型別提示 (Type Hints) 以及建構強韌、高效且易於維護的 Python 應用程式之最佳實踐。
|
||
---
|
||
|
||
# Python 開發模式 (Python Development Patterns)
|
||
|
||
用於建構強韌、高效且易於維護的應用程式之道地 Python 模式與最佳實踐。
|
||
|
||
## 何時啟用
|
||
|
||
- 編寫新的 Python 程式碼。
|
||
- 審查 Python 程式碼。
|
||
- 重構現有的 Python 程式碼。
|
||
- 設計 Python 套件或模組。
|
||
|
||
## 核心原則
|
||
|
||
### 1. 可讀性至上 (Readability Counts)
|
||
|
||
Python 優先考慮可讀性。程式碼應當顯而易見且易於理解。
|
||
|
||
```python
|
||
# 正確：清晰且具備可讀性
|
||
def get_active_users(users: list[User]) -> list[User]:
|
||
"""從提供的清單中僅回傳活躍的使用者。"""
|
||
return [user for user in users if user.is_active]
|
||
|
||
|
||
# 錯誤：雖然取巧但令人困惑
|
||
def get_active_users(u):
|
||
return [x for x in u if x.a]
|
||
```
|
||
|
||
### 2. 明示優於暗示 (Explicit is Better Than Implicit)
|
||
|
||
避免使用神祕的機制；應明確表達程式碼的功能。
|
||
|
||
```python
|
||
# 正確：明示配置資訊
|
||
import logging
|
||
|
||
logging.basicConfig(
|
||
level=logging.INFO,
|
||
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
|
||
)
|
||
|
||
# 錯誤：隱藏的副作用
|
||
import some_module
|
||
some_module.setup() # 這具體做了什麼？
|
||
```
|
||
|
||
### 3. EAFP 模式 — 請求原諒比請求許可更容易
|
||
|
||
Python 傾向於使用例外處理，而非預先檢查條件。
|
||
|
||
```python
|
||
# 正確：EAFP 風格
|
||
def get_value(dictionary: dict, key: str) -> Any:
|
||
try:
|
||
return dictionary[key]
|
||
except KeyError:
|
||
return default_value
|
||
|
||
# 錯誤：LBYL (三思而後行) 風格
|
||
def get_value(dictionary: dict, key: str) -> Any:
|
||
if key in dictionary:
|
||
return dictionary[key]
|
||
else:
|
||
return default_value
|
||
```
|
||
|
||
## 型別提示 (Type Hints)
|
||
|
||
### 基礎型別註解
|
||
|
||
```python
|
||
from typing import Optional, List, Dict, Any
|
||
|
||
def process_user(
|
||
user_id: str,
|
||
data: Dict[str, Any],
|
||
active: bool = True
|
||
) -> Optional[User]:
|
||
"""處理使用者並回傳更新後的使用者物件或 None。"""
|
||
if not active:
|
||
return None
|
||
return User(user_id, data)
|
||
```
|
||
|
||
### 現代型別提示 (Python 3.9+)
|
||
|
||
```python
|
||
# Python 3.9+ - 直接使用內建型別
|
||
def process_items(items: list[str]) -> dict[str, int]:
|
||
return {item: len(item) for item in items}
|
||
|
||
# Python 3.8 及更早版本 - 需使用 typing 模組
|
||
from typing import List, Dict
|
||
|
||
def process_items(items: List[str]) -> Dict[str, int]:
|
||
return {item: len(item) for item in items}
|
||
```
|
||
|
||
### 型別別名與 TypeVar
|
||
|
||
```python
|
||
from typing import TypeVar, Union
|
||
|
||
# 針對複雜型別建立別名
|
||
JSON = Union[dict[str, Any], list[Any], str, int, float, bool, None]
|
||
|
||
def parse_json(data: str) -> JSON:
|
||
return json.loads(data)
|
||
|
||
# 泛型型別
|
||
T = TypeVar('T')
|
||
|
||
def first(items: list[T]) -> T | None:
|
||
"""回傳第一個項目，若清單為空則回傳 None。"""
|
||
return items[0] if items else None
|
||
```
|
||
|
||
### 基於 Protocol 的鴨子型別 (Duck Typing)
|
||
|
||
```python
|
||
from typing import Protocol
|
||
|
||
class Renderable(Protocol):
|
||
def render(self) -> str:
|
||
"""將物件渲染為字串。"""
|
||
|
||
def render_all(items: list[Renderable]) -> str:
|
||
"""渲染所有實作了 Renderable 協定的項目。"""
|
||
return "\n".join(item.render() for item in items)
|
||
```
|
||
|
||
## 例外處理模式
|
||
|
||
### 具體的例外處理
|
||
|
||
```python
|
||
# 正確：捕捉特定的例外
|
||
def load_config(path: str) -> Config:
|
||
try:
|
||
with open(path) as f:
|
||
return Config.from_json(f.read())
|
||
except FileNotFoundError as e:
|
||
raise ConfigError(f"找不到配置檔案: {path}") from e
|
||
except json.JSONDecodeError as e:
|
||
raise ConfigError(f"配置檔案中存在無效的 JSON: {path}") from e
|
||
|
||
# 錯誤：寬泛的 except
|
||
def load_config(path: str) -> Config:
|
||
try:
|
||
with open(path) as f:
|
||
return Config.from_json(f.read())
|
||
except:
|
||
return None # 靜默失敗！
|
||
```
|
||
|
||
### 例外鏈 (Exception Chaining)
|
||
|
||
```python
|
||
def process_data(data: str) -> Result:
|
||
try:
|
||
parsed = json.loads(data)
|
||
except json.JSONDecodeError as e:
|
||
# 使用 'from e' 鏈結例外以保留堆疊追蹤資訊
|
||
raise ValueError(f"解析資料失敗: {data}") from e
|
||
```
|
||
|
||
### 自定義例外階層
|
||
|
||
```python
|
||
class AppError(Exception):
|
||
"""所有應用程式錯誤的基底例外。"""
|
||
pass
|
||
|
||
class ValidationError(AppError):
|
||
"""當輸入驗證失敗時拋出。"""
|
||
pass
|
||
|
||
class NotFoundError(AppError):
|
||
"""當找不到請求的資源時拋出。"""
|
||
pass
|
||
|
||
# 使用方式
|
||
def get_user(user_id: str) -> User:
|
||
user = db.find_user(user_id)
|
||
if not user:
|
||
raise NotFoundError(f"找不到使用者: {user_id}")
|
||
return user
|
||
```
|
||
|
||
## 上下文管理器 (Context Managers)
|
||
|
||
### 資源管理
|
||
|
||
```python
|
||
# 正確：使用上下文管理器
|
||
def process_file(path: str) -> str:
|
||
with open(path, 'r') as f:
|
||
return f.read()
|
||
|
||
# 錯誤：手動管理資源
|
||
def process_file(path: str) -> str:
|
||
f = open(path, 'r')
|
||
try:
|
||
return f.read()
|
||
finally:
|
||
f.close()
|
||
```
|
||
|
||
### 自定義上下文管理器
|
||
|
||
```python
|
||
from contextlib import contextmanager
|
||
import time
|
||
|
||
@contextmanager
|
||
def timer(name: str):
|
||
"""用於計算程式區塊執行時間的上下文管理器。"""
|
||
start = time.perf_counter()
|
||
yield
|
||
elapsed = time.perf_counter() - start
|
||
print(f"{name} 耗時 {elapsed:.4f} 秒")
|
||
|
||
# 使用方式
|
||
with timer("資料處理"):
|
||
process_large_dataset()
|
||
```
|
||
|
||
## 解析式 (Comprehensions) 與產生器 (Generators)
|
||
|
||
### 清單解析式
|
||
|
||
```python
|
||
# 正確：使用清單解析式進行簡易轉換
|
||
names = [user.name for user in users if user.is_active]
|
||
|
||
# 錯誤：手動迴圈
|
||
names = []
|
||
for user in users:
|
||
if user.is_active:
|
||
names.append(user.name)
|
||
|
||
# 過於複雜的解析式應展開處理
|
||
# 錯誤：過於複雜
|
||
result = [x * 2 for x in items if x > 0 if x % 2 == 0]
|
||
|
||
# 正確：使用產生器函式或展開迴圈以利閱讀
|
||
def filter_and_transform(items: Iterable[int]) -> list[int]:
|
||
result = []
|
||
for x in items:
|
||
if x > 0 and x % 2 == 0:
|
||
result.append(x * 2)
|
||
return result
|
||
```
|
||
|
||
### 產生器表達式
|
||
|
||
```python
|
||
# 正確：使用產生器進行惰性求值
|
||
total = sum(x * x for x in range(1_000_000))
|
||
|
||
# 錯誤：建立了一個巨大的中間清單
|
||
total = sum([x * x for x in range(1_000_000)])
|
||
```
|
||
|
||
### 產生器函式
|
||
|
||
```python
|
||
def read_large_file(path: str) -> Iterator[str]:
|
||
"""逐行讀取大型檔案。"""
|
||
with open(path) as f:
|
||
for line in f:
|
||
yield line.strip()
|
||
|
||
# 使用方式
|
||
for line in read_large_file("huge.txt"):
|
||
process(line)
|
||
```
|
||
|
||
## 資料類別 (Data Classes) 與具名元組 (Named Tuples)
|
||
|
||
### 資料類別 (Data Classes)
|
||
|
||
```python
|
||
from dataclasses import dataclass, field
|
||
from datetime import datetime
|
||
|
||
@dataclass
|
||
class User:
|
||
"""使用者實體，自動生成 __init__, __repr__, 與 __eq__。"""
|
||
id: str
|
||
name: str
|
||
email: str
|
||
created_at: datetime = field(default_factory=datetime.now)
|
||
is_active: bool = True
|
||
|
||
# 使用方式
|
||
user = User(
|
||
id="123",
|
||
name="Alice",
|
||
email="alice@example.com"
|
||
)
|
||
```
|
||
|
||
### 具名元組 (Named Tuples)
|
||
|
||
```python
|
||
from typing import NamedTuple
|
||
|
||
class Point(NamedTuple):
|
||
"""不可變的 2D 座標點。"""
|
||
x: float
|
||
y: float
|
||
|
||
def distance(self, other: 'Point') -> float:
|
||
return ((self.x - other.x) ** 2 + (self.y - other.y) ** 2) ** 0.5
|
||
|
||
# 使用方式
|
||
p1 = Point(0, 0)
|
||
p2 = Point(3, 4)
|
||
print(p1.distance(p2)) # 5.0
|
||
```
|
||
|
||
## 裝飾器 (Decorators)
|
||
|
||
### 函式裝飾器
|
||
|
||
```python
|
||
import functools
|
||
import time
|
||
from typing import Callable
|
||
|
||
def timer(func: Callable) -> Callable:
|
||
"""用於計時函式執行時間的裝飾器。"""
|
||
@functools.wraps(func)
|
||
def wrapper(*args, **kwargs):
|
||
start = time.perf_counter()
|
||
result = func(*args, **kwargs)
|
||
elapsed = time.perf_counter() - start
|
||
print(f"{func.__name__} 執行耗時 {elapsed:.4f} 秒")
|
||
return result
|
||
return wrapper
|
||
```
|
||
|
||
## 並發模式 (Concurrency Patterns)
|
||
|
||
### I/O 密集型任務使用執行緒 (Threading)
|
||
|
||
```python
|
||
import concurrent.futures
|
||
|
||
def fetch_url(url: str) -> str:
|
||
"""擷取 URL 內容（I/O 密集型操作）。"""
|
||
import urllib.request
|
||
with urllib.request.urlopen(url) as response:
|
||
return response.read().decode()
|
||
|
||
def fetch_all_urls(urls: list[str]) -> dict[str, str]:
|
||
"""使用執行緒池並行擷取多個 URL。"""
|
||
with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
|
||
future_to_url = {executor.submit(fetch_url, url): url for url in urls}
|
||
results = {}
|
||
for future in concurrent.futures.as_completed(future_to_url):
|
||
url = future_to_url[future]
|
||
try:
|
||
results[url] = future.result()
|
||
except Exception as e:
|
||
results[url] = f"錯誤: {e}"
|
||
return results
|
||
```
|
||
|
||
### CPU 密集型任務使用多進程 (Multiprocessing)
|
||
|
||
```python
|
||
def process_data(data: list[int]) -> int:
|
||
"""CPU 密集型計算。"""
|
||
return sum(x ** 2 for x in data)
|
||
|
||
def process_all(datasets: list[list[int]]) -> list[int]:
|
||
"""使用多個進程處理多個資料集。"""
|
||
with concurrent.futures.ProcessPoolExecutor() as executor:
|
||
results = list(executor.map(process_data, datasets))
|
||
return results
|
||
```
|
||
|
||
## 專案與套件組織
|
||
|
||
### 標準專案佈局
|
||
|
||
```
|
||
myproject/
|
||
├── src/ # 原始碼目錄
|
||
│ └── mypackage/
|
||
│ ├── __init__.py
|
||
│ ├── main.py
|
||
│ ├── api/
|
||
│ │ ├── __init__.py
|
||
│ │ └── routes.py
|
||
│ ├── models/
|
||
│ │ ├── __init__.py
|
||
│ │ └── user.py
|
||
│ └── utils/
|
||
│ ├── __init__.py
|
||
│ └── helpers.py
|
||
├── tests/ # 測試目錄
|
||
│ ├── __init__.py
|
||
│ ├── conftest.py
|
||
│ ├── test_api.py
|
||
│ └── test_models.py
|
||
├── pyproject.toml # 專案配置設定
|
||
├── README.md
|
||
└── .gitignore
|
||
```
|
||
|
||
### 匯入慣例 (Import Conventions)
|
||
|
||
```python
|
||
# 正确：匯入順序 — 標準函式庫、第三方套件、本地模組
|
||
import os
|
||
import sys
|
||
from pathlib import Path
|
||
|
||
import requests
|
||
from fastapi import FastAPI
|
||
|
||
from mypackage.models import User
|
||
from mypackage.utils import format_name
|
||
```
|
||
|
||
## 記憶體與效能
|
||
|
||
### 使用 __slots__ 提升記憶體效率
|
||
|
||
```python
|
||
# 錯誤：一般類別使用 __dict__（耗費更多記憶體）
|
||
class Point:
|
||
def __init__(self, x: float, y: float):
|
||
self.x = x
|
||
self.y = y
|
||
|
||
# 正確：使用 __slots__ 減少記憶體消耗
|
||
class Point:
|
||
__slots__ = ['x', 'y']
|
||
|
||
def __init__(self, x: float, y: float):
|
||
self.x = x
|
||
self.y = y
|
||
```
|
||
|
||
### 避免在迴圈中進行字串拼接
|
||
|
||
```python
|
||
# 錯誤：字串不可變性導致 O(n²) 複雜度
|
||
result = ""
|
||
for item in items:
|
||
result += str(item)
|
||
|
||
# 正確：使用 join 達成 O(n) 複雜度
|
||
result = "".join(str(item) for item in items)
|
||
```
|
||
|
||
## Python 工具整合
|
||
|
||
### 必要指令
|
||
|
||
```bash
|
||
# 程式碼格式化
|
||
black .
|
||
isort .
|
||
|
||
# 靜態分析 (Linter)
|
||
ruff check .
|
||
pylint mypackage/
|
||
|
||
# 型別檢查
|
||
mypy .
|
||
|
||
# 執行測試
|
||
pytest --cov=mypackage --cov-report=html
|
||
|
||
# 安全性掃描
|
||
bandit -r .
|
||
```
|
||
|
||
## 常見語法習慣 (Idioms) 快速參考
|
||
|
||
| 語法習慣 | 說明描述 |
|
||
|-------|-------------|
|
||
| **EAFP** | 請求原諒比請求許可更容易 |
|
||
| **上下文管理器** | 使用 `with` 語句管理資源 |
|
||
| **清單解析式** | 用於簡易的資料轉換 |
|
||
| **產生器** | 用於惰性求值與大型資料集處理 |
|
||
| **型別提示** | 註解函式簽名以提升安全性 |
|
||
| **資料類別** | 提供自動生成方法的資料容器 |
|
||
| **__slots__** | 優化物件記憶體占用 |
|
||
| **f-strings** | 引進自 Python 3.6 的強化字串格式化 |
|
||
| **pathlib.Path** | 引進自 Python 3.4 的物件導向路徑操作 |
|
||
| **enumerate** | 在迴圈中同時獲取索引與元素 |
|
||
|
||
## 應避免的反模式
|
||
|
||
```python
|
||
# 錯誤：可變物件作為預設參數 (Mutable default arguments)
|
||
def append_to(item, items=[]):
|
||
items.append(item)
|
||
return items
|
||
|
||
# 正確：使用 None 並在函式內部建立新清單
|
||
def append_to(item, items=None):
|
||
if items is None:
|
||
items = []
|
||
items.append(item)
|
||
return items
|
||
|
||
# 錯誤：使用 type() 檢查型別
|
||
if type(obj) == list:
|
||
process(obj)
|
||
|
||
# 正確：使用 isinstance
|
||
if isinstance(obj, list):
|
||
process(obj)
|
||
|
||
# 錯誤：使用 == 與 None 進行比較
|
||
if value == None:
|
||
process()
|
||
|
||
# 正確：使用 is 判斷身分
|
||
if value is None:
|
||
process()
|
||
|
||
# 錯誤：使用星號匯入 (import *)
|
||
from os.path import *
|
||
|
||
# 正確：明確匯入所需項目
|
||
from os.path import join, exists
|
||
```
|
||
|
||
**請記住**：Python 程式碼應具備可讀性、明確性，並遵循「最小驚訝原則」。當遇到疑慮時，應優先考慮清晰度而非技術上的取巧。
|