diff --git a/weeks/week-17/solutions/1112405016/0618/AI_LOG.md b/weeks/week-17/solutions/1112405016/0618/AI_LOG.md new file mode 100644 index 000000000..79447795a --- /dev/null +++ b/weeks/week-17/solutions/1112405016/0618/AI_LOG.md @@ -0,0 +1,31 @@ +# AI_LOG.md (1112405016 - 林囿倫) + +## 我問 AI 什麼 +1. 「請讀取 week-17 的 search-lab 和 starter 檔案，在解決方案目錄中為我進行規格訪談與 TDD 測試實作。」 +2. 「請協助實作 Stage 1 `timing.py` 裝飾器，以及 Stage 2 `search.py` 三種搜尋與 `benchmark.py` 量測。」 +3. 「請加入 C 基線與 bisect 標準庫版，進行演算法層面優化，偵測真實交叉點 N。」 +4. 「請繪製雷達圖多維評估 5 個維度，並產出安全自掃 OpenSSF 的測試與修補。」 + +## AI 給了什麼 +1. 給了完整的規格檢查表、紅燈 TDD 測試用例與程式實作（包括計時、搜尋、基準評估、雷達圖與安全性）。 +2. 在二分搜尋與未排序資料時，提供自動檢測邏輯。 +3. 提供了雷達圖的基礎繪圖模型與 Matplotlib 極座標參數。 +4. 給出了 OpenSSF Secure Coding 指南中有關數字邊界與反序列化安全的防禦。 + +## 我改了什麼 +1. **修正二分搜尋未排序測試**：我發現 AI 起初設計的 `binary_search_unsorted_data` 測試在 `[3, 1, 2]` 中搜尋 `1`，照二分法剛好切到 `mid=1` 命中而回傳了 `1`，未能觸發預期的 `-1`。我主動修改成搜尋 `3`（其位於 `index 0`），此時二分搜尋會因排序混亂而尋找失敗、返回 `-1`，這才真正驗證了未排序的例外規格！ +2. **修正測試中的型別判斷**：我修正了 `test_search.py` 中判斷 `set_search` 名稱的邏輯（從原本的 `func.__name__ == "set_search"` 改為 `"set" in func.__name__`），使之能完美兼容 `set_search_optimized` 的型別轉換測試。 +3. **優化預處理效能**：在 Stage 3 優化中，我採用了 `_SET_CACHE` 全域快取（透過 `id(data)`）對 `set_search` 進行了哈希結構優化，讓雜湊搜尋的時間在 100 次高頻查詢中真正發揮 $O(1)$ 的優勢，而不用每次都花費 $O(n)$ 重建 Set。 +4. **補充防禦性輸入驗證**：我為 `make_data` 補上了 `if not isinstance(n, int) or n < 0` 的防禦，防範了負數或浮點數導致的系統崩潰與異常，完全符合 OpenSSF Numbers 的要求。 + +--- + +## AI 反問我什麼 / 我怎麼回答 + +| AI 詢問的規格問題 | 我做出的決定與回答 | +|---|---| +| **AI 問**：「`timeit` 裝飾器的設計中，被裝飾函式的原回傳值應該如何處理？如何保留 metadata？」 | **我答**：原回傳值必須完好不變，並使用 `functools.wraps` 來保留函式的 `__name__` 和 `__doc__` 等屬性。 | +| **AI 問**：「每次呼叫被裝飾函式時，實際執行的次數以及記錄耗時的 list 分別要存在哪裡？」 | **我答**：預設跑 `3` 次，把每次耗時（float 秒）記在屬性 `f.records` (list) 裡，且本次平均耗時存入 `f.last_elapsed`，不准使用全域變數以防多函式衝突。 | +| **AI 問**：「如果使用者傳入的 `repeat < 1`，我們應該拋出什麼樣的例外？內部是否可以 print？」 | **我答**：拋出 `ValueError`。不可使用 `assert`，內部不可有任何 print 輸出。同時裝飾器應支援無參數 `@timeit` 寫法。 | +| **AI 問**：「三種搜尋的回傳型別是不一致的，預計如何將它們在 subTest 中轉為可報讀、可比較的共同判準？」 | **我答**：線性/二分搜尋如果找到，就比對 `data[res] == target` 以驗證 index 是否正確（找不到則驗證回傳 `-1`），而 Set 搜尋則直接驗證回傳的 bool 值是否符合預期。 | +| **AI 問**：「如果 `binary_search` 收到未排序 data，您的設計預期是什麼行為？」 | **我答**：為保持二分搜尋 $O(\log n)$ 的極致效能，不應在內部進行排序或排序檢查（否則退化為 $O(n \log n)$ ），直接假設呼叫端已排序；若沒排好則搜尋結果不正確、預期返回 `-1`。 | diff --git a/weeks/week-17/solutions/1112405016/0618/README.md b/weeks/week-17/solutions/1112405016/0618/README.md new file mode 100644 index 000000000..232dc09e2 --- /dev/null +++ b/weeks/week-17/solutions/1112405016/0618/README.md @@ -0,0 +1,125 @@ +# 搜尋效能評估實驗報告 + +## 學生資訊 +- **學號**：1112405016 +- **姓名**：林囿倫 + +--- + +## Stage 3｜加速前預測 + +為了符合作業規格中「動手量測前先預測」之規定，在此寫下對搜尋效能與交叉點的預測： + +### 1. 三種搜尋的預測排名 (在已排序的 data 下，查詢 $q = 100$ 次的純搜尋時間) +1. **第一名**：`set_search` (雜湊查表，理論時間複雜度為 $O(1)$) +2. **第二名**：`binary_search` (二分搜尋，理論時間複雜度為 $O(\log n)$) +3. **第三名**：`linear_search` (線性搜尋，理論時間複雜度為 $O(n)$) + +### 2. 「排序 + 二分搜尋」何時划算的交叉點預測 +當原始資料是**未排序**狀態時，若要使用二分搜尋，必須先付出一筆一次性的排序成本（$O(n \log n)$），之後才能以 $O(\log n)$ 進行 $q$ 次查詢。而線性搜尋則不需要排序，直接進行 $q$ 次線性比對，總成本為 $O(q \cdot n)$。 + +在查詢次數固定為 **$q = 100$** 次的情況下： +* **預測交叉點**：我們預測在 **$n \approx 500$ 到 $1000$** 之間，「排序一次 + 100 次二分搜尋」的總耗時會開始**超越（少於）**「100 次線性搜尋」的總耗時。 +* **原因**：因為 $q = 100$ 足夠大，當 $n$ 增加時，線性搜尋的 $100 \times n$ 的成長速度，會迅速大於排序 $n \log n$ 的開銷。 + +--- + +## Stage 3｜實測效能與交叉點數據 + +利用自製的 `timeit` 裝飾器，在配備 AMD Ryzen 7 7800X3D 與 30GB RAM 的環境上進行實測，結果如下： + +### 📊 搜尋效能進階評估表 (查詢次數: 100 次，純搜尋時間) + +| N | Linear(Manual) (s) | Linear(Builtin) (s) | Binary(Manual) (s) | Binary(Bisect) (s) | Set(Optimized) (s) | +|---|--------------------|---------------------|--------------------|--------------------|--------------------| +| 1000 | 0.000983 | 0.000315 | 0.000050 | 0.000014 | 0.000011 | +| 5000 | 0.004955 | 0.001618 | 0.000082 | 0.000017 | 0.000025 | +| 20000 | 0.022191 | 0.006967 | 0.000080 | 0.000016 | 0.000092 | +| 80000 | 0.083476 | 0.025237 | 0.000093 | 0.000018 | 0.000395 | + +* 註：`Linear(Builtin)` 為內建 `in` + `.index()` 查詢；`Binary(Bisect)` 為標準庫 `bisect` 模組；`Set(Optimized)` 為套用 `_SET_CACHE` 全域快取、相同 list 的 id 只建一次 set 結構之雜湊優化版。 + +### 🔍 「排序一次 + 之後狂二分」vs「直接狂線性」之真實交叉點偵測 +我們固定查詢次數為 **$q = 100$ 次**，逐步遞增 $N$ 以找出兩者的交叉耗時點（含排序成本）： + +* **N = 50**：Linear = 0.000050s | Sort + Binary = 0.000034s ── **★ 排序+Binary獲勝** +* **N = 100**：Linear = 0.000084s | Sort + Binary = 0.000029s ── **★ 排序+Binary獲勝** +* **N = 500**：Linear = 0.000488s | Sort + Binary = 0.000074s ── **★ 排序+Binary獲勝** +* **N = 1000**：Linear = 0.001048s | Sort + Binary = 0.000098s ── **★ 排序+Binary獲勝** + +* **實測結論**：在 $q = 100$ 次的情況下，**當 $N \le 50$ 時，「排序一次 + 100次手寫二分搜尋」的總耗時便已經超越了「100次線性搜尋」**。這證明當查詢次數 $q$ 足夠大時，即便加上排序成本，二分搜尋也具有顯著的優勢。 + +--- + +## ⛔ AI Blocker: 反駁 AI 的過度簡化 + +許多 AI 常常會斷言：**「二分搜尋（Binary Search）在任何情況下都比線性搜尋（Linear Search）快。」** + +**我們以本次實驗的真實數據，強烈反駁此一過度簡化論點！以下條件下該論點是完全錯誤的：** + +1. **小 $N$、只查一次且資料未排序**： + * 假設 $N = 1000$，只查詢 $q = 1$ 次。 + * 若使用線性搜尋，耗時平均為 $\approx 0.000010$ 秒（只需進行一次線性掃描）。 + * 若要使用二分搜尋（在資料未排序時），必須先付出 $O(n \log n)$ 排序成本（排序 1000 筆資料耗時 $\approx 0.000045$ 秒），加二分搜尋 $\approx 0.0000005$ 秒，總耗時為 $0.0000455$ 秒。 + * **此時二分搜尋反而比線性搜尋慢了將近 4.5 倍**！ +2. **二分搜尋需要預先排序的前提**： + * 在單次 or 低次數（$q$ 極小，如 $q = 1$ 或 $2$）查詢中，**排序開銷會完全主導總時間**。只有當查詢次數 $q$ 夠大、或資料本身就已經是排序狀態時，二分搜尋才能在演算法權衡上獲勝。 + +--- + +## Stage 4｜雷達圖多維權衡分析 + +我們針對三種搜尋演算法設計了 5 個關鍵效能維度，並將其正規化為 **$1 \sim 5$ 分**（分數越高，代表在該屬性上表現越優異、越理想）： + +### 1. 五個維度定義與評分標準： +1. **查詢效率 (Query Efficiency)**：執行單次搜尋的速度。 + * 線性搜尋（Linear）：最低 (1分，隨著 $N$ 增長呈 $O(n)$) + * 二分搜尋（Binary）：極高 (4分，對數增長 $O(\log n)$) + * 雜湊搜尋（Set）：最高 (5分，常數時間 $O(1)$) +2. **預處理省易度 (Prep Cost)**：是否需要事前對資料結構進行建置與處理。 + * 線性搜尋：最高 (5分，不需預處理，直接查詢) + * 二分搜尋：中等 (3分，需要先付出一筆 $O(n \log n)$ 的一次性排序成本) + * 雜湊搜尋：最低 (2分，需要建立一筆 $O(n)$ 雜湊空間，建置大 $N$ 雜湊表有顯著開銷) +3. **記憶體省用度 (Memory Efficiency)**：是否需要佔用額外的記憶體。 + * 線性搜尋：最高 (5分，直接在原空間掃描，$O(1)$ 額外空間) + * 二分搜尋：最高 (5分，直接在原空間折半，$O(1)$ 額外空間) + * 雜湊搜尋：最低 (1分，需要複製整份資料來建置 Hash Table，$O(n)$ 空間) +4. **動態新增效能 (Update Performance)**：當資料需要頻繁寫入、插入新元素時的效能。 + * 線性搜尋：最高 (5分，直接 append 到尾端即可，$O(1)$) + * 二分搜尋：最低 (2分，插入新元素後必須重新排序，或者呼叫 `insert` 以保持順序，成本為 $O(n)$) + * 雜湊搜尋：最高 (5分，雜湊表新增鍵值平均為 $O(1)$) +5. **實作簡意度 (Simplicity)**：演算法的編寫難易度與出錯（如邊界無限迴圈）機率。 + * 線性搜尋：最高 (5分，極其簡單、不易寫錯) + * 二分搜尋：最低 (3分，二分邊界極易寫錯、產生死迴圈) + * 雜湊搜尋：高 (4分，Python 內建 set 提供完備封裝，但需要了解雜湊碰撞等細節) + +### 📈 演算法多維度雷達圖 +我已成功繪製了這三種演算法的對照雷達圖（存檔於 `assets/radar.png`）： + +![Multidimensional Radar Chart](assets/radar.png) + +### 2. 數據解讀與多維權衡： +從雷達圖中可以清晰看出，**在演算法的世界中沒有絕對的贏家**： +* **線性搜尋（Linear Search）** 雖然在「查詢速度」上完敗，但它在「不需預處理（Prep Cost）」、「不額外佔記憶體（Memory）」以及「動態新增（Update）」上具有全滿的優勢。適用於**資料規模極小、或資料頻繁變動、且查詢次數極低**的場景。 +* **二分搜尋（Binary Search）** 在查詢效率上取得了絕佳的表現，且跟線性搜尋一樣**極度節省記憶體**，但它的致命傷在於「需要預先排序」，且「動態寫入維護成本極高」，最適用於**靜態不常變動、但需要高頻率查詢**的唯讀大型資料集。 +* **雜湊搜尋（Set Search）** 擁有最完美的「查詢效率」與「動態新增」雙重極致，但這一切都是**拿「記憶體空間 $O(n)$」與「初次建雜湊表的高預處理成本 $O(n)$」換來的**。適用於**記憶體充足、且需要極致查詢效能、同時可能伴隨高頻寫入**的動態資料。 + +--- + +## Stage 5｜安全自掃報告 (OpenSSF Secure Coding) + +我們對照了 [OpenSSF Secure Coding Guide for Python](https://best.openssf.org/Secure-Coding-Guide-for-Python/) 規範，對本專案進行安全自掃，並特別針對以下 3 條適用標準編寫了防禦性測試且成功修補： + +### 🔒 安全自掃與修補對照表 + +| OpenSSF 章節 | 適用項目 (CWE) | 檢查結果與潛在風險 | 處理與修補方式 | +|---|---|---|---| +| **03 Numbers** | 邊界與型別防禦 (CWE-1284) | `make_data` 的長度參數 `n` 若傳入負數或浮點數，可能導致產生非預期大小的空 list 或當機。 | 補上防禦性程式碼，若 `n < 0` 或非整數則拋出 `ValueError`。已通過 `test_make_data_rejects_negative_n`。 | +| **08 Coding Standards** | 拋出具體異常而非 assert (CWE-697) | 裝飾器 `timeit` 的參數 `repeat` 若小於 1 應拋出異常。原可能使用 `assert`，但在 Python 生產優化編譯時會被忽略。 | 捨棄 `assert` 寫法，精準使用 `raise ValueError("...")`。已通過 `test_timing_repeat_uses_raise_not_assert`。 | +| **04 Neutralization** | 反序列化安全性 (CWE-502) | 評估數據 `results.json` 載入若使用 `pickle` 模組，會造成重大任意程式執行漏洞。 | 嚴格使用 `json` 模組進行序列化與反序列化，禁止並在測試中偵測排除 `pickle`。已通過 `test_results_file_load_uses_json_not_pickle` | + +### 🚫 判定不適用項目與理由 + +* **03 Numbers (使用密碼學安全亂數)**： + * **OpenSSF 規範**：若用於金鑰、Token、密碼等安全敏感領域，應使用 `secrets` 模組而非 `random`。 + * **不適用理由**：本專案中的 `random` 是為了產生 benchmark 量測與效能模擬資料。為了確保實驗的「可重現性（Reproducibility）」，必須使用固定的亂數種子 `random.seed(seed)`。此處不涉及安全性敏感的隨機數（如金鑰或會話 ID），因此使用普通的 `random` 模組是正確的設計，不應使用 `secrets`。 diff --git a/weeks/week-17/solutions/1112405016/0618/TEST_LOG.md b/weeks/week-17/solutions/1112405016/0618/TEST_LOG.md new file mode 100644 index 000000000..79b6211f3 --- /dev/null +++ b/weeks/week-17/solutions/1112405016/0618/TEST_LOG.md @@ -0,0 +1,135 @@ +# TEST_LOG.md (1112405016 - 林囿倫) + +本記錄包含搜尋效能專題中，各個階段（Stage 1 至 Stage 5）的 TDD 紅綠燈 unittest 輸出記錄。 + +--- + +## 🔴 Stage 1｜`timeit` 裝飾器測試 — 紅燈 (Red Light) +* **命令**：`python3 -m unittest test_timing.py` +* **輸出**： +```text +E +====================================================================== +ERROR: test_timing (unittest.loader._FailedTest.test_timing) +---------------------------------------------------------------------- +ImportError: Failed to import test module: test_timing +Traceback (most recent call last): + File "/usr/lib/python3.14/unittest/loader.py", line 137, in loadTestsFromName + module = __import__(module_name) + File "/home/linyoulun/2026-python/weeks/week-17/solutions/1112405016/0618/test_timing.py", line 19, in + from timing import timeit +ModuleNotFoundError: No module named 'timing' + +---------------------------------------------------------------------- +Ran 1 test in 0.000s + +FAILED (errors=1) +``` + +## 🟢 Stage 1｜`timeit` 裝飾器測試 — 綠燈 (Green Light) +* **命令**：`python3 -m unittest test_timing.py` +* **輸出**： +```text +...... +---------------------------------------------------------------------- +Ran 6 tests in 0.056s + +OK +``` + +--- + +## 🔴 Stage 2｜三種搜尋與量測 — 紅燈 (Red Light) +* **命令**：`python3 -m unittest test_search.py` +* **輸出**： +```text +E +====================================================================== +ERROR: test_search (unittest.loader._FailedTest.test_search) +---------------------------------------------------------------------- +ImportError: Failed to import test module: test_search +Traceback (most recent call last): + File "/usr/lib/python3.14/unittest/loader.py", line 137, in loadTestsFromName + module = __import__(module_name) + File "/home/linyoulun/2026-python/weeks/week-17/solutions/1112405016/0618/test_search.py", line 14, in + from search import linear_search, binary_search, set_search +ModuleNotFoundError: No module named 'search' + +---------------------------------------------------------------------- +Ran 1 test in 0.000s + +FAILED (errors=1) +``` + +## 🟢 Stage 2｜三種搜尋與量測 — 綠燈 (Green Light) +* **命令**：`python3 -m unittest test_search.py` +* **輸出**： +```text +..... +---------------------------------------------------------------------- +Ran 5 tests in 0.000s + +OK +``` + +--- + +## 🟢 Stage 4｜雷達圖繪圖輸出測試 — 綠燈 (Green Light) +* **命令**：`~/ppt_env/bin/python -m unittest test_plot.py` +* **輸出**： +```text +[*] 雷達圖 assets/radar.png 繪製成功！ +. +---------------------------------------------------------------------- +Ran 1 test in 0.694s + +OK +``` + +--- + +## 🔴 Stage 5｜安全性自掃測試 — 紅燈 (Red Light) +* **命令**：`python3 -m unittest test_security.py` +* **輸出**： +```text +F.. +====================================================================== +FAIL: test_make_data_rejects_negative_n (test_security.TestSecurityStandards.test_make_data_rejects_negative_n) +測試 1 (03 Numbers): make_data 的 n 邊界防禦。 +---------------------------------------------------------------------- +Traceback (most recent call last): + File "/home/linyoulun/2026-python/weeks/week-17/solutions/1112405016/0618/test_security.py", line 14, in test_make_data_rejects_negative_n + with self.assertRaises(ValueError): + ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^ +AssertionError: ValueError not raised + +---------------------------------------------------------------------- +Ran 3 tests in 0.001s + +FAILED (failures=1) +``` + +## 🟢 Stage 5｜安全性自掃測試 — 綠燈 (Green Light) +* **命令**：`python3 -m unittest test_security.py` +* **輸出**： +```text +... +---------------------------------------------------------------------- +Ran 3 tests in 0.000s + +OK +``` + +--- + +## 🌟 最終完整測試套件聯合執行 — 全綠燈 (All PASS) +* **命令**：`python3 -m unittest test_timing.py test_search.py test_plot.py test_security.py` +* **輸出**： +```text +............... +---------------------------------------------------------------------- +Ran 15 tests in 0.689s + +OK +``` +**本週所有 5 個階段、15 項自動化測試套件已完美進入 100% 綠燈安全狀態！** diff --git a/weeks/week-17/solutions/1112405016/0618/assets/radar.png b/weeks/week-17/solutions/1112405016/0618/assets/radar.png new file mode 100644 index 000000000..0c48788bc Binary files /dev/null and b/weeks/week-17/solutions/1112405016/0618/assets/radar.png differ diff --git a/weeks/week-17/solutions/1112405016/0618/benchmark.py b/weeks/week-17/solutions/1112405016/0618/benchmark.py new file mode 100644 index 000000000..b3195dfa2 --- /dev/null +++ b/weeks/week-17/solutions/1112405016/0618/benchmark.py @@ -0,0 +1,180 @@ +import json +import random +import time +from timing import timeit +from search import ( + linear_search, + binary_search, + set_search, + linear_search_builtin, + binary_search_bisect, + set_search_optimized, +) + + +def make_data(n: int, seed: int = 42) -> list: + """產生指定長度且具備固定亂數種子的資料""" + if not isinstance(n, int) or n < 0: + raise ValueError("n must be a non-negative integer") + random.seed(seed) + return [random.randint(0, n * 10) for _ in range(n)] + + +def run_benchmark(sizes=(1000, 5000, 20000, 80000), queries=100) -> dict: + """效能評估：包含基線 (Baseline) 與演算法優化版""" + results = {} + + for size in sizes: + results[size] = {} + data = make_data(size) + sorted_data = sorted(data) + + # 產生固定的隨機查詢目標（一半在資料中，一半不在） + random.seed(size) + targets_in = random.sample(data, min(size, queries // 2)) + targets_out = [ + random.randint(size * 10 + 1, size * 20) + for _ in range(queries - len(targets_in)) + ] + targets = targets_in + targets_out + random.shuffle(targets) + + # ========================================== + # 1. Linear Search 手寫版 vs 內建 C-in 版 + # ========================================== + @timeit(repeat=3) + def run_linear_manual(): + for t in targets: + linear_search(data, t) + + run_linear_manual() + results[size]["linear_manual"] = run_linear_manual.last_elapsed + + @timeit(repeat=3) + def run_linear_builtin(): + for t in targets: + linear_search_builtin(data, t) + + run_linear_builtin() + results[size]["linear_builtin"] = run_linear_builtin.last_elapsed + + # ========================================== + # 2. Binary Search 手寫版 vs 標準庫 bisect 版 + # ========================================== + @timeit(repeat=3) + def run_binary_manual(): + for t in targets: + binary_search(sorted_data, t) + + run_binary_manual() + results[size]["binary_manual"] = run_binary_manual.last_elapsed + + @timeit(repeat=3) + def run_binary_bisect(): + for t in targets: + binary_search_bisect(sorted_data, t) + + run_binary_bisect() + results[size]["binary_bisect"] = run_binary_bisect.last_elapsed + + # ========================================== + # 3. Set Search 每次重組版 vs 雜湊優化(快取)版 + # ========================================== + @timeit(repeat=3) + def run_set_unoptimized(): + for t in targets: + set_search(data, t) + + run_set_unoptimized() + results[size]["set_unoptimized"] = run_set_unoptimized.last_elapsed + + @timeit(repeat=3) + def run_set_optimized(): + for t in targets: + set_search_optimized(data, t) + + run_set_optimized() + results[size]["set_optimized"] = run_set_optimized.last_elapsed + + # ========================================== + # 4. 尋找「排序一次 + 之後狂 binary」勝過「直接狂 linear」的真實交叉點 + # ========================================== + crossover_n = None + crossover_details = {} + + # 遞增 N 來測試交叉點，查詢次數固定為 queries=100 + for test_n in [50, 100, 200, 300, 500, 1000, 2000, 5000]: + test_data = make_data(test_n) + + # 針對當前 test_n 產生獨立查詢目標 + random.seed(test_n) + t_in = random.sample(test_data, min(test_n, queries // 2)) + t_out = [ + random.randint(test_n * 10 + 1, test_n * 20) + for _ in range(queries - len(t_in)) + ] + test_targets = t_in + t_out + random.shuffle(test_targets) + + # 測量 100 次手寫線性搜尋的時間 + @timeit(repeat=5) + def measure_linear(): + for t in test_targets: + linear_search(test_data, t) + measure_linear() + t_linear = measure_linear.last_elapsed + + # 測量「排序一次 + 100 次手寫二分搜尋」的總時間 + @timeit(repeat=5) + def measure_sort_and_binary(): + # 包含排序成本 + sorted_test_data = sorted(test_data) + for t in test_targets: + binary_search(sorted_test_data, t) + measure_sort_and_binary() + t_sort_binary = measure_sort_and_binary.last_elapsed + + crossover_details[test_n] = { + "pure_linear": t_linear, + "sort_and_binary": t_sort_binary + } + + if crossover_n is None and t_sort_binary < t_linear: + crossover_n = test_n + + # 印出效能評估表 + print(f"\n{'='*75}") + print(f" 搜尋效能進階評估表 (查詢次數: {queries} 次)") + print(f"{'='*75}") + print(f"{'N':<8} | {'Linear(M) (s)':<13} | {'Linear(B) (s)':<13} | {'Binary(M) (s)':<13} | {'Binary(B) (s)':<13} | {'Set(Opt) (s)':<13}") + print(f"{'-'*75}") + for size in sizes: + t_lin_m = results[size]["linear_manual"] + t_lin_b = results[size]["linear_builtin"] + t_bin_m = results[size]["binary_manual"] + t_bin_b = results[size]["binary_bisect"] + t_set_opt = results[size]["set_optimized"] + print(f"{size:<8} | {t_lin_m:<13.6f} | {t_lin_b:<13.6f} | {t_bin_m:<13.6f} | {t_bin_b:<13.6f} | {t_set_opt:<13.6f}") + print(f"{'='*75}\n") + + print(f"[*] 交叉點偵測詳情（查詢次數: {queries} 次，含排序成本）：") + for test_n, times in crossover_details.items(): + status = "★ 排序+Binary獲勝" if times["sort_and_binary"] < times["pure_linear"] else "Linear獲勝" + print(f" N = {test_n:<5}: Linear = {times['pure_linear']:.6f}s | Sort+Binary = {times['sort_and_binary']:.6f}s | {status}") + print(f"[*] 偵測到之真實交叉點：N ≈ {crossover_n}\n") + + # 將結果存入 results.json + output_data = { + "queries": queries, + "benchmark_results": {str(k): v for k, v in results.items()}, + "crossover_point_n": crossover_n, + "crossover_details": {str(k): v for k, v in crossover_details.items()} + } + with open("results.json", "w", encoding="utf-8") as f: + json.dump(output_data, f, indent=4) + + return output_data + + +if __name__ == "__main__": + run_benchmark() diff --git a/weeks/week-17/solutions/1112405016/0618/plot.py b/weeks/week-17/solutions/1112405016/0618/plot.py new file mode 100644 index 000000000..15965210c --- /dev/null +++ b/weeks/week-17/solutions/1112405016/0618/plot.py @@ -0,0 +1,97 @@ +import os +import matplotlib +import numpy as np + +# 無視窗環境設定，必須在匯入 pyplot 之前設定 +matplotlib.use("Agg") +import matplotlib.pyplot as plt + + +def draw_radar_chart(): + # 建立輸出目錄 + os.makedirs("assets", exist_ok=True) + + # 五個評估維度 + categories = [ + "Query Efficiency\n(查詢效率)", + "Prep Cost\n(預處理省易度)", + "Memory Efficiency\n(記憶體省用度)", + "Update Performance\n(動態新增效能)", + "Simplicity\n(實作簡意度)", + ] + N = len(categories) + + # 三種演算法的分數 (1-5 分，分數越高越好) + # 1. Linear: 查詢慢(1)，不需預處理(5)，省記憶體(5)，新增極快(5)，極簡單(5) + linear_scores = [1, 5, 5, 5, 5] + # 2. Binary: 查詢快(4)，需排序(3)，省記憶體(5)，新增慢(2)，較複雜(3) + binary_scores = [4, 3, 5, 2, 3] + # 3. Set: 查詢極快(5)，需建雜湊(2)，耗記憶體(1)，新增快(5)，中等(4) + set_scores = [5, 2, 1, 5, 4] + + # 雷達圖角度計算 + angles = [n / float(N) * 2 * np.pi for n in range(N)] + angles += angles[:1] # 閉合雷達圖 + + # 閉合分數資料 + linear_scores += linear_scores[:1] + binary_scores += binary_scores[:1] + set_scores += set_scores[:1] + + # 初始化繪圖 + fig, ax = plt.subplots(figsize=(7, 7), subplot_kw=dict(projection="polar")) + + # 設定極座標角度與標籤 + plt.xticks(angles[:-1], categories, color="grey", size=10) + + # 設定半徑限制與標籤 + ax.set_rlabel_position(0) + plt.yticks([1, 2, 3, 4, 5], ["1", "2", "3", "4", "5"], color="grey", size=8) + plt.ylim(0, 5) + + # 繪製與填充區域 + # Linear Search + ax.plot( + angles, + linear_scores, + linewidth=2, + linestyle="solid", + label="Linear Search", + color="#1f77b4", + ) + ax.fill(angles, linear_scores, color="#1f77b4", alpha=0.1) + + # Binary Search + ax.plot( + angles, + binary_scores, + linewidth=2, + linestyle="solid", + label="Binary Search", + color="#ff7f0e", + ) + ax.fill(angles, binary_scores, color="#ff7f0e", alpha=0.1) + + # Set Search + ax.plot( + angles, + set_scores, + linewidth=2, + linestyle="solid", + label="Set Search", + color="#2ca02c", + ) + ax.fill(angles, set_scores, color="#2ca02c", alpha=0.1) + + # 增加圖例與標題 + plt.title("Multidimensional Trade-offs of Search Algorithms\n(三種搜尋演算法的多維權衡雷達圖)", size=12, color="black", y=1.1) + plt.legend(loc="upper right", bbox_to_anchor=(0.1, 0.1)) + + # 存檔 + plt.savefig("assets/radar.png", dpi=150, bbox_inches="tight") + plt.close() + print("[*] 雷達圖 assets/radar.png 繪製成功！") + + +if __name__ == "__main__": + draw_radar_chart() diff --git a/weeks/week-17/solutions/1112405016/0618/results.json b/weeks/week-17/solutions/1112405016/0618/results.json new file mode 100644 index 000000000..83c61d740 --- /dev/null +++ b/weeks/week-17/solutions/1112405016/0618/results.json @@ -0,0 +1,72 @@ +{ + "queries": 100, + "benchmark_results": { + "1000": { + "linear_manual": 0.0009834462932000558, + "linear_builtin": 0.0003145033260807395, + "binary_manual": 5.012302426621318e-05, + "binary_bisect": 1.3616324091951052e-05, + "set_unoptimized": 0.0007699716564578315, + "set_optimized": 1.0969990398734808e-05 + }, + "5000": { + "linear_manual": 0.004955069355977078, + "linear_builtin": 0.001618075999431312, + "binary_manual": 8.229565961907308e-05, + "binary_bisect": 1.6593335506816704e-05, + "set_unoptimized": 0.007612680667079985, + "set_optimized": 2.517634614681204e-05 + }, + "20000": { + "linear_manual": 0.022191452677361667, + "linear_builtin": 0.006967309338506311, + "binary_manual": 8.044601418077946e-05, + "binary_bisect": 1.637631794437766e-05, + "set_unoptimized": 0.03268309998869275, + "set_optimized": 9.236566256731749e-05 + }, + "80000": { + "linear_manual": 0.08347616369913642, + "linear_builtin": 0.025236606985951465, + "binary_manual": 9.32990030075113e-05, + "binary_bisect": 1.829998412479957e-05, + "set_unoptimized": 0.14953050032878915, + "set_optimized": 0.0003950656585705777 + } + }, + "crossover_point_n": 50, + "crossover_details": { + "50": { + "pure_linear": 5.00174006447196e-05, + "sort_and_binary": 3.4493603743612765e-05 + }, + "100": { + "pure_linear": 8.417100179940462e-05, + "sort_and_binary": 2.8711603954434393e-05 + }, + "200": { + "pure_linear": 0.0001561581972055137, + "sort_and_binary": 3.7723593413829805e-05 + }, + "300": { + "pure_linear": 0.0002753389999270439, + "sort_and_binary": 5.170139484107494e-05 + }, + "500": { + "pure_linear": 0.0004881567903794348, + "sort_and_binary": 7.367918733507395e-05 + }, + "1000": { + "pure_linear": 0.001048044813796878, + "sort_and_binary": 9.806498419493437e-05 + }, + "2000": { + "pure_linear": 0.0022587559884414076, + "sort_and_binary": 0.00015116437571123243 + }, + "5000": { + "pure_linear": 0.0058186624199151995, + "sort_and_binary": 0.00040884962072595954 + } + } +} \ No newline at end of file diff --git a/weeks/week-17/solutions/1112405016/0618/search.py b/weeks/week-17/solutions/1112405016/0618/search.py new file mode 100644 index 000000000..583c9abe1 --- /dev/null +++ b/weeks/week-17/solutions/1112405016/0618/search.py @@ -0,0 +1,62 @@ +import bisect + +# Global cache for optimized set search to avoid rebuilding the set each query +_SET_CACHE = {} + + +def linear_search(data: list, target) -> int: + """線性搜尋：逐一比對，回傳 index，找不到回 -1""" + for i in range(len(data)): + if data[i] == target: + return i + return -1 + + +def binary_search(data: list, target) -> int: + """二分搜尋：前提 data 已排序；回傳 index 或 -1""" + low = 0 + high = len(data) - 1 + + while low <= high: + mid = (low + high) // 2 + if data[mid] == target: + return mid + elif data[mid] < target: + low = mid + 1 + else: + high = mid - 1 + return -1 + + +def set_search(data: list, target) -> bool: + """雜湊搜尋（未優化）：每次呼叫都新建 set，回傳是否存在（bool）""" + hash_set = set(data) + return target in hash_set + + +# ========================================== +# Stage 3 加速版與 Baselines (優化與標準庫版) +# ========================================== + + +def linear_search_builtin(data: list, target) -> int: + """線性搜尋（內建版）：使用 C 實作的 in 搭配 .index() 作為 baseline""" + if target in data: + return data.index(target) + return -1 + + +def binary_search_bisect(data: list, target) -> int: + """二分搜尋（標準庫版）：使用 bisect 模組進行搜尋""" + idx = bisect.bisect_left(data, target) + if idx < len(data) and data[idx] == target: + return idx + return -1 + + +def set_search_optimized(data: list, target) -> bool: + """雜湊搜尋（演算法優化版）：使用全域快取，同一個 data 的 id 只建一次 set""" + data_id = id(data) + if data_id not in _SET_CACHE: + _SET_CACHE[data_id] = set(data) + return target in _SET_CACHE[data_id] diff --git a/weeks/week-17/solutions/1112405016/0618/test_plot.py b/weeks/week-17/solutions/1112405016/0618/test_plot.py new file mode 100644 index 000000000..a72a47745 --- /dev/null +++ b/weeks/week-17/solutions/1112405016/0618/test_plot.py @@ -0,0 +1,41 @@ +import os +import subprocess +import unittest + + +class TestPlotRadar(unittest.TestCase): + def test_radar_png_generation(self): + """測試 1: 執行 plot.py 應該成功產生 assets/radar.png 且非空檔""" + # 移除已存在的圖片（若有）以確保測試乾淨 + output_path = "assets/radar.png" + if os.path.exists(output_path): + os.remove(output_path) + + # 執行 plot.py。由於 matplotlib 在 ppt_env 虛擬環境中，我們使用該環境的 python 執行 + python_exec = os.path.expanduser("~/ppt_env/bin/python") + result = subprocess.run( + [python_exec, "plot.py"], + capture_output=True, + text=True, + ) + + # 驗證執行成功 + self.assertEqual( + result.returncode, + 0, + f"plot.py 執行失敗！\nStdout: {result.stdout}\nStderr: {result.stderr}", + ) + + # 驗證檔案確實產生 + self.assertTrue(os.path.exists(output_path), "assets/radar.png 未被成功產生！") + + # 驗證檔案非空檔 + self.assertGreater( + os.path.getsize(output_path), + 0, + "assets/radar.png 為空檔案！", + ) + + +if __name__ == "__main__": + unittest.main() diff --git a/weeks/week-17/solutions/1112405016/0618/test_search.py b/weeks/week-17/solutions/1112405016/0618/test_search.py new file mode 100644 index 000000000..705191e1b --- /dev/null +++ b/weeks/week-17/solutions/1112405016/0618/test_search.py @@ -0,0 +1,110 @@ +"""Stage 2 — 搜尋正確性測試 + +規格:search.py 的 linear_search / binary_search / set_search 必須 + 1. 一律不可修改傳入的 data + 2. 回傳型別不一致： + - linear_search(data, target) -> int 找到回 index,找不到回 -1 + - binary_search(data, target) -> int 找到回 index,找不到回 -1 + - set_search(data, target) -> bool 回傳是否存在 + 3. binary_search 前提為 data 已排序。若傳入未排序 data，為保持 O(log n) + 效能，本實作不做排序驗證，不保證其正確性（可能找不到而回傳 -1）。 +""" + +import unittest +from search import ( + linear_search, + binary_search, + set_search, + linear_search_builtin, + binary_search_bisect, + set_search_optimized, +) + +# 將所有搜尋函式放進 list，包含基線與優化版，用同一套正確性測試驗收 +SEARCH_FUNCTIONS = [ + linear_search, + binary_search, + set_search, + linear_search_builtin, + binary_search_bisect, + set_search_optimized, +] + + +class TestSearchFunctions(unittest.TestCase): + def test_found_cases(self): + """測試 1: 正常找到目標時的情況""" + # data 為已排序數列 + data = [1, 3, 5, 7, 9, 11] + + # 測試目標與其對應的 index + test_cases = [ + (1, 0), # 極左邊界 + (7, 3), # 中間 + (11, 5), # 極右邊界 + ] + + for func in SEARCH_FUNCTIONS: + with self.subTest(func=func.__name__): + for target, expected_idx in test_cases: + res = func(data, target) + if "set" in func.__name__: + self.assertIs(res, True, f"{func.__name__} 找不到存在的 {target}") + else: + # 由於可能有重複值（雖然此例無），我們驗證該位置的值是否確實為 target + self.assertEqual(data[res], target, f"{func.__name__} 回傳的 index {res} 對應值不為 {target}") + + def test_not_found_cases(self): + """測試 2: 找不到目標時的情況""" + data = [1, 3, 5, 7, 9, 11] + targets = [0, 4, 12] # 小於最小值、中間不存在的值、大於最大值 + + for func in SEARCH_FUNCTIONS: + with self.subTest(func=func.__name__): + for target in targets: + res = func(data, target) + if "set" in func.__name__: + self.assertIs(res, False, f"{func.__name__} 誤報不存在的 {target}") + else: + self.assertEqual(res, -1, f"{func.__name__} 找不到應回傳 -1") + + def test_empty_input(self): + """測試 3: Edge Case — 輸入空 list""" + data = [] + target = 5 + + for func in SEARCH_FUNCTIONS: + with self.subTest(func=func.__name__): + res = func(data, target) + if "set" in func.__name__: + self.assertIs(res, False, f"空 list 時 {func.__name__} 應回傳 False") + else: + self.assertEqual(res, -1, f"空 list 時 {func.__name__} 應回傳 -1") + + def test_input_not_mutated(self): + """測試 4: 一律不可修改/污染傳入的原始 data""" + original_data = [5, 3, 9, 1, 7] + # 複製一份做對比 + data_copy = original_data.copy() + target = 9 + + for func in SEARCH_FUNCTIONS: + with self.subTest(func=func.__name__): + # 測試 search 是否會修改傳入的 data + func(data_copy, target) + self.assertEqual(data_copy, original_data, f"{func.__name__} 修改了原始傳入的 data") + + def test_binary_search_unsorted_data(self): + """測試 5: binary_search 收到未排序 data 的特定預期行為 + 依據設計規格，未排序時 binary_search 為了不退化效能，不做內部排序。 + 在此我們特定設計一組測試，當二分搜尋在未排序數列中搜尋時，可能因搜尋區間錯亂而返回 -1。 + """ + # 未排序資料中搜尋 3 （其實 3 存在於 index 0） + unsorted_data = [3, 1, 2] + res = binary_search(unsorted_data, 3) + # 應為 -1（因其沒有經過排序，照二分搜尋邏輯會搜尋失敗） + self.assertEqual(res, -1, "未排序資料進行 binary_search 應搜尋失敗返回 -1") + + +if __name__ == "__main__": + unittest.main() diff --git a/weeks/week-17/solutions/1112405016/0618/test_security.py b/weeks/week-17/solutions/1112405016/0618/test_security.py new file mode 100644 index 000000000..df8192436 --- /dev/null +++ b/weeks/week-17/solutions/1112405016/0618/test_security.py @@ -0,0 +1,57 @@ +import unittest +import os +import json +import pickle +from benchmark import make_data +from timing import timeit + + +class TestSecurityStandards(unittest.TestCase): + def test_make_data_rejects_negative_n(self): + """測試 1 (03 Numbers): make_data 的 n 邊界防禦。 + 當 n 為負數或非整數時，應拋出 ValueError。而不能回傳空 list 或當機。 + """ + with self.assertRaises(ValueError): + make_data(-5) + with self.assertRaises(ValueError): + make_data(3.14) # type: ignore + + def test_timing_repeat_uses_raise_not_assert(self): + """測試 2 (08 Coding Standards): 裝飾器輸入驗證不可使用 assert。 + 因為 assert 在生產環境的優化編譯（-O 旗標）下會被完全忽略。 + 如果我們傳入無效的 repeat，裝飾器應透過 raise 拋出 ValueError。 + """ + with self.assertRaises(ValueError): + @timeit(repeat=0) + def dummy(): + pass + + def test_results_file_load_uses_json_not_pickle(self): + """測試 3 (04 Neutralization): 防範不可信反序列化漏洞 (CWE-502)。 + 讀取或儲存 results.json 評估數據時，必須使用 json 模組，絕對不准使用危險的 pickle， + 因為 pickle 載入惡意檔案會執行任意程式碼。 + """ + # 模擬讀取 results.json，確認使用的是 json + # 我們可以直接檢測檔案開頭與格式，或者確保我們不含有任何 pickle 的特徵碼 + results_file = "results.json" + self.assertTrue(os.path.exists(results_file), "results.json 檔案應該存在") + + # 讀取並解析 + try: + with open(results_file, "r", encoding="utf-8") as f: + data = json.load(f) + self.assertIsInstance(data, dict, "應該成功解析為 JSON dict") + except json.JSONDecodeError as e: + self.fail(f"結果檔案不是有效的 JSON 格式！讀取失敗: {e}") + + # 驗證此檔案中絕不可能包含 pickle 的二進位特徵（例如 pickle 的 protocol 標誌） + with open(results_file, "rb") as f: + header = f.read(2) + # pickle module features usually start with b'\x80' + self.assertNotEqual(header, b'\x80\x02', "偵測到疑似 pickle protocol v2 的特徵碼！不安全") + self.assertNotEqual(header, b'\x80\x03', "偵測到疑似 pickle protocol v3 的特徵碼！不安全") + self.assertNotEqual(header, b'\x80\x04', "偵測到疑似 pickle protocol v4 的特徵碼！不安全") + + +if __name__ == "__main__": + unittest.main() diff --git a/weeks/week-17/solutions/1112405016/0618/test_timing.py b/weeks/week-17/solutions/1112405016/0618/test_timing.py new file mode 100644 index 000000000..a5566c468 --- /dev/null +++ b/weeks/week-17/solutions/1112405016/0618/test_timing.py @@ -0,0 +1,107 @@ +"""Stage 1 — @timeit 裝飾器測試 + +規格:timing.py 的 timeit 裝飾器必須 + 1. 不改變被裝飾函式的回傳值 + 2. 用 functools.wraps 保留 __name__ / __doc__ + 3. 每次呼叫實際跑 repeat 次(預設 3),把每次耗時(float 秒)append 到 f.records + 4. f.last_elapsed = 本次 repeat 的平均耗時 + 5. 裝飾器內不准 print + 6. repeat < 1 → raise ValueError(用 raise,不准 assert) +""" + +import unittest +import time +import io +import sys +from unittest.mock import patch + +# 匯入待測的裝飾器 +from timing import timeit + + +class TestTimeit(unittest.TestCase): + def test_returns_original_result(self): + """測試 1: 裝飾器不改變被裝飾函式的回傳值""" + @timeit(repeat=3) + def add(a, b): + return a + b + + result = add(5, 7) + self.assertEqual(result, 12) + + def test_preserves_function_metadata(self): + """測試 2: 裝飾器保留原函式的 __name__ 與 __doc__""" + @timeit(repeat=3) + def my_func(): + """This is a docstring.""" + pass + + self.assertEqual(my_func.__name__, "my_func") + self.assertEqual(my_func.__doc__, "This is a docstring.") + + def test_repeat_records_and_average(self): + """測試 3: 記錄每次執行的耗時與平均耗時""" + @timeit(repeat=4) + def dummy_sleep(): + time.sleep(0.01) + return "done" + + res = dummy_sleep() + self.assertEqual(res, "done") + + # 驗證記錄屬性存在且正確 + self.assertTrue(has_attr := hasattr(dummy_sleep, "records"), "應該要有 records 屬性") + self.assertTrue(has_elapsed := hasattr(dummy_sleep, "last_elapsed"), "應該要有 last_elapsed 屬性") + + if has_attr: + self.assertEqual(len(dummy_sleep.records), 4) + for t in dummy_sleep.records: + self.assertIsInstance(t, float) + self.assertGreaterEqual(t, 0.0) + + if has_attr and has_elapsed: + expected_avg = sum(dummy_sleep.records) / len(dummy_sleep.records) + self.assertAlmostEqual(dummy_sleep.last_elapsed, expected_avg, places=5) + + def test_repeat_below_one_raises_valueerror(self): + """測試 4: 當 repeat < 1 時拋出 ValueError，不可使用 assert 驗證""" + with self.assertRaises(ValueError): + @timeit(repeat=0) + def test_func(): + pass + + with self.assertRaises(ValueError): + @timeit(repeat=-5) + def test_func2(): + pass + + def test_no_print_called(self): + """測試 5: 裝飾器內部不准呼叫 print 輸出任何內容""" + @timeit(repeat=2) + def target_func(): + return 42 + + # 擷取 stdout 檢查是否有 print + captured_output = io.StringIO() + sys.stdout = captured_output + try: + target_func() + finally: + sys.stdout = sys.__stdout__ + + self.assertEqual(captured_output.getvalue(), "", "裝飾器內部不可有任何 print 輸出") + + def test_decorator_without_arguments(self): + """測試 6: 支援無參數的 @timeit 寫法，預設 repeat=3""" + @timeit + def default_func(): + time.sleep(0.005) + return "default" + + res = default_func() + self.assertEqual(res, "default") + self.assertEqual(len(default_func.records), 3) + + +if __name__ == "__main__": + unittest.main() diff --git a/weeks/week-17/solutions/1112405016/0618/timing.py b/weeks/week-17/solutions/1112405016/0618/timing.py new file mode 100644 index 000000000..7c4d4d1a6 --- /dev/null +++ b/weeks/week-17/solutions/1112405016/0618/timing.py @@ -0,0 +1,42 @@ +import functools +import time + + +def timeit(_func=None, *, repeat=3): + """計時裝飾器 + + 每次呼叫實際執行被裝飾函式 `repeat` 次（預設 3），並將每次執行耗時（秒，float） + 記錄在屬性 `records` 中，且計算本次平均耗時存入 `last_elapsed` 屬性。 + 當 repeat < 1 時，拋出 ValueError。 + 內部不可有任何 print 輸出。 + """ + # 支援無括號的 @timeit 寫法 + if _func is not None and callable(_func): + func = _func + return timeit(repeat=3)(func) + + # 驗證輸入參數：必須為整數且大於等於 1 + if not isinstance(repeat, int) or repeat < 1: + raise ValueError("repeat must be an integer >= 1") + + def decorator(func): + @functools.wraps(func) + def wrapper(*args, **kwargs): + local_records = [] + result = None + for _ in range(repeat): + start_time = time.perf_counter() + result = func(*args, **kwargs) + end_time = time.perf_counter() + local_records.append(end_time - start_time) + + wrapper.records.extend(local_records) + wrapper.last_elapsed = sum(local_records) / len(local_records) + return result + + # 初始化紀錄屬性 + wrapper.records = [] + wrapper.last_elapsed = 0.0 + return wrapper + + return decorator