Repository 指南 · 概覽 · v2
simonw / sqlite-utils
“Python CLI utility and library for manipulating SQLite databases” — 作者自述
- CLI Tools
- Python
- Apache-2.0 · 開源授權
- 原始 repository
- simonw/sqlite-utils
- 來源平台
- GitHub
- 擁有者 / 組織
- simonw
- 授權
- Apache-2.0 · 開源授權
- 分析的版本
- 85b1be10c81d9dd3567e36faf8dd411e4a8789bd
- 最後驗證
原始專案有更新，但本指南引用的程式碼沒有變動。預設分支已前進到 6bc1d33d583c，2026-10-03 檢查。版本差異比對了 2 個變動的檔案，本指南引用的程式碼區域都沒有變動。本頁描述的仍是版本 85b1be10c81d；整個 repository 的統計數字（檔案數、呼叫次數等）指的是那個版本。
本頁中文由負責的 AI 編輯依英文正式版本 v2 翻譯；程式碼名稱、路徑、行號與數字都經確定性檢查，與英文版一致。陳述與依據表保留英文原文，因為那是獨立驗證者核對過的紀錄。看英文原文
simonw/sqlite-utils：repository 概覽
本頁用語說明
- Entrypoint record（進入點記錄）
- 分析器標記為「程式可能從這裡開始執行」的檔案。附有 __main__ guard 摘錄時，表示檔案裡有 if __name__ == "__main__": 區塊，摘錄顯示它呼叫了什麼；沒有摘錄時，只是依檔名判斷。
- Bounded static execution path（有界靜態執行路徑）
- 不執行程式、直接從原始碼重建出的呼叫鏈，走到固定步數就停。它說明在紙面上能追到多遠，不代表實際執行時會發生什麼。
- Unresolved boundary（未解析邊界）
- 靜態路徑停下的地方：下一個呼叫進入外部函式庫，或不執行就無法確定。這是本次分析的邊界，不是 repository 的缺陷。
- Static relations（靜態關係）
- 在原始碼中找到的呼叫與 import。「external or unresolved」表示指向分析範圍以外。
- Module role（模組角色）
- 分析器依呼叫進出次數推論的檔案標籤（例如 core、entry/orchestration、leaf）。它描述的是在呼叫圖中的位置，不是作者的設計意圖。
- Test-like files（類測試檔案）
- 名稱或位置看起來像測試的檔案。本次分析只計數，不執行。
- Observed · inferred · author-claimed · unresolved
- 每句話的依據：直接讀自分析的檔案；由分析器從檔案推論；repository 作者自述（metadata、README）；或本次分析無法確定。
- Verified（已驗證）
- 本頁有兩種用法。在分析器的記錄裡（「verified provenance」「verified entrypoint」），它表示這筆記錄是直接從分析的檔案讀到的，也就是本指南所說的 observed；以進入點來說，就是檔案裡確實有 __main__ guard 的文字。分析器在 2026-10-04 修正後，只有 cli.py、main.py 這類像進入點的檔名、沒有 guard 的檔案，會記為 inferred（推測）；在那之前分析的指南仍把這類檔案標成 verified，它依然只是對檔案用途的推測。它不代表程式被執行或測試過。「最後驗證」是這份指南最後一次通過本實驗室檢查的日期，檢查對象是所標示版本的分析記錄，不是對 repository 本身的審查。
一個 Python 專案的靜態概覽，頂層套件是 sqlite_utils，作者自述它是操作 SQLite 資料庫的 CLI 工具與函式庫。執行從 sqlite_utils/__main__.py 開始，它會呼叫 sqlite_utils/cli.py 裡的 cli。靜態呼叫次數集中在 sqlite_utils/db.py，這個 repository 有 59 個測試檔案。記錄到的 8,672 條靜態關係中，有 7,360 條仍是外部或未解析。
這個 repository 是什麼
GitHub metadata 把這個 repository 描述為「Python CLI utility and library for manipulating SQLite databases」（操作 SQLite 資料庫的 Python CLI 工具與函式庫）。列出的首頁是 https://sqlite-utils.datasette.io 。平台 metadata 記錄的主要語言是 Python，有 935,041 個 Python 位元組、1,547 個 C 位元組和 955 個 Just 位元組。授權是 Apache-2.0，專案根目錄有 LICENSE 檔案。分析器記錄了 release 4.2.1（2026-08-13 發布）和 2,168 個 star（2026-09-14）。topics 包括 cli、click、sqlite 和 datasette-tool。程式碼放在頂層的 sqlite_utils 套件目錄裡。分析器的摘要描述這是一個有 107 個被分析檔案的 Python 專案，圍繞 docs、sqlite_utils 和 tests 組織。
執行怎麼開始
sqlite_utils/__main__.py 有一個 __main__ 執行守衛，摘錄內容是 if __name__ == "__main__": cli()。分析器另外依檔名啟發式規則，把 sqlite_utils/cli.py 記錄為可能的可執行進入點。一條有界靜態執行路徑從 __main__.py 走到 sqlite_utils/cli.py 裡的 cli 函式，屬於本地呼叫。從 cli.py 出發，記錄到的路徑經過未解析的外部邊界到達 click.option；cli.py 也會呼叫 sqlite_utils/utils.py 裡的 maximize_csv_field_size_limit，它在未解析的邊界到達 csv.field_size_limit 和內建的 int。還有一條從 cli.py 出發的路徑，停在一個名為 strip 的未解析外部目標。所以大多數記錄到的路徑走一兩步就停在未解析邊界，而不是追出很深的本地呼叫鏈。
Repository 結構與模組連結度
有三個頂層目錄被記錄為子系統：docs、sqlite_utils 和 tests。這個 repository 有 59 個測試檔案或類測試檔案，以 tests/conftest.py 為中心。分析資料記錄了 8,672 條靜態關係：8,263 個呼叫和 409 個 import，其中 1,312 條解析到本地目標，7,360 條仍是外部或未解析。依靜態呼叫次數，分析器把 sqlite_utils/db.py 歸為 service/core 候選，它的呼入次數是分析資料中最高的：381 個呼入、317 個呼出。sqlite_utils/cli.py 是 entry/orchestration 候選（127 入、194 出），sqlite_utils/__init__.py 則是 leaf/data-boundary 候選，有 312 個呼入、沒有任何呼出。sqlite_utils/create_table_parser.py（165 入、122 出）和 sqlite_utils/utils.py（91 入、16 出）也是 service/core 候選。這些次數是靜態計數，角色標籤是分析器的推論；它們暗示 db.py 是被呼叫最多的模組，而不是量測到的執行時特性。
依賴證據與測試面
這個 repository 剛好只有一個建置／依賴清單檔：pyproject.toml。分析器只從 requirements 形式的清單檔解析依賴記錄，不解析 pyproject.toml 的依賴表。因此，這份分析資料沒有任何解析出的第三方依賴記錄，光靠這些證據無法還原專案的依賴清單。Click 在這裡只以 repository topic，以及 cli.py 裡未解析的 click.option 呼叫邊界出現，並不是解析出的依賴。測試面有 59 個測試檔案或類測試檔案，以 tests/conftest.py 為中心。具名的測試模組包括 tests/test_cli.py、tests/test_cli_insert.py、tests/test_transform.py、tests/test_create_table_parser.py 和 tests/test_mutator_transactions.py。測試範例：tests/test_cli.py 裡的 test_help 和 test_tables；tests/test_cli_insert.py 裡的 test_insert_simple 和 test_insert_from_stdin。
建議的閱讀順序
分析器把 README.md、pyproject.toml、LICENSE、sqlite_utils/__main__.py 和 sqlite_utils/cli.py 標為重要檔案。一個可行的順序：先讀 README.md；接著是 pyproject.toml 和 LICENSE；然後是 sqlite_utils/__main__.py 和 sqlite_utils/cli.py，從它的 cli 函式開始；再來是 sqlite_utils/db.py，從 quote_identifier 開始；然後是 sqlite_utils/utils.py 的 maximize_csv_field_size_limit；最後看 tests/test_cli.py 裡具體的 CLI 行為。這個順序是根據分析器的標記和符號記錄提出的建議，不是 repository 自己說明的事實。
這次分析的限制
這次分析只有靜態的部分：反射、執行期依賴注入、動態 import、monkey-patching、產生的程式碼、框架在執行期的接線和動態分派都沒有解析。安裝、執行與建置的推論並不完整，安裝指令也沒有驗證。依賴解析只涵蓋 requirements 形式的清單檔，所以證據裡沒有 pyproject.toml 的依賴表。來自 README 的文字是逐行擷取的，可能抓到程式碼行而不是說明文字，所以 README 的陳述最多只算作者自述。在記錄到的 8,672 條靜態關係中，7,360 條是外部或未解析。因為動態 import 和動態分派都沒有解析，外掛式或動態載入的程式碼路徑，這次分析無法追蹤。CLI 和函式庫在執行時的行為，這份分析資料無法確定。
值得注意的符號
- sqlite_utils/cli.py：cli（第 180-181 行）、CaseInsensitiveChoice（96-101）、output_options（104-151）、tables（213-287）、views（313-355）、optimize（367-384）、rebuild_fts（395-410）、analyze（420-437）。
- sqlite_utils/db.py：quote_identifier（93-99）、fold_identifier_case（147-152）、resolve_casing（155-167）、ForeignKey（251-304）、TransformError（325-326）、AlterError（435-436）。
- sqlite_utils/utils.py：maximize_csv_field_size_limit（87-99）、find_spatialite（102-127）、column_affinity（170-188）、decode_base64_values（191-204）、Format（244-248）。
- sqlite_utils/create_table_parser.py：Check（16-26）、Unique（43-50）、ParseError（53-54）、_Token（58-65）、_lex（233-293）、_split_spans（322-349）。
這次分析無法確定的事
這些是撰寫模型對分析記錄自己的說明。lim_3、exec_* 或 claim_… 這類識別碼指的是那次分析裡的記錄；陳述與依據表引用的也是同一批記錄。
- 記錄到的 8,672 條靜態關係中有 7,360 條是外部或未解析，所以除了在本地解析的 1,312 條邊之外，這份分析資料無法確定其他行為。
- 這份分析資料沒有任何解析出的第三方依賴記錄，因為分析器 v0.10 不解析 pyproject.toml 的依賴表；依賴必須直接從清單檔確認。
- important_2（readme.md）被排除了，因為這個路徑不在被分析的清單裡（大小寫不同的比對）；正式的 README 檔名，這份分析資料沒有定論。
- 教學陳述 claim_4d30ade3e21e 斷言沒有可用的有界靜態執行路徑，但分析資料列出了 13 條有界執行路徑；這裡關於執行流程的陳述，以列出的 exec_* 記錄為依據。
- 教學陳述 claim_31023ca59768 回報有 1,127 條已解析的靜態呼叫關係，這和 relation_counts（呼叫與 import 合計 1,312 條本地關係）不一致；這個差異在這裡沒有解決。
- 所有發現都是靜態的，而且只針對單一版本（分析資料的分析版本 85b1be10c81d9dd3567e36faf8dd411e4a8789bd）；沒有做任何執行時驗證，也不聲稱有。
陳述與依據 — 39 條陳述，39 條經獨立驗證者確認（英文原文）
上面每一句都是一條陳述，各自引用分析裡的依據編號。編號是這次分析內部的；表格列出每條陳述靠的是什麼、依據有多強。
Every substantive statement above is a claim bound to grounding IDs of the analyzed revision. Global grounding IDs are namespaced by the analysis run.
| Claim | Epistemic status | Verifier | Grounding (global IDs) |
|---|---|---|---|
| c1 Repository metadata describes the project as a 'Python CLI utility and library for manipulating SQLite databases'. | author_claimed | supported | analysis_4dc72394ecce6742:meta_description |
| c2 The repository's listed homepage is https://sqlite-utils.datasette.io. | author_claimed | supported | analysis_4dc72394ecce6742:meta_homepage |
| c3 Platform metadata records Python as the primary language, with 935,041 Python bytes, 1,547 C bytes, and 955 Just bytes. | observed | supported | analysis_4dc72394ecce6742:meta_primary_language, analysis_4dc72394ecce6742:meta_language_bytes |
| c4 The license is Apache-2.0 per platform metadata, and a LICENSE file exists at the project root. | observed | supported | analysis_4dc72394ecce6742:meta_license, analysis_4dc72394ecce6742:important_4 |
| c5 The analyzer recorded release 4.2.1 published 2026-08-13 and 2,168 stargazers as of 2026-09-14. | observed | supported | analysis_4dc72394ecce6742:meta_latest_release, analysis_4dc72394ecce6742:meta_stars |
| c6 Repository topics include cli, click, sqlite, and datasette-tool. | observed | supported | analysis_4dc72394ecce6742:meta_topics |
| c7 The repository's code lives in a top-level sqlite_utils package directory. | observed | supported | analysis_4dc72394ecce6742:subsys_2 |
| c8 The analyzer's repository summary describes a Python project of 107 analyzed files organized around the docs, sqlite_utils, and tests directories. | inferred | supported | analysis_4dc72394ecce6742:summary_repository |
| c9 sqlite_utils/__main__.py contains a __main__ execution guard whose excerpt invokes cli(). | observed | supported | analysis_4dc72394ecce6742:py_entry_766b287179b9 |
| c10 The analyzer records sqlite_utils/cli.py as a likely executable entrypoint by filename heuristic and flags it as an important file. | observed | supported | analysis_4dc72394ecce6742:entry_1, analysis_4dc72394ecce6742:important_6 |
| c11 A bounded static execution path runs from sqlite_utils/__main__.py to the function cli in sqlite_utils/cli.py as a local call. | inferred | supported | analysis_4dc72394ecce6742:exec_646e4227082d |
| c12 Recorded execution paths from sqlite_utils/cli.py reach click.option through unresolved external boundaries. | inferred | supported | analysis_4dc72394ecce6742:exec_13a2f2c834ee, analysis_4dc72394ecce6742:exec_00b231e391d5 |
| c13 cli.py calls maximize_csv_field_size_limit in sqlite_utils/utils.py, which reaches csv.field_size_limit and the builtin int at unresolved boundaries. | inferred | supported | analysis_4dc72394ecce6742:exec_585cacddd5fa, analysis_4dc72394ecce6742:exec_6afdc3bbf9ee, analysis_4dc72394ecce6742:py_func_8b355fe7ad10 |
| c14 One bounded path from sqlite_utils/cli.py terminates at an unresolved external target named strip. | inferred | supported | analysis_4dc72394ecce6742:exec_905105dee30d |
| c15 The analyzer records docs, sqlite_utils, and tests as top-level directory subsystems. | observed | supported | analysis_4dc72394ecce6742:subsys_1, analysis_4dc72394ecce6742:subsys_2, analysis_4dc72394ecce6742:subsys_3 |
| c16 The repository contains 59 test files or test-like files, anchored at tests/conftest.py. | observed | supported | analysis_4dc72394ecce6742:ev_tests_1 |
| c17 The packet records 8,672 static relations (8,263 calls, 409 imports): 1,312 resolved locally and 7,360 external or unresolved. | observed | supported | analysis_4dc72394ecce6742:relation_counts |
| c18 sqlite_utils/db.py is classified as a service/core candidate with 381 incoming and 317 outgoing static calls, the highest incoming degree in the packet. | inferred | supported | analysis_4dc72394ecce6742:role_6 |
| c19 sqlite_utils/cli.py is an entry/orchestration candidate (127 incoming, 194 outgoing), and sqlite_utils/__init__.py is a leaf/data-boundary candidate (312 incoming, 0 outgoing). | inferred | supported | analysis_4dc72394ecce6742:role_4, analysis_4dc72394ecce6742:role_2 |
| c20 sqlite_utils/create_table_parser.py (165 in, 122 out) and sqlite_utils/utils.py (91 in, 16 out) are service/core candidates. | inferred | supported | analysis_4dc72394ecce6742:role_5, analysis_4dc72394ecce6742:role_10 |
| c21 The repository contains exactly one build/dependency manifest file, pyproject.toml. | observed | supported | analysis_4dc72394ecce6742:ev_manifest_1, analysis_4dc72394ecce6742:important_3 |
| c22 Dependency records come only from requirements-style manifests parsed by analyzer v0.10; pyproject.toml dependency tables are not parsed. | observed | supported | analysis_4dc72394ecce6742:lim_3 |
| c23 Because pyproject.toml is the only manifest and its dependency tables are not parsed, this packet contains no parsed third-party dependency records. | inferred | supported | analysis_4dc72394ecce6742:lim_3, analysis_4dc72394ecce6742:ev_manifest_1 |
| c24 In this packet, click appears only as a repository topic and as unresolved click.option call boundaries from cli.py. | inferred | supported | analysis_4dc72394ecce6742:meta_topics, analysis_4dc72394ecce6742:exec_13a2f2c834ee |
| c25 Among 59 test files anchored at tests/conftest.py, named test modules include tests/test_cli.py, tests/test_cli_insert.py, tests/test_transform.py, tests/test_create_table_parser.py, and tests/test_mutator_transactions.py. | observed | supported | analysis_4dc72394ecce6742:ev_tests_1, analysis_4dc72394ecce6742:py_func_f8390e9c8ef8, analysis_4dc72394ecce6742:py_func_b24624f67bd6, analysis_4dc72394ecce6742:py_func_070713079dfb, analysis_4dc72394ecce6742:py_func_38b91d4d090b, analysis_4dc72394ecce6742:py_func_2471c52f4c96 |
| c26 Named tests include test_help and test_tables in tests/test_cli.py, and test_insert_simple and test_insert_from_stdin in tests/test_cli_insert.py. | observed | supported | analysis_4dc72394ecce6742:py_func_f8390e9c8ef8, analysis_4dc72394ecce6742:py_func_bf7669ce64ed, analysis_4dc72394ecce6742:py_func_b24624f67bd6, analysis_4dc72394ecce6742:py_func_0b7609eaa294 |
| c27 README.md, pyproject.toml, LICENSE, sqlite_utils/__main__.py, and sqlite_utils/cli.py are flagged by the analyzer as important files. | observed | supported | analysis_4dc72394ecce6742:important_1, analysis_4dc72394ecce6742:important_3, analysis_4dc72394ecce6742:important_4, analysis_4dc72394ecce6742:important_5, analysis_4dc72394ecce6742:important_6 |
| c28 Suggested order: README.md; pyproject.toml and LICENSE; sqlite_utils/__main__.py then sqlite_utils/cli.py starting at cli(); sqlite_utils/db.py from quote_identifier; sqlite_utils/utils.py at maximize_csv_field_size_limit; then tests/test_cli.py for concrete CLI behavior. | inferred | supported | analysis_4dc72394ecce6742:important_1, analysis_4dc72394ecce6742:important_3, analysis_4dc72394ecce6742:important_4, analysis_4dc72394ecce6742:important_5, analysis_4dc72394ecce6742:important_6, analysis_4dc72394ecce6742:entry_1, analysis_4dc72394ecce6742:py_func_c7ac54256da1, analysis_4dc72394ecce6742:py_func_895e7594ef10, analysis_4dc72394ecce6742:py_func_8b355fe7ad10, analysis_4dc72394ecce6742:py_func_f8390e9c8ef8 |
| c29 The analysis is static only: reflection, runtime dependency injection, dynamic imports, monkey-patching, generated code, framework runtime wiring, and dynamic dispatch are not resolved. | observed | supported | analysis_4dc72394ecce6742:lim_1 |
| c30 Install/run/build inference is partial, and installation commands are not verified. | observed | supported | analysis_4dc72394ecce6742:lim_2 |
| c31 Dependency parsing in this analysis is limited to requirements-style manifests, so pyproject.toml dependency tables are absent from the evidence. | observed | supported | analysis_4dc72394ecce6742:lim_3 |
| c32 README claim extraction is line-based and may capture code lines instead of prose; README-derived text is author-claimed at best. | observed | supported | analysis_4dc72394ecce6742:lim_4 |
| c33 7,360 of the 8,672 recorded static relations are external or unresolved. | observed | supported | analysis_4dc72394ecce6742:relation_counts |
| c34 Because dynamic imports and dynamic dispatch are unresolved, plugin-style or dynamically loaded code paths cannot be traced by this analysis. | inferred | supported | analysis_4dc72394ecce6742:lim_1 |
| c35 Runtime behavior of the CLI and library is not established by this packet. | unresolved | supported | analysis_4dc72394ecce6742:lim_2 |
| c36 sqlite_utils/cli.py defines cli (lines 180-181), CaseInsensitiveChoice (96-101), output_options (104-151), tables (213-287), views (313-355), optimize (367-384), rebuild_fts (395-410), and analyze (420-437). | observed | supported | analysis_4dc72394ecce6742:py_func_c7ac54256da1, analysis_4dc72394ecce6742:py_class_c4f5fc9952ac, analysis_4dc72394ecce6742:py_func_5310ab543796, analysis_4dc72394ecce6742:py_func_1004876b64ba, analysis_4dc72394ecce6742:py_func_cd237bec2059, analysis_4dc72394ecce6742:py_func_95dea1910e6e, analysis_4dc72394ecce6742:py_func_b990acac609b, analysis_4dc72394ecce6742:py_func_c3e19b4595a5 |
| c37 sqlite_utils/db.py defines quote_identifier (93-99), fold_identifier_case (147-152), resolve_casing (155-167), ForeignKey (251-304), TransformError (325-326), and AlterError (435-436). | observed | supported | analysis_4dc72394ecce6742:py_func_895e7594ef10, analysis_4dc72394ecce6742:py_func_66010139651f, analysis_4dc72394ecce6742:py_func_f94e945e4095, analysis_4dc72394ecce6742:py_class_e2aeaef12f8d, analysis_4dc72394ecce6742:py_class_a8cbde8cc362, analysis_4dc72394ecce6742:py_class_5676bf693f65 |
| c38 sqlite_utils/utils.py defines maximize_csv_field_size_limit (87-99), find_spatialite (102-127), column_affinity (170-188), decode_base64_values (191-204), and Format (244-248). | observed | supported | analysis_4dc72394ecce6742:py_func_8b355fe7ad10, analysis_4dc72394ecce6742:py_func_84fe978c3c1e, analysis_4dc72394ecce6742:py_func_e67f7500ffa6, analysis_4dc72394ecce6742:py_func_7d90a9fdb7f0, analysis_4dc72394ecce6742:py_class_43d6659fb81c |
| c39 sqlite_utils/create_table_parser.py defines Check (16-26), Unique (43-50), ParseError (53-54), _Token (58-65), _lex (233-293), and _split_spans (322-349). | observed | supported | analysis_4dc72394ecce6742:py_class_a774596ccd1a, analysis_4dc72394ecce6742:py_class_beab94e0942b, analysis_4dc72394ecce6742:py_class_b0e3b5579c5b, analysis_4dc72394ecce6742:py_class_b01383807491, analysis_4dc72394ecce6742:py_func_f882924ac5ae, analysis_4dc72394ecce6742:py_func_f943092a02cc |
來源、權利與說明 · attribution-license-templates/v0.1
權利聲明。原始 repository 託管於 GitHub。其原始碼、文件、名稱、媒體與相關素材的權利，仍屬各自的作者、貢獻者與其他權利人所有，並受該 repository 的授權條款約束。
Original repository hosted on GitHub. Repository source code, documentation, names, media, and related project materials remain subject to the rights of their respective authors, contributors, and other rights holders and to applicable repository license terms.
平台聲明。GitHub 是所連結 repository 的來源託管平台。GitHub 與相關標誌為 GitHub, Inc. 的商標。除非另有明確說明，EVEMISS Technology 與 GitHub 之間沒有隸屬或背書關係。
GitHub is the source hosting platform for the linked repository. GitHub and related marks are trademarks of GitHub, Inc. EVEMISS Technology is not affiliated with or endorsed by GitHub unless explicitly stated otherwise.
這一頁怎麼來的。本頁由對應版本的 repository 分析與 AI 輔助的編輯工具產生。技術陳述綁定所分析的版本；原始 repository 更新後，可能重新驗證。
This page was produced using revision-aware repository analysis and AI-assisted editorial tooling. Technical claims are tied to the analyzed repository revision and may be revalidated when the source repository changes.
本頁包含 AI 輔助分析，並經 EVEMISS Technology 人工與 AI 協力審閱。 · 回報權利疑慮 · 所有 repository 指南