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

drawio_python-0.1.4/HISTORY.md

@@ -0,0 +1,41 @@
+# Unreleased
+
+- Render pages to PNG, SVG, PDF and JPEG on any OS: a built-in native renderer (SVG
+  with no dependencies, raster through Pillow), the draw.io desktop exporter, or the
+  official diagrams.net viewer in a headless browser.
+- Add layout checks (`drawio lint`): overflowing text, overlaps, connectors through
+  shapes or labels, children outside containers, small text and aspect ratio for a
+  target size.
+- Add automatic layout (`drawio.layout`: layered, row, column, grid), `page.fit()`,
+  `page.autosize()`, text metrics, named shapes, images, colour presets,
+  `Theme.drawio()`, arrow ends, absolute coordinates, cell geometry accessors,
+  `page.remove()`, `page.find()`, `Document.import_page()` and `remove_page()`.
+- New CLI commands for agents, all with `--json`: render, lint, inspect, fit, layout,
+  merge, shapes, doctor and skill; ship an agent skill installable with
+  `drawio skill install`.
+- Fix `save()` creating files with mode 0600; explain duplicate-ID clashes with
+  generated IDs.
+- 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.4/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.4/PKG-INFO

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: drawio-python
+Version: 0.1.4
+Summary: Build, check and export editable draw.io diagrams in Python; made for people and agents
+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"
+Requires-Dist: Pillow>=9.1; extra == "test"
+Provides-Extra: render
+Requires-Dist: Pillow>=9.1; extra == "render"
+Provides-Extra: browser-render
+Requires-Dist: playwright>=1.40; extra == "browser-render"
+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, check and export editable draw.io diagrams in Python. The library writes
+native draw.io XML (every shape stays editable in draw.io), measures labels, finds
+layout problems, lays shapes out, and renders PNG, SVG or PDF on Linux, macOS and
+Windows. The core needs only the Python standard library; Python 3.9 or newer.
+
+It is built to be driven by coding agents as much as by people: every command has
+`--json` output, and an agent skill ships with the package.
+
+## Install
+
+```sh
+pip install 'drawio-python[render]'      # core + PNG/JPEG/PDF output (Pillow)
+pip install drawio-python                # core only: build, lint, SVG
+pip install 'drawio-python[browser-render]'  # exact rendering of any draw.io file
+```
+
+From a checkout: `python -m pip install -e '.[render,test]'`. Check what the machine
+can render with `drawio doctor`.
+
+## Agents
+
+```sh
+drawio skill install          # into ~/.claude/skills, ~/.codex/skills and/or ~/.agents/skills
+drawio skill show             # print the skill
+```
+
+The skill (`drawio/skill/SKILL.md`) teaches the loop **build, `drawio lint`,
+`drawio render`, look, fix**, the API, slide sizing and the common errors.
+
+## 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.
+
+## Shapes, layout and fitting text
+
+```python
+from drawio import Document, Theme
+from drawio.layout import layered
+from drawio.shapes import color
+
+doc = Document(theme=Theme.drawio())   # the draw.io editor's own look
+page = doc.add_page("Flow")
+start = page.box("Start", 0, 0, 120, 50, shape="rounded", style=color("green"))
+check = page.box("Valid?", 0, 0, 120, 80, shape="rhombus")
+store = page.box("Orders", 0, 0, 120, 80, shape="cylinder", style=color("yellow"))
+page.connect(start, check)
+page.connect(check, store, "yes")
+layered(page, direction="down")        # ranks along the connectors; also row/column/grid
+page.fit()                             # grow containers and the page around the shapes
+doc.save("flow.drawio", overwrite=True)
+```
+
+- `shape=` accepts `rounded, ellipse, circle, rhombus, cylinder, hexagon, triangle,
+  parallelogram, document, cloud, process, note, card, step, actor` or any draw.io
+  shape name; `page.image()` embeds a picture file.
+- `connect(..., arrow=None)` draws an undirected line; `arrow` and `start_arrow` take
+  any draw.io marker (`drawio shapes` lists them).
+- `box(..., absolute=True)` takes page coordinates inside a container;
+  `box(..., autosize=True)` or `page.autosize(cell)` grows a box to fit its label.
+- Cells expose `x`, `y`, `width`, `height`, `bounds`, `style`, `text`, `move()`,
+  `resize()`, `set_style()`; pages offer `find()`, `children()`, `remove()`;
+  documents offer `import_page()` and `remove_page()`.
+
+## Check the layout
+
+```sh
+drawio lint flow.drawio                     # exit status 1 when something is wrong
+drawio lint deck.drawio --fit 8.15x4.85in   # also: text below 12 pt once placed on a slide
+drawio inspect flow.drawio --json           # every shape box and connector route
+```
+
+Lint reports overflowing labels, overlapping shapes and labels, connectors that run
+through shapes or labels, children outside containers, and (with `--fit`) text that
+ends up too small and aspect-ratio mismatches. Text widths are estimated from
+Helvetica/Arial metrics, close to draw.io's wrapping.
+
+## Render
+
+```sh
+drawio render flow.drawio -o flow.png --scale 2
+drawio render flow.drawio -o flow.svg              # plain SVG text, no foreignObject
+drawio render deck.drawio -o slide.png --aspect 16:9
+drawio render big.drawio --all-pages -f pdf
+```
+
+| Backend | Requirements | Output |
+|---|---|---|
+| `native` | none for SVG; Pillow for PNG, JPEG, PDF | shapes this library makes and common draw.io shapes |
+| `desktop` | [draw.io desktop](https://github.com/jgraph/drawio-desktop/releases) | exact |
+| `browser` | `[browser-render]` extra plus Chrome, Edge or `playwright install chromium` | exact, including stencils and icons |
+| `auto` | | desktop when installed, otherwise native |
+
+The browser backend loads the official diagrams.net viewer, downloaded once to the
+user cache (set `DRAWIO_VIEWER_JS` to work offline). On Linux the desktop backend
+needs a display or `xvfb-run`. Native PDF is vector when `cairosvg` or `rsvg-convert`
+is available, otherwise a raster image. `drawio doctor` reports all of this.
+
+## CLI
+
+```sh
+drawio new empty.drawio --name Overview
+drawio validate publishing.drawio --check-bounds
+drawio info publishing.drawio
+drawio url publishing.drawio
+drawio render | lint | inspect | fit | layout | merge | shapes | doctor | skill
+```
+
+`python -m drawio` runs the same commands, which helps when the draw.io desktop
+app also installed a `drawio` command. Commands that report take `--json`. `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 with `drawio.layout` for
+an authored or automatic layout.
+
+`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:
+
+- `.[render]`: Pillow, for PNG, JPEG and PDF output of the native renderer.
+- `.[browser-render]`: Playwright, for the exact `browser` render backend.
+- `.[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, render with the native backend 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.4/README.md

@@ -0,0 +1,248 @@
+# drawio-python
+
+Build, check and export editable draw.io diagrams in Python. The library writes
+native draw.io XML (every shape stays editable in draw.io), measures labels, finds
+layout problems, lays shapes out, and renders PNG, SVG or PDF on Linux, macOS and
+Windows. The core needs only the Python standard library; Python 3.9 or newer.
+
+It is built to be driven by coding agents as much as by people: every command has
+`--json` output, and an agent skill ships with the package.
+
+## Install
+
+```sh
+pip install 'drawio-python[render]'      # core + PNG/JPEG/PDF output (Pillow)
+pip install drawio-python                # core only: build, lint, SVG
+pip install 'drawio-python[browser-render]'  # exact rendering of any draw.io file
+```
+
+From a checkout: `python -m pip install -e '.[render,test]'`. Check what the machine
+can render with `drawio doctor`.
+
+## Agents
+
+```sh
+drawio skill install          # into ~/.claude/skills, ~/.codex/skills and/or ~/.agents/skills
+drawio skill show             # print the skill
+```
+
+The skill (`drawio/skill/SKILL.md`) teaches the loop **build, `drawio lint`,
+`drawio render`, look, fix**, the API, slide sizing and the common errors.
+
+## 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.
+
+## Shapes, layout and fitting text
+
+```python
+from drawio import Document, Theme
+from drawio.layout import layered
+from drawio.shapes import color
+
+doc = Document(theme=Theme.drawio())   # the draw.io editor's own look
+page = doc.add_page("Flow")
+start = page.box("Start", 0, 0, 120, 50, shape="rounded", style=color("green"))
+check = page.box("Valid?", 0, 0, 120, 80, shape="rhombus")
+store = page.box("Orders", 0, 0, 120, 80, shape="cylinder", style=color("yellow"))
+page.connect(start, check)
+page.connect(check, store, "yes")
+layered(page, direction="down")        # ranks along the connectors; also row/column/grid
+page.fit()                             # grow containers and the page around the shapes
+doc.save("flow.drawio", overwrite=True)
+```
+
+- `shape=` accepts `rounded, ellipse, circle, rhombus, cylinder, hexagon, triangle,
+  parallelogram, document, cloud, process, note, card, step, actor` or any draw.io
+  shape name; `page.image()` embeds a picture file.
+- `connect(..., arrow=None)` draws an undirected line; `arrow` and `start_arrow` take
+  any draw.io marker (`drawio shapes` lists them).
+- `box(..., absolute=True)` takes page coordinates inside a container;
+  `box(..., autosize=True)` or `page.autosize(cell)` grows a box to fit its label.
+- Cells expose `x`, `y`, `width`, `height`, `bounds`, `style`, `text`, `move()`,
+  `resize()`, `set_style()`; pages offer `find()`, `children()`, `remove()`;
+  documents offer `import_page()` and `remove_page()`.
+
+## Check the layout
+
+```sh
+drawio lint flow.drawio                     # exit status 1 when something is wrong
+drawio lint deck.drawio --fit 8.15x4.85in   # also: text below 12 pt once placed on a slide
+drawio inspect flow.drawio --json           # every shape box and connector route
+```
+
+Lint reports overflowing labels, overlapping shapes and labels, connectors that run
+through shapes or labels, children outside containers, and (with `--fit`) text that
+ends up too small and aspect-ratio mismatches. Text widths are estimated from
+Helvetica/Arial metrics, close to draw.io's wrapping.
+
+## Render
+
+```sh
+drawio render flow.drawio -o flow.png --scale 2
+drawio render flow.drawio -o flow.svg              # plain SVG text, no foreignObject
+drawio render deck.drawio -o slide.png --aspect 16:9
+drawio render big.drawio --all-pages -f pdf
+```
+
+| Backend | Requirements | Output |
+|---|---|---|
+| `native` | none for SVG; Pillow for PNG, JPEG, PDF | shapes this library makes and common draw.io shapes |
+| `desktop` | [draw.io desktop](https://github.com/jgraph/drawio-desktop/releases) | exact |
+| `browser` | `[browser-render]` extra plus Chrome, Edge or `playwright install chromium` | exact, including stencils and icons |
+| `auto` | | desktop when installed, otherwise native |
+
+The browser backend loads the official diagrams.net viewer, downloaded once to the
+user cache (set `DRAWIO_VIEWER_JS` to work offline). On Linux the desktop backend
+needs a display or `xvfb-run`. Native PDF is vector when `cairosvg` or `rsvg-convert`
+is available, otherwise a raster image. `drawio doctor` reports all of this.
+
+## CLI
+
+```sh
+drawio new empty.drawio --name Overview
+drawio validate publishing.drawio --check-bounds
+drawio info publishing.drawio
+drawio url publishing.drawio
+drawio render | lint | inspect | fit | layout | merge | shapes | doctor | skill
+```
+
+`python -m drawio` runs the same commands, which helps when the draw.io desktop
+app also installed a `drawio` command. Commands that report take `--json`. `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 with `drawio.layout` for
+an authored or automatic layout.
+
+`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:
+
+- `.[render]`: Pillow, for PNG, JPEG and PDF output of the native renderer.
+- `.[browser-render]`: Playwright, for the exact `browser` render backend.
+- `.[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, render with the native backend 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).