erdscope 0.3.0__tar.gz → 0.4.0__tar.gz

{erdscope-0.3.0 → erdscope-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: erdscope
-Version: 0.3.0
-Summary: Interactive, self-contained ER-diagram HTML and Excel table definitions from a live MySQL or PostgreSQL database — single file, zero required dependencies
+Version: 0.4.0
+Summary: Interactive, self-contained ER-diagram HTML and Excel table definitions from a MySQL, PostgreSQL, or SQLite database and/or application code (Rails / Prisma / Django) — single file, zero required dependencies
 Author: tas6
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/orapli/erdscope
@@ -9,7 +9,7 @@ Project-URL: Documentation, https://orapli.github.io/erdscope/manual.html
 Project-URL: Live demo, https://orapli.github.io/erdscope/
 Project-URL: Repository, https://github.com/orapli/erdscope
 Project-URL: Issues, https://github.com/orapli/erdscope/issues
-Keywords: erd,er-diagram,database,schema,mysql,rails,prisma,django,documentation
+Keywords: erd,er-diagram,database,schema,mysql,postgresql,postgres,sqlite,rails,prisma,django,documentation
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -43,6 +43,8 @@ zero-dependency Python CLI.
 
 ```bash
 pip install erdscope
+erdscope demo   # no database of your own? try it right now — opens a sample diagram
+
 erdscope mysql://readonly@127.0.0.1:3306/myapp_production -o erd.html
 erdscope postgres://readonly@127.0.0.1:5432/myapp_production -o erd.html
 erdscope sqlite:///path/to/app.db -o erd.html
@@ -87,6 +89,18 @@ curl -O https://raw.githubusercontent.com/orapli/erdscope/main/erd.py
 python3 erd.py ...   # identical to the erdscope command below
 ```
 
+No database of your own to point it at yet? `erdscope demo` builds a small sample
+e-commerce SQLite database in a temp directory, generates the diagram, and opens it in
+your browser — nothing to download or set up:
+
+```bash
+erdscope demo
+```
+
+It's a normal run under the hood, so every other flag still applies
+(`erdscope demo --excel defs.xlsx`, `erdscope demo --only 'order*'`, ...); add
+`--no-open` to skip launching the browser.
+
 ```bash
 erdscope mysql://readonly@127.0.0.1:3306/myapp_production -o erd.html
 
@@ -114,9 +128,10 @@ erdscope --config schema.yml -o erd.html
 erdscope --models /path/to/rails/app --models /path/to/schema.prisma -o erd.html
 ```
 
-Want to try it right now with no database of your own? A ready-to-run SQLite
-sample ships in [`examples/`](examples/) — `python3 erd.py
-sqlite:///examples/demo_shop.db -o shop.html`. See [examples/README.md](examples/README.md).
+Cloned the repository instead of installing from PyPI? A ready-to-run SQLite sample
+(the same schema `erdscope demo` uses) also ships committed in
+[`examples/`](examples/) — `python3 erd.py sqlite:///examples/demo_shop.db -o shop.html`.
+See [examples/README.md](examples/README.md).
 
 Behind a bastion? Open an SSH tunnel first and point at localhost:
 
@@ -134,7 +149,8 @@ itself is made.
 
 | Option | Description |
 |---|---|
-| `-o FILE` | Output HTML path (default: `erd.html`) |
+| `demo` | Positional value: generate from a bundled sample database instead of a real one — no database of your own needed. Every other flag below still applies |
+| `-o FILE` | Output HTML path (default: `erd.html`; `erd_demo.html` for `demo`, so it never overwrites a real run's output) |
 | `--models PATH` | Merge associations parsed from code: a Rails project (or `app/models` dir), a `schema.prisma`, or a Django project — auto-detected. **Repeatable** — multiple sources merge in the order given (later wins). Usable with no database URL |
 | `--excel FILE.xlsx` | Also write a table-definition workbook: an overview sheet plus one sheet per table (columns, defaults, keys, comments, indexes, associations) |
 | `--excel-template FILE.xlsx` | Override the workbook's colors/fonts/borders from a template `.xlsx` — see `excel-template.xlsx` and its `Styles` sheet for the 5-cell contract (default: built-in styling) |
@@ -145,6 +161,7 @@ itself is made.
 | `--table-map 'Widget=crm_widgets'` | Rails only: override a model's table when static analysis can't determine it (e.g. `table_name` set inside a concern that lives in a gem, not the app). Repeatable; comma-separated lists accepted |
 | `--config PATH` | Load defaults from a config file instead of repeating flags — see below. Auto-discovered as `.erdscope.json`/`.yml`/`.yaml` in the current directory if not given |
 | `--no-config` | Skip config auto-discovery even if `.erdscope.*` exists in the cwd |
+| `--no-open` | Skip automatically opening a browser after generating. Only relevant to `demo` (which opens one by default); accepted but has no effect on a normal run |
 
 ## Config file
 
@@ -153,7 +170,8 @@ Once the flag list above gets long, put it in a config file instead — `.erdsco
 Most keys mirror a CLI option (an explicit flag always wins over the config); the DB
 connection is config-only as `engine`/`host`/`port`/`user`/`database` — deliberately with
 no password field — and `relations` manually declares relations no FK, code, or inference
-can find. See the [Config file chapter of the manual](https://orapli.github.io/erdscope/manual.html#config-file) for the full key
+can find. `engine` can also be `"sqlite"`, in which case `database` is a local file path
+(not a database name) and `host`/`port`/`user` don't apply. See the [Config file chapter of the manual](https://orapli.github.io/erdscope/manual.html#config-file) for the full key
 list and semantics, and [`erdscope.example.yml`](erdscope.example.yml) for a fully
 annotated sample based on the live demo's schema.
 
@@ -275,6 +293,45 @@ pip install playwright && playwright install chromium
 python3 -m unittest tests.test_e2e -v
 ```
 
+## Performance
+
+Measured against synthetic SQLite schemas (`benchmarks/gen_schema.py`, ~2 FK edges per
+table) at three sizes:
+
+| Tables | Edges | CLI gen (median) | HTML size | Initial paint (median) | Re-layout (median) | Python RSS | JS heap |
+|---|---|---|---|---|---|---|---|
+| 100   | 190   | 0.05 s | 292 KB  | 91 ms  | 37 ms  | 37 MB | 2.0 MB |
+| 300   | 592   | 0.06 s | 533 KB  | 206 ms | 131 ms | 42 MB | 1.9 MB |
+| 1,000 | 2,015 | 0.11 s | 1.35 MB | 1.18 s | 1.04 s | 59 MB | 3.2 MB |
+
+Notes: measured in a sandboxed Linux environment against headless Chromium
+(Playwright), not dedicated hardware — treat these as relative/order-of-magnitude
+numbers rather than absolute guarantees for your machine. "CLI gen" and the browser
+timings are each the median of 3 runs; Python RSS/JS heap are single best-effort
+samples. Generation itself (`erd.py sqlite:///... -o out.html`) stays fast at every
+size tested — SQLite parsing isn't the bottleneck.
+
+**Recommendation:** the constraint at scale is the browser-side interactive
+re-layout, not generation. Linear interpolation between the 300- and 1,000-table
+measurements above puts the 1-second crossing at roughly 970 tables; we round that
+down to **~900 tables** as a deliberately conservative rule of thumb, since these
+are single-environment numbers (initial paint itself stays comfortably under 3
+seconds through 1,000 tables). Past that rough threshold, narrow the diagram with
+`--only`/`--exclude` instead of
+rendering the whole schema at once — see the [manual's Large
+schemas section](https://orapli.github.io/erdscope/manual.html#large-schemas) for
+details.
+
+Reproduce or re-run at other sizes with:
+
+```bash
+python3 benchmarks/gen_schema.py --tables 300 --out /tmp/bench_300.db
+python3 benchmarks/run_bench.py --tables 100,300,1000   # generates, benchmarks, prints JSON + a summary table
+```
+
+`run_bench.py` is a manual script (not part of the `unittest` suite) — see its
+docstring for the full methodology and the Playwright venv it expects.
+
 ## Extending
 
 Everything downstream (UI, layouts, exports) consumes the intermediate representation

erdscope-0.3.0/erdscope.egg-info/PKG-INFO → erdscope-0.4.0/README.md

@@ -1,37 +1,3 @@
-Metadata-Version: 2.4
-Name: erdscope
-Version: 0.3.0
-Summary: Interactive, self-contained ER-diagram HTML and Excel table definitions from a live MySQL or PostgreSQL database — single file, zero required dependencies
-Author: tas6
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/orapli/erdscope
-Project-URL: Documentation, https://orapli.github.io/erdscope/manual.html
-Project-URL: Live demo, https://orapli.github.io/erdscope/
-Project-URL: Repository, https://github.com/orapli/erdscope
-Project-URL: Issues, https://github.com/orapli/erdscope/issues
-Keywords: erd,er-diagram,database,schema,mysql,rails,prisma,django,documentation
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Database
-Classifier: Topic :: Documentation
-Classifier: Topic :: Software Development :: Documentation
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: mysql
-Requires-Dist: PyMySQL; extra == "mysql"
-Provides-Extra: postgres
-Requires-Dist: psycopg[binary]; extra == "postgres"
-Provides-Extra: yaml
-Requires-Dist: PyYAML; extra == "yaml"
-Provides-Extra: all
-Requires-Dist: PyMySQL; extra == "all"
-Requires-Dist: psycopg[binary]; extra == "all"
-Requires-Dist: PyYAML; extra == "all"
-Dynamic: license-file
-
 # erdscope
 
 [![CI](https://github.com/orapli/erdscope/actions/workflows/ci.yml/badge.svg)](https://github.com/orapli/erdscope/actions/workflows/ci.yml)
@@ -43,6 +9,8 @@ zero-dependency Python CLI.
 
 ```bash
 pip install erdscope
+erdscope demo   # no database of your own? try it right now — opens a sample diagram
+
 erdscope mysql://readonly@127.0.0.1:3306/myapp_production -o erd.html
 erdscope postgres://readonly@127.0.0.1:5432/myapp_production -o erd.html
 erdscope sqlite:///path/to/app.db -o erd.html
@@ -87,6 +55,18 @@ curl -O https://raw.githubusercontent.com/orapli/erdscope/main/erd.py
 python3 erd.py ...   # identical to the erdscope command below
 ```
 
+No database of your own to point it at yet? `erdscope demo` builds a small sample
+e-commerce SQLite database in a temp directory, generates the diagram, and opens it in
+your browser — nothing to download or set up:
+
+```bash
+erdscope demo
+```
+
+It's a normal run under the hood, so every other flag still applies
+(`erdscope demo --excel defs.xlsx`, `erdscope demo --only 'order*'`, ...); add
+`--no-open` to skip launching the browser.
+
 ```bash
 erdscope mysql://readonly@127.0.0.1:3306/myapp_production -o erd.html
 
@@ -114,9 +94,10 @@ erdscope --config schema.yml -o erd.html
 erdscope --models /path/to/rails/app --models /path/to/schema.prisma -o erd.html
 ```
 
-Want to try it right now with no database of your own? A ready-to-run SQLite
-sample ships in [`examples/`](examples/) — `python3 erd.py
-sqlite:///examples/demo_shop.db -o shop.html`. See [examples/README.md](examples/README.md).
+Cloned the repository instead of installing from PyPI? A ready-to-run SQLite sample
+(the same schema `erdscope demo` uses) also ships committed in
+[`examples/`](examples/) — `python3 erd.py sqlite:///examples/demo_shop.db -o shop.html`.
+See [examples/README.md](examples/README.md).
 
 Behind a bastion? Open an SSH tunnel first and point at localhost:
 
@@ -134,7 +115,8 @@ itself is made.
 
 | Option | Description |
 |---|---|
-| `-o FILE` | Output HTML path (default: `erd.html`) |
+| `demo` | Positional value: generate from a bundled sample database instead of a real one — no database of your own needed. Every other flag below still applies |
+| `-o FILE` | Output HTML path (default: `erd.html`; `erd_demo.html` for `demo`, so it never overwrites a real run's output) |
 | `--models PATH` | Merge associations parsed from code: a Rails project (or `app/models` dir), a `schema.prisma`, or a Django project — auto-detected. **Repeatable** — multiple sources merge in the order given (later wins). Usable with no database URL |
 | `--excel FILE.xlsx` | Also write a table-definition workbook: an overview sheet plus one sheet per table (columns, defaults, keys, comments, indexes, associations) |
 | `--excel-template FILE.xlsx` | Override the workbook's colors/fonts/borders from a template `.xlsx` — see `excel-template.xlsx` and its `Styles` sheet for the 5-cell contract (default: built-in styling) |
@@ -145,6 +127,7 @@ itself is made.
 | `--table-map 'Widget=crm_widgets'` | Rails only: override a model's table when static analysis can't determine it (e.g. `table_name` set inside a concern that lives in a gem, not the app). Repeatable; comma-separated lists accepted |
 | `--config PATH` | Load defaults from a config file instead of repeating flags — see below. Auto-discovered as `.erdscope.json`/`.yml`/`.yaml` in the current directory if not given |
 | `--no-config` | Skip config auto-discovery even if `.erdscope.*` exists in the cwd |
+| `--no-open` | Skip automatically opening a browser after generating. Only relevant to `demo` (which opens one by default); accepted but has no effect on a normal run |
 
 ## Config file
 
@@ -153,7 +136,8 @@ Once the flag list above gets long, put it in a config file instead — `.erdsco
 Most keys mirror a CLI option (an explicit flag always wins over the config); the DB
 connection is config-only as `engine`/`host`/`port`/`user`/`database` — deliberately with
 no password field — and `relations` manually declares relations no FK, code, or inference
-can find. See the [Config file chapter of the manual](https://orapli.github.io/erdscope/manual.html#config-file) for the full key
+can find. `engine` can also be `"sqlite"`, in which case `database` is a local file path
+(not a database name) and `host`/`port`/`user` don't apply. See the [Config file chapter of the manual](https://orapli.github.io/erdscope/manual.html#config-file) for the full key
 list and semantics, and [`erdscope.example.yml`](erdscope.example.yml) for a fully
 annotated sample based on the live demo's schema.
 
@@ -275,6 +259,45 @@ pip install playwright && playwright install chromium
 python3 -m unittest tests.test_e2e -v
 ```
 
+## Performance
+
+Measured against synthetic SQLite schemas (`benchmarks/gen_schema.py`, ~2 FK edges per
+table) at three sizes:
+
+| Tables | Edges | CLI gen (median) | HTML size | Initial paint (median) | Re-layout (median) | Python RSS | JS heap |
+|---|---|---|---|---|---|---|---|
+| 100   | 190   | 0.05 s | 292 KB  | 91 ms  | 37 ms  | 37 MB | 2.0 MB |
+| 300   | 592   | 0.06 s | 533 KB  | 206 ms | 131 ms | 42 MB | 1.9 MB |
+| 1,000 | 2,015 | 0.11 s | 1.35 MB | 1.18 s | 1.04 s | 59 MB | 3.2 MB |
+
+Notes: measured in a sandboxed Linux environment against headless Chromium
+(Playwright), not dedicated hardware — treat these as relative/order-of-magnitude
+numbers rather than absolute guarantees for your machine. "CLI gen" and the browser
+timings are each the median of 3 runs; Python RSS/JS heap are single best-effort
+samples. Generation itself (`erd.py sqlite:///... -o out.html`) stays fast at every
+size tested — SQLite parsing isn't the bottleneck.
+
+**Recommendation:** the constraint at scale is the browser-side interactive
+re-layout, not generation. Linear interpolation between the 300- and 1,000-table
+measurements above puts the 1-second crossing at roughly 970 tables; we round that
+down to **~900 tables** as a deliberately conservative rule of thumb, since these
+are single-environment numbers (initial paint itself stays comfortably under 3
+seconds through 1,000 tables). Past that rough threshold, narrow the diagram with
+`--only`/`--exclude` instead of
+rendering the whole schema at once — see the [manual's Large
+schemas section](https://orapli.github.io/erdscope/manual.html#large-schemas) for
+details.
+
+Reproduce or re-run at other sizes with:
+
+```bash
+python3 benchmarks/gen_schema.py --tables 300 --out /tmp/bench_300.db
+python3 benchmarks/run_bench.py --tables 100,300,1000   # generates, benchmarks, prints JSON + a summary table
+```
+
+`run_bench.py` is a manual script (not part of the `unittest` suite) — see its
+docstring for the full methodology and the Playwright venv it expects.
+
 ## Extending
 
 Everything downstream (UI, layouts, exports) consumes the intermediate representation