simonw / sqlite-utils · Architecture

The GitHub repository metadata describes this project as a 'Python CLI utility and library for manipulating SQLite databases'; treat that as author-claimed, not analyzer-verified. Static analysis covered 107 files: 59 under tests/, 18 under docs/, 11 under sqlite_utils/, 10 under .github/, and 9 at the repository root. The top-level directories docs, sqlite_utils and tests are each flagged as a subsystem. The recorded primary language is Python; recorded topics include cli, click, sqlite and datasette.

sqlite_utils/__main__.py contains a Python __main__ execution guard whose guarded body calls cli(). sqlite_utils/cli.py is separately flagged as a likely executable entrypoint by a filename heuristic and marked important for that reason. The listed bounded path from that guard is a single local step — sqlite_utils/__main__.py to cli in sqlite_utils/cli.py — ending with terminal reason 'leaf'; it is not truncated and reports no cycle. Of the 10 listed execution-path records, the 9 that start at sqlite_utils/cli.py all end at an unresolved external target (terminal reason 'unresolved_boundary'): one at strip, two via maximize_csv_field_size_limit in sqlite_utils/utils.py to csv.field_size_limit and int, and six at click.option; none is truncated and none reports a cycle. The reconstruction overview reports 2 entrypoints and 13 bounded execution paths, while only 10 path records are listed here.

All 20 listed module-role records derive their roles from static resolved call degree and entrypoint membership, so every role below is an analyzer inference from call counts, not a runtime observation.

• sqlite_utils/db.py — 'service/core candidate' (381 incoming, 317 outgoing static calls)
• sqlite_utils/cli.py — 'entry/orchestration candidate' (127 in, 194 out)
• sqlite_utils/__init__.py — 'leaf/data-boundary candidate' (312 in, 0 out)
• sqlite_utils/create_table_parser.py — 'service/core candidate' (165 in, 122 out)
• sqlite_utils/utils.py — 'service/core candidate' (91 in, 16 out)
• sqlite_utils/plugins.py — 'service/core candidate' (19 in, 1 out)

Of the 20 listed role records, 14 are test modules labelled 'service/core candidate' or 'orchestration candidate'; tests/test_cli.py, for example, shows 7 incoming and 116 outgoing calls. Across those records, db.py holds the highest incoming-call count (381), and __init__.py the highest incoming count among records with zero outgoing calls (312).

All nine listed paths that start at sqlite_utils/cli.py stop at unresolved external targets instead of continuing into local code. The targets involved are strip and click.option (called from sqlite_utils/cli.py) and csv.field_size_limit and int (reached via maximize_csv_field_size_limit in sqlite_utils/utils.py). In totals, 7360 of the 8672 recorded static relations are external or unresolved; 1312 resolve locally, and the relations comprise 8263 calls and 409 imports. None of the 10 listed execution-path records shows plugin loading, although a sqlite_utils/plugins.py module appears among the role records.

The packet contains no dependency records, so manifest-level dependencies between parts are not established here. The limitation record explains the gap: dependency records come only from requirements-style manifests, and pyproject.toml dependency tables were not parsed. Individual module-to-module import edges appear in the packet's resolved-relation sample without citable identifiers, so this asset does not restate them; in aggregate, 409 import relations and 8263 calls were recorded.

The limitation record states that reflection, runtime dependency injection, dynamic imports, monkey-patching, generated code, framework runtime wiring and dynamic dispatch are not resolved by this static analysis. Installation and run/build inference is partial, and installation commands are not verified. README claim extraction is line-based and may capture code lines instead of prose claims, so README-derived statements are author_claimed at best. The manifest's actual_capabilities fields describe the analyzer, not the analyzed repository, and are excluded from repository evidence. Dynamic dispatch, reflection, generated code and runtime framework behaviour therefore remain unestablished by this asset.

README.md, pyproject.toml and LICENSE are classified as project-level important files, so they make natural first reads. The two flagged entrypoints, sqlite_utils/__main__.py and sqlite_utils/cli.py, come next. A workable order from there: read the __main__ guard, follow its one-step path into cli(), then use the role records as a map for db.py, utils.py, create_table_parser.py and plugins.py before reading deeper code.