scrybe-plugin-docx 0.4.0__tar.gz

scrybe_plugin_docx-0.4.0/PKG-INFO

@@ -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/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scrybe-plugin-docx"
+version = "0.4.0"
+description = "Scrybe plugin — render Markdown to Word (.docx) with embedded Mermaid PNGs"
+license = {text = "AGPL-3.0-or-later"}
+requires-python = ">=3.9"
+dependencies = [
+    "python-docx>=1.1",
+    "mistune>=3.0",
+    "Pillow>=10.0",
+    # Embeds the Mermaid source into rendered diagram PNGs (iTXt), so the
+    # PNGs in the .docx round-trip back to source via `scrybe_mermaid.extract`.
+    "scrybe-mermaid>=0.2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-mock>=3"]
+
+[project.scripts]
+scrybe-docx = "scrybe_plugin_docx.main:main"
+
+[project.urls]
+Homepage = "https://github.com/hartsock/scrybe"
+Issues = "https://github.com/hartsock/scrybe/issues/3"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["scrybe_plugin_docx*"]

scrybe_plugin_docx-0.4.0/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-0.4.0/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-0.4.0/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-0.4.0/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/scrybe_plugin_docx.egg-info/PKG-INFO

@@ -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/scrybe_plugin_docx.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+pyproject.toml
+scrybe_plugin_docx/__init__.py
+scrybe_plugin_docx/main.py
+scrybe_plugin_docx/mermaid.py
+scrybe_plugin_docx/renderer.py
+scrybe_plugin_docx.egg-info/PKG-INFO
+scrybe_plugin_docx.egg-info/SOURCES.txt
+scrybe_plugin_docx.egg-info/dependency_links.txt
+scrybe_plugin_docx.egg-info/entry_points.txt
+scrybe_plugin_docx.egg-info/requires.txt
+scrybe_plugin_docx.egg-info/top_level.txt
+tests/test_renderer.py

scrybe_plugin_docx-0.4.0/scrybe_plugin_docx.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

scrybe_plugin_docx-0.4.0/scrybe_plugin_docx.egg-info/entry_points.txt

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

scrybe_plugin_docx-0.4.0/scrybe_plugin_docx.egg-info/requires.txt

@@ -0,0 +1,8 @@
+python-docx>=1.1
+mistune>=3.0
+Pillow>=10.0
+scrybe-mermaid>=0.2
+
+[dev]
+pytest>=8
+pytest-mock>=3

scrybe_plugin_docx-0.4.0/scrybe_plugin_docx.egg-info/top_level.txt

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

scrybe_plugin_docx-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scrybe_plugin_docx-0.4.0/tests/test_renderer.py

@@ -0,0 +1,188 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright 2026 Shawn Hartsock and contributors
+
+"""Unit tests for scrybe_plugin_docx.renderer.
+
+Requires python-docx and mistune. Tests are skipped when deps are absent.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+docx = pytest.importorskip("docx", reason="python-docx not installed")
+mistune = pytest.importorskip("mistune", reason="mistune not installed")
+
+from scrybe_plugin_docx.renderer import MarkdownToDocx, _inline_text  # noqa: E402
+
+# ---------------------------------------------------------------------------
+# _inline_text helper
+# ---------------------------------------------------------------------------
+
+
+def test_inline_text_plain():
+    tokens = [{"type": "raw", "raw": "hello world"}]
+    assert _inline_text(tokens) == "hello world"
+
+
+def test_inline_text_nested_strong():
+    tokens = [
+        {"type": "raw", "raw": "foo "},
+        {"type": "strong", "children": [{"type": "raw", "raw": "bar"}]},
+    ]
+    assert _inline_text(tokens) == "foo bar"
+
+
+def test_inline_text_softline():
+    tokens = [
+        {"type": "raw", "raw": "a"},
+        {"type": "softline"},
+        {"type": "raw", "raw": "b"},
+    ]
+    assert _inline_text(tokens) == "a b"
+
+
+# ---------------------------------------------------------------------------
+# MarkdownToDocx.build()
+# ---------------------------------------------------------------------------
+
+
+def _build(md: str, **kwargs):
+    return MarkdownToDocx(md, **kwargs).build()
+
+
+def test_heading_level1():
+    doc = _build("# Hello")
+    paras = [p for p in doc.paragraphs if p.text.strip()]
+    assert paras[0].text == "Hello"
+    assert paras[0].style.name.startswith("Heading")
+
+
+def test_heading_levels():
+    doc = _build("# H1\n\n## H2\n\n### H3")
+    headings = [p for p in doc.paragraphs if p.text.strip()]
+    assert len(headings) == 3
+    assert headings[0].style.name == "Heading 1"
+    assert headings[1].style.name == "Heading 2"
+    assert headings[2].style.name == "Heading 3"
+
+
+def test_paragraph_plain():
+    doc = _build("Hello world.")
+    paras = [p for p in doc.paragraphs if p.text.strip()]
+    assert paras[0].text == "Hello world."
+
+
+def test_paragraph_bold_italic():
+    doc = _build("**bold** and *italic*")
+    p = next(p for p in doc.paragraphs if p.text.strip())
+    runs = [r for r in p.runs if r.text.strip()]
+    bold_runs = [r for r in runs if r.bold]
+    italic_runs = [r for r in runs if r.italic]
+    assert any(r.text == "bold" for r in bold_runs)
+    assert any(r.text == "italic" for r in italic_runs)
+
+
+def test_bullet_list():
+    doc = _build("- apple\n- banana\n- cherry")
+    list_paras = [p for p in doc.paragraphs if p.style.name == "List Bullet"]
+    assert len(list_paras) == 3
+    texts = [p.text for p in list_paras]
+    assert "apple" in texts
+    assert "cherry" in texts
+
+
+def test_ordered_list():
+    doc = _build("1. first\n2. second")
+    list_paras = [p for p in doc.paragraphs if p.style.name == "List Number"]
+    assert len(list_paras) == 2
+
+
+def test_code_block_monospace():
+    doc = _build("```python\nprint('hi')\n```")
+    paras = [p for p in doc.paragraphs if p.text.strip()]
+    assert any(p.text == "print('hi')" for p in paras)
+    code_para = next(p for p in paras if p.text == "print('hi')")
+    assert code_para.runs[0].font.name == "Courier New"
+
+
+def test_table():
+    md = "| A | B |\n|---|---|\n| 1 | 2 |"
+    doc = _build(md)
+    assert len(doc.tables) == 1
+    table = doc.tables[0]
+    assert table.cell(0, 0).text.strip() == "A"
+    assert table.cell(1, 1).text.strip() == "2"
+
+
+def test_mermaid_no_diagrams_fallback():
+    md = "```mermaid\ngraph TD; A-->B\n```"
+    doc = _build(md, render_diagrams=False)
+    paras = [p for p in doc.paragraphs if p.text.strip()]
+    assert any("A-->B" in p.text for p in paras)
+
+
+def test_mermaid_mmdc_unavailable_falls_back(monkeypatch):
+    """When mmdc is not on PATH, mermaid block falls back to monospace text."""
+    import scrybe_plugin_docx.mermaid as m
+    import scrybe_plugin_docx.renderer as r
+
+    def _raise(_):
+        raise m.MermaidUnavailable("no mmdc")
+
+    # renderer.py imports `render_mermaid_to_png` by value, so patch the name
+    # bound in the renderer module (patching the mermaid module's attribute
+    # would not affect the already-imported reference).
+    monkeypatch.setattr(r, "render_mermaid_to_png", _raise)
+
+    md = "```mermaid\ngraph TD; A-->B\n```"
+    doc = _build(md, render_diagrams=True)
+    paras = [p for p in doc.paragraphs if p.text.strip()]
+    assert any("A-->B" in p.text for p in paras)
+
+
+def test_empty_input():
+    doc = _build("")
+    # Should produce a Document without errors.
+    assert doc is not None
+
+
+def test_thematic_break():
+    doc = _build("above\n\n---\n\nbelow")
+    texts = [p.text for p in doc.paragraphs if p.text.strip()]
+    assert any("─" in t for t in texts)
+
+
+def test_inline_code():
+    doc = _build("use `config.toml` here")
+    p = next(p for p in doc.paragraphs if p.text.strip())
+    runs = {r.text: r for r in p.runs if r.text.strip()}
+    assert "config.toml" in runs
+    assert runs["config.toml"].font.name == "Courier New"
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def test_cli_stdin(tmp_path, monkeypatch):
+    import io, sys
+    from scrybe_plugin_docx.main import main
+
+    out = tmp_path / "out.docx"
+    monkeypatch.setattr(sys, "stdin", io.StringIO("# Title\n\nBody text."))
+    rc = main(["-o", str(out)])
+    assert rc == 0
+    assert out.exists()
+
+
+def test_cli_file_input(tmp_path):
+    from scrybe_plugin_docx.main import main
+
+    src = tmp_path / "input.md"
+    src.write_text("# Hello\n\nWorld.", encoding="utf-8")
+    out = tmp_path / "out.docx"
+    rc = main([str(src), "-o", str(out)])
+    assert rc == 0
+    assert out.exists()