athena-python-docx 0.1.0__py3-none-any.whl

docx/document.py

@@ -0,0 +1,335 @@
+"""Document class — mirrors python-docx's Document.
+
+Phase 1 supported methods:
+    .paragraphs        -> list[Paragraph]  (snapshot on access)
+    .tables            -> list[Table]
+    .add_paragraph(text, style=None) -> Paragraph
+    .add_heading(text, level=1) -> Paragraph
+    .add_table(rows, cols, style=None) -> Table
+    .add_picture(image_path_or_stream, width=None, height=None) -> None
+    .add_page_break() -> None
+    .save(path=None) -> None  (path ignored; always in-place)
+    .close() -> None
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import sys
+from typing import TYPE_CHECKING, BinaryIO
+
+from docx._batching import run_sync
+from docx.client import Session
+from docx.errors import DocumentClosedError, ValidationError
+
+if TYPE_CHECKING:
+    from docx.shared import Emu
+    from docx.table import Table
+    from docx.text.paragraph import Paragraph
+
+
+def _log_warn(msg: str) -> None:
+    print(f"[docx-sdk] WARN: {msg}", file=sys.stderr)
+
+
+class Document:
+    """A Word document backed by a Superdoc/Keryx Y.Doc.
+
+    Construct via :func:`docx.api.Document` (recommended) — do not
+    instantiate this class directly in user code.
+    """
+
+    def __init__(self, *, asset_id: str) -> None:
+        self._session: Session = Session(asset_id=asset_id)
+        self._saved: bool = False
+        self._closed: bool = False
+
+    # ---- Public properties ----
+
+    @property
+    def paragraphs(self) -> list["Paragraph"]:
+        """Return all paragraphs in document order.
+
+        python-docx returns a live list; we return a snapshot.
+        For a live-ish list, call this again.
+        """
+        from docx.text.paragraph import Paragraph
+
+        self._ensure_open()
+        blocks: list[dict] = run_sync(
+            self._session.doc.blocks.list({"type": "paragraph"}),
+        )
+        return [
+            Paragraph(session=self._session, node_id=b["nodeId"])
+            for b in blocks
+        ]
+
+    @property
+    def tables(self) -> list["Table"]:
+        """Return all tables in document order."""
+        from docx.table import Table
+
+        self._ensure_open()
+        find_result: dict = run_sync(
+            self._session.doc.find({"type": "table"}),
+        )
+        items: list[dict] = find_result.get("items", [])
+        return [
+            Table(session=self._session, node_id=item["address"]["nodeId"])
+            for item in items
+        ]
+
+    # ---- Append operations ----
+
+    def add_paragraph(
+        self,
+        text: str = "",
+        style: str | None = None,
+    ) -> "Paragraph":
+        """Append a new paragraph at the end of the document.
+
+        Args:
+            text: The paragraph text.
+            style: The paragraph style name (e.g. "Heading 1", "Normal").
+                   If None, uses the default style.
+
+        Returns:
+            The newly-created Paragraph.
+        """
+        from docx.text.paragraph import Paragraph
+
+        self._ensure_open()
+        md: str
+        if style and style.lower().startswith("heading"):
+            try:
+                level: int = int(style.rsplit(" ", 1)[-1])
+            except ValueError:
+                level = 1
+            md = f"{'#' * level} {text}\n\n"
+        else:
+            md = f"{text}\n\n"
+
+        result: dict = run_sync(
+            self._session.doc.insert(
+                {"value": md, "type": "markdown"},
+            ),
+        )
+        node_id: str = _extract_inserted_node_id(result, expected_type="paragraph")
+        if not node_id:
+            raise RuntimeError(
+                f"Superdoc did not return a nodeId for add_paragraph: {result!r}",
+            )
+        return Paragraph(session=self._session, node_id=node_id)
+
+    def add_heading(
+        self,
+        text: str = "",
+        level: int = 1,
+    ) -> "Paragraph":
+        """Append a heading (convenience over add_paragraph)."""
+        if not 0 <= level <= 9:
+            raise ValidationError(
+                f"level must be in 0..9; got {level}",
+            )
+        style: str = "Title" if level == 0 else f"Heading {level}"
+        return self.add_paragraph(text=text, style=style)
+
+    def add_table(
+        self,
+        rows: int,
+        cols: int,
+        style: str | None = None,
+    ) -> "Table":
+        """Append a table with the given dimensions."""
+        from docx.table import Table
+
+        self._ensure_open()
+        if rows < 1 or cols < 1:
+            raise ValidationError(
+                f"rows and cols must be >= 1; got rows={rows} cols={cols}",
+            )
+
+        result: dict = run_sync(
+            self._session.doc.create.table(
+                {"rows": rows, "cols": cols},
+            ),
+        )
+        result_data: dict = (
+            result.get("result", {}) if isinstance(result, dict) else {}
+        )
+        table_info: dict = (
+            result_data.get("table", {}) if isinstance(result_data, dict) else {}
+        )
+        node_id: str = str(table_info.get("nodeId", ""))
+        if not node_id:
+            raise RuntimeError(
+                f"Superdoc did not return a nodeId for add_table: {result!r}",
+            )
+
+        if style:
+            run_sync(
+                self._session.doc.tables.set_style(
+                    {"nodeId": node_id, "styleId": style},
+                ),
+            )
+            # Re-fetch nodeId — set_style may rotate it. Prefer matching the
+            # original id so concurrent table insertions from other editors
+            # don't cause us to pick up the wrong table. Only fall back to
+            # last-in-list (with a warning) when the original id is gone.
+            refetch: dict = run_sync(
+                self._session.doc.find({"type": "table"}),
+            )
+            items: list[dict] = refetch.get("items", [])
+            matched: bool = any(
+                isinstance(item, dict)
+                and item.get("address", {}).get("nodeId") == node_id
+                for item in items
+            )
+            if not matched and items:
+                last: dict = items[-1] if isinstance(items[-1], dict) else {}
+                new_id: str = str(last.get("address", {}).get("nodeId", ""))
+                if new_id:
+                    import sys
+                    print(
+                        f"[docx-sdk] WARN: add_table nodeId rotated after "
+                        f"set_style: {node_id} -> {new_id}",
+                        file=sys.stderr,
+                    )
+                    node_id = new_id
+
+        return Table(session=self._session, node_id=node_id)
+
+    def add_picture(
+        self,
+        image_path_or_stream: str | BinaryIO,
+        width: "Emu | int | None" = None,
+        height: "Emu | int | None" = None,
+    ) -> None:
+        """Append an inline image at the end of the document."""
+        self._ensure_open()
+
+        image_bytes: bytes
+        content_type: str = "image/png"
+        if isinstance(image_path_or_stream, str):
+            with open(image_path_or_stream, "rb") as f:
+                image_bytes = f.read()
+            lower: str = image_path_or_stream.lower()
+            if lower.endswith((".jpg", ".jpeg")):
+                content_type = "image/jpeg"
+            elif lower.endswith(".gif"):
+                content_type = "image/gif"
+            elif lower.endswith(".webp"):
+                content_type = "image/webp"
+        elif isinstance(image_path_or_stream, io.IOBase):
+            image_bytes = image_path_or_stream.read()
+        else:
+            raise TypeError(
+                "Expected path str or binary stream, "
+                f"got {type(image_path_or_stream).__name__}",
+            )
+
+        b64: str = base64.b64encode(image_bytes).decode("ascii")
+        data_uri: str = f"data:{content_type};base64,{b64}"
+
+        # Default 6-inch wide, proportional 4.5-inch tall at 96 DPI
+        # (python-docx uses image's intrinsic size; we don't have that here,
+        # so we default to a reasonable 6x4.5 inch rectangle)
+        w_px: float = _emu_to_px(width) if width is not None else 576.0
+        h_px: float = _emu_to_px(height) if height is not None else 432.0
+
+        run_sync(
+            self._session.doc.create.image(
+                {
+                    "src": data_uri,
+                    "size": {"width": w_px, "height": h_px},
+                    "at": {"kind": "documentEnd"},
+                },
+            ),
+        )
+
+    def add_page_break(self) -> None:
+        """Append a page break at the end of the document."""
+        self._ensure_open()
+        # Use form-feed character; Superdoc's markdown parser converts
+        # this to a <w:br w:type="page"/> in export.
+        run_sync(
+            self._session.doc.insert(
+                {"value": "\f", "type": "text"},
+            ),
+        )
+
+    # ---- Lifecycle ----
+
+    def save(self, path: str | None = None) -> None:  # noqa: ARG002
+        """Flush pending edits to Keryx.
+
+        `path` is accepted for python-docx parity but ignored — writes
+        are always in-place against the Y.Doc. Saving to a local file
+        is not supported in Phase 1 (use the Olympus UI's Export DOCX).
+        """
+        self._ensure_open()
+        run_sync(self._session.save(in_place=True))
+        self._saved = True
+
+    def close(self) -> None:
+        """Close the session. Not strictly needed (context-managed)."""
+        if self._closed:
+            return
+        try:
+            run_sync(self._session.close())
+        finally:
+            self._closed = True
+
+    def __enter__(self) -> "Document":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:  # noqa: ANN001
+        if exc_type is None and not self._saved and self._session.is_open:
+            try:
+                self.save()
+            except Exception as e:
+                _log_warn(f"autosave failed for {self._session.asset_id}: {e}")
+        self.close()
+
+    # ---- Internals ----
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise DocumentClosedError(
+                f"Document {self._session.asset_id} is closed.",
+            )
+        if not self._session.is_open:
+            run_sync(self._session.open())
+
+
+# ---- Module-level helpers ----
+
+def _extract_inserted_node_id(result: dict, *, expected_type: str) -> str:
+    """Parse Superdoc's insert() response to find the new nodeId.
+
+    Superdoc rotates response shape across versions. Defensively probe.
+    """
+    if not isinstance(result, dict):
+        return ""
+    data_obj: object = result.get("result", {})
+    data: dict = data_obj if isinstance(data_obj, dict) else {}
+    nodes_obj: object = data.get("insertedNodes", data.get("nodes", []))
+    nodes: list = nodes_obj if isinstance(nodes_obj, list) else []
+    for node in nodes:
+        if not isinstance(node, dict):
+            continue
+        if node.get("type") == expected_type:
+            return str(node.get("nodeId", ""))
+    if nodes and isinstance(nodes[-1], dict):
+        return str(nodes[-1].get("nodeId", ""))
+    return ""
+
+
+def _emu_to_px(emu: object) -> float:
+    """EMU → px at 96 DPI. 914400 EMU = 1 inch.
+
+    Accepts Emu/Inches/Pt subclasses (all of which are int) or plain int.
+    """
+    val: float = float(emu) if not hasattr(emu, "emu") else float(emu.emu)  # type: ignore[union-attr]
+    return val / 914400.0 * 96.0

docx/enum/__init__.py

@@ -0,0 +1 @@
+"""Enum submodule — mirrors python-docx.enum."""

docx/enum/table.py

@@ -0,0 +1,15 @@
+"""Table-related enums — python-docx parity (docx.enum.table).
+
+Phase 1 includes only WD_ROW_HEIGHT_RULE as a placeholder; Phase 2 will
+expand to WD_CELL_VERTICAL_ALIGNMENT, WD_TABLE_ALIGNMENT, etc.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class WD_ROW_HEIGHT_RULE(Enum):
+    AUTO = "auto"
+    AT_LEAST = "atLeast"
+    EXACTLY = "exact"

docx/enum/text.py

@@ -0,0 +1,29 @@
+"""Paragraph alignment — python-docx parity (docx.enum.text).
+
+python-docx exposes a richer set (DISTRIBUTE, THAI_JUSTIFY, etc.). Phase 1
+implements the top 4 (LEFT, CENTER, RIGHT, JUSTIFY) — the others return
+None from the getter and accept-but-no-op on the setter.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class WD_ALIGN_PARAGRAPH(Enum):
+    """Paragraph alignment. python-docx exposes these exact names."""
+
+    LEFT = "left"
+    CENTER = "center"
+    RIGHT = "right"
+    JUSTIFY = "justify"
+
+    def to_superdoc(self) -> str:
+        return self.value
+
+    @classmethod
+    def from_superdoc(cls, s: str) -> "WD_ALIGN_PARAGRAPH | None":
+        try:
+            return cls(s.lower())
+        except ValueError:
+            return None

docx/errors.py

@@ -0,0 +1,30 @@
+"""Exception types for athena-python-docx."""
+
+from __future__ import annotations
+
+
+class DocxError(Exception):
+    """Base class for all athena-python-docx errors."""
+
+
+class SessionError(DocxError):
+    """Raised when the Superdoc SDK session cannot be established or used."""
+
+
+class AuthenticationError(SessionError):
+    """Raised when Keryx rejects the collab token."""
+
+
+class UnsupportedProviderError(SessionError):
+    """Raised when the asset is on ysweet instead of yhub.
+
+    Phase 1 only supports yhub; ysweet-routed assets must be migrated first.
+    """
+
+
+class DocumentClosedError(DocxError):
+    """Raised when operating on a closed Document."""
+
+
+class ValidationError(DocxError):
+    """Raised when SDK-level validation fails (bad args, out-of-range indices)."""

docx/shared.py

@@ -0,0 +1,81 @@
+"""Length and color types — python-docx parity.
+
+python-docx defines these in docx.shared. We mirror the class surface,
+but delegate underlying math (Inches→Emu, Pt→Emu) to simple formulas.
+"""
+
+from __future__ import annotations
+
+
+class Emu(int):
+    """English Metric Unit. 914400 EMU = 1 inch."""
+
+    def __new__(cls, value: int | float) -> "Emu":
+        return super().__new__(cls, int(value))
+
+    @property
+    def emu(self) -> int:
+        return int(self)
+
+    @property
+    def inches(self) -> float:
+        return int(self) / 914400
+
+    @property
+    def cm(self) -> float:
+        return int(self) / 360000
+
+    @property
+    def mm(self) -> float:
+        return int(self) / 36000
+
+    @property
+    def pt(self) -> float:
+        return int(self) / 12700
+
+
+class Inches(Emu):
+    def __new__(cls, value: float) -> "Inches":
+        return super().__new__(cls, int(value * 914400))  # type: ignore[return-value]
+
+
+class Pt(Emu):
+    def __new__(cls, value: float) -> "Pt":
+        return super().__new__(cls, int(value * 12700))  # type: ignore[return-value]
+
+
+class Cm(Emu):
+    def __new__(cls, value: float) -> "Cm":
+        return super().__new__(cls, int(value * 360000))  # type: ignore[return-value]
+
+
+class Mm(Emu):
+    def __new__(cls, value: float) -> "Mm":
+        return super().__new__(cls, int(value * 36000))  # type: ignore[return-value]
+
+
+class RGBColor(tuple):
+    """24-bit RGB color. python-docx parity."""
+
+    def __new__(cls, r: int, g: int, b: int) -> "RGBColor":
+        if not all(0 <= v <= 255 for v in (r, g, b)):
+            raise ValueError(
+                f"RGBColor components must be 0..255; got ({r}, {g}, {b})",
+            )
+        return super().__new__(cls, (r, g, b))  # type: ignore[arg-type]
+
+    def __str__(self) -> str:
+        r, g, b = self
+        return f"{r:02X}{g:02X}{b:02X}"
+
+    def __repr__(self) -> str:
+        return f"RGBColor(0x{self[0]:02X}, 0x{self[1]:02X}, 0x{self[2]:02X})"
+
+    @classmethod
+    def from_string(cls, rgb_hex_str: str) -> "RGBColor":
+        s: str = rgb_hex_str.lstrip("#")
+        if len(s) != 6:
+            raise ValueError(
+                f"RGBColor.from_string expects 6 hex chars; got {rgb_hex_str!r}",
+            )
+        return cls(int(s[0:2], 16), int(s[2:4], 16), int(s[4:6], 16))