scrybe-plugin-docx 0.4.0__py3-none-any.whl

scrybe_plugin_docx/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright 2026 Shawn Hartsock and contributors
+
+from .renderer import MarkdownToDocx
+
+__all__ = ["MarkdownToDocx"]

scrybe_plugin_docx/main.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright 2026 Shawn Hartsock and contributors
+
+"""scrybe-docx — render Markdown to a Word (.docx) file.
+
+Usage:
+    scrybe-docx [INPUT] -o OUTPUT [--no-diagrams]
+    cat file.md | scrybe-docx -o output.docx
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .renderer import MarkdownToDocx
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="scrybe-docx",
+        description="Render a Markdown file to Word (.docx) with embedded Mermaid diagrams.",
+    )
+    parser.add_argument(
+        "input",
+        nargs="?",
+        type=Path,
+        metavar="FILE",
+        help="Input Markdown file (default: stdin).",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=Path("output.docx"),
+        metavar="OUTPUT",
+        help="Output .docx path (default: output.docx).",
+    )
+    parser.add_argument(
+        "--no-diagrams",
+        action="store_true",
+        help="Skip Mermaid rendering; keep fenced blocks as monospace text.",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.input:
+        source = args.input.read_text(encoding="utf-8")
+    else:
+        source = sys.stdin.read()
+
+    try:
+        doc = MarkdownToDocx(source, render_diagrams=not args.no_diagrams).build()
+    except ImportError as exc:
+        print(f"error: missing dependency — {exc}", file=sys.stderr)
+        print("  pip install scrybe-plugin-docx", file=sys.stderr)
+        return 1
+
+    doc.save(args.output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scrybe_plugin_docx/mermaid.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright 2026 Shawn Hartsock and contributors
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+class MermaidUnavailable(Exception):
+    pass
+
+
+def render_mermaid_to_png(source: str) -> bytes:
+    """Render a Mermaid diagram source string to PNG bytes via the mmdc CLI."""
+    mmdc = shutil.which("mmdc")
+    if mmdc is None:
+        raise MermaidUnavailable(
+            "mmdc not found on PATH. Install @mermaid-js/mermaid-cli "
+            "(`npm install -g @mermaid-js/mermaid-cli`) or use --no-diagrams."
+        )
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        src = Path(tmpdir) / "diagram.mmd"
+        out = Path(tmpdir) / "diagram.png"
+        src.write_text(source, encoding="utf-8")
+
+        result = subprocess.run(
+            [mmdc, "-i", str(src), "-o", str(out)],
+            capture_output=True,
+            timeout=60,
+        )
+        if result.returncode != 0:
+            raise MermaidUnavailable(
+                f"mmdc exited {result.returncode}: {result.stderr.decode(errors='replace')}"
+            )
+        return out.read_bytes()

scrybe_plugin_docx/renderer.py

@@ -0,0 +1,253 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright 2026 Shawn Hartsock and contributors
+
+"""MarkdownToDocx — walk a mistune 3.x AST and emit a python-docx Document."""
+
+from __future__ import annotations
+
+import io
+import os
+from typing import TYPE_CHECKING
+
+from docx import Document
+from docx.shared import Inches, Pt
+
+from .mermaid import MermaidUnavailable, render_mermaid_to_png
+
+if TYPE_CHECKING:
+    from docx.text.paragraph import Paragraph
+
+
+class MarkdownToDocx:
+    """Convert a Markdown string to a python-docx Document.
+
+    Args:
+        source: Markdown source text.
+        render_diagrams: When True (default), Mermaid fenced blocks are
+            rendered to PNG via mmdc and embedded as images. When False
+            (or when mmdc is unavailable), the fenced block is kept as a
+            monospace code block.
+    """
+
+    def __init__(self, source: str, *, render_diagrams: bool = True) -> None:
+        self.source = source
+        self.render_diagrams = render_diagrams
+
+    def build(self) -> Document:
+        import mistune  # deferred so the module can be imported for type-checking
+
+        doc = Document()
+        md = mistune.create_markdown(renderer="ast", plugins=["table"])
+        tokens = md(self.source) or []
+        _BlockVisitor(doc, render_diagrams=self.render_diagrams).visit_all(tokens)
+        return doc
+
+
+# ---------------------------------------------------------------------------
+# Internal AST visitors
+# ---------------------------------------------------------------------------
+
+
+class _BlockVisitor:
+    def __init__(self, doc: Document, *, render_diagrams: bool) -> None:
+        self.doc = doc
+        self.render_diagrams = render_diagrams
+
+    def visit_all(self, tokens: list[dict]) -> None:
+        for token in tokens:
+            self._visit(token)
+
+    def _visit(self, token: dict) -> None:
+        t = token.get("type", "")
+        handler = getattr(self, f"_on_{t}", None)
+        if handler:
+            handler(token)
+
+    # --- block handlers ---
+
+    def _on_heading(self, token: dict) -> None:
+        level = token.get("attrs", {}).get("level", 1)
+        text = _inline_text(token.get("children", []))
+        self.doc.add_heading(text, level=level)
+
+    def _on_paragraph(self, token: dict) -> None:
+        children = token.get("children", [])
+        # A lone image in a paragraph gets its own picture paragraph.
+        if len(children) == 1 and children[0].get("type") == "image":
+            self._embed_image(children[0])
+            return
+        p = self.doc.add_paragraph()
+        _InlineVisitor(p).visit_all(children)
+
+    def _on_block_code(self, token: dict) -> None:
+        info = (token.get("attrs") or {}).get("info") or ""
+        lang = info.split()[0] if info else ""
+        # mistune's block_code raw includes a trailing newline; strip it so
+        # the rendered paragraph text matches the source faithfully.
+        code = token.get("raw", "").rstrip("\n")
+
+        if lang == "mermaid" and self.render_diagrams:
+            self._render_mermaid(code)
+            return
+
+        p = self.doc.add_paragraph()
+        run = p.add_run(code)
+        run.font.name = "Courier New"
+        run.font.size = Pt(9)
+
+    def _on_list(self, token: dict) -> None:
+        ordered = (token.get("attrs") or {}).get("ordered", False)
+        for item in token.get("children", []):
+            self._on_list_item(item, ordered=ordered)
+
+    def _on_list_item(self, token: dict, *, ordered: bool = False) -> None:
+        style = "List Number" if ordered else "List Bullet"
+        p = self.doc.add_paragraph(style=style)
+        for child in token.get("children", []):
+            ct = child.get("type", "")
+            if ct in ("paragraph", "block_text"):
+                # mistune emits `block_text` for list-item content in tight
+                # lists and `paragraph` in loose lists; both wrap inline runs.
+                _InlineVisitor(p).visit_all(child.get("children", []))
+            else:
+                # Nested block inside list item — recurse.
+                self._visit(child)
+
+    def _on_block_quote(self, token: dict) -> None:
+        self.visit_all(token.get("children", []))
+
+    def _on_table(self, token: dict) -> None:
+        children = token.get("children", [])
+        head_tok = next((c for c in children if c.get("type") == "table_head"), None)
+        body_tok = next((c for c in children if c.get("type") == "table_body"), None)
+
+        # mistune's table plugin puts table_cells directly inside table_head
+        # (no intermediate row wrapper) but wraps body cells in table_row.
+        # Normalize so head and body have the same shape: list[row] where
+        # row.children == list[cell].
+        head_rows = [head_tok] if head_tok else []
+        body_rows = (body_tok or {}).get("children", [])
+        all_rows = head_rows + body_rows
+        if not all_rows:
+            return
+
+        num_cols = len(all_rows[0].get("children", []))
+        if num_cols == 0:
+            return
+
+        table = self.doc.add_table(rows=len(all_rows), cols=num_cols)
+        table.style = "Table Grid"
+
+        for row_idx, row_tok in enumerate(all_rows):
+            for col_idx, cell_tok in enumerate(row_tok.get("children", [])):
+                if col_idx < num_cols:
+                    table.cell(row_idx, col_idx).text = _inline_text(
+                        cell_tok.get("children", [])
+                    )
+
+    def _on_thematic_break(self, token: dict) -> None:  # noqa: ARG002
+        self.doc.add_paragraph("─" * 40)
+
+    def _on_blank_line(self, token: dict) -> None:  # noqa: ARG002
+        pass
+
+    # --- helpers ---
+
+    def _embed_image(self, token: dict) -> None:
+        url = (token.get("attrs") or {}).get("url", "")
+        alt = (token.get("attrs") or {}).get("alt", url)
+        if url and os.path.exists(url):
+            try:
+                self.doc.add_picture(url, width=Inches(5.5))
+                return
+            except Exception:
+                pass
+        self.doc.add_paragraph(f"[Image: {alt}]")
+
+    def _render_mermaid(self, source: str) -> None:
+        try:
+            png = render_mermaid_to_png(source)
+            png = _embed_mermaid_source(png, source)
+            self.doc.add_picture(io.BytesIO(png), width=Inches(5.5))
+        except MermaidUnavailable:
+            # Fall back to monospace block.
+            p = self.doc.add_paragraph()
+            run = p.add_run(source)
+            run.font.name = "Courier New"
+            run.font.size = Pt(9)
+
+
+class _InlineVisitor:
+    """Adds formatted runs to an existing paragraph."""
+
+    def __init__(self, paragraph: Paragraph) -> None:
+        self.p = paragraph
+
+    def visit_all(self, tokens: list[dict]) -> None:
+        for token in tokens:
+            self._visit(token, bold=False, italic=False)
+
+    def _visit(self, token: dict, *, bold: bool, italic: bool) -> None:
+        t = token.get("type", "")
+        if t in ("text", "raw"):
+            self._run(token.get("raw", ""), bold=bold, italic=italic)
+        elif t == "strong":
+            for child in token.get("children", []):
+                self._visit(child, bold=True, italic=italic)
+        elif t == "emphasis":
+            for child in token.get("children", []):
+                self._visit(child, bold=bold, italic=True)
+        elif t == "codespan":
+            run = self._run(token.get("raw", ""), bold=bold, italic=italic)
+            run.font.name = "Courier New"
+        elif t == "link":
+            # Render link text; URL is lost (Word hyperlinks require COM/OPC manipulation).
+            for child in token.get("children", []):
+                self._visit(child, bold=bold, italic=italic)
+        elif t in ("softline", "softbreak", "linebreak"):
+            self._run(" ", bold=False, italic=False)
+        elif t == "image":
+            alt = (token.get("attrs") or {}).get("alt", "")
+            self._run(f"[{alt}]", bold=False, italic=False)
+
+    def _run(self, text: str, *, bold: bool, italic: bool):
+        run = self.p.add_run(text)
+        run.bold = bold
+        run.italic = italic
+        return run
+
+
+def _embed_mermaid_source(png: bytes, source: str) -> bytes:
+    """Embed the Mermaid source into the PNG's iTXt metadata, round-trippable
+    via `scrybe_mermaid.extract`. Falls back to the unmodified PNG if the
+    `scrybe_mermaid` binding (or its embed step) is unavailable, so export
+    never fails just because the codec is missing.
+    """
+    try:
+        import scrybe_mermaid
+
+        return scrybe_mermaid.embed(png, source)
+    except Exception:
+        return png
+
+
+def _inline_text(tokens: list[dict]) -> str:
+    """Extract plain text from inline tokens (no formatting).
+
+    mistune 3.x emits inline text as `{"type": "text", "raw": "..."}`.
+    Earlier versions used `"type": "raw"` — accept both for resilience.
+    """
+    parts: list[str] = []
+    for tok in tokens:
+        t = tok.get("type", "")
+        if t in ("text", "raw"):
+            parts.append(tok.get("raw", ""))
+        elif t in ("strong", "emphasis", "link"):
+            parts.append(_inline_text(tok.get("children", [])))
+        elif t == "codespan":
+            parts.append(tok.get("raw", ""))
+        elif t in ("softline", "softbreak", "linebreak"):
+            parts.append(" ")
+        elif t == "image":
+            parts.append((tok.get("attrs") or {}).get("alt", ""))
+    return "".join(parts)

scrybe_plugin_docx-0.4.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: scrybe-plugin-docx
+Version: 0.4.0
+Summary: Scrybe plugin — render Markdown to Word (.docx) with embedded Mermaid PNGs
+License: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/hartsock/scrybe
+Project-URL: Issues, https://github.com/hartsock/scrybe/issues/3
+Requires-Python: >=3.9
+Requires-Dist: python-docx>=1.1
+Requires-Dist: mistune>=3.0
+Requires-Dist: Pillow>=10.0
+Requires-Dist: scrybe-mermaid>=0.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-mock>=3; extra == "dev"

scrybe_plugin_docx-0.4.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+scrybe_plugin_docx/__init__.py,sha256=0ucqCxYnaNdCWb03a88CgDxaQOWqHalbU8LO9e6Du3k,162
+scrybe_plugin_docx/main.py,sha256=U_zDMPlKs6VCFk2vhXwWRuJ9EvY7MVrRoUTStNrfdjo,1669
+scrybe_plugin_docx/mermaid.py,sha256=vKFaEfoTFcJRhvkXYEBxVZZtS0DVcA8anR7sGqjLHTE,1145
+scrybe_plugin_docx/renderer.py,sha256=sX3Q9Vk-mA0lx6pIerEUddYJL7k7dGlRmy9VmCqnhg4,9429
+scrybe_plugin_docx-0.4.0.dist-info/METADATA,sha256=5zkR_rBd7zhHbTvQyvuyZdmsHvDsO7z-Tlg7oxGwGoY,551
+scrybe_plugin_docx-0.4.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+scrybe_plugin_docx-0.4.0.dist-info/entry_points.txt,sha256=1zQk0h2afzURDEP2f3wr78hEST-g4XL7EyHDiwONWTo,61
+scrybe_plugin_docx-0.4.0.dist-info/top_level.txt,sha256=s4hjnsr-do2xhgn1GEmg0DBK8Jj8SNFcH-XjT6EKszE,19
+scrybe_plugin_docx-0.4.0.dist-info/RECORD,,

scrybe_plugin_docx-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

scrybe_plugin_docx-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scrybe-docx = scrybe_plugin_docx.main:main

scrybe_plugin_docx-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+scrybe_plugin_docx