erdscope 0.6.0__tar.gz → 0.7.0__tar.gz

erdscope-0.7.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: erdscope
+Version: 0.7.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
+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,postgresql,postgres,sqlite,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
+
+<div align="center">
+  <img src="docs/img/erdscope-banner.svg" alt="erdscope — explore the schema you have" width="100%">
+
+  **Database, application code, or config — turn whatever you have into one explorable schema.**
+
+  [![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/)
+  [![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB)](https://pypi.org/project/erdscope/)
+  [![License](https://img.shields.io/badge/license-MIT-14B8A6)](LICENSE)
+
+  [Live demo](https://orapli.github.io/erdscope/) · [User manual](https://orapli.github.io/erdscope/manual.html) · [日本語マニュアル](https://orapli.github.io/erdscope/manual.ja.html)
+</div>
+
+erdscope generates a **self-contained, interactive ER diagram** and, when you want it,
+an **Excel table-definition workbook**. Start with a database, model code, a config file,
+or any combination of them. The result is one portable HTML file you can explore, share,
+and keep with your project.
+
+```bash
+pip install erdscope
+erdscope demo
+```
+
+That is the whole quickstart. A sample shop diagram opens in your browser—no database,
+account, or project setup required.
+
+[![Interactive diagram generated by erdscope](docs/screenshot.png)](https://orapli.github.io/erdscope/)
+
+## Bring whatever schema you have
+
+<div align="center">
+  <img src="docs/img/input-flow.svg" alt="Database, application code, and config merge into an interactive ER diagram and Excel workbook" width="880">
+</div>
+
+| Start from | What erdscope reads | Good for |
+|---|---|---|
+| **A database** | MySQL, PostgreSQL, or SQLite catalogs | Exploring the schema that is actually deployed |
+| **Application code** | Rails, Prisma, or Django projects | Reviewing a project without database access |
+| **Config** | JSON or YAML source declarations, tables, relations, notes, and groups | Reusing settings, designing a schema, or adding documentation |
+
+Use just one source, or combine them. Physical database facts, application-level
+associations, and your explicit documentation are merged into one consistent view.
+
+The examples below use CLI arguments when that makes the input obvious. For repeatable
+usage, put the same settings and model sources in `.erdscope.json`, `.erdscope.yml`, or
+another file selected with `--config`. A config can also define a complete schema by
+itself. Explicit CLI arguments override the corresponding config values.
+
+## Pick your starting point
+
+### Explore a live database
+
+```bash
+erdscope postgres://readonly@127.0.0.1:5432/myapp -o schema.html
+```
+
+MySQL uses the same shape. SQLite needs no driver and works with Python's standard library:
+
+```bash
+erdscope sqlite:///path/to/app.db -o schema.html
+```
+
+### Review application models without a database
+
+```bash
+# Rails, Prisma, or Django project — auto-detected
+erdscope --models ./my-app -o schema.html
+```
+
+### Sketch or document a schema from config alone
+
+```bash
+erdscope --config examples/schema-only.json -o schema.html
+```
+
+[`examples/schema-only.json`](examples/schema-only.json) is a complete, zero-database
+example with tables, relations, notes, and a domain group. Config can also patch or remove
+items supplied by another source. See the [config guide](https://orapli.github.io/erdscope/manual.html#config-file).
+
+### Combine database facts, application context, and documentation
+
+```bash
+erdscope mysql://readonly@127.0.0.1:3306/myapp \
+  --config .erdscope.yml \
+  -o schema.html
+```
+
+```yaml
+# .erdscope.yml
+models:
+  - ./app/models
+groups:
+  - { id: sales, title: Sales, tables: [orders, order_items] }
+notes:
+  - id: order-retention
+    target: { type: table, table: orders }
+    text: Orders are retained for seven years after account closure.
+```
+
+This is where the layered input model shines: use the database for columns and real
+foreign keys, code for associations such as polymorphic or through relations, and config
+for corrections, domain groups, operational notes, and ADR links.
+
+### Hand off both a diagram and table definitions
+
+```bash
+erdscope sqlite:///path/to/app.db \
+  -o schema.html \
+  --excel table-definitions.xlsx
+```
+
+The HTML is self-contained and the workbook can be styled with an Excel template—useful
+for reviews, audits, onboarding, and documentation deliverables.
+
+## What you can do in the viewer
+
+- Search tables, columns, comments, and attached notes.
+- Focus on dependencies or dependents and control traversal depth.
+- Hide tables, rearrange the layout, and move domain groups together.
+- Inspect DB FKs, schema FKs, declared associations, and inferred relations.
+- Save named views and share a link to the current view.
+- Export the current canvas as PNG or SVG, or print it cleanly.
+- Switch to dark mode; everything runs locally in the generated HTML.
+
+Try these interactions in the **[live demo](https://orapli.github.io/erdscope/)**, or use
+the illustrated **[viewer guide](https://orapli.github.io/erdscope/manual.html#viewer-guide)**.
+
+## Installation
+
+```bash
+pip install erdscope
+```
+
+The core CLI, SQLite reader, HTML generator, and Excel writer use only the Python standard
+library. Install an optional driver when you want a direct server connection:
+
+```bash
+pip install 'erdscope[mysql]'     # PyMySQL
+pip install 'erdscope[postgres]'  # psycopg
+pip install 'erdscope[yaml]'      # PyYAML for .yml/.yaml config
+pip install 'erdscope[all]'
+```
+
+Prefer a single file? Download [`erd.py`](erd.py) and run it with Python 3.9+:
+
+```bash
+python3 erd.py demo
+```
+
+## Config and CLI overrides
+
+Config is the convenient home for recurring inputs and settings. It is auto-discovered
+as `.erdscope.json`, `.erdscope.yml`, or `.erdscope.yaml` in the current directory, or
+you can select a file with `--config`. When the same setting is supplied both ways, the
+explicit CLI argument wins.
+
+| Option | Purpose |
+|---|---|
+| `--config PATH` | Load model sources, defaults, schema definitions or patches, notes, and groups |
+| `--models PATH` | Override config `models` with Rails, Prisma, or Django input; repeatable |
+| `--excel FILE.xlsx` | Also generate a table-definition workbook |
+| `--emit-json FILE.json` | Also write a canonical JSON schema snapshot with a content fingerprint (`-` for stdout) |
+| `--emit-config FILE.yml\|.json` | Also write the schema as a config-authoring file, re-importable via `--config` (`-` for stdout, always JSON) |
+| `--diff SNAPSHOT.json` | Compare this run against a saved `--emit-json` snapshot and exit 0/1/2 instead of generating output (CI drift gate) |
+| `--only 'user*,order*'` | Generate only matching tables |
+| `--exclude '*_logs'` | Leave matching tables out |
+| `--infer-fk` | Add clearly marked relation guesses from `*_id` columns |
+| `--no-open` | Do not open the browser after `demo` |
+
+For every option and config key, see the **[CLI and config reference](https://orapli.github.io/erdscope/manual.html#cli-reference)**.
+
+## Supported inputs
+
+erdscope is tested against MySQL 8.4, PostgreSQL 16, CPython's bundled SQLite, Rails
+7.x/8.x projects, Prisma 5/6 schemas, and Django 4.2/5.x models. Details and parser
+boundaries are listed in the
+[compatibility guide](https://orapli.github.io/erdscope/manual.html#verified-versions).
+
+## Project resources
+
+- **[Live demo](https://orapli.github.io/erdscope/)** — explore a generated shop schema.
+- **[User manual](https://orapli.github.io/erdscope/manual.html)** — complete setup, viewer, config, export, and troubleshooting guide.
+- **[Examples](examples/)** — ready-to-run SQLite and config-only inputs.
+- **[Changelog](CHANGELOG.md)** — features and behavior by release.
+- **[Issues](https://github.com/orapli/erdscope/issues)** — bug reports and feature requests.
+
+## Development
+
+Source lives under `src/erdscope/`; the distributable `erd.py` is generated from it.
+
+```bash
+python3 -m unittest discover -s tests -v
+python3 tools/build_single_file.py --check
+```
+
+See the [engineering quickstart](openwiki/quickstart.md) before changing providers,
+merge behavior, the viewer, or generated artifacts.
+
+## License
+
+[MIT](LICENSE)

erdscope-0.7.0/README.md

@@ -0,0 +1,201 @@
+<div align="center">
+  <img src="docs/img/erdscope-banner.svg" alt="erdscope — explore the schema you have" width="100%">
+
+  **Database, application code, or config — turn whatever you have into one explorable schema.**
+
+  [![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/)
+  [![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB)](https://pypi.org/project/erdscope/)
+  [![License](https://img.shields.io/badge/license-MIT-14B8A6)](LICENSE)
+
+  [Live demo](https://orapli.github.io/erdscope/) · [User manual](https://orapli.github.io/erdscope/manual.html) · [日本語マニュアル](https://orapli.github.io/erdscope/manual.ja.html)
+</div>
+
+erdscope generates a **self-contained, interactive ER diagram** and, when you want it,
+an **Excel table-definition workbook**. Start with a database, model code, a config file,
+or any combination of them. The result is one portable HTML file you can explore, share,
+and keep with your project.
+
+```bash
+pip install erdscope
+erdscope demo
+```
+
+That is the whole quickstart. A sample shop diagram opens in your browser—no database,
+account, or project setup required.
+
+[![Interactive diagram generated by erdscope](docs/screenshot.png)](https://orapli.github.io/erdscope/)
+
+## Bring whatever schema you have
+
+<div align="center">
+  <img src="docs/img/input-flow.svg" alt="Database, application code, and config merge into an interactive ER diagram and Excel workbook" width="880">
+</div>
+
+| Start from | What erdscope reads | Good for |
+|---|---|---|
+| **A database** | MySQL, PostgreSQL, or SQLite catalogs | Exploring the schema that is actually deployed |
+| **Application code** | Rails, Prisma, or Django projects | Reviewing a project without database access |
+| **Config** | JSON or YAML source declarations, tables, relations, notes, and groups | Reusing settings, designing a schema, or adding documentation |
+
+Use just one source, or combine them. Physical database facts, application-level
+associations, and your explicit documentation are merged into one consistent view.
+
+The examples below use CLI arguments when that makes the input obvious. For repeatable
+usage, put the same settings and model sources in `.erdscope.json`, `.erdscope.yml`, or
+another file selected with `--config`. A config can also define a complete schema by
+itself. Explicit CLI arguments override the corresponding config values.
+
+## Pick your starting point
+
+### Explore a live database
+
+```bash
+erdscope postgres://readonly@127.0.0.1:5432/myapp -o schema.html
+```
+
+MySQL uses the same shape. SQLite needs no driver and works with Python's standard library:
+
+```bash
+erdscope sqlite:///path/to/app.db -o schema.html
+```
+
+### Review application models without a database
+
+```bash
+# Rails, Prisma, or Django project — auto-detected
+erdscope --models ./my-app -o schema.html
+```
+
+### Sketch or document a schema from config alone
+
+```bash
+erdscope --config examples/schema-only.json -o schema.html
+```
+
+[`examples/schema-only.json`](examples/schema-only.json) is a complete, zero-database
+example with tables, relations, notes, and a domain group. Config can also patch or remove
+items supplied by another source. See the [config guide](https://orapli.github.io/erdscope/manual.html#config-file).
+
+### Combine database facts, application context, and documentation
+
+```bash
+erdscope mysql://readonly@127.0.0.1:3306/myapp \
+  --config .erdscope.yml \
+  -o schema.html
+```
+
+```yaml
+# .erdscope.yml
+models:
+  - ./app/models
+groups:
+  - { id: sales, title: Sales, tables: [orders, order_items] }
+notes:
+  - id: order-retention
+    target: { type: table, table: orders }
+    text: Orders are retained for seven years after account closure.
+```
+
+This is where the layered input model shines: use the database for columns and real
+foreign keys, code for associations such as polymorphic or through relations, and config
+for corrections, domain groups, operational notes, and ADR links.
+
+### Hand off both a diagram and table definitions
+
+```bash
+erdscope sqlite:///path/to/app.db \
+  -o schema.html \
+  --excel table-definitions.xlsx
+```
+
+The HTML is self-contained and the workbook can be styled with an Excel template—useful
+for reviews, audits, onboarding, and documentation deliverables.
+
+## What you can do in the viewer
+
+- Search tables, columns, comments, and attached notes.
+- Focus on dependencies or dependents and control traversal depth.
+- Hide tables, rearrange the layout, and move domain groups together.
+- Inspect DB FKs, schema FKs, declared associations, and inferred relations.
+- Save named views and share a link to the current view.
+- Export the current canvas as PNG or SVG, or print it cleanly.
+- Switch to dark mode; everything runs locally in the generated HTML.
+
+Try these interactions in the **[live demo](https://orapli.github.io/erdscope/)**, or use
+the illustrated **[viewer guide](https://orapli.github.io/erdscope/manual.html#viewer-guide)**.
+
+## Installation
+
+```bash
+pip install erdscope
+```
+
+The core CLI, SQLite reader, HTML generator, and Excel writer use only the Python standard
+library. Install an optional driver when you want a direct server connection:
+
+```bash
+pip install 'erdscope[mysql]'     # PyMySQL
+pip install 'erdscope[postgres]'  # psycopg
+pip install 'erdscope[yaml]'      # PyYAML for .yml/.yaml config
+pip install 'erdscope[all]'
+```
+
+Prefer a single file? Download [`erd.py`](erd.py) and run it with Python 3.9+:
+
+```bash
+python3 erd.py demo
+```
+
+## Config and CLI overrides
+
+Config is the convenient home for recurring inputs and settings. It is auto-discovered
+as `.erdscope.json`, `.erdscope.yml`, or `.erdscope.yaml` in the current directory, or
+you can select a file with `--config`. When the same setting is supplied both ways, the
+explicit CLI argument wins.
+
+| Option | Purpose |
+|---|---|
+| `--config PATH` | Load model sources, defaults, schema definitions or patches, notes, and groups |
+| `--models PATH` | Override config `models` with Rails, Prisma, or Django input; repeatable |
+| `--excel FILE.xlsx` | Also generate a table-definition workbook |
+| `--emit-json FILE.json` | Also write a canonical JSON schema snapshot with a content fingerprint (`-` for stdout) |
+| `--emit-config FILE.yml\|.json` | Also write the schema as a config-authoring file, re-importable via `--config` (`-` for stdout, always JSON) |
+| `--diff SNAPSHOT.json` | Compare this run against a saved `--emit-json` snapshot and exit 0/1/2 instead of generating output (CI drift gate) |
+| `--only 'user*,order*'` | Generate only matching tables |
+| `--exclude '*_logs'` | Leave matching tables out |
+| `--infer-fk` | Add clearly marked relation guesses from `*_id` columns |
+| `--no-open` | Do not open the browser after `demo` |
+
+For every option and config key, see the **[CLI and config reference](https://orapli.github.io/erdscope/manual.html#cli-reference)**.
+
+## Supported inputs
+
+erdscope is tested against MySQL 8.4, PostgreSQL 16, CPython's bundled SQLite, Rails
+7.x/8.x projects, Prisma 5/6 schemas, and Django 4.2/5.x models. Details and parser
+boundaries are listed in the
+[compatibility guide](https://orapli.github.io/erdscope/manual.html#verified-versions).
+
+## Project resources
+
+- **[Live demo](https://orapli.github.io/erdscope/)** — explore a generated shop schema.
+- **[User manual](https://orapli.github.io/erdscope/manual.html)** — complete setup, viewer, config, export, and troubleshooting guide.
+- **[Examples](examples/)** — ready-to-run SQLite and config-only inputs.
+- **[Changelog](CHANGELOG.md)** — features and behavior by release.
+- **[Issues](https://github.com/orapli/erdscope/issues)** — bug reports and feature requests.
+
+## Development
+
+Source lives under `src/erdscope/`; the distributable `erd.py` is generated from it.
+
+```bash
+python3 -m unittest discover -s tests -v
+python3 tools/build_single_file.py --check
+```
+
+See the [engineering quickstart](openwiki/quickstart.md) before changing providers,
+merge behavior, the viewer, or generated artifacts.
+
+## License
+
+[MIT](LICENSE)