athena-python-docx 0.1.3__tar.gz → 0.1.6__tar.gz

{athena_python_docx-0.1.3 → athena_python_docx-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.1.3
+Version: 0.1.6
 Summary: Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>

{athena_python_docx-0.1.3 → athena_python_docx-0.1.6}/docx/__init__.py

@@ -6,7 +6,7 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.1.3"
+__version__ = "0.1.6"
 
 from docx.api import Document
 

{athena_python_docx-0.1.3 → athena_python_docx-0.1.6}/docx/document.py

@@ -51,19 +51,37 @@ class Document:
     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.
+        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"}),
+        # doc.blocks.list takes `nodeTypes: list[str]` (not `type: str`).
+        # Include "heading" too so iterating over paragraphs covers both —
+        # python-docx does not distinguish headings from paragraphs at the
+        # Document.paragraphs level either (they're all Paragraph instances).
+        raw: object = run_sync(
+            self._session.doc.blocks.list(
+                {"nodeTypes": ["paragraph", "heading"], "includeText": True},
+            ),
         )
-        return [
-            Paragraph(session=self._session, node_id=b["nodeId"])
-            for b in blocks
-        ]
+        # Real shape: {"blocks": [{"kind":"block","nodeType":..,"nodeId":..,"text":..}], ...}
+        if isinstance(raw, dict):
+            blocks_obj: object = raw.get("blocks", [])
+            blocks: list = blocks_obj if isinstance(blocks_obj, list) else []
+        elif isinstance(raw, list):
+            blocks = raw
+        else:
+            blocks = []
+        out: list["Paragraph"] = []
+        for b in blocks:
+            if not isinstance(b, dict):
+                continue
+            node_id: str = str(b.get("nodeId", ""))
+            if node_id:
+                out.append(Paragraph(session=self._session, node_id=node_id))
+        return out
 
     @property
     def tables(self) -> list["Table"]:
@@ -101,48 +119,29 @@ class Document:
 
         self._ensure_open()
 
-        # Superdoc's markdown parser rejects empty input with
-        # "Markdown produced no content to insert." For an empty paragraph
-        # (python-docx's `doc.add_paragraph()` with no args), we use the
-        # text-type insert with a single space and immediately clear it —
-        # same pattern as `agora/web/api/super_docs/superdoc_write_utils.py`
-        # around line 1085.
-        result: dict
-        node_id: str
-        if not text and not (style and style.lower().startswith("heading")):
-            result = run_sync(
-                self._session.doc.insert(
-                    {"value": " ", "type": "text"},
-                ),
-            )
-            node_id = _extract_inserted_node_id(result, expected_type="paragraph")
-            if node_id:
-                # Clear the placeholder space so the paragraph reads as empty
-                # (matches python-docx semantics: a freshly-added blank paragraph
-                # has empty `.text`).
-                run_sync(
-                    self._session.doc.blocks.update_text(
-                        {"nodeId": node_id, "text": ""},
-                    ),
-                )
-        else:
-            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 = run_sync(
-                self._session.doc.insert(
-                    {"value": md, "type": "markdown"},
-                ),
-            )
-            node_id = _extract_inserted_node_id(result, expected_type="paragraph")
-
+        # Use Superdoc's canonical primitive `doc.create.paragraph`. It
+        # accepts an `at` anchor and a `text` body; an empty `text` creates
+        # a truly-empty paragraph (no markdown-parser edge case).
+        #
+        # For heading styles we still dispatch to add_heading, which uses
+        # `doc.create.heading` (also canonical, takes `level`).
+        if style and style.lower().startswith("heading"):
+            try:
+                level: int = int(style.rsplit(" ", 1)[-1])
+            except ValueError:
+                level = 1
+            return self.add_heading(text=text, level=level)
+        if style and style.lower() == "title":
+            return self.add_heading(text=text, level=0)
+
+        params: dict = {
+            "text": text,
+            "at": {"kind": "documentEnd"},
+        }
+        result: dict = run_sync(
+            self._session.doc.create.paragraph(params),
+        )
+        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}",
@@ -154,13 +153,33 @@ class Document:
         text: str = "",
         level: int = 1,
     ) -> "Paragraph":
-        """Append a heading (convenience over add_paragraph)."""
+        """Append a heading via Superdoc's canonical `doc.create.heading`."""
+        from docx.text.paragraph import Paragraph
+
+        self._ensure_open()
         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)
+
+        # Map level 0 → Title, 1..9 → Heading N. create.heading understands
+        # level directly (level=0 means Title in python-docx semantics; Superdoc
+        # accepts levels 1..9 for HeadingN and may interpret 0 as Title depending
+        # on version — we pass level as-is).
+        params: dict = {
+            "text": text,
+            "level": level if level >= 1 else 1,
+            "at": {"kind": "documentEnd"},
+        }
+        result: dict = run_sync(
+            self._session.doc.create.heading(params),
+        )
+        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_heading: {result!r}",
+            )
+        return Paragraph(session=self._session, node_id=node_id)
 
     def add_table(
         self,
@@ -168,7 +187,7 @@ class Document:
         cols: int,
         style: str | None = None,
     ) -> "Table":
-        """Append a table with the given dimensions."""
+        """Append a table with the given dimensions via `doc.create.table`."""
         from docx.table import Table
 
         self._ensure_open()
@@ -177,18 +196,18 @@ class Document:
                 f"rows and cols must be >= 1; got rows={rows} cols={cols}",
             )
 
+        # The real param is `columns` (not `cols`). `at` is required to
+        # position the table; we always append to document end.
         result: dict = run_sync(
             self._session.doc.create.table(
-                {"rows": rows, "cols": cols},
+                {
+                    "rows": rows,
+                    "columns": cols,
+                    "at": {"kind": "documentEnd"},
+                },
             ),
         )
-        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", ""))
+        node_id: str = _extract_inserted_node_id(result, expected_type="table")
         if not node_id:
             raise RuntimeError(
                 f"Superdoc did not return a nodeId for add_table: {result!r}",
@@ -201,9 +220,7 @@ class Document:
                 ),
             )
             # 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.
+            # original id; fall back to last-in-list with a warning.
             refetch: dict = run_sync(
                 self._session.doc.find({"type": "table"}),
             )
@@ -233,7 +250,7 @@ class Document:
         width: "Emu | int | None" = None,
         height: "Emu | int | None" = None,
     ) -> None:
-        """Append an inline image at the end of the document."""
+        """Append an inline image via `doc.create.image`."""
         self._ensure_open()
 
         image_bytes: bytes
@@ -259,9 +276,6 @@ class Document:
         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
 
@@ -276,13 +290,16 @@ class Document:
         )
 
     def add_page_break(self) -> None:
-        """Append a page break at the end of the document."""
+        """Append a page break at the end of the document.
+
+        Uses `doc.create.section_break` with OOXML `breakType="nextPage"`,
+        which is the canonical hard page break (what python-docx's
+        ``add_page_break()`` produces).
+        """
         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"},
+            self._session.doc.create.section_break(
+                {"at": {"kind": "documentEnd"}, "breakType": "nextPage"},
             ),
         )
 
@@ -333,29 +350,32 @@ class Document:
 # ---- Module-level helpers ----
 
 def _extract_inserted_node_id(result: dict, *, expected_type: str) -> str:
-    """Parse Superdoc's insert() response to find the relevant blockId.
-
-    Superdoc rotates response shapes across versions; we probe in order
-    of "most current" first. Real observed shape (superdoc-sdk 1.6.0.dev29):
-
-        {
-          "receipt": {
-            "resolution": {
-              "target": {"kind": "text", "blockId": "<uuid>", "range": {...}}
-            }
-          },
-          ...
-        }
+    """Parse Superdoc create/insert response to find the new node's blockId.
 
-    Older/alternate shapes we also accept:
-      - top-level ``blockId``
-      - nested ``result.insertedNodes[].nodeId`` (when typed = expected_type)
-      - last element of ``result.nodes``
+    Real observed shapes (superdoc-sdk 1.6.0.dev29):
+
+      doc.create.paragraph/heading/table returns
+          {"success": True, "<paragraph|heading|table>": {"nodeId": "..."}}
+
+      doc.insert (markdown/text) returns
+          {"receipt": {"resolution": {"target": {"blockId": "..."}}}, ...}
+
+    We probe create-shape first (nested by expected_type), then insert-shape.
+    Returns "" if nothing matches.
     """
     if not isinstance(result, dict):
         return ""
 
-    # Shape 1 (current): receipt.resolution.target.blockId
+    # Shape 1 — doc.create.paragraph/heading/table/image: top-level key
+    # named by the result type holds `{kind, nodeType, nodeId}`.
+    for key in (expected_type, "paragraph", "heading", "table", "image"):
+        obj = result.get(key)
+        if isinstance(obj, dict):
+            node_id = obj.get("nodeId")
+            if isinstance(node_id, str) and node_id:
+                return node_id
+
+    # Shape 2 — doc.insert: receipt.resolution.target.blockId.
     receipt: object = result.get("receipt")
     if isinstance(receipt, dict):
         resolution: object = receipt.get("resolution")
@@ -366,7 +386,7 @@ def _extract_inserted_node_id(result: dict, *, expected_type: str) -> str:
                 if block_id:
                     return block_id
 
-    # Shape 2: top-level blockId or target.blockId
+    # Shape 3 — top-level blockId or target.blockId.
     top_block: object = result.get("blockId")
     if isinstance(top_block, str) and top_block:
         return top_block
@@ -376,7 +396,7 @@ def _extract_inserted_node_id(result: dict, *, expected_type: str) -> str:
         if tb:
             return tb
 
-    # Shape 3 (legacy): nested result.result.insertedNodes[] / nodes[]
+    # Shape 4 (legacy): nested result.result.insertedNodes[] / nodes[].
     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", []))

{athena_python_docx-0.1.3 → athena_python_docx-0.1.6}/docx/table.py

@@ -1,11 +1,16 @@
 """Table, _Row, _Column, _Cell — python-docx parity.
 
-Phase 1 surface:
-    Table.rows, Table.columns, Table.cell(row_idx, col_idx)
-    Table.add_row(), Table.add_column()
-    Table.style (get/set)
-    _Cell.text (get/set)
-    _Cell.merge(other_cell)
+Phase 1 supported:
+    Table.rows / columns      — via doc.tables.get
+    Table.cell(r, c)          — builds a _Cell proxy (lazy)
+    Table.add_row / add_column — via doc.tables.insert_row / insert_column
+    Table.style setter         — via doc.tables.set_style
+    _Cell.text getter          — via doc.tables.get_cells (filtered)
+    _Cell.merge(other)         — via doc.tables.merge_cells
+
+Phase 1 NOT supported (NotImplementedError):
+    Table.style getter         — via doc.tables.getStyles/getProperties
+    _Cell.text setter          — needs find+replace-in-cell design
 """
 
 from __future__ import annotations
@@ -20,6 +25,12 @@ if TYPE_CHECKING:
     from docx.client import Session
 
 
+_STUB_SUFFIX = (
+    " — not yet mapped to a Superdoc SDK primitive; see "
+    "docx-studio/python-sdk/CLAUDE.md for Phase 2 scope."
+)
+
+
 def _log_warn(msg: str) -> None:
     print(f"[docx-sdk] WARN: {msg}", file=sys.stderr)
 
@@ -30,26 +41,28 @@ class Table:
         self._node_id: str = node_id
 
     def _fresh_node_id(self) -> str:
-        """Re-find this table by its position. Superdoc rotates nodeIds
-        after style/option changes (see superdoc_write_utils.py:942-948).
-        """
-        find_result: dict = run_sync(
+        """Re-find this table by its original nodeId first; warn+last-in-list
+        as a last resort (set_style etc. can rotate ids)."""
+        find_result: object = run_sync(
             self._session.doc.find({"type": "table"}),
         )
-        items: list[dict] = find_result.get("items", [])
+        items_obj: object = (
+            find_result.get("items", []) if isinstance(find_result, dict) else []
+        )
+        items: list = items_obj if isinstance(items_obj, list) else []
         for item in items:
-            addr: dict = item.get("address", {}) if isinstance(item, dict) else {}
-            if addr.get("nodeId") == self._node_id:
+            if not isinstance(item, dict):
+                continue
+            addr = item.get("address", {})
+            if isinstance(addr, dict) and addr.get("nodeId") == self._node_id:
                 return self._node_id
-        # Not found by exact id — trust the LAST table as ours, with a warning
         if items:
-            last_addr: dict = (
-                items[-1].get("address", {}) if isinstance(items[-1], dict) else {}
-            )
+            last = items[-1] if isinstance(items[-1], dict) else {}
+            last_addr = last.get("address", {}) if isinstance(last, dict) else {}
             new_id: str = str(last_addr.get("nodeId", ""))
             if new_id:
                 _log_warn(
-                    f"Table nodeId rotated: {self._node_id} -> {new_id}",
+                    f"table nodeId rotated: {self._node_id} -> {new_id}",
                 )
                 self._node_id = new_id
         return self._node_id
@@ -57,21 +70,29 @@ class Table:
     @property
     def rows(self) -> list["_Row"]:
         nid: str = self._fresh_node_id()
-        info_obj: object = run_sync(
-            self._session.doc.tables.get({"nodeId": nid}),
+        info: object = run_sync(self._session.doc.tables.get({"nodeId": nid}))
+        info_dict: dict = info if isinstance(info, dict) else {}
+        # doc.tables.get may return row count at various paths
+        row_count: int = int(
+            info_dict.get("rows")
+            or info_dict.get("rowCount")
+            or (info_dict.get("table", {}) or {}).get("rows")
+            or 0,
         )
-        info: dict = info_obj if isinstance(info_obj, dict) else {}
-        row_count: int = int(info.get("rows", 0))
         return [_Row(table=self, index=i) for i in range(row_count)]
 
     @property
     def columns(self) -> list["_Column"]:
         nid: str = self._fresh_node_id()
-        info_obj: object = run_sync(
-            self._session.doc.tables.get({"nodeId": nid}),
+        info: object = run_sync(self._session.doc.tables.get({"nodeId": nid}))
+        info_dict: dict = info if isinstance(info, dict) else {}
+        col_count: int = int(
+            info_dict.get("columns")
+            or info_dict.get("cols")
+            or info_dict.get("columnCount")
+            or (info_dict.get("table", {}) or {}).get("columns")
+            or 0,
         )
-        info: dict = info_obj if isinstance(info_obj, dict) else {}
-        col_count: int = int(info.get("cols", 0))
         return [_Column(table=self, index=j) for j in range(col_count)]
 
     def cell(self, row_idx: int, col_idx: int) -> "_Cell":
@@ -81,15 +102,15 @@ class Table:
         nid: str = self._fresh_node_id()
         row_count: int = len(self.rows)
         if row_count < 1:
-            raise ValidationError(
-                f"Cannot add row to empty table {nid}",
-            )
+            raise ValidationError(f"Cannot add row to empty table {nid}")
+        # Real params: nodeId, rowIndex, position, count
         run_sync(
             self._session.doc.tables.insert_row(
                 {
-                    "tableNodeId": nid,
+                    "nodeId": nid,
                     "rowIndex": row_count - 1,
                     "position": "below",
+                    "count": 1,
                 },
             ),
         )
@@ -99,15 +120,14 @@ class Table:
         nid: str = self._fresh_node_id()
         col_count: int = len(self.columns)
         if col_count < 1:
-            raise ValidationError(
-                f"Cannot add column to empty table {nid}",
-            )
+            raise ValidationError(f"Cannot add column to empty table {nid}")
         run_sync(
             self._session.doc.tables.insert_column(
                 {
-                    "tableNodeId": nid,
+                    "nodeId": nid,
                     "columnIndex": col_count - 1,
                     "position": "right",
+                    "count": 1,
                 },
             ),
         )
@@ -115,13 +135,7 @@ class Table:
 
     @property
     def style(self) -> str | None:
-        nid: str = self._fresh_node_id()
-        info_obj: object = run_sync(
-            self._session.doc.tables.get({"nodeId": nid}),
-        )
-        info: dict = info_obj if isinstance(info_obj, dict) else {}
-        style_id: str = str(info.get("styleId", ""))
-        return style_id or None
+        raise NotImplementedError("Table.style getter" + _STUB_SUFFIX)
 
     @style.setter
     def style(self, value: str | None) -> None:
@@ -170,28 +184,30 @@ class _Cell:
     @property
     def text(self) -> str:
         nid: str = self._table._fresh_node_id()
-        cell_obj: object = run_sync(
-            self._table._session.doc.tables.get_cell(
-                {"tableNodeId": nid, "row": self._row, "col": self._col},
+        result: object = run_sync(
+            self._table._session.doc.tables.get_cells(
+                {
+                    "nodeId": nid,
+                    "rowIndex": self._row,
+                    "columnIndex": self._col,
+                },
             ),
         )
-        if not isinstance(cell_obj, dict):
+        if not isinstance(result, dict):
+            return ""
+        cells_obj: object = result.get("cells", result.get("items", []))
+        cells: list = cells_obj if isinstance(cells_obj, list) else []
+        if not cells or not isinstance(cells[0], dict):
             return ""
-        return str(cell_obj.get("text", ""))
+        first = cells[0]
+        text: object = first.get("text")
+        if isinstance(text, str):
+            return text
+        return ""
 
     @text.setter
-    def text(self, value: str) -> None:
-        nid: str = self._table._fresh_node_id()
-        run_sync(
-            self._table._session.doc.tables.update_cell_text(
-                {
-                    "tableNodeId": nid,
-                    "row": self._row,
-                    "col": self._col,
-                    "text": value,
-                },
-            ),
-        )
+    def text(self, value: str) -> None:  # noqa: ARG002
+        raise NotImplementedError("_Cell.text setter" + _STUB_SUFFIX)
 
     def merge(self, other: "_Cell") -> "_Cell":
         if other._table is not self._table:
@@ -202,11 +218,9 @@ class _Cell:
         run_sync(
             self._table._session.doc.tables.merge_cells(
                 {
-                    "tableNodeId": nid,
-                    "startRow": self._row,
-                    "startCol": self._col,
-                    "endRow": other._row,
-                    "endCol": other._col,
+                    "nodeId": nid,
+                    "start": {"rowIndex": self._row, "columnIndex": self._col},
+                    "end": {"rowIndex": other._row, "columnIndex": other._col},
                 },
             ),
         )