drawio-python 0.1.0__tar.gz → 0.1.3__tar.gz

drawio_python-0.1.3/HISTORY.md

@@ -0,0 +1,26 @@
+# Unreleased
+
+- Add a standard-library XML API for documents, pages, nested containers,
+  editable shapes, port anchors and connector waypoints.
+- Load existing uncompressed/compressed diagrams and append pages while retaining
+  existing XML and metadata.
+- Render legacy Graph output to `.drawio` / `.xml` without Selenium; retain CSV,
+  text, optional PDF export and explicit browser helpers.
+- Fix graph edge identity, child registration, repeated CSV output and CSV quoting.
+- Preserve labels and circular nodes in the basic Mermaid importer; reject
+  unsupported syntax instead of silently dropping edges.
+- Add an offline CLI, native examples, tests and a Python/OS CI matrix.
+
+Changelog
+=========
+
+
+0.1.2 (2021-08-14)
+------------------
+- Fix release, README and windows CI. [Bruno Rocha]
+- Release: version 0.1.0. [Bruno Rocha]
+
+
+0.1.0 (2021-08-14)
+------------------
+- Add release command. [Bruno Rocha]

drawio_python-0.1.3/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE
+include HISTORY.md
+include Containerfile
+include README.md
+include requirements*.txt
+include mkdocs.yml
+graft examples
+graft docs
+graft tests
+graft drawio
+global-exclude __pycache__ *.py[cod]

drawio_python-0.1.3/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: drawio-python
+Version: 0.1.3
+Summary: Create editable, multi-page draw.io diagrams with native Python XML
+Home-page: https://github.com/maycuatroi1/drawio/
+Author: Nguyen Anh Binh
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-cov>=4; extra == "test"
+Requires-Dist: ruff>=0.9; extra == "test"
+Requires-Dist: build>=1; extra == "test"
+Provides-Extra: browser
+Requires-Dist: selenium>=4; extra == "browser"
+Requires-Dist: webdriver-manager>=4; extra == "browser"
+Provides-Extra: pdf
+Requires-Dist: graphviz>=0.20; extra == "pdf"
+Provides-Extra: excel
+Requires-Dist: pandas>=1.5; extra == "excel"
+Requires-Dist: xlsxwriter>=3; extra == "excel"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+# drawio-python
+
+Build editable draw.io diagrams in Python. Save XML files without Selenium,
+Chrome, an export server, or runtime dependencies. Requires Python 3.9 or newer.
+
+The native API supports multiple pages, nested containers, styled shapes,
+connector ports and waypoints. The existing `Graph` / `Node` API still works.
+
+## Install this checkout
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[test]'
+```
+
+These instructions use the updated source. The version on PyPI may differ.
+
+## Create a diagram
+
+```python
+from drawio import Document
+
+document = Document()
+page = document.add_page("Publishing", id="publishing")
+
+source = page.box("Draft", 40, 180, id="draft")
+library = page.container("Library", 500, 80, 350, 350, id="library")
+articles = page.box("Articles", 20, 70, 310, 70, parent=library)
+page.box("Images", 20, 180, 310, 70, parent=library)
+
+page.connect(
+    source, articles, "publish",
+    source_port=(1, 0.5), target_port=(0, 0.5),
+    waypoints=[(370, 225), (370, 185)],
+)
+
+document.add_page("Notes").text("A second editable tab", 40, 40)
+document.validate(check_bounds=True)
+document.save("publishing.drawio")
+```
+
+Open the file in draw.io or diagrams.net. Each block and connector remains a
+native editable object. Child coordinates are relative to the parent container;
+connector waypoints use page coordinates.
+
+`save()` refuses to replace an existing file. Pass `overwrite=True` when you
+intend to update it. File writing uses an atomic replace or exclusive creation.
+
+## Add a page to an existing file
+
+```python
+from drawio import Document
+
+document = Document.load("publishing.drawio")
+page = document.add_page("Review Details", id="review-details")
+page.box("Editorial review", 40, 80)
+document.save("publishing-v2.drawio")
+```
+
+The loader accepts uncompressed and compressed draw.io XML. It retains existing
+page IDs, cells, geometry and metadata; it expands compressed pages on output.
+It does not preserve byte-for-byte formatting, signatures or compression.
+
+## Style and labels
+
+```python
+from drawio import Document, Theme
+
+document = Document(theme=Theme(font_family="Arial", font_size=20))
+page = document.add_page("Styled")
+page.box("Plain text: A & B < C", 40, 40,
+         style={"fillColor": "#e7effb", "fontStyle": 1})
+page.box("<b>Trusted HTML</b><br/>Subtitle", 300, 40, html=True)
+```
+
+Labels default to plain text. Use `html=True` only for markup you trust. Style
+mappings use draw.io property names such as `fillColor`, `shape` and `fontSize`.
+XML escaping is handled by the writer.
+
+## CLI
+
+```sh
+python -m drawio new empty.drawio --name Overview
+python -m drawio validate publishing.drawio --check-bounds
+python -m drawio info publishing.drawio
+python -m drawio url publishing.drawio
+```
+
+The installed `drawio` command exposes the same interface. `url` prints an editor
+link containing the complete diagram. Generating the URL makes no network
+request; anyone with the link can read its embedded content.
+
+For an open editor's **Extras > Edit Diagram** dialog, use `page.to_xml()` to
+obtain that page's `mxGraphModel`. Importing through that dialog may retain the
+editor's current Grid, Page View and Background settings.
+
+## Existing Graph / Node API
+
+```python
+from drawio import Graph, Node
+
+graph = Graph(name="Review")
+a = Node("Draft", shape="rectangle", x=40, y=80)
+b = Node("Published", shape="rectangle", x=400, y=80)
+graph.add_nodes([a, b])
+a >> "approve" >> b
+
+graph.render("review.drawio", show=False)
+```
+
+`.drawio` and `.xml` rendering now uses the native writer and returns the output
+path. `Graph.render()` retains its overwrite behavior. `show=True` saves first,
+then asks the default browser to open an encoded editor URL; it no longer waits
+for console input. Tests and examples use `show=False`.
+
+Unpositioned legacy nodes use a simple grid, including disconnected graphs and
+cycles. Use `Node(x=..., y=...)` or the native `Page` API for an authored layout.
+The library does not provide automatic graph layout or SVG/PNG rendering.
+
+`to_draw_io_csv()` and `to_draw_io()` still return the legacy CSV and text forms.
+The basic Mermaid importer retains the historical import path:
+
+```python
+from drawio.itergrations.mermaid.mermaid_controller import MermaidController
+
+graph = MermaidController().load("flowchart LR; A[Draft] -->|approve| B[Published]")
+graph.render("mermaid.drawio")
+```
+
+Supported Mermaid input includes node declarations, `-->`, `-->|label|`, chained
+edges, and rectangular, circular, parenthesized and diamond node labels. Direction
+headers are accepted, but the legacy renderer uses the grid described above.
+Subgraphs, styling directives and other edge syntax raise errors rather than
+silently dropping content. This importer is not a complete Mermaid parser.
+
+## Examples and optional integrations
+
+```sh
+python examples/native_document.py
+python examples/complex-example.py
+```
+
+The first example writes `output/publishing.drawio` with two tabs and nested
+containers. The second demonstrates loading a file and adding a page.
+
+Optional extras:
+
+- `.[pdf]`: Python Graphviz binding; also install the Graphviz `dot` executable.
+- `.[browser]`: legacy Selenium helpers for callers importing `DrawIOBrowser`
+  directly. They are not part of native rendering and are not live-browser
+  tested by the default suite.
+- `.[excel]`: dependencies for the existing ERD spreadsheet exporter.
+- `.[docs]`: MkDocs.
+
+## Development
+
+```sh
+make lint
+make test
+make build
+```
+
+Tests write real XML and run examples in temporary directories. They do not
+install packages, download browser drivers, or launch Chrome. See
+[the API reference](docs/index.md) and [contribution guide](CONTRIBUTING.md).

drawio_python-0.1.3/README.md

@@ -0,0 +1,166 @@
+# drawio-python
+
+Build editable draw.io diagrams in Python. Save XML files without Selenium,
+Chrome, an export server, or runtime dependencies. Requires Python 3.9 or newer.
+
+The native API supports multiple pages, nested containers, styled shapes,
+connector ports and waypoints. The existing `Graph` / `Node` API still works.
+
+## Install this checkout
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[test]'
+```
+
+These instructions use the updated source. The version on PyPI may differ.
+
+## Create a diagram
+
+```python
+from drawio import Document
+
+document = Document()
+page = document.add_page("Publishing", id="publishing")
+
+source = page.box("Draft", 40, 180, id="draft")
+library = page.container("Library", 500, 80, 350, 350, id="library")
+articles = page.box("Articles", 20, 70, 310, 70, parent=library)
+page.box("Images", 20, 180, 310, 70, parent=library)
+
+page.connect(
+    source, articles, "publish",
+    source_port=(1, 0.5), target_port=(0, 0.5),
+    waypoints=[(370, 225), (370, 185)],
+)
+
+document.add_page("Notes").text("A second editable tab", 40, 40)
+document.validate(check_bounds=True)
+document.save("publishing.drawio")
+```
+
+Open the file in draw.io or diagrams.net. Each block and connector remains a
+native editable object. Child coordinates are relative to the parent container;
+connector waypoints use page coordinates.
+
+`save()` refuses to replace an existing file. Pass `overwrite=True` when you
+intend to update it. File writing uses an atomic replace or exclusive creation.
+
+## Add a page to an existing file
+
+```python
+from drawio import Document
+
+document = Document.load("publishing.drawio")
+page = document.add_page("Review Details", id="review-details")
+page.box("Editorial review", 40, 80)
+document.save("publishing-v2.drawio")
+```
+
+The loader accepts uncompressed and compressed draw.io XML. It retains existing
+page IDs, cells, geometry and metadata; it expands compressed pages on output.
+It does not preserve byte-for-byte formatting, signatures or compression.
+
+## Style and labels
+
+```python
+from drawio import Document, Theme
+
+document = Document(theme=Theme(font_family="Arial", font_size=20))
+page = document.add_page("Styled")
+page.box("Plain text: A & B < C", 40, 40,
+         style={"fillColor": "#e7effb", "fontStyle": 1})
+page.box("<b>Trusted HTML</b><br/>Subtitle", 300, 40, html=True)
+```
+
+Labels default to plain text. Use `html=True` only for markup you trust. Style
+mappings use draw.io property names such as `fillColor`, `shape` and `fontSize`.
+XML escaping is handled by the writer.
+
+## CLI
+
+```sh
+python -m drawio new empty.drawio --name Overview
+python -m drawio validate publishing.drawio --check-bounds
+python -m drawio info publishing.drawio
+python -m drawio url publishing.drawio
+```
+
+The installed `drawio` command exposes the same interface. `url` prints an editor
+link containing the complete diagram. Generating the URL makes no network
+request; anyone with the link can read its embedded content.
+
+For an open editor's **Extras > Edit Diagram** dialog, use `page.to_xml()` to
+obtain that page's `mxGraphModel`. Importing through that dialog may retain the
+editor's current Grid, Page View and Background settings.
+
+## Existing Graph / Node API
+
+```python
+from drawio import Graph, Node
+
+graph = Graph(name="Review")
+a = Node("Draft", shape="rectangle", x=40, y=80)
+b = Node("Published", shape="rectangle", x=400, y=80)
+graph.add_nodes([a, b])
+a >> "approve" >> b
+
+graph.render("review.drawio", show=False)
+```
+
+`.drawio` and `.xml` rendering now uses the native writer and returns the output
+path. `Graph.render()` retains its overwrite behavior. `show=True` saves first,
+then asks the default browser to open an encoded editor URL; it no longer waits
+for console input. Tests and examples use `show=False`.
+
+Unpositioned legacy nodes use a simple grid, including disconnected graphs and
+cycles. Use `Node(x=..., y=...)` or the native `Page` API for an authored layout.
+The library does not provide automatic graph layout or SVG/PNG rendering.
+
+`to_draw_io_csv()` and `to_draw_io()` still return the legacy CSV and text forms.
+The basic Mermaid importer retains the historical import path:
+
+```python
+from drawio.itergrations.mermaid.mermaid_controller import MermaidController
+
+graph = MermaidController().load("flowchart LR; A[Draft] -->|approve| B[Published]")
+graph.render("mermaid.drawio")
+```
+
+Supported Mermaid input includes node declarations, `-->`, `-->|label|`, chained
+edges, and rectangular, circular, parenthesized and diamond node labels. Direction
+headers are accepted, but the legacy renderer uses the grid described above.
+Subgraphs, styling directives and other edge syntax raise errors rather than
+silently dropping content. This importer is not a complete Mermaid parser.
+
+## Examples and optional integrations
+
+```sh
+python examples/native_document.py
+python examples/complex-example.py
+```
+
+The first example writes `output/publishing.drawio` with two tabs and nested
+containers. The second demonstrates loading a file and adding a page.
+
+Optional extras:
+
+- `.[pdf]`: Python Graphviz binding; also install the Graphviz `dot` executable.
+- `.[browser]`: legacy Selenium helpers for callers importing `DrawIOBrowser`
+  directly. They are not part of native rendering and are not live-browser
+  tested by the default suite.
+- `.[excel]`: dependencies for the existing ERD spreadsheet exporter.
+- `.[docs]`: MkDocs.
+
+## Development
+
+```sh
+make lint
+make test
+make build
+```
+
+Tests write real XML and run examples in temporary directories. They do not
+install packages, download browser drivers, or launch Chrome. See
+[the API reference](docs/index.md) and [contribution guide](CONTRIBUTING.md).

drawio_python-0.1.3/docs/index.md

@@ -0,0 +1,109 @@
+# Native XML API
+
+Install the checkout with `python -m pip install -e '.[test]'`.
+See the repository README for the quick start and legacy API migration notes.
+
+## Document
+
+```python
+from drawio import Document, Theme
+
+doc = Document(theme=Theme(font_family="Helvetica", font_size=18))
+page = doc.add_page("Overview", id="overview", width=1600, height=1000)
+```
+
+| Method | Result |
+| --- | --- |
+| `add_page(name, id=None, width=1600, height=1000, background="#ffffff")` | New editable `Page` |
+| `get_page(id)` | Page with that ID, or `ValueError` |
+| `pages` | Tuple of pages in document order |
+| `validate(check_bounds=False)` | Check page/cell IDs, endpoints and parent hierarchy |
+| `to_xml(pretty=True)` | Complete `mxfile` XML string |
+| `save(path, overwrite=False)` | Save UTF-8 XML and return a `Path` |
+| `to_url()` | Encoded diagrams.net editor URL; no network access |
+| `Document.load(path, max_bytes=...)` | Load UTF-8 `.drawio` / `.xml` |
+| `Document.from_xml(xml, max_bytes=...)` | Load an XML string or UTF-8 bytes |
+
+Explicit IDs are useful for stable diffs. Generated IDs follow insertion order
+and skip IDs already in use. Page IDs must be unique within a document; cell IDs
+must be unique within a page. Different pages may reuse a cell ID.
+
+Loading accepts `mxfile`, a single `diagram`, or a standalone `mxGraphModel`.
+The default input and expanded-model limit is 10 MiB. You can raise `max_bytes`
+for trusted larger documents. The loader rejects DTD/entity declarations and
+invalid compressed data. It preserves supported XML structure and unknown
+metadata, including draw.io `object` wrappers; it is not a full schema validator
+for every draw.io plugin or custom shape.
+
+## Page and Cell
+
+```python
+box = page.box("Input", 40, 80, width=200, height=90, id="input")
+group = page.container("Output", 500, 80, 360, 360, id="output")
+child = page.box("Article", 20, 70, 320, 80, parent=group)
+page.text("Overview", 40, 20, 700, 40, style={"fontSize": 28})
+page.connect(box, child, "publish")
+```
+
+`box`, `container` and `text` accept `id`, `parent`, `style` and `html` keyword
+arguments and return a `Cell`. Use a returned `Cell` or an existing cell ID as a
+parent or connector endpoint. References cannot cross page boundaries.
+
+- `box(label, x, y, width=200, height=90, ...)`: native shape.
+- `container(label, x, y, width, height, ...)`: shape with a top-aligned title and
+  nested child blocks.
+- `text(label, x, y, width=400, height=40, ...)`: borderless text.
+- `connect(source, target, label="", ...)`: native orthogonal connector.
+- `get(id)`: existing cell reference.
+- `cells`: tuple of cell references, including root/layer cells.
+- `name`: editable tab name.
+- `to_xml()`: the current page's `mxGraphModel` XML.
+
+A child's `(x, y)` is relative to its parent. Reserve space for the container
+heading yourself. Nested container coordinates follow the same rule. The writer
+does not pack, resize or align child blocks for you.
+
+`validate(check_bounds=True)` also checks ordinary child rectangles against
+parent bounds. Relative ports are exempt from this bounds check. Validation does
+not measure text, detect shape overlaps or guarantee optimal connector routing.
+
+`Cell.element`, `Page.model`, `Page.element` and `Document.element` expose the
+underlying ElementTree elements for advanced XML editing. Call `validate()`
+after a manual change; prefer the builder methods for creating cells and pages.
+
+## Connectors
+
+```python
+page.connect(
+    box, child, "publish",
+    id="publish-edge",
+    source_port=(1, 0.5),
+    target_port=(0, 0.5),
+    waypoints=[(400, 125), (400, 190)],
+    dashed=True,
+    style={"strokeColor": "#246a52", "fontSize": 16},
+)
+```
+
+Ports are normalized `(x, y)` pairs in `[0, 1]`. `(1, 0.5)` is the right edge's
+midpoint; `(0.5, 1)` is the bottom midpoint. Omit ports to let draw.io choose them.
+Waypoints use page coordinates even when an endpoint belongs to a container.
+Labels on connectors use plain text.
+
+## Styles and text
+
+`Theme` sets `font_family`, `font_size`, `fill_color`, `stroke_color`,
+`text_color` and `line_color`. Per-cell style dictionaries override the defaults.
+Style keys use draw.io names; booleans become `1` or `0`. Semicolons in style
+values and delimiters in keys are rejected.
+
+Plain-text labels support Unicode, quotes, newlines and XML-significant
+characters. The writer escapes XML. A style dictionary cannot opt into HTML:
+pass `html=True` to a shape method when you intend to render trusted markup.
+
+```python
+page.box("<b>Title</b><br/>Subtitle", 40, 300, html=True)
+```
+
+XML generation works offline. To inspect the visual result, open the file in
+draw.io. Use that editor or draw.io Desktop for image/PDF exports.

drawio_python-0.1.3/drawio/VERSION

@@ -0,0 +1 @@
+0.1.3

drawio_python-0.1.3/drawio/__init__.py

@@ -0,0 +1,5 @@
+from .document import Cell, Document, Page, Theme
+from .entities.graph.graph import Graph
+from .entities.graph.node import Node
+
+__all__ = ["Cell", "Document", "Graph", "Node", "Page", "Theme"]

drawio_python-0.1.3/drawio/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m drawio."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

drawio_python-0.1.3/drawio/cli.py

@@ -0,0 +1,60 @@
+"""Offline utilities for editable draw.io files."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from drawio.document import Document
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="Generate and inspect native draw.io XML")
+    version = Path(__file__).with_name("VERSION").read_text(encoding="utf-8").strip()
+    parser.add_argument("--version", action="version", version=version)
+    commands = parser.add_subparsers(dest="command", required=True)
+    validate = commands.add_parser("validate", help="Check IDs, references and parent hierarchy")
+    validate.add_argument("input", type=Path)
+    validate.add_argument(
+        "--check-bounds", action="store_true", help="Also reject children outside containers"
+    )
+    info = commands.add_parser("info", help="Print page IDs, names and cell counts as JSON")
+    info.add_argument("input", type=Path)
+    url = commands.add_parser("url", help="Encode file contents in an editor URL (no upload)")
+    url.add_argument("input", type=Path)
+    new = commands.add_parser("new", help="Create an empty one-page document")
+    new.add_argument("output", type=Path)
+    new.add_argument("--name", default="Overview")
+    new.add_argument("--overwrite", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "new":
+            document = Document()
+            document.add_page(args.name)
+            print(document.save(args.output, overwrite=args.overwrite))
+            return 0
+        document = Document.load(args.input)
+        if args.command == "validate":
+            document.validate(check_bounds=args.check_bounds)
+            print(f"Valid: {len(document.pages)} page(s)")
+        elif args.command == "info":
+            print(
+                json.dumps(
+                    [
+                        {
+                            "id": page.id,
+                            "name": page.name,
+                            "shapes": sum(c.element.get("vertex") == "1" for c in page.cells),
+                            "connectors": sum(c.element.get("edge") == "1" for c in page.cells),
+                        }
+                        for page in document.pages
+                    ],
+                    indent=2,
+                )
+            )
+        elif args.command == "url":
+            print(document.to_url())
+        return 0
+    except (OSError, ValueError, TypeError) as exc:
+        print(f"drawio: {exc}", file=sys.stderr)
+        return 1