Python 單元測試與除錯：profile / timeit 效能分析

---

簡介

在開發 Python 程式時，功能正確固然重要，但 效能 常常是決定程式是否能在實務環境中順利運作的關鍵。即使演算法正確，若執行速度過慢，也會造成使用者體驗不佳或資源浪費。
profile 與 timeit 兩個內建模組提供了簡潔卻強大的效能分析工具，讓開發者能快速定位瓶頸、比較不同實作，並在單元測試階段即驗證效能是否符合預期。

本篇文章將以 易懂的語言 介紹如何使用 cProfile、profile、timeit 以及配套的 pstats、snakeviz，並透過多個實用範例說明其使用方式、常見陷阱與最佳實踐，最後帶出實務應用情境，幫助你在 Python 開發流程中自然地加入效能測試。

---

核心概念

1. 為什麼要做效能分析

• 避免資源浪費：過慢的程式會佔用過多 CPU、記憶體或 I/O，進而影響整體系統。
• 早期發現瓶頸：在功能測試階段就找出慢速區塊，可減少日後重構的成本。
• 量化改進：透過準確的測量，才能說服自己或團隊「這次優化真的有效」。

2. cProfile 與 profile

模組	特點	何時使用
cProfile	使用 C 語言實作，速度快、開銷低。	大多數日常效能分析，尤其在大型程式或第三方套件上。
profile	完全以 Python 實作，較慢但可自訂追蹤行為。	需要自訂 profiler（例如只追蹤特定函式）時。

2.1 基本使用

import cProfile, pstats, io

def heavy_computation(n: int) -> int:
    """計算 1~n 的平方和，故意使用較慢的寫法作示範。"""
    total = 0
    for i in range(1, n + 1):
        total += i * i          # O(n) 的簡單迴圈
    return total

# 直接在程式內部執行 cProfile
cProfile.run('heavy_computation(10_000)', 'prof_output')

產生的 prof_output 檔案可用 pstats 讀取並排序：

import pstats

stats = pstats.Stats('prof_output')
stats.strip_dirs().sort_stats('cumulative').print_stats(10)

說明：strip_dirs() 會去除檔案路徑，sort_stats('cumulative') 依累積時間排序，print_stats(10) 只顯示前 10 筆最耗時的函式。

3. timeit：微基準測試

timeit 針對 極小片段（通常是單一函式或單行程式）做高精度測量，內部會自動執行多次、排除首次執行的 warm‑up 效應。

3.1 基本範例

import timeit

def fib_recursive(n: int) -> int:
    if n <= 1:
        return n
    return fib_recursive(n-1) + fib_recursive(n-2)

# 測量 fib_recursive(20) 執行 100 次的平均時間
elapsed = timeit.timeit('fib_recursive(20)', globals=globals(), number=100)
print(f'平均執行時間: {elapsed/100:.6f} 秒')

3.2 使用 repeat 取得多組結果

times = timeit.repeat('sum(range(1000))', number=1000, repeat=5)
print('最小、平均、最大執行時間 (秒):',
      f'{min(times):.6f}', f'{sum(times)/len(times):.6f}', f'{max(times):.6f}')

3.3 以 setup 省去重複匯入

code = '''
def work(data):
    return [x*2 for x in data]
'''

setup = 'from __main__ import work, list(range(1000))'
elapsed = timeit.timeit('work(list(range(1000)))', setup=setup, number=500)
print(f'list comprehension 500 次耗時: {elapsed:.4f} 秒')

4. 圖形化分析：snakeviz

cProfile 的文字報表雖然完整，但有時難以快速看出「熱點」分布。安裝 snakeviz（pip install snakeviz）後，只要：

python -m cProfile -o prof.out my_script.py
snakeviz prof.out

即可在瀏覽器中以互動樹狀圖呈現每個函式的呼叫關係與耗時，對於 大型專案 的瓶頸定位相當直觀。

---

常見陷阱與最佳實踐

陷阱	為何會發生	解決方式
測量環境不一致	測試時 CPU 可能被其他程式佔用，導致時間波動。	關閉不必要的背景程式，或在 CI 環境使用固定的資源限制。
使用 time.time()	解析度太低，受系統調度影響大。	使用 timeit 或 perf_counter()，它提供更高精度。
忽略 warm‑up	JIT（如 PyPy）或快取會讓第一次執行較慢。	timeit 內建自動 warm‑up，若自行測量，先跑一次再正式計時。
測試資料過小	微基準測試的相對誤差會被雜訊掩蓋。	讓測試迴圈足夠大（number 參數）或使用 repeat 取多次平均。
把所有程式碼放在同一個檔案	cProfile 會把所有函式都列出，難以聚焦。	將待測功能抽離成模組，或使用 profile 的 runctx 只追蹤特定區段。

最佳實踐

1. 先寫測試，再測量：在單元測試中加入效能斷言（例如 assert elapsed < 0.05），確保改版不會退化。
2. 分層測量：先用 timeit 找出最慢的微觀片段，再以 cProfile 觀察整體呼叫圖。
3. 使用 pstats 的 filter：只顯示自己寫的模組，避免標準庫噪聲。
4. 版本控制結果：把 *.prof 或 *.txt 的報表加入 CI，讓每次 PR 都能自動比較前後差異。

---

實際應用場景

1. 資料清理管線：在 ETL 工作中，常見 pandas.apply 與純 Python 迴圈的效能差異。使用 cProfile 可快速找出哪一步佔用最多 CPU，然後改用向量化操作。
2. 演算法競賽：題目往往要求在秒級內完成大量計算，timeit 能幫助你比較不同實作（遞迴 vs 動態規劃）哪個更快。
3. Web API 回應時間：將每個 endpoint 包裝成小函式，使用 timeit 在本機測試不同序列化方式（json vs orjson）的差異，確保服務符合 SLA。
4. 機器學習前處理：特徵工程常涉及大量文字或影像處理，cProfile 能協助找出 CPU 密集的函式，進而決定是否使用多執行緒或 Cython 加速。

---

總結

• 效能分析 不應是事後才做的事，而是與功能測試同步進行的必備步驟。
• cProfile/profile 提供 全程追蹤，適合找出函式呼叫圖中的熱點；timeit 則是 微基準，適合比較單一程式片段的差異。
• 配合 pstats、snakeviz、repeat 等工具，可將龐雜的報表轉化為直觀的資訊，快速定位問題。
• 了解常見陷阱（測試環境、warm‑up、資料規模）並遵守最佳實踐，才能得到可靠且可重現的測量結果。

把這套 profile / timeit 流程寫進日常的單元測試與 CI 中，你的 Python 專案將在功能正確的同時，保持 高效能、可擴充，更能在實務環境中贏得使用者與團隊的信任。祝你寫程式、測效能兩手抓，開發更順暢！