simonw / datasette

GitHub metadata 把這個專案描述為「An open source multi-tool for exploring and publishing data」（一個用來探索和發布資料的開源多功能工具），首頁是 datasette.io。主要語言是 Python；位元組分布列出約 2.47 百萬個 Python 位元組，另有 JavaScript、HTML、CSS、Shell、C、Dockerfile 和 Just 檔案。repository topics 包括 asgi、automatic-api、csv、datasets、datasette、docker、json、python、sql 和 sqlite。授權是 Apache-2.0，repository 根目錄有 LICENSE 檔案。在結構上，被分析的快照有 333 個檔案：一個 datasette 套件（135 個檔案），加上 tests（102）、docs（50）、demos（7）和幾個其他的頂層目錄。列出的最新 release 是 1.0a39（2026-09-11 發布），這個 repository 在 2026-09-14 有 11,460 個 star。

datasette/__main__.py 裡唯一可見的啟動程式碼，是一個呼叫 cli() 的 main 守衛：

if __name__ == "__main__":
    cli()

一條有界靜態執行路徑記錄了 __main__ 把控制交給 datasette/cli.py 裡的 cli，然後就在那裡以葉節點結束。datasette/app.py 和 datasette/cli.py 都被標記為可能的可執行進入點（檔名啟發式規則）。app.py 被標為 entry/orchestration 候選，有 356 個呼入和 197 個靜態呼出。它包含兩個大型類別：Datasette（第 394-3037 行）和 DatasetteRouter（第 3040-3314 行）。請注意限制：從 app.py 出發的每一條追蹤到的執行路徑，都停在 logging.getLogger、contextvars.ContextVar、collections.namedtuple 或 Setting 這類未解析的外部邊界，所以更深層的執行期接線無法確定。

• 頂層配置把應用程式套件 datasette 和 docs、tests 兩個子系統分開。
• datasette/utils/__init__.py 是連結最多的 Python 模組（519 個呼入／53 個呼出），定義了 CustomJSONEncoder 和 sqlite_timelimit。
• 其次是 datasette/utils/asgi.py（369 個呼入），它定義了 Request、AsgiLifespan、AsgiStream 和 AsgiWriter，以及 NotFound、Forbidden 這類例外類別。
• 在列出的 Python 模組中，datasette/views/table.py 的呼出次數最高（283 出／46 入），這暗示它協調許多模組；它定義了 TableContext 和 Row。
• datasette/__init__.py（348 入／0 出）和 datasette/resources.py（227 入／0 出）看起來是 leaf/data-boundary 模組；resources.py 定義了 DatabaseResource、TableResource 和 QueryResource。
• 前端素材放在 datasette/static 底下；分析器回報整體連結度最高的是 edit-tools.js（808/808）和 table.js（83/83），但 JavaScript 的分析只是有界的啟發式判斷。

這份分析資料裡的清單檔證據只涵蓋 JavaScript 工具。package.json 是偵測到的兩個建置／依賴清單檔之一，列出的執行期依賴有 @codemirror/lang-sql ^6.3.3、codemirror ^6.0.1、rollup ^3.30.0、@rollup/plugin-node-resolve ^15.0.1 和 @rollup/plugin-terser ^0.1.0，另有開發用依賴 prettier ^3.0.0。依賴解析在這裡有硬性限制：只解析了 requirements 形式的清單檔，沒有解析 pyproject.toml 的依賴表，所以這次分析無法確定 Python 套件本身的依賴。tests 子系統有 102 個測試檔案。抽樣的 tests/test_api_write.py 定義了輔助函式 ds_write 和 write_token，以及 test_structured_writes_require_ordinary_tables、test_base64_write_api_insert_upsert_update_decode_blobs 這類測試。tests/build_small_spatialite_db.py 是專案層級重要的可能進入點，它的 __main__ 守衛會呼叫 generate_it("spatialite.db")，產生一個 SQLite 測試資料庫。

1. README.md：被標為專案層級的重要檔案，通常是第一站。
2. pyproject.toml 和 package.json：打包與工具的清單檔，兩者都被標為重要。
3. 先看 datasette/__main__.py，再看 datasette/cli.py：這是啟動鏈；靜態路徑從 __main__ 守衛走到 cli。
4. datasette/app.py：居中協調的模組，放著 Datasette 和 DatasetteRouter 類別。
5. datasette/utils/__init__.py 和 datasette/utils/asgi.py：在列出的 Python 模組中呼入次數最高（519 和 369；就整體而言，edit-tools.js 回報了 808 個呼入）。
6. datasette/views/table.py：在 Python 模組中呼出次數最高的 view 邏輯（283；就整體而言，edit-tools.js 回報了 808 個呼出），很適合用來觀察請求怎麼到達其他程式碼。

修改程式時，請從偵測到的進入點 datasette/app.py 開始追蹤，並手動檢查下游的影響，因為動態行為在靜態分析中沒有解析。

• 只有靜態分析：反射、動態 import、monkey-patching、產生的程式碼、框架在執行期的接線和動態分派都沒有解析，所以從這份分析資料無法確定外掛怎麼被發現和載入。
• 安裝、執行與建置的推論並不完整；安裝指令沒有驗證，分析資料裡也沒有任何執行時或執行結果。
• 在 21,338 條靜態關係中，15,850 條是外部或未解析，5,488 條在本地解析。
• 有兩個檔案只被清點、沒有被解析（過大、壓縮過或 vendored）；有界分析也會略過超過 400 kB 的檔案、壓縮打包檔和 vendored 目錄。
• 依賴的涵蓋並不完整：pyproject.toml 的依賴表沒有被解析。
• README 陳述的擷取是逐行進行的，可能抓到程式碼行，所以任何來自 README 的陳述最多只算 author_claimed。

• Datasette（datasette/app.py，第 394-3037 行）和 DatasetteRouter（第 3040-3314 行）：app.py 裡的兩個大型類別，分析器把這個模組標為 entry/orchestration 候選。
• DatabaseResource、TableResource、QueryResource（datasette/resources.py）：這些類別所在的模組被標為 leaf/data-boundary 候選。
• Request、AsgiLifespan、AsgiStream、AsgiWriter，以及 NotFound/Forbidden/BadRequest/PayloadTooLarge 例外（datasette/utils/asgi.py）：這些類別所在的模組，在列出的 Python 模組中呼入次數第二高（369）。
• CustomJSONEncoder 和 sqlite_timelimit（datasette/utils/__init__.py），加上 TableContext 和 Row（datasette/views/table.py）：分別位在列出的 Python 模組中呼入次數最多（519）和呼出次數最多（283）的模組裡。