make-drawio-png 0.1.0__tar.gz

make_drawio_png-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/

make_drawio_png-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoichiro Sakaigawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

make_drawio_png-0.1.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.5
+Name: make-drawio-png
+Version: 0.1.0
+Summary: Convert .drawio XML files into re-editable .drawio.png — zero external dependencies
+Project-URL: Homepage, https://github.com/phssakaigawa/make-drawio-png
+Project-URL: Repository, https://github.com/phssakaigawa/make-drawio-png
+Project-URL: Bug Tracker, https://github.com/phssakaigawa/make-drawio-png/issues
+Project-URL: Changelog, https://github.com/phssakaigawa/make-drawio-png/releases
+Author: Shoichiro Sakaigawa
+License: MIT License
+        
+        Copyright (c) 2026 Shoichiro Sakaigawa
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai-agent,diagram-as-code,diagrams,drawio,png
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# make-drawio-png
+
+[![PyPI version](https://img.shields.io/pypi/v/make-drawio-png)](https://pypi.org/project/make-drawio-png/)
+[![Python](https://img.shields.io/pypi/pyversions/make-drawio-png)](https://pypi.org/project/make-drawio-png/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/phssakaigawa/make-drawio-png/blob/main/LICENSE)
+[![CI](https://github.com/phssakaigawa/make-drawio-png/actions/workflows/ci.yml/badge.svg)](https://github.com/phssakaigawa/make-drawio-png/actions/workflows/ci.yml)
+
+**[日本語版 README はこちら → README.ja.md](https://github.com/phssakaigawa/make-drawio-png/blob/main/README.ja.md)**
+
+A Python library that implements the **`.drawio.png` file format** — the
+re-editable PNG format used by [draw.io / diagrams.net](https://www.diagrams.net/).
+
+With this library you can **generate `.drawio.png` files programmatically**,
+without opening draw.io at all.  The generated files are indistinguishable
+from those exported by draw.io itself.
+
+### What is the `.drawio.png` format?
+
+A `.drawio.png` file is simultaneously:
+- a **standard PNG image** — viewable in any image viewer, browser, or AI agent
+- a **fully editable draw.io source** — open it in draw.io to restore and edit the diagram
+
+This is achieved by embedding the diagram XML inside a PNG `tEXt` chunk
+(`keyword=mxfile`, `value=URL-encoded UTF-8 XML`), following the
+[draw.io open-source specification](https://github.com/jgraph/drawio).
+draw.io reads that chunk to restore the diagram; image viewers see only the PNG pixel data.
+
+### Use cases
+
+- **AI agents / Bob**: generate diagrams as code, embed them in Markdown docs, preview as PNG
+- **CI/CD pipelines**: produce architecture diagrams from `.drawio` XML without a GUI
+- **Documentation automation**: keep diagrams as re-editable sources alongside rendered images
+
+---
+
+## Install
+
+```bash
+pip install make-drawio-png
+```
+
+> **Note for Windows users — read the PATH section below before installing.**
+
+---
+
+## Usage
+
+### CLI
+
+```bash
+# embed only — re-editable but 1×1 placeholder image (no draw.io needed)
+python -m make_drawio_png architecture.drawio
+
+# render + embed — visually rendered AND re-editable (requires draw.io desktop)
+python -m make_drawio_png --render architecture.drawio
+
+# explicit output path
+python -m make_drawio_png --render flow.drawio docs/images/flow.drawio.png
+```
+
+> **Windows / Bob shell users:** Use `python -m make_drawio_png` instead of the
+> `make-drawio-png` command — it works without any PATH changes.  See the
+> [PATH guide](#windows--python-path-guide) below.
+
+### Python API
+
+```python
+from make_drawio_png import drawio_export, drawio_to_png
+
+# Recommended: render + embed (requires draw.io desktop)
+drawio_export("architecture.drawio")
+# → architecture.drawio.png  (rendered + re-editable)
+
+# Zero dependencies: embed only (re-editable, 1×1 placeholder image)
+drawio_to_png("architecture.drawio")
+# → architecture.drawio.png  (re-editable, no visual content)
+```
+
+### draw.io desktop (required for `--render` / `drawio_export`)
+
+```bash
+winget install JGraph.Draw   # Windows
+brew install --cask drawio   # macOS
+snap install drawio          # Linux
+```
+
+The CLI is auto-detected after installation.
+Set `DRAWIO_PATH` to override the location.
+
+---
+
+## Windows — Python PATH guide
+
+On Windows, `pip install` places the `make-drawio-png` CLI script in a
+`Scripts` directory that is **not always in PATH by default**.  
+The table below shows where scripts land depending on how you install:
+
+| Install command | Scripts directory | In PATH by default? |
+|---|---|---|
+| `pip install make-drawio-png` (system-wide) | `%LOCALAPPDATA%\Python\pythoncore-X.Y-64\Scripts` | ❌ usually not |
+| `pip install --user make-drawio-png` | `%APPDATA%\Python\PythonXYZ\Scripts` | ❌ usually not |
+| `pip install make-drawio-png` (venv active) | `<venv>\Scripts` | ✅ while venv is active |
+
+### Checking your Scripts path
+
+```powershell
+python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
+# e.g. C:\Users\you\AppData\Local\Python\pythoncore-3.14-64\Scripts
+
+python -c "import sysconfig; print(sysconfig.get_path('scripts','nt_user'))"
+# e.g. C:\Users\you\AppData\Roaming\Python\Python314\Scripts
+```
+
+### Adding Scripts to PATH (one-time setup)
+
+```powershell
+# Append to your user PATH permanently
+$scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
+[System.Environment]::SetEnvironmentVariable(
+    "PATH",
+    "$([System.Environment]::GetEnvironmentVariable('PATH','User'));$scripts",
+    "User"
+)
+# → restart your terminal / shell after this
+```
+
+### Workaround: use `python -m` instead of the CLI
+
+If you don't want to touch PATH at all, call the module directly:
+
+```powershell
+python -m make_drawio_png architecture.drawio
+```
+
+This always works regardless of PATH because Python itself is on PATH.
+
+---
+
+## Bob / Claude Code shell
+
+When using IBM Bob or Claude Code on Windows, the shell inherits the **same
+PATH as the process that launched Bob/Claude** — there is no separate Python
+environment.
+
+| Scenario | `python3` resolves to | `make-drawio-png` CLI available? |
+|---|---|---|
+| Launched from a terminal where Python Scripts is in PATH | your Python installation | ✅ |
+| Launched from Windows start menu / system tray | system PATH (Scripts likely missing) | ❌ use `python -m` |
+| Launched inside an active venv | venv Python + Scripts | ✅ |
+
+**Recommended practice for Bob/Claude Code users:**
+
+Always invoke via `python -m` so the PATH question is irrelevant:
+
+```python
+# In Bob's execute_command tool
+python3 -m make_drawio_png "<path>.drawio"
+```
+
+Or reference the script by its absolute path after installation:
+
+```python
+import subprocess, sysconfig, pathlib
+scripts = pathlib.Path(sysconfig.get_path("scripts"))
+subprocess.run([scripts / "make-drawio-png", "architecture.drawio"])
+```
+
+---
+
+## How it works
+
+![How make-drawio-png works](https://raw.githubusercontent.com/phssakaigawa/make-drawio-png/main/docs/how-it-works.drawio.png)
+
+The `.drawio.png` file is both a valid PNG image and a re-editable draw.io
+source.  draw.io reads the embedded `tEXt[mxfile]` chunk to restore the full
+diagram; image viewers and AI agents see only the PNG pixel data.
+
+### PNG chunk layout
+
+```
+PNG Signature  (8 bytes)
+IHDR chunk     (25 bytes)
+tEXt chunk     (keyword="mxfile" \x00 URL-encoded-XML)   ← diagram XML here
+IDAT chunk     (compressed pixel data)
+IEND chunk
+```
+
+---
+
+## Requirements
+
+- Python ≥ 3.9
+- No external dependencies (uses only `struct`, `zlib`, `urllib.parse` from stdlib)
+
+---
+
+## License
+
+MIT © 2026 Shoichiro Sakaigawa

make_drawio_png-0.1.0/README.md

@@ -0,0 +1,199 @@
+# make-drawio-png
+
+[![PyPI version](https://img.shields.io/pypi/v/make-drawio-png)](https://pypi.org/project/make-drawio-png/)
+[![Python](https://img.shields.io/pypi/pyversions/make-drawio-png)](https://pypi.org/project/make-drawio-png/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/phssakaigawa/make-drawio-png/blob/main/LICENSE)
+[![CI](https://github.com/phssakaigawa/make-drawio-png/actions/workflows/ci.yml/badge.svg)](https://github.com/phssakaigawa/make-drawio-png/actions/workflows/ci.yml)
+
+**[日本語版 README はこちら → README.ja.md](https://github.com/phssakaigawa/make-drawio-png/blob/main/README.ja.md)**
+
+A Python library that implements the **`.drawio.png` file format** — the
+re-editable PNG format used by [draw.io / diagrams.net](https://www.diagrams.net/).
+
+With this library you can **generate `.drawio.png` files programmatically**,
+without opening draw.io at all.  The generated files are indistinguishable
+from those exported by draw.io itself.
+
+### What is the `.drawio.png` format?
+
+A `.drawio.png` file is simultaneously:
+- a **standard PNG image** — viewable in any image viewer, browser, or AI agent
+- a **fully editable draw.io source** — open it in draw.io to restore and edit the diagram
+
+This is achieved by embedding the diagram XML inside a PNG `tEXt` chunk
+(`keyword=mxfile`, `value=URL-encoded UTF-8 XML`), following the
+[draw.io open-source specification](https://github.com/jgraph/drawio).
+draw.io reads that chunk to restore the diagram; image viewers see only the PNG pixel data.
+
+### Use cases
+
+- **AI agents / Bob**: generate diagrams as code, embed them in Markdown docs, preview as PNG
+- **CI/CD pipelines**: produce architecture diagrams from `.drawio` XML without a GUI
+- **Documentation automation**: keep diagrams as re-editable sources alongside rendered images
+
+---
+
+## Install
+
+```bash
+pip install make-drawio-png
+```
+
+> **Note for Windows users — read the PATH section below before installing.**
+
+---
+
+## Usage
+
+### CLI
+
+```bash
+# embed only — re-editable but 1×1 placeholder image (no draw.io needed)
+python -m make_drawio_png architecture.drawio
+
+# render + embed — visually rendered AND re-editable (requires draw.io desktop)
+python -m make_drawio_png --render architecture.drawio
+
+# explicit output path
+python -m make_drawio_png --render flow.drawio docs/images/flow.drawio.png
+```
+
+> **Windows / Bob shell users:** Use `python -m make_drawio_png` instead of the
+> `make-drawio-png` command — it works without any PATH changes.  See the
+> [PATH guide](#windows--python-path-guide) below.
+
+### Python API
+
+```python
+from make_drawio_png import drawio_export, drawio_to_png
+
+# Recommended: render + embed (requires draw.io desktop)
+drawio_export("architecture.drawio")
+# → architecture.drawio.png  (rendered + re-editable)
+
+# Zero dependencies: embed only (re-editable, 1×1 placeholder image)
+drawio_to_png("architecture.drawio")
+# → architecture.drawio.png  (re-editable, no visual content)
+```
+
+### draw.io desktop (required for `--render` / `drawio_export`)
+
+```bash
+winget install JGraph.Draw   # Windows
+brew install --cask drawio   # macOS
+snap install drawio          # Linux
+```
+
+The CLI is auto-detected after installation.
+Set `DRAWIO_PATH` to override the location.
+
+---
+
+## Windows — Python PATH guide
+
+On Windows, `pip install` places the `make-drawio-png` CLI script in a
+`Scripts` directory that is **not always in PATH by default**.  
+The table below shows where scripts land depending on how you install:
+
+| Install command | Scripts directory | In PATH by default? |
+|---|---|---|
+| `pip install make-drawio-png` (system-wide) | `%LOCALAPPDATA%\Python\pythoncore-X.Y-64\Scripts` | ❌ usually not |
+| `pip install --user make-drawio-png` | `%APPDATA%\Python\PythonXYZ\Scripts` | ❌ usually not |
+| `pip install make-drawio-png` (venv active) | `<venv>\Scripts` | ✅ while venv is active |
+
+### Checking your Scripts path
+
+```powershell
+python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
+# e.g. C:\Users\you\AppData\Local\Python\pythoncore-3.14-64\Scripts
+
+python -c "import sysconfig; print(sysconfig.get_path('scripts','nt_user'))"
+# e.g. C:\Users\you\AppData\Roaming\Python\Python314\Scripts
+```
+
+### Adding Scripts to PATH (one-time setup)
+
+```powershell
+# Append to your user PATH permanently
+$scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
+[System.Environment]::SetEnvironmentVariable(
+    "PATH",
+    "$([System.Environment]::GetEnvironmentVariable('PATH','User'));$scripts",
+    "User"
+)
+# → restart your terminal / shell after this
+```
+
+### Workaround: use `python -m` instead of the CLI
+
+If you don't want to touch PATH at all, call the module directly:
+
+```powershell
+python -m make_drawio_png architecture.drawio
+```
+
+This always works regardless of PATH because Python itself is on PATH.
+
+---
+
+## Bob / Claude Code shell
+
+When using IBM Bob or Claude Code on Windows, the shell inherits the **same
+PATH as the process that launched Bob/Claude** — there is no separate Python
+environment.
+
+| Scenario | `python3` resolves to | `make-drawio-png` CLI available? |
+|---|---|---|
+| Launched from a terminal where Python Scripts is in PATH | your Python installation | ✅ |
+| Launched from Windows start menu / system tray | system PATH (Scripts likely missing) | ❌ use `python -m` |
+| Launched inside an active venv | venv Python + Scripts | ✅ |
+
+**Recommended practice for Bob/Claude Code users:**
+
+Always invoke via `python -m` so the PATH question is irrelevant:
+
+```python
+# In Bob's execute_command tool
+python3 -m make_drawio_png "<path>.drawio"
+```
+
+Or reference the script by its absolute path after installation:
+
+```python
+import subprocess, sysconfig, pathlib
+scripts = pathlib.Path(sysconfig.get_path("scripts"))
+subprocess.run([scripts / "make-drawio-png", "architecture.drawio"])
+```
+
+---
+
+## How it works
+
+![How make-drawio-png works](https://raw.githubusercontent.com/phssakaigawa/make-drawio-png/main/docs/how-it-works.drawio.png)
+
+The `.drawio.png` file is both a valid PNG image and a re-editable draw.io
+source.  draw.io reads the embedded `tEXt[mxfile]` chunk to restore the full
+diagram; image viewers and AI agents see only the PNG pixel data.
+
+### PNG chunk layout
+
+```
+PNG Signature  (8 bytes)
+IHDR chunk     (25 bytes)
+tEXt chunk     (keyword="mxfile" \x00 URL-encoded-XML)   ← diagram XML here
+IDAT chunk     (compressed pixel data)
+IEND chunk
+```
+
+---
+
+## Requirements
+
+- Python ≥ 3.9
+- No external dependencies (uses only `struct`, `zlib`, `urllib.parse` from stdlib)
+
+---
+
+## License
+
+MIT © 2026 Shoichiro Sakaigawa

make_drawio_png-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "make-drawio-png"
+version = "0.1.0"
+description = "Convert .drawio XML files into re-editable .drawio.png — zero external dependencies"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Shoichiro Sakaigawa" }]
+keywords = ["drawio", "diagrams", "png", "diagram-as-code", "ai-agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+    "Topic :: Multimedia :: Graphics",
+]
+requires-python = ">=3.9"
+# No runtime dependencies — pure Python standard library only
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/phssakaigawa/make-drawio-png"
+Repository = "https://github.com/phssakaigawa/make-drawio-png"
+"Bug Tracker" = "https://github.com/phssakaigawa/make-drawio-png/issues"
+Changelog = "https://github.com/phssakaigawa/make-drawio-png/releases"
+
+[project.scripts]
+make-drawio-png = "make_drawio_png.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/make_drawio_png"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/",
+    "tests/",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]

make_drawio_png-0.1.0/src/make_drawio_png/__init__.py

@@ -0,0 +1,384 @@
+"""
+make_drawio_png
+===============
+Convert a .drawio XML file into a re-editable .drawio.png — zero external
+dependencies, pure Python standard library.
+
+The .drawio.png format embeds the diagram XML inside a PNG ``tEXt`` chunk
+(keyword ``mxfile``, value URL-encoded UTF-8 XML).  draw.io / diagrams.net
+reads that chunk to restore the diagram, so the file is both a valid PNG
+*and* a fully editable draw.io source.
+
+Two rendering modes
+-------------------
+1. **Embed only** (zero dependencies) — ``drawio_to_png()``
+   Produces a ``.drawio.png`` that is re-editable in draw.io but shows only a
+   1×1 white pixel as a visual image.  No external tool required.
+
+2. **Full render** (requires draw.io desktop) — ``drawio_render_png()``
+   Uses the draw.io CLI to export a fully-rendered PNG image.
+
+3. **Both at once** (recommended) — ``drawio_export()``
+   Calls the draw.io CLI to render, then embeds the XML into that PNG so the
+   result is *both* visually rich *and* re-editable.
+
+Quick start
+-----------
+    # CLI
+    make-drawio-png architecture.drawio            # embed only
+    make-drawio-png --render architecture.drawio   # full render + embed
+    python -m make_drawio_png --render flow.drawio
+
+    # Python API
+    from make_drawio_png import drawio_to_png, drawio_export
+    drawio_to_png("architecture.drawio")           # embed only
+    drawio_export("architecture.drawio")           # render + embed (recommended)
+
+draw.io CLI installation
+------------------------
+draw.io desktop bundles a headless CLI exporter.  Install it once per machine:
+
+  Windows : winget install JGraph.Draw
+  macOS   : brew install --cask drawio
+  Linux   : snap install drawio
+            # or download .deb/.rpm from https://github.com/jgraph/drawio-desktop/releases
+
+After installation the executable is auto-detected by this library.
+You can also set the ``DRAWIO_PATH`` environment variable to point to a custom
+location.
+"""
+
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Shoichiro Sakaigawa
+
+from __future__ import annotations
+
+import os
+import shutil
+import struct
+import subprocess
+import sys
+import zlib
+from pathlib import Path
+from urllib.parse import quote
+
+__version__ = "0.1.0"
+__all__ = [
+    "drawio_to_png",
+    "drawio_render_png",
+    "drawio_export",
+    "find_drawio_cli",
+    "DrawioCLINotFoundError",
+]
+
+
+# ---------------------------------------------------------------------------
+# draw.io CLI detection
+# ---------------------------------------------------------------------------
+
+# Per-platform candidate paths (in priority order)
+_DRAWIO_CANDIDATES: dict[str, list[str]] = {
+    "win32": [
+        r"%LOCALAPPDATA%\Programs\draw.io\draw.io.exe",
+        r"C:\Program Files\draw.io\draw.io.exe",
+        r"C:\Program Files (x86)\draw.io\draw.io.exe",
+    ],
+    "darwin": [
+        "/Applications/draw.io.app/Contents/MacOS/draw.io",
+        "/usr/local/bin/drawio",
+    ],
+    "linux": [
+        "/snap/bin/drawio",
+        "/usr/bin/drawio",
+        "/usr/local/bin/drawio",
+    ],
+}
+
+
+class DrawioCLINotFoundError(FileNotFoundError):
+    """Raised when the draw.io CLI executable cannot be found.
+
+    Install draw.io desktop:
+      Windows : winget install JGraph.Draw
+      macOS   : brew install --cask drawio
+      Linux   : snap install drawio
+    Or set the DRAWIO_PATH environment variable to the executable path.
+    """
+
+
+def find_drawio_cli() -> str:
+    """
+    Return the path to the draw.io CLI executable.
+
+    Resolution order:
+    1. ``DRAWIO_PATH`` environment variable
+    2. ``drawio`` / ``draw.io`` on ``PATH`` (via shutil.which)
+    3. Platform-specific default install locations
+
+    Raises
+    ------
+    DrawioCLINotFoundError
+        If the executable cannot be found.
+    """
+    # 1. Explicit env override
+    env_path = os.environ.get("DRAWIO_PATH")
+    if env_path and Path(env_path).is_file():
+        return env_path
+
+    # 2. PATH lookup
+    for name in ("drawio", "draw.io"):
+        found = shutil.which(name)
+        if found:
+            return found
+
+    # 3. Platform default locations
+    platform = sys.platform
+    candidates = _DRAWIO_CANDIDATES.get(platform, [])
+    for raw in candidates:
+        expanded = Path(os.path.expandvars(raw))
+        if expanded.is_file():
+            return str(expanded)
+
+    install_hint = {
+        "win32":  "winget install JGraph.Draw",
+        "darwin": "brew install --cask drawio",
+        "linux":  "snap install drawio",
+    }.get(platform, "https://github.com/jgraph/drawio-desktop/releases")
+
+    raise DrawioCLINotFoundError(
+        "draw.io CLI not found.\n"
+        f"Install it with:  {install_hint}\n"
+        "Or set the DRAWIO_PATH environment variable to the executable path."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal PNG helpers
+# ---------------------------------------------------------------------------
+
+def _png_chunk(chunk_type: bytes, data: bytes) -> bytes:
+    """Build a PNG chunk: [4-byte length][4-byte type][data][4-byte CRC]."""
+    body = chunk_type + data
+    crc = zlib.crc32(body) & 0xFFFFFFFF
+    return struct.pack(">I", len(data)) + body + struct.pack(">I", crc)
+
+
+def _make_minimal_png() -> bytes:
+    """
+    Return a 1×1 white RGB PNG.
+
+    draw.io derives canvas dimensions from the embedded XML, not from the PNG
+    image size, so a 1×1 placeholder is sufficient when rendering is not needed.
+    """
+    PNG_SIG = b"\x89PNG\r\n\x1a\n"
+    ihdr_data = struct.pack(">IIBBBBB", 1, 1, 8, 2, 0, 0, 0)
+    ihdr = _png_chunk(b"IHDR", ihdr_data)
+    idat = _png_chunk(b"IDAT", zlib.compress(b"\x00\xff\xff\xff"))
+    iend = _png_chunk(b"IEND", b"")
+    return PNG_SIG + ihdr + idat + iend
+
+
+def _embed_text_chunk(png_bytes: bytes, keyword: str, text: str) -> bytes:
+    """
+    Insert a ``tEXt`` chunk immediately before the first ``IDAT`` chunk.
+
+    draw.io expects:
+      - chunk type  : ``tEXt``
+      - keyword     : ``"mxfile"``
+      - text value  : URL-encoded (UTF-8) mxfile XML  (ASCII only result)
+    """
+    sig = png_bytes[:8]
+    body = png_bytes[8:]
+    chunk_data = keyword.encode("ascii") + b"\x00" + text.encode("ascii")
+    text_chunk = _png_chunk(b"tEXt", chunk_data)
+    idat_type_offset = body.find(b"IDAT")
+    insert_at = max(idat_type_offset - 4, 0)
+    return sig + body[:insert_at] + text_chunk + body[insert_at:]
+
+
+def _encode_xml(drawio_path: str) -> str:
+    """Read a .drawio file and return its URL-encoded (UTF-8) content."""
+    with open(drawio_path, encoding="utf-8") as fh:
+        return quote(fh.read(), safe="", encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def drawio_to_png(drawio_path: str, output_path: str | None = None) -> str:
+    """
+    Embed a ``.drawio`` XML into a re-editable ``.drawio.png`` (no rendering).
+
+    The output is a valid PNG containing only a 1×1 white placeholder image,
+    but with the full diagram XML embedded in a ``tEXt[mxfile]`` chunk so
+    draw.io can restore it.  No external tools required.
+
+    For a visually rendered PNG use :func:`drawio_export` instead.
+
+    Parameters
+    ----------
+    drawio_path:
+        Path to the source ``.drawio`` file.
+    output_path:
+        Destination path.  Defaults to ``drawio_path + ".png"``.
+
+    Returns
+    -------
+    str
+        Path of the written ``.drawio.png`` file.
+    """
+    if output_path is None:
+        output_path = drawio_path + ".png"
+
+    encoded = _encode_xml(drawio_path)
+    png = _make_minimal_png()
+    png = _embed_text_chunk(png, "mxfile", encoded)
+
+    with open(output_path, "wb") as fh:
+        fh.write(png)
+
+    print(f"[make_drawio_png] {output_path}  ({len(png) / 1024:.1f} KB)  [embed only]")
+    return output_path
+
+
+def drawio_render_png(
+    drawio_path: str,
+    output_path: str | None = None,
+    *,
+    scale: float = 1.0,
+    quality: int = 100,
+    drawio_cli: str | None = None,
+) -> str:
+    """
+    Render a ``.drawio`` file to a PNG image using the draw.io CLI.
+
+    The output is a fully-rendered PNG image (not re-editable by draw.io).
+    For a re-editable rendered PNG use :func:`drawio_export` instead.
+
+    Requires draw.io desktop to be installed.
+
+    Parameters
+    ----------
+    drawio_path:
+        Path to the source ``.drawio`` file.
+    output_path:
+        Destination path.  Defaults to ``drawio_path`` with ``.png`` extension.
+    scale:
+        Export scale factor (default 1.0).
+    quality:
+        PNG quality hint passed to draw.io (default 100).
+    drawio_cli:
+        Path to the draw.io executable.  Auto-detected when omitted.
+
+    Returns
+    -------
+    str
+        Path of the written PNG file.
+
+    Raises
+    ------
+    DrawioCLINotFoundError
+        If draw.io CLI cannot be found.
+    subprocess.CalledProcessError
+        If the draw.io CLI exits with a non-zero status.
+    """
+    src = Path(drawio_path)
+    if output_path is None:
+        output_path = str(src.with_suffix(".png"))
+
+    cli = drawio_cli or find_drawio_cli()
+
+    cmd = [
+        cli,
+        "--export",
+        "--format", "png",
+        "--scale", str(scale),
+        "--quality", str(quality),
+        "--output", output_path,
+        str(src),
+    ]
+    subprocess.run(cmd, check=True, capture_output=True)
+
+    size_kb = Path(output_path).stat().st_size / 1024
+    print(f"[make_drawio_png] {output_path}  ({size_kb:.1f} KB)  [rendered]")
+    return output_path
+
+
+def drawio_export(
+    drawio_path: str,
+    output_path: str | None = None,
+    *,
+    scale: float = 1.0,
+    quality: int = 100,
+    drawio_cli: str | None = None,
+) -> str:
+    """
+    Render a ``.drawio`` file and embed the XML — producing a fully-rendered,
+    re-editable ``.drawio.png``.
+
+    This is the **recommended** function: it combines :func:`drawio_render_png`
+    (visual rendering via draw.io CLI) and :func:`drawio_to_png` (XML embedding)
+    into a single step.
+
+    Requires draw.io desktop to be installed.
+
+    Parameters
+    ----------
+    drawio_path:
+        Path to the source ``.drawio`` file.
+    output_path:
+        Destination path.  Defaults to ``drawio_path + ".png"``.
+    scale:
+        Export scale factor (default 1.0).
+    quality:
+        PNG quality hint (default 100).
+    drawio_cli:
+        Path to the draw.io executable.  Auto-detected when omitted.
+
+    Returns
+    -------
+    str
+        Path of the written ``.drawio.png`` file.
+
+    Raises
+    ------
+    DrawioCLINotFoundError
+        If draw.io CLI cannot be found.
+    """
+    if output_path is None:
+        output_path = drawio_path + ".png"
+
+    # Step 1: render to a temp file (draw.io replaces .drawio ext with .png)
+    src = Path(drawio_path)
+    rendered_path = str(src.with_suffix(".png"))
+
+    cli = drawio_cli or find_drawio_cli()
+    cmd = [
+        cli,
+        "--export",
+        "--format", "png",
+        "--scale", str(scale),
+        "--quality", str(quality),
+        "--output", rendered_path,
+        str(src),
+    ]
+    subprocess.run(cmd, check=True, capture_output=True)
+
+    # Step 2: embed the XML tEXt chunk into the rendered PNG
+    with open(rendered_path, "rb") as fh:
+        png_bytes = fh.read()
+
+    encoded = _encode_xml(drawio_path)
+    png_bytes = _embed_text_chunk(png_bytes, "mxfile", encoded)
+
+    with open(output_path, "wb") as fh:
+        fh.write(png_bytes)
+
+    # Clean up intermediate file if it differs from the final output
+    if Path(rendered_path).resolve() != Path(output_path).resolve():
+        Path(rendered_path).unlink(missing_ok=True)
+
+    size_kb = len(png_bytes) / 1024
+    print(f"[make_drawio_png] {output_path}  ({size_kb:.1f} KB)  [rendered + embedded]")
+    return output_path

make_drawio_png-0.1.0/src/make_drawio_png/__main__.py

@@ -0,0 +1,75 @@
+"""CLI entry point — invoked as ``make-drawio-png`` or ``python -m make_drawio_png``."""
+
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Shoichiro Sakaigawa
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from make_drawio_png import (
+    DrawioCLINotFoundError,
+    drawio_export,
+    drawio_to_png,
+    find_drawio_cli,
+    __version__,
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="make-drawio-png",
+        description=(
+            "Convert a .drawio XML file into a re-editable .drawio.png.\n\n"
+            "Modes:\n"
+            "  (default)  Embed only — XML embedded in tEXt chunk, 1x1 placeholder image.\n"
+            "             Zero dependencies. draw.io can restore the diagram.\n\n"
+            "  --render   Render + embed — draw.io CLI renders the diagram visually,\n"
+            "             then the XML is embedded. Requires draw.io desktop.\n"
+            "             Install: winget install JGraph.Draw  (Windows)\n"
+            "                      brew install --cask drawio  (macOS)\n"
+            "                      snap install drawio         (Linux)\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("input", help="Source .drawio file")
+    parser.add_argument("output", nargs="?", help="Output .drawio.png (default: <input>.png)")
+    parser.add_argument(
+        "--render", "-r",
+        action="store_true",
+        help="Use draw.io CLI to render a visual PNG before embedding XML",
+    )
+    parser.add_argument(
+        "--scale",
+        type=float,
+        default=1.0,
+        help="Render scale factor (default: 1.0, used with --render)",
+    )
+    parser.add_argument(
+        "--drawio-path",
+        metavar="PATH",
+        help="Path to draw.io executable (overrides DRAWIO_PATH env var)",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    args = parser.parse_args()
+
+    if args.render:
+        try:
+            cli = args.drawio_path or find_drawio_cli()
+        except DrawioCLINotFoundError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)
+        drawio_export(
+            args.input,
+            args.output,
+            scale=args.scale,
+            drawio_cli=cli,
+        )
+    else:
+        drawio_to_png(args.input, args.output)
+
+
+if __name__ == "__main__":
+    main()

make_drawio_png-0.1.0/tests/test_make_drawio_png.py

@@ -0,0 +1,262 @@
+"""Tests for make_drawio_png."""
+
+import os
+import struct
+import zlib
+from pathlib import Path
+from urllib.parse import unquote
+
+import pytest
+
+from make_drawio_png import (
+    DrawioCLINotFoundError,
+    __version__,
+    drawio_export,
+    drawio_render_png,
+    drawio_to_png,
+    find_drawio_cli,
+)
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+MINIMAL_DRAWIO = """\
+<mxfile host="app.diagrams.net">
+  <diagram id="test-diagram" name="Test">
+    <mxGraphModel>
+      <root>
+        <mxCell id="0"/>
+        <mxCell id="1" parent="0"/>
+        <mxCell id="2" value="Hello 日本語" style="rounded=1;" vertex="1" parent="1">
+          <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
+"""
+
+
+@pytest.fixture
+def drawio_file(tmp_path: Path) -> Path:
+    p = tmp_path / "test.drawio"
+    p.write_text(MINIMAL_DRAWIO, encoding="utf-8")
+    return p
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _read_png_chunks(data: bytes) -> list[tuple[str, bytes]]:
+    """Parse PNG into list of (chunk_type, chunk_data) tuples."""
+    chunks = []
+    assert data[:8] == b"\x89PNG\r\n\x1a\n", "Not a valid PNG signature"
+    i = 8
+    while i < len(data):
+        length = struct.unpack(">I", data[i : i + 4])[0]
+        chunk_type = data[i + 4 : i + 8].decode("ascii")
+        chunk_data = data[i + 8 : i + 8 + length]
+        chunks.append((chunk_type, chunk_data))
+        i += 12 + length
+    return chunks
+
+
+def _get_mxfile_xml(png_path: str) -> str:
+    """Extract and decode the mxfile XML embedded in a .drawio.png."""
+    data = Path(png_path).read_bytes()
+    chunks = _read_png_chunks(data)
+    text_chunks = [(t, d) for t, d in chunks if t == "tEXt"]
+    assert text_chunks, "No tEXt chunk found"
+    keyword, _, value = text_chunks[0][1].partition(b"\x00")
+    assert keyword == b"mxfile"
+    return unquote(value.decode("ascii"), encoding="utf-8")
+
+
+def _has_drawio_cli() -> bool:
+    try:
+        find_drawio_cli()
+        return True
+    except DrawioCLINotFoundError:
+        return False
+
+
+requires_drawio = pytest.mark.skipif(
+    not _has_drawio_cli(),
+    reason="draw.io CLI not installed (winget install JGraph.Draw / brew install --cask drawio)",
+)
+
+
+# ---------------------------------------------------------------------------
+# Tests: version
+# ---------------------------------------------------------------------------
+
+class TestVersion:
+    def test_version_string(self):
+        assert isinstance(__version__, str)
+        assert __version__.count(".") >= 1
+
+
+# ---------------------------------------------------------------------------
+# Tests: find_drawio_cli
+# ---------------------------------------------------------------------------
+
+class TestFindDrawioCli:
+    def test_env_var_override(self, tmp_path: Path):
+        fake_exe = tmp_path / "drawio.exe"
+        fake_exe.write_bytes(b"")
+        os.environ["DRAWIO_PATH"] = str(fake_exe)
+        try:
+            result = find_drawio_cli()
+            assert result == str(fake_exe)
+        finally:
+            del os.environ["DRAWIO_PATH"]
+
+    def test_not_found_raises(self, monkeypatch):
+        monkeypatch.delenv("DRAWIO_PATH", raising=False)
+        monkeypatch.setattr("shutil.which", lambda _: None)
+        # Patch candidates to empty so it always raises
+        import make_drawio_png as m
+        orig = m._DRAWIO_CANDIDATES
+        m._DRAWIO_CANDIDATES = {}
+        try:
+            with pytest.raises(DrawioCLINotFoundError):
+                find_drawio_cli()
+        finally:
+            m._DRAWIO_CANDIDATES = orig
+
+    @requires_drawio
+    def test_finds_installed_drawio(self):
+        path = find_drawio_cli()
+        assert Path(path).is_file()
+
+
+# ---------------------------------------------------------------------------
+# Tests: drawio_to_png (embed only)
+# ---------------------------------------------------------------------------
+
+class TestDrawioToPng:
+    def test_creates_output_file(self, drawio_file: Path):
+        result = drawio_to_png(str(drawio_file))
+        assert Path(result).exists()
+
+    def test_default_output_path(self, drawio_file: Path):
+        result = drawio_to_png(str(drawio_file))
+        assert Path(result) == drawio_file.parent / (drawio_file.name + ".png")
+
+    def test_explicit_output_path(self, drawio_file: Path, tmp_path: Path):
+        out = tmp_path / "custom.drawio.png"
+        result = drawio_to_png(str(drawio_file), str(out))
+        assert Path(result) == out
+        assert out.exists()
+
+    def test_output_is_valid_png(self, drawio_file: Path):
+        result = drawio_to_png(str(drawio_file))
+        assert Path(result).read_bytes()[:8] == b"\x89PNG\r\n\x1a\n"
+
+    def test_contains_mxfile_text_chunk(self, drawio_file: Path):
+        result = drawio_to_png(str(drawio_file))
+        xml = _get_mxfile_xml(result)
+        assert xml.startswith("<mxfile")
+
+    def test_embedded_xml_roundtrips(self, drawio_file: Path):
+        result = drawio_to_png(str(drawio_file))
+        assert _get_mxfile_xml(result) == MINIMAL_DRAWIO
+
+    def test_japanese_survives_roundtrip(self, drawio_file: Path):
+        result = drawio_to_png(str(drawio_file))
+        assert "日本語" in _get_mxfile_xml(result)
+
+    def test_text_chunk_before_idat(self, drawio_file: Path):
+        result = drawio_to_png(str(drawio_file))
+        chunks = _read_png_chunks(Path(result).read_bytes())
+        types = [t for t, _ in chunks]
+        assert types.index("tEXt") < types.index("IDAT")
+
+    def test_all_chunk_crcs_valid(self, drawio_file: Path):
+        result = drawio_to_png(str(drawio_file))
+        data = Path(result).read_bytes()
+        i = 8
+        while i < len(data):
+            length = struct.unpack(">I", data[i : i + 4])[0]
+            chunk_type = data[i + 4 : i + 8]
+            chunk_data = data[i + 8 : i + 8 + length]
+            stored = struct.unpack(">I", data[i + 8 + length : i + 12 + length])[0]
+            expected = zlib.crc32(chunk_type + chunk_data) & 0xFFFFFFFF
+            assert stored == expected, f"CRC mismatch in chunk {chunk_type}"
+            i += 12 + length
+
+    def test_ends_with_iend(self, drawio_file: Path):
+        result = drawio_to_png(str(drawio_file))
+        chunks = _read_png_chunks(Path(result).read_bytes())
+        assert chunks[-1][0] == "IEND"
+
+
+# ---------------------------------------------------------------------------
+# Tests: drawio_render_png (render only, requires draw.io CLI)
+# ---------------------------------------------------------------------------
+
+@requires_drawio
+class TestDrawioRenderPng:
+    def test_creates_rendered_png(self, drawio_file: Path):
+        out = str(drawio_file.with_suffix(".png"))
+        result = drawio_render_png(str(drawio_file), out)
+        assert Path(result).exists()
+        assert Path(result).stat().st_size > 1000  # real image, not placeholder
+
+    def test_output_is_valid_png(self, drawio_file: Path):
+        out = str(drawio_file.with_suffix(".png"))
+        result = drawio_render_png(str(drawio_file), out)
+        assert Path(result).read_bytes()[:8] == b"\x89PNG\r\n\x1a\n"
+
+    def test_no_mxfile_chunk(self, drawio_file: Path):
+        """drawio_render_png does NOT embed XML — that's drawio_export's job."""
+        out = str(drawio_file.with_suffix(".png"))
+        result = drawio_render_png(str(drawio_file), out)
+        chunks = _read_png_chunks(Path(result).read_bytes())
+        text_keywords = []
+        for t, d in chunks:
+            if t == "tEXt":
+                kw, _, _ = d.partition(b"\x00")
+                text_keywords.append(kw.decode("ascii", errors="replace"))
+        assert "mxfile" not in text_keywords
+
+
+# ---------------------------------------------------------------------------
+# Tests: drawio_export (render + embed, requires draw.io CLI)
+# ---------------------------------------------------------------------------
+
+@requires_drawio
+class TestDrawioExport:
+    def test_creates_drawio_png(self, drawio_file: Path):
+        result = drawio_export(str(drawio_file))
+        assert Path(result).exists()
+
+    def test_default_output_path(self, drawio_file: Path):
+        result = drawio_export(str(drawio_file))
+        assert Path(result) == drawio_file.parent / (drawio_file.name + ".png")
+
+    def test_output_is_valid_png(self, drawio_file: Path):
+        result = drawio_export(str(drawio_file))
+        assert Path(result).read_bytes()[:8] == b"\x89PNG\r\n\x1a\n"
+
+    def test_has_mxfile_text_chunk(self, drawio_file: Path):
+        result = drawio_export(str(drawio_file))
+        xml = _get_mxfile_xml(result)
+        assert xml.startswith("<mxfile")
+
+    def test_japanese_survives_roundtrip(self, drawio_file: Path):
+        result = drawio_export(str(drawio_file))
+        assert "日本語" in _get_mxfile_xml(result)
+
+    def test_rendered_image_is_not_placeholder(self, drawio_file: Path):
+        result = drawio_export(str(drawio_file))
+        assert Path(result).stat().st_size > 1000  # real rendered content
+
+    def test_text_chunk_before_idat(self, drawio_file: Path):
+        result = drawio_export(str(drawio_file))
+        chunks = _read_png_chunks(Path(result).read_bytes())
+        types = [t for t, _ in chunks]
+        assert types.index("tEXt") < types.index("IDAT")