erdscope 0.5.0__tar.gz → 0.6.0__tar.gz

{erdscope-0.5.0/erdscope.egg-info → erdscope-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: erdscope
-Version: 0.5.0
+Version: 0.6.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
@@ -37,9 +37,15 @@ Dynamic: license-file
 [![CI](https://github.com/orapli/erdscope/actions/workflows/ci.yml/badge.svg)](https://github.com/orapli/erdscope/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/erdscope)](https://pypi.org/project/erdscope/)
 
-Generate a **self-contained, interactive ER diagram** — and an **Excel table-definition
+**Interactive ER diagrams and documented schema definitions.** Generate a
+**self-contained, interactive ER diagram** — and an **Excel table-definition
 workbook** — from a live MySQL, PostgreSQL, or SQLite database, with a single-file,
-zero-dependency Python CLI.
+zero-dependency Python CLI. Turn an ER diagram into a documented schema: attach design
+decisions, operational rules, and ADR links to tables and relationships with config
+[`notes:`](#notes-attach-design-decisions-to-the-diagram) — plain text and http(s) links
+only, validated against the real schema so a note can never point at something that
+doesn't exist — and draw a rounded, titled frame around a set of related tables with config
+[`groups:`](#groups-draw-a-frame-around-related-tables).
 
 ```bash
 pip install erdscope
@@ -248,6 +254,12 @@ sources:
 (The optional top-level `version: 1` is a config-format marker — currently the only
 supported value, with no other effect; it's for future config-format changes to key off.)
 
+A typed source that parses **nothing** — say, a Prisma project accidentally declared as
+`rails.models` — is a hard error naming the source id and the layout the type expected,
+never a silently empty diagram. If an empty result is genuinely intended (a scaffolded
+but still-empty `app/models`, for example), opt in per source with `allow_empty: true`;
+a `rails.project` entry passes the flag down to both of its expanded halves.
+
 A **`rails.project`** entry is a macro for a whole Rails app root: it expands to both the
 `rails.schema` (`<root>/db/schema.rb`) and `rails.models` (`<root>/app/models`) halves,
 whichever exist —
@@ -267,6 +279,91 @@ closer to the real database than code is, but a live DB read still wins when bot
 present. See the [Input sources chapter of the manual](https://orapli.github.io/erdscope/manual.html#input-sources)
 for the full `sources[]` reference.
 
+### Notes: attach design decisions to the diagram
+
+Config **`notes:`** attaches short, plain-text write-ups — design decisions, operational
+rules, ADR links — to a table, a specific relation, or the whole diagram. Notes never
+touch the schema itself (no effect on columns, associations, or merge precedence); they're
+a read-only sidecar validated against the final merged schema and rendered next to it:
+
+```yaml
+notes:
+  - id: user-retention
+    target: { type: table, table: users }
+    title: Retention policy
+    text: Suspended accounts are kept for 1 year, then anonymized.
+    links:
+      - { label: ADR-004, url: https://example.com/adr/004 }
+
+  - id: order-ownership
+    target: { type: relation, source_table: orders, target_table: users, foreign_key: user_id }
+    text: Orders are kept after a user is anonymized (financial record-keeping).
+
+  - id: diagram-conventions
+    target: { type: global }
+    title: How to read this diagram
+    text: The dotted amber edge is an inferred relation, not a real FK.
+```
+
+- Every note needs a config-unique `id` and non-empty `text`; `title` and `links` are
+  optional. Link `url`s must be `http://` or `https://` — anything else (`javascript:`,
+  `data:`, a bare string) is rejected at load time.
+- `target.type` is `table`, `relation`, or `global`. A `relation` note is identified by
+  `source_table` (the side that **holds** the association — the `belongs_to`/FK-holding
+  side for a `belongs_to`, the owning side for a `has_many`) and `target_table`;
+  `foreign_key`/`name`/`assoc_type`/`through`/`polymorphic` are optional narrowing keys for
+  when a table has more than one relation to the same target (`assoc_type` is the
+  association kind — `has_many`/`belongs_to`/`has_one`/`has_and_belongs_to_many` — which
+  tells apart, say, a `has_many` and a `has_one` that share a name and target). A note that
+  matches no relation, or more than one, is a hard error naming the note's `id` — never a
+  silent guess.
+- Validation runs **twice**, like `tables:` above: syntax at load time, then semantically
+  against the schema that results **after** DB/`--models`/config `tables:` are all merged
+  — so a note can reference a table or relation that config itself adds, and a note on
+  something config *removes* is correctly an error.
+- Rendered as plain, HTML-escaped text only — no Markdown, no raw HTML, no scripts — in
+  the table's detail panel, next to the matching relation, or in the diagram's legend for
+  a `global` note. Notes are also searchable (title, text, link labels). A note whose
+  table is hidden from the current view simply doesn't appear in the (now absent) detail
+  panel; a `global` note's legend entry is unaffected.
+- `write_excel` accepts the same notes but doesn't use them yet in this release — an Excel
+  Notes sheet is a possible future addition, not implemented today.
+
+See the [Notes chapter of the manual](https://orapli.github.io/erdscope/manual.html#notes)
+for the full reference.
+
+### Groups: draw a frame around related tables
+
+Config **`groups:`** draws a rounded frame with a title around a set of related tables in
+the diagram — a lightweight way to call out a domain ("Billing", "Orders") without changing
+the schema or the layout. Like `notes:`, it's a read-only sidecar validated against the
+final merged schema:
+
+```yaml
+groups:
+  - id: billing
+    title: Billing
+    tables: [invoices, payments, coupons]
+    color: "#0d9488"
+
+  - id: catalog
+    tables: [products, categories, product_categories]
+```
+
+- Every group needs a config-unique `id` and non-empty `tables`; `title` (defaults to `id`)
+  and `color` (a hex string, e.g. `#0d9488`) are optional.
+- A table may belong to **at most one** group — claiming the same table from two groups is
+  a hard error naming both group `id`s and the table, not a silently-picked winner. There's
+  no support for overlapping/nested groups in this release.
+- Validation runs twice, like `notes:`/`tables:` above: syntax at load time, then
+  semantically against the final merged schema, so a group can reference a table config
+  itself adds, and a group naming something config *removes* is correctly an error.
+- Purely visual: groups never affect layout, merge precedence, or associations — the frame
+  is drawn around wherever its member tables already ended up. In the viewer, drag a
+  group's title to move every member together; a "Groups" toolbar toggle shows/hides the
+  frames, and both PNG and SVG exports include them. `--only`/`--exclude` narrow a group's
+  membership down to the surviving tables, dropping the group entirely if none remain.
+
 ## Dependencies
 
 `erd.py` runs with **zero required dependencies** — everything below is optional, and
@@ -292,6 +389,24 @@ Test-only, and only if you run that particular suite:
 | [openpyxl](https://pypi.org/project/openpyxl/) | Roundtrip-verifying `--excel` output in the unit tests (`tests/test_erd.py`); that one test skips itself if it's missing |
 | [Playwright](https://playwright.dev/python/) | The browser E2E suite (`tests/test_e2e.py`) — see [Tests](#tests) below |
 
+## Verified versions
+
+The input formats erdscope parses change rarely, so exact versions matter less than
+they might seem — newer releases are expected to keep working, though constructs
+beyond the tested ones may be ignored rather than parsed. For the record, this is what
+each input is actually verified against:
+
+| Input | Verified against |
+|---|---|
+| MySQL | **8.4** — real-server integration tests in CI (`information_schema`); developed against 8.x |
+| PostgreSQL | **16** — real-server integration tests in CI (`pg_catalog`/`information_schema`) |
+| SQLite | the `sqlite3` module bundled with CPython (any supported 3.x) |
+| Rails `schema.rb` | the format Rails **7.x / 8.x** writes (`ActiveRecord::Schema[7.x]`, and the classic un-versioned header) |
+| Rails models | the association DSL as of Rails **7.x** — `has_many`/`has_one`/`belongs_to`/`has_and_belongs_to_many`, `through:`, `polymorphic:`, STI, concerns, custom base classes; also exercised against Mastodon's real codebase. Dynamically computed definitions (and `structure.sql`) are out of scope |
+| Prisma | the schema language as of Prisma **5 / 6** — `@map`/`@@map`, enums, named relations, implicit and explicit m2m, self-relations, composite `@@id`/`@@unique`, `@@schema` |
+| Django | models as of Django **4.2 / 5.x** — FK / OneToOne / M2M (incl. `through=`), abstract bases, `db_table`/`db_column`, `GenericForeignKey` (kept as a polymorphic marker); a swappable `AUTH_USER_MODEL` FK keeps its column and skips the edge |
+| Python | 3.9+ (`requires-python`); CI runs the latest CPython 3.x |
+
 ## What you get
 
 Feature highlights — each link goes to the relevant [manual](https://orapli.github.io/erdscope/manual.html) chapter:
@@ -316,6 +431,12 @@ Feature highlights — each link goes to the relevant [manual](https://orapli.gi
   the live view and exports
 - **Extras** — a built-in `?` shortcuts/help popup, dark mode, print stylesheet,
   resizable/collapsible panes
+- **[Notes](#notes-attach-design-decisions-to-the-diagram)** — attach design decisions,
+  operational rules, and ADR links to a table, a relation, or the whole diagram, validated
+  against the real schema and searchable alongside tables/columns
+- **[Groups](#groups-draw-a-frame-around-related-tables)** — draw a rounded, titled frame
+  around a set of related tables to call out a domain, purely visual, draggable by its
+  title, with its own toolbar toggle and export support
 
 ## Tests
 
@@ -324,7 +445,11 @@ python3 -m unittest discover -s tests -v
 ```
 
 The IR builders and the Excel writer are covered by pure unit tests; the overlay
-parsers have minimal fixtures under `tests/fixture_*`. No database is required to
+parsers have fixtures under `tests/fixture_*` — basic plus advanced constructs per
+framework — and every input provider is additionally held to one shared contract
+(`tests/test_provider_contract.py`): typed dispatch, standalone HTML/Excel generation,
+merging over a DB layer, 1:N / 1:1 / M:N / self-reference, association provenance, and
+empty-input diagnostics, all over the same small domain. No database is required to
 run the tests.
 
 `tests/test_e2e.py` drives the generated HTML's client-side JS (grid layout,

{erdscope-0.5.0 → erdscope-0.6.0}/README.md

@@ -3,9 +3,15 @@
 [![CI](https://github.com/orapli/erdscope/actions/workflows/ci.yml/badge.svg)](https://github.com/orapli/erdscope/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/erdscope)](https://pypi.org/project/erdscope/)
 
-Generate a **self-contained, interactive ER diagram** — and an **Excel table-definition
+**Interactive ER diagrams and documented schema definitions.** Generate a
+**self-contained, interactive ER diagram** — and an **Excel table-definition
 workbook** — from a live MySQL, PostgreSQL, or SQLite database, with a single-file,
-zero-dependency Python CLI.
+zero-dependency Python CLI. Turn an ER diagram into a documented schema: attach design
+decisions, operational rules, and ADR links to tables and relationships with config
+[`notes:`](#notes-attach-design-decisions-to-the-diagram) — plain text and http(s) links
+only, validated against the real schema so a note can never point at something that
+doesn't exist — and draw a rounded, titled frame around a set of related tables with config
+[`groups:`](#groups-draw-a-frame-around-related-tables).
 
 ```bash
 pip install erdscope
@@ -214,6 +220,12 @@ sources:
 (The optional top-level `version: 1` is a config-format marker — currently the only
 supported value, with no other effect; it's for future config-format changes to key off.)
 
+A typed source that parses **nothing** — say, a Prisma project accidentally declared as
+`rails.models` — is a hard error naming the source id and the layout the type expected,
+never a silently empty diagram. If an empty result is genuinely intended (a scaffolded
+but still-empty `app/models`, for example), opt in per source with `allow_empty: true`;
+a `rails.project` entry passes the flag down to both of its expanded halves.
+
 A **`rails.project`** entry is a macro for a whole Rails app root: it expands to both the
 `rails.schema` (`<root>/db/schema.rb`) and `rails.models` (`<root>/app/models`) halves,
 whichever exist —
@@ -233,6 +245,91 @@ closer to the real database than code is, but a live DB read still wins when bot
 present. See the [Input sources chapter of the manual](https://orapli.github.io/erdscope/manual.html#input-sources)
 for the full `sources[]` reference.
 
+### Notes: attach design decisions to the diagram
+
+Config **`notes:`** attaches short, plain-text write-ups — design decisions, operational
+rules, ADR links — to a table, a specific relation, or the whole diagram. Notes never
+touch the schema itself (no effect on columns, associations, or merge precedence); they're
+a read-only sidecar validated against the final merged schema and rendered next to it:
+
+```yaml
+notes:
+  - id: user-retention
+    target: { type: table, table: users }
+    title: Retention policy
+    text: Suspended accounts are kept for 1 year, then anonymized.
+    links:
+      - { label: ADR-004, url: https://example.com/adr/004 }
+
+  - id: order-ownership
+    target: { type: relation, source_table: orders, target_table: users, foreign_key: user_id }
+    text: Orders are kept after a user is anonymized (financial record-keeping).
+
+  - id: diagram-conventions
+    target: { type: global }
+    title: How to read this diagram
+    text: The dotted amber edge is an inferred relation, not a real FK.
+```
+
+- Every note needs a config-unique `id` and non-empty `text`; `title` and `links` are
+  optional. Link `url`s must be `http://` or `https://` — anything else (`javascript:`,
+  `data:`, a bare string) is rejected at load time.
+- `target.type` is `table`, `relation`, or `global`. A `relation` note is identified by
+  `source_table` (the side that **holds** the association — the `belongs_to`/FK-holding
+  side for a `belongs_to`, the owning side for a `has_many`) and `target_table`;
+  `foreign_key`/`name`/`assoc_type`/`through`/`polymorphic` are optional narrowing keys for
+  when a table has more than one relation to the same target (`assoc_type` is the
+  association kind — `has_many`/`belongs_to`/`has_one`/`has_and_belongs_to_many` — which
+  tells apart, say, a `has_many` and a `has_one` that share a name and target). A note that
+  matches no relation, or more than one, is a hard error naming the note's `id` — never a
+  silent guess.
+- Validation runs **twice**, like `tables:` above: syntax at load time, then semantically
+  against the schema that results **after** DB/`--models`/config `tables:` are all merged
+  — so a note can reference a table or relation that config itself adds, and a note on
+  something config *removes* is correctly an error.
+- Rendered as plain, HTML-escaped text only — no Markdown, no raw HTML, no scripts — in
+  the table's detail panel, next to the matching relation, or in the diagram's legend for
+  a `global` note. Notes are also searchable (title, text, link labels). A note whose
+  table is hidden from the current view simply doesn't appear in the (now absent) detail
+  panel; a `global` note's legend entry is unaffected.
+- `write_excel` accepts the same notes but doesn't use them yet in this release — an Excel
+  Notes sheet is a possible future addition, not implemented today.
+
+See the [Notes chapter of the manual](https://orapli.github.io/erdscope/manual.html#notes)
+for the full reference.
+
+### Groups: draw a frame around related tables
+
+Config **`groups:`** draws a rounded frame with a title around a set of related tables in
+the diagram — a lightweight way to call out a domain ("Billing", "Orders") without changing
+the schema or the layout. Like `notes:`, it's a read-only sidecar validated against the
+final merged schema:
+
+```yaml
+groups:
+  - id: billing
+    title: Billing
+    tables: [invoices, payments, coupons]
+    color: "#0d9488"
+
+  - id: catalog
+    tables: [products, categories, product_categories]
+```
+
+- Every group needs a config-unique `id` and non-empty `tables`; `title` (defaults to `id`)
+  and `color` (a hex string, e.g. `#0d9488`) are optional.
+- A table may belong to **at most one** group — claiming the same table from two groups is
+  a hard error naming both group `id`s and the table, not a silently-picked winner. There's
+  no support for overlapping/nested groups in this release.
+- Validation runs twice, like `notes:`/`tables:` above: syntax at load time, then
+  semantically against the final merged schema, so a group can reference a table config
+  itself adds, and a group naming something config *removes* is correctly an error.
+- Purely visual: groups never affect layout, merge precedence, or associations — the frame
+  is drawn around wherever its member tables already ended up. In the viewer, drag a
+  group's title to move every member together; a "Groups" toolbar toggle shows/hides the
+  frames, and both PNG and SVG exports include them. `--only`/`--exclude` narrow a group's
+  membership down to the surviving tables, dropping the group entirely if none remain.
+
 ## Dependencies
 
 `erd.py` runs with **zero required dependencies** — everything below is optional, and
@@ -258,6 +355,24 @@ Test-only, and only if you run that particular suite:
 | [openpyxl](https://pypi.org/project/openpyxl/) | Roundtrip-verifying `--excel` output in the unit tests (`tests/test_erd.py`); that one test skips itself if it's missing |
 | [Playwright](https://playwright.dev/python/) | The browser E2E suite (`tests/test_e2e.py`) — see [Tests](#tests) below |
 
+## Verified versions
+
+The input formats erdscope parses change rarely, so exact versions matter less than
+they might seem — newer releases are expected to keep working, though constructs
+beyond the tested ones may be ignored rather than parsed. For the record, this is what
+each input is actually verified against:
+
+| Input | Verified against |
+|---|---|
+| MySQL | **8.4** — real-server integration tests in CI (`information_schema`); developed against 8.x |
+| PostgreSQL | **16** — real-server integration tests in CI (`pg_catalog`/`information_schema`) |
+| SQLite | the `sqlite3` module bundled with CPython (any supported 3.x) |
+| Rails `schema.rb` | the format Rails **7.x / 8.x** writes (`ActiveRecord::Schema[7.x]`, and the classic un-versioned header) |
+| Rails models | the association DSL as of Rails **7.x** — `has_many`/`has_one`/`belongs_to`/`has_and_belongs_to_many`, `through:`, `polymorphic:`, STI, concerns, custom base classes; also exercised against Mastodon's real codebase. Dynamically computed definitions (and `structure.sql`) are out of scope |
+| Prisma | the schema language as of Prisma **5 / 6** — `@map`/`@@map`, enums, named relations, implicit and explicit m2m, self-relations, composite `@@id`/`@@unique`, `@@schema` |
+| Django | models as of Django **4.2 / 5.x** — FK / OneToOne / M2M (incl. `through=`), abstract bases, `db_table`/`db_column`, `GenericForeignKey` (kept as a polymorphic marker); a swappable `AUTH_USER_MODEL` FK keeps its column and skips the edge |
+| Python | 3.9+ (`requires-python`); CI runs the latest CPython 3.x |
+
 ## What you get
 
 Feature highlights — each link goes to the relevant [manual](https://orapli.github.io/erdscope/manual.html) chapter:
@@ -282,6 +397,12 @@ Feature highlights — each link goes to the relevant [manual](https://orapli.gi
   the live view and exports
 - **Extras** — a built-in `?` shortcuts/help popup, dark mode, print stylesheet,
   resizable/collapsible panes
+- **[Notes](#notes-attach-design-decisions-to-the-diagram)** — attach design decisions,
+  operational rules, and ADR links to a table, a relation, or the whole diagram, validated
+  against the real schema and searchable alongside tables/columns
+- **[Groups](#groups-draw-a-frame-around-related-tables)** — draw a rounded, titled frame
+  around a set of related tables to call out a domain, purely visual, draggable by its
+  title, with its own toolbar toggle and export support
 
 ## Tests
 
@@ -290,7 +411,11 @@ python3 -m unittest discover -s tests -v
 ```
 
 The IR builders and the Excel writer are covered by pure unit tests; the overlay
-parsers have minimal fixtures under `tests/fixture_*`. No database is required to
+parsers have fixtures under `tests/fixture_*` — basic plus advanced constructs per
+framework — and every input provider is additionally held to one shared contract
+(`tests/test_provider_contract.py`): typed dispatch, standalone HTML/Excel generation,
+merging over a DB layer, 1:N / 1:1 / M:N / self-reference, association provenance, and
+empty-input diagnostics, all over the same small domain. No database is required to
 run the tests.
 
 `tests/test_e2e.py` drives the generated HTML's client-side JS (grid layout,