athena-python-docx 0.1.2__tar.gz → 0.1.5__tar.gz

{athena_python_docx-0.1.2 → athena_python_docx-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.1.2
+Version: 0.1.5
 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.2 → athena_python_docx-0.1.5}/docx/__init__.py

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

{athena_python_docx-0.1.2 → athena_python_docx-0.1.5}/docx/client.py

@@ -172,20 +172,28 @@ class Session:
             )
         return self._doc_handle
 
-    async def save(self, *, in_place: bool = True) -> None:
-        """Flush pending mutations to Keryx and persist.
-
-        The AsyncSuperDocClient writes over WebSocket; we add a short
-        flush delay (matches superdoc_write_utils.py:227-237) to
-        ensure updates land before dispose().
+    async def save(self, *, in_place: bool = True) -> None:  # noqa: ARG002
+        """Ensure pending mutations have flushed to Keryx.
+
+        In collab mode (our only mode), the Y-Websocket provider streams
+        updates to Keryx as they happen — there's no explicit save RPC
+        to call. The underlying Superdoc SDK's ``save({"inPlace": True})``
+        targets file-backed docs and errors with "this session has no
+        source path" for collab sessions. So save() is a thin flush:
+        sleep briefly so in-flight WebSocket frames land, then return.
+
+        The ``in_place`` kwarg is accepted for python-docx parity but
+        has no effect in collab mode (there is no alternate target).
         """
         if not self._opened:
             raise SessionError("Cannot save a session that was never opened.")
         if self._closed:
             raise DocumentClosedError(f"Session {self._asset_id} is closed.")
 
-        await self._doc_handle.save({"inPlace": in_place})
-        _log_info(f"Saved {self._asset_id}")
+        # Short flush — matches superdoc_write_utils.py's 1-second pre-close
+        # delay. Keeps a single in-flight frame from being dropped on close.
+        await asyncio.sleep(1)
+        _log_info(f"Saved (flushed) {self._asset_id}")
 
     async def close(self) -> None:
         """Close the Superdoc session. Idempotent."""

{athena_python_docx-0.1.2 → athena_python_docx-0.1.5}/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.2 → athena_python_docx-0.1.5}/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},
                 },
             ),
         )

athena_python_docx-0.1.5/docx/text/paragraph.py

@@ -0,0 +1,152 @@
+"""Paragraph — mirrors python-docx's Paragraph class.
+
+Phase 1 supported:
+    .text (getter, via doc.get_node_by_id)
+
+Phase 1 NOT supported (raises NotImplementedError with a clear message):
+    .text setter       — Superdoc has no direct block-text replace
+    .runs              — returns []; iterating post-hoc runs requires
+                         a node-content walker we haven't built yet
+    .style getter      — works via get_node_by_id
+    .style setter      — uses doc.styles.paragraph.set_style
+    .alignment get/set — no direct Superdoc equivalent wired yet
+    .add_run(text)     — works via doc.insert with target at end of block
+
+All stubs point at the follow-up design note in CLAUDE.md so agents
+see actionable errors instead of opaque AttributeErrors from the
+underlying SDK.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docx._batching import run_sync
+
+if TYPE_CHECKING:
+    from docx.client import Session
+    from docx.enum.text import WD_ALIGN_PARAGRAPH
+    from docx.text.run import Run
+
+
+_STUB_SUFFIX = (
+    " — not yet mapped to a Superdoc SDK primitive; see "
+    "docx-studio/python-sdk/CLAUDE.md for Phase 2 scope."
+)
+
+
+def _node_text(session: "Session", node_id: str) -> str:
+    """Fetch a block's full text via doc.get_node_by_id."""
+    info: object = run_sync(
+        session.doc.get_node_by_id({"id": node_id}),
+    )
+    if not isinstance(info, dict):
+        return ""
+    node: object = info.get("node")
+    if isinstance(node, dict):
+        text: object = node.get("text")
+        if isinstance(text, str):
+            return text
+    return ""
+
+
+class Paragraph:
+    """A paragraph block in a Word document."""
+
+    def __init__(self, *, session: "Session", node_id: str) -> None:
+        self._session: "Session" = session
+        self._node_id: str = node_id
+
+    @property
+    def text(self) -> str:
+        """Return the plain-text content of this paragraph."""
+        return _node_text(self._session, self._node_id)
+
+    @text.setter
+    def text(self, value: str) -> None:  # noqa: ARG002
+        raise NotImplementedError(
+            "Paragraph.text setter" + _STUB_SUFFIX,
+        )
+
+    @property
+    def runs(self) -> list["Run"]:
+        """Return the runs in this paragraph.
+
+        Returns `[]` until the Phase 2 node-content walker lands.
+        """
+        return []
+
+    @property
+    def style(self) -> str | None:
+        info: object = run_sync(
+            self._session.doc.get_node_by_id({"id": self._node_id}),
+        )
+        if not isinstance(info, dict):
+            return None
+        node: object = info.get("node")
+        if not isinstance(node, dict):
+            return None
+        style_id: object = node.get("styleId") or node.get("style")
+        return str(style_id) if style_id else None
+
+    @style.setter
+    def style(self, value: str | None) -> None:
+        target: dict = {
+            "kind": "block",
+            "nodeType": "paragraph",
+            "nodeId": self._node_id,
+        }
+        run_sync(
+            self._session.doc.styles.paragraph.set_style(
+                {"target": target, "styleId": value or "Normal"},
+            ),
+        )
+
+    @property
+    def alignment(self) -> "WD_ALIGN_PARAGRAPH | None":
+        raise NotImplementedError(
+            "Paragraph.alignment getter" + _STUB_SUFFIX,
+        )
+
+    @alignment.setter
+    def alignment(self, value: "WD_ALIGN_PARAGRAPH | None") -> None:  # noqa: ARG002
+        raise NotImplementedError(
+            "Paragraph.alignment setter" + _STUB_SUFFIX,
+        )
+
+    def add_run(
+        self,
+        text: str = "",
+        style: str | None = None,  # noqa: ARG002
+    ) -> "Run":
+        """Append a run to this paragraph.
+
+        Inserts `text` at the END of the block via doc.insert with a
+        block-targeted range. Returns a Run proxy that references the
+        newly-inserted character span.
+        """
+        from docx.text.run import Run
+
+        # Fetch the block's current text to know where "end of block" is.
+        current: str = _node_text(self._session, self._node_id)
+        start: int = len(current)
+
+        # Insert at end of the block. The insert params support targeting
+        # a block + offset: {blockId, start, end} at top level where start==end
+        # means an insertion point (not a range).
+        run_sync(
+            self._session.doc.insert(
+                {
+                    "value": text,
+                    "type": "text",
+                    "blockId": self._node_id,
+                    "start": start,
+                    "end": start,
+                },
+            ),
+        )
+        return Run(
+            session=self._session,
+            block_id=self._node_id,
+            range_=(start, start + len(text)),
+        )

{athena_python_docx-0.1.2 → athena_python_docx-0.1.5}/docx/text/run.py

@@ -1,4 +1,15 @@
-"""Run and Font — matches python-docx's run.Run and text.font.Font."""
+"""Run and Font — mirrors python-docx's run.Run and text.font.Font.
+
+Phase 1 supported:
+    Run.text  getter — via doc.get_node_by_id, sliced by range
+    Run.text  setter — via doc.replace (exists)
+    Run.bold / italic / underline setters — via doc.format.apply (exists)
+    Font.name / size / color.rgb setters  — via doc.format.apply
+
+Phase 1 NOT supported (NotImplementedError with a clear message):
+    Run.bold / italic / underline getters   — needs inline-format reader
+    Font.name / size / color.rgb getters    — needs inline-format reader
+"""
 
 from __future__ import annotations
 
@@ -11,6 +22,26 @@ 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 _block_text(session: "Session", block_id: str) -> str:
+    info: object = run_sync(
+        session.doc.get_node_by_id({"id": block_id}),
+    )
+    if not isinstance(info, dict):
+        return ""
+    node: object = info.get("node")
+    if isinstance(node, dict):
+        text: object = node.get("text")
+        if isinstance(text, str):
+            return text
+    return ""
+
+
 class Run:
     """A text run — a contiguous span with uniform formatting."""
 
@@ -35,12 +66,7 @@ class Run:
 
     @property
     def text(self) -> str:
-        block_obj: object = run_sync(
-            self._session.doc.blocks.get({"nodeId": self._block_id}),
-        )
-        full: str = (
-            str(block_obj.get("text", "")) if isinstance(block_obj, dict) else ""
-        )
+        full: str = _block_text(self._session, self._block_id)
         return full[self._range[0] : self._range[1]]
 
     @text.setter
@@ -62,7 +88,7 @@ class Run:
 
     @property
     def bold(self) -> bool | None:
-        return self._get_inline_bool("bold")
+        raise NotImplementedError("Run.bold getter" + _STUB_SUFFIX)
 
     @bold.setter
     def bold(self, value: bool | None) -> None:
@@ -72,7 +98,7 @@ class Run:
 
     @property
     def italic(self) -> bool | None:
-        return self._get_inline_bool("italic")
+        raise NotImplementedError("Run.italic getter" + _STUB_SUFFIX)
 
     @italic.setter
     def italic(self, value: bool | None) -> None:
@@ -82,7 +108,7 @@ class Run:
 
     @property
     def underline(self) -> bool | None:
-        return self._get_inline_bool("underline")
+        raise NotImplementedError("Run.underline getter" + _STUB_SUFFIX)
 
     @underline.setter
     def underline(self, value: bool | None) -> None:
@@ -94,42 +120,16 @@ class Run:
     def font(self) -> "Font":
         return Font(self)
 
-    def _get_inline_bool(self, name: str) -> bool | None:
-        block_obj: object = run_sync(
-            self._session.doc.blocks.get({"nodeId": self._block_id}),
-        )
-        if not isinstance(block_obj, dict):
-            return None
-        inline_obj: object = block_obj.get("inline", {})
-        if not isinstance(inline_obj, dict):
-            return None
-        val: object = inline_obj.get(name)
-        return val if isinstance(val, bool) else None
-
 
 class Font:
-    """Font properties of a Run.
-
-    Accessed via `run.font`; do not instantiate directly.
-    """
+    """Font properties of a Run. Accessed via `run.font`; do not instantiate."""
 
     def __init__(self, run: Run) -> None:
         self._run: Run = run
 
-    def _get_inline(self) -> dict:
-        block_obj: object = run_sync(
-            self._run._session.doc.blocks.get({"nodeId": self._run._block_id}),
-        )
-        if not isinstance(block_obj, dict):
-            return {}
-        inline_obj: object = block_obj.get("inline", {})
-        return inline_obj if isinstance(inline_obj, dict) else {}
-
     @property
     def name(self) -> str | None:
-        inline: dict = self._get_inline()
-        value: str = str(inline.get("fontFamily", ""))
-        return value or None
+        raise NotImplementedError("Font.name getter" + _STUB_SUFFIX)
 
     @name.setter
     def name(self, value: str | None) -> None:
@@ -139,11 +139,7 @@ class Font:
 
     @property
     def size(self) -> "Pt | None":
-        inline: dict = self._get_inline()
-        sz: object = inline.get("fontSize")
-        if isinstance(sz, (int, float)):
-            return Pt(float(sz))
-        return None
+        raise NotImplementedError("Font.size getter" + _STUB_SUFFIX)
 
     @size.setter
     def size(self, value: "Pt | int | None") -> None:
@@ -160,25 +156,14 @@ class Font:
 
 
 class _ColorProxy:
-    """Matches python-docx's `run.font.color` property, which returns a
-    ColorFormat object with `.rgb` get/set.
-    """
+    """Matches python-docx's `run.font.color` — has .rgb get/set."""
 
     def __init__(self, run: Run) -> None:
         self._run: Run = run
 
     @property
     def rgb(self) -> "RGBColor | None":
-        block_obj: object = run_sync(
-            self._run._session.doc.blocks.get({"nodeId": self._run._block_id}),
-        )
-        if not isinstance(block_obj, dict):
-            return None
-        inline_obj: object = block_obj.get("inline", {})
-        if not isinstance(inline_obj, dict):
-            return None
-        hex_: str = str(inline_obj.get("color", ""))
-        return RGBColor.from_string(hex_) if hex_ else None
+        raise NotImplementedError("Font.color.rgb getter" + _STUB_SUFFIX)
 
     @rgb.setter
     def rgb(self, value: "RGBColor | None") -> None:

{athena_python_docx-0.1.2 → athena_python_docx-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.1.2"
+version = "0.1.5"
 description = "Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack"
 readme = "README.md"
 license = "MIT"

athena_python_docx-0.1.2/docx/text/paragraph.py

@@ -1,141 +0,0 @@
-"""Paragraph — mirrors python-docx's Paragraph class.
-
-Phase 1 surface:
-    .text (get/set)
-    .runs -> list[Run]  (returns empty list in Phase 1 — Phase 2 will implement)
-    .style (get/set)
-    .alignment (get/set)
-    .add_run(text, bold=None, italic=None, ...) -> Run
-"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from docx._batching import run_sync
-from docx.enum.text import WD_ALIGN_PARAGRAPH
-
-if TYPE_CHECKING:
-    from docx.client import Session
-    from docx.text.run import Run
-
-
-class Paragraph:
-    """A paragraph block in a Word document."""
-
-    def __init__(self, *, session: "Session", node_id: str) -> None:
-        self._session: "Session" = session
-        self._node_id: str = node_id
-
-    @property
-    def text(self) -> str:
-        """Return the plain-text content of this paragraph."""
-        block_obj: object = run_sync(
-            self._session.doc.blocks.get({"nodeId": self._node_id}),
-        )
-        if not isinstance(block_obj, dict):
-            return ""
-        return str(block_obj.get("text", ""))
-
-    @text.setter
-    def text(self, value: str) -> None:
-        """Replace the entire text content of this paragraph."""
-        run_sync(
-            self._session.doc.blocks.update_text(
-                {"nodeId": self._node_id, "text": value},
-            ),
-        )
-
-    @property
-    def runs(self) -> list["Run"]:
-        """Return the runs in this paragraph.
-
-        Phase 1: returns an empty list. Superdoc's block model doesn't
-        expose a runs accessor on individual paragraphs in the current
-        SDK version; iterating them would require a custom JSON walker.
-        Phase 2 will implement this.
-        """
-        return []
-
-    @property
-    def style(self) -> str | None:
-        block_obj: object = run_sync(
-            self._session.doc.blocks.get({"nodeId": self._node_id}),
-        )
-        if not isinstance(block_obj, dict):
-            return None
-        style_id: str = str(block_obj.get("styleId", ""))
-        return style_id or None
-
-    @style.setter
-    def style(self, value: str | None) -> None:
-        run_sync(
-            self._session.doc.blocks.set_style(
-                {"nodeId": self._node_id, "styleId": value or "Normal"},
-            ),
-        )
-
-    @property
-    def alignment(self) -> "WD_ALIGN_PARAGRAPH | None":
-        block_obj: object = run_sync(
-            self._session.doc.blocks.get({"nodeId": self._node_id}),
-        )
-        if not isinstance(block_obj, dict):
-            return None
-        raw: str = str(block_obj.get("alignment", ""))
-        return WD_ALIGN_PARAGRAPH.from_superdoc(raw) if raw else None
-
-    @alignment.setter
-    def alignment(self, value: "WD_ALIGN_PARAGRAPH | None") -> None:
-        sd_value: str = (
-            value.to_superdoc() if value is not None else "left"
-        )
-        run_sync(
-            self._session.doc.format.set_alignment(
-                {
-                    "target": {"kind": "block", "nodeId": self._node_id},
-                    "value": sd_value,
-                },
-            ),
-        )
-
-    def add_run(
-        self,
-        text: str = "",
-        style: str | None = None,  # noqa: ARG002
-    ) -> "Run":
-        """Append a run to this paragraph and return it.
-
-        Strategy: append text at the end of the paragraph, then return
-        a Run proxy targeting that character range.
-
-        Args:
-            text: The text content of the new run.
-            style: Ignored in Phase 1 (python-docx parity — accepts the
-                   kwarg but has no-op behavior until Superdoc exposes
-                   run-style references).
-        """
-        from docx.text.run import Run
-
-        # Get current length to compute range start
-        block_obj: object = run_sync(
-            self._session.doc.blocks.get({"nodeId": self._node_id}),
-        )
-        current_text: str = (
-            str(block_obj.get("text", "")) if isinstance(block_obj, dict) else ""
-        )
-        range_start: int = len(current_text)
-
-        # Append text to the block
-        run_sync(
-            self._session.doc.blocks.append_text(
-                {"nodeId": self._node_id, "text": text},
-            ),
-        )
-        range_end: int = range_start + len(text)
-
-        return Run(
-            session=self._session,
-            block_id=self._node_id,
-            range_=(range_start, range_end),
-        )