athena-python-docx 0.2.0__tar.gz → 0.2.2__tar.gz

{athena_python_docx-0.2.0 → athena_python_docx-0.2.2}/PKG-INFO

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

@@ -6,11 +6,21 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 from docx.api import Document
+# Re-exports python-docx ships at docx top-level for convenience.
+from docx.shared import Emu, Inches, Pt, Cm, Mm, Twips, Length, RGBColor
 
 __all__ = [
     "Document",
+    "Emu",
+    "Inches",
+    "Pt",
+    "Cm",
+    "Mm",
+    "Twips",
+    "Length",
+    "RGBColor",
     "__version__",
 ]

{athena_python_docx-0.2.0 → athena_python_docx-0.2.2}/docx/document.py

@@ -22,9 +22,15 @@ from typing import TYPE_CHECKING, BinaryIO
 from docx._batching import run_sync
 from docx.client import Session
 from docx.errors import DocumentClosedError, ValidationError
+# python-docx re-exports a subset of symbols at docx.document; mirror those
+# so `from docx.document import Emu` etc. works.
+from docx.enum.section import WD_SECTION, WD_SECTION_START  # noqa: F401
+from docx.enum.text import WD_BREAK  # noqa: F401
+from docx.section import Section, Sections  # noqa: F401
+from docx.shared import Cm, Emu, Inches, Length, Mm, Pt, RGBColor, Twips  # noqa: F401
+from docx.text.run import Run  # noqa: F401
 
 if TYPE_CHECKING:
-    from docx.shared import Emu
     from docx.table import Table
     from docx.text.paragraph import Paragraph
 
@@ -80,7 +86,15 @@ class Document:
                 continue
             node_id: str = str(b.get("nodeId", ""))
             if node_id:
-                out.append(Paragraph(session=self._session, node_id=node_id))
+                nt_raw = b.get("nodeType")
+                nt: str = nt_raw if isinstance(nt_raw, str) and nt_raw else "paragraph"
+                out.append(
+                    Paragraph(
+                        session=self._session,
+                        node_id=node_id,
+                        node_type=nt,
+                    ),
+                )
         return out
 
     @property
@@ -204,7 +218,9 @@ class Document:
             raise RuntimeError(
                 f"Superdoc did not return a nodeId for add_paragraph: {result!r}",
             )
-        return Paragraph(session=self._session, node_id=node_id)
+        return Paragraph(
+            session=self._session, node_id=node_id, node_type="paragraph",
+        )
 
     def add_heading(
         self,
@@ -239,7 +255,11 @@ class Document:
                 raise RuntimeError(
                     f"Superdoc did not return a nodeId for add_heading(level=0): {result!r}",
                 )
-            paragraph = Paragraph(session=self._session, node_id=node_id)
+            paragraph = Paragraph(
+                session=self._session,
+                node_id=node_id,
+                node_type="paragraph",
+            )
             paragraph.style = "Title"
             return paragraph
 
@@ -251,12 +271,17 @@ class Document:
         result = run_sync(
             self._session.doc.create.heading(params),
         )
-        node_id = _extract_inserted_node_id(result, expected_type="paragraph")
+        # Bug fix: was passing expected_type="paragraph" here (wrong); the
+        # fallback loop recovered but the code of intent was wrong. Fixed to
+        # expected_type="heading" so we extract from the correct response key.
+        node_id = _extract_inserted_node_id(result, expected_type="heading")
         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)
+        return Paragraph(
+            session=self._session, node_id=node_id, node_type="heading",
+        )
 
     def add_table(
         self,

{athena_python_docx-0.2.0 → athena_python_docx-0.2.2}/docx/enum/text.py

@@ -113,6 +113,15 @@ class WD_BREAK(Enum):
     LINE_CLEAR_RIGHT = "lineClearRight"
     LINE_CLEAR_ALL = "lineClearAll"
     TEXT_WRAPPING = "textWrapping"
+    # python-docx 1.x also exposes section breaks via WD_BREAK
+    SECTION_CONTINUOUS = "sectionContinuous"
+    SECTION_EVEN_PAGE = "sectionEvenPage"
+    SECTION_NEXT_PAGE = "sectionNextPage"
+    SECTION_ODD_PAGE = "sectionOddPage"
+
+
+# python-docx internal alias
+WD_BREAK_TYPE = WD_BREAK
 
 
 class WD_UNDERLINE(Enum):
@@ -137,6 +146,7 @@ class WD_UNDERLINE(Enum):
 
 
 class WD_COLOR_INDEX(Enum):
+    INHERITED = "inherit"
     AUTO = "default"
     BLACK = "black"
     BLUE = "blue"
@@ -156,5 +166,12 @@ class WD_COLOR_INDEX(Enum):
     YELLOW = "yellow"
 
 
-# Alias used by python-docx as well
+# Aliases used by python-docx as well
 WD_COLOR = WD_COLOR_INDEX
+WD_PARAGRAPH_ALIGNMENT = WD_ALIGN_PARAGRAPH
+
+
+# python-docx 1.x base class that WD_* enums inherit from — we don't need
+# the real base, just a name users can subclass-check against.
+class BaseXmlEnum(Enum):
+    pass

{athena_python_docx-0.2.0 → athena_python_docx-0.2.2}/docx/table.py

@@ -58,27 +58,57 @@ def _find_first_paragraph_id(obj: object) -> str:
 
 
 def _collect_paragraph_ids(obj: object, out: list[str]) -> None:
-    """Walk a node tree and collect all paragraph/heading nodeIds in order."""
+    """Walk a node tree and collect all paragraph/heading nodeIds in order.
+
+    Tolerates multiple shapes Superdoc emits:
+      - cell getNodeById:  {"node": {"kind": "paragraph", "id": "UUID",
+                                      "paragraph": {"inlines": [...]}}}
+        (the cell's inner paragraph — server reports `id` as a bare UUID
+         that the addressing layer expects as `paragraph:UUID`)
+      - prosemirror-style: {"type": "paragraph", "attrs": {"nodeId": ...}}
+      - typed-wrapper:     {"paragraph": {...}, "nodeId": "..."}
+      - flat-address:      {"kind": "block", "nodeType": "paragraph", "nodeId": ...}
+      - block-list shape:  {"nodeType": "paragraph", "nodeId": ...}
+    """
+    seen: set[str] = set(out)
+
+    def _add(nid: object) -> None:
+        if not isinstance(nid, str) or not nid:
+            return
+        # Superdoc uses bare UUIDs (or short hashes) — no `paragraph:`
+        # prefix. Pass the value through verbatim.
+        if nid in seen:
+            return
+        seen.add(nid)
+        out.append(nid)
+
     if isinstance(obj, dict):
+        # Cell getNodeById shape: {kind: "paragraph", id: "<UUID>", paragraph: {...}}
+        kind: object = obj.get("kind")
+        if kind == "paragraph" and isinstance(obj.get("id"), str):
+            _add(obj.get("id"))
+            # Some responses also put the wrapper's id at nodeId.
+            _add(obj.get("nodeId"))
+        # Prosemirror-style
         t: object = obj.get("type")
         if isinstance(t, str) and t in ("paragraph", "heading"):
             attrs: object = obj.get("attrs")
-            nid: str = ""
             if isinstance(attrs, dict):
-                n = attrs.get("nodeId") or attrs.get("id")
-                if isinstance(n, str):
-                    nid = n
-            if not nid:
-                n2 = obj.get("nodeId")
-                if isinstance(n2, str):
-                    nid = n2
-            if nid:
-                out.append(nid)
+                _add(attrs.get("nodeId") or attrs.get("id"))
+            _add(obj.get("nodeId"))
+            _add(obj.get("id"))
+        # Flat-address / block-list
+        node_type: object = obj.get("nodeType")
+        if isinstance(node_type, str) and node_type in ("paragraph", "heading"):
+            _add(obj.get("nodeId"))
+        # Typed-wrapper
         for key in ("paragraph", "heading"):
             if key in obj and isinstance(obj[key], dict):
-                n3 = obj.get("nodeId")
-                if isinstance(n3, str) and n3 and n3 not in out:
-                    out.append(n3)
+                _add(obj.get("nodeId"))
+                inner = obj[key]
+                if isinstance(inner, dict):
+                    _add(inner.get("nodeId"))
+        # Recurse
         for v in obj.values():
             _collect_paragraph_ids(v, out)
     elif isinstance(obj, list):
@@ -514,14 +544,60 @@ class _Cell:
         return {"kind": "block", "nodeType": "tableCell", "nodeId": self._cell_id()}
 
     def _inner_paragraph_ids(self) -> list[str]:
+        """Locate the paragraph nodeIds inside this cell, trying multiple
+        Superdoc response shapes.
+
+        Strategies (in order):
+          1. doc.getNodeById with explicit nodeType=tableCell
+          2. doc.getNodeById with just {id: ...}
+          3. doc.getNode with target=tableCell address
+          4. doc.blocks.list filtered to paragraph/heading + location match
+        """
         cell_id = self._cell_id()
-        node_info: object = run_sync(
-            self._table._session.doc.get_node_by_id(
-                {"id": cell_id, "nodeType": "tableCell"},
-            ),
-        )
+        session = self._table._session
         ids: list[str] = []
-        _collect_paragraph_ids(node_info, ids)
+
+        # Strategy 1: with explicit nodeType
+        try:
+            info = run_sync(
+                session.doc.get_node_by_id(
+                    {"id": cell_id, "nodeType": "tableCell"},
+                ),
+            )
+            _collect_paragraph_ids(info, ids)
+            if ids:
+                return ids
+        except Exception:
+            pass
+
+        # Strategy 2: without nodeType (some sdk versions expect only id)
+        try:
+            info = run_sync(session.doc.get_node_by_id({"id": cell_id}))
+            _collect_paragraph_ids(info, ids)
+            if ids:
+                return ids
+        except Exception:
+            pass
+
+        # Strategy 3: doc.getNode with target address
+        try:
+            info = run_sync(
+                session.doc.get_node(
+                    {
+                        "target": {
+                            "kind": "block",
+                            "nodeType": "tableCell",
+                            "nodeId": cell_id,
+                        },
+                    },
+                ),
+            )
+            _collect_paragraph_ids(info, ids)
+            if ids:
+                return ids
+        except Exception:
+            pass
+
         return ids
 
     @property
@@ -548,68 +624,87 @@ class _Cell:
 
     @text.setter
     def text(self, value: str) -> None:
-        from docx.text.paragraph import _node_text
-
-        ids = self._inner_paragraph_ids()
-        if not ids:
-            raise RuntimeError(
-                f"No paragraph child found in cell "
-                f"({self._row}, {self._col}); cannot set _Cell.text.",
+        """Set the cell's text content.
+
+        The cell's single inner paragraph is addressed indirectly — Superdoc
+        doesn't expose a paragraph ref that's usable as a `blockId` for text
+        selections. Instead we use `doc.insert` with a structural paragraph
+        fragment at `placement=insideEnd`, which APPENDS inline runs to the
+        cell's existing paragraph. For a freshly-created (empty) cell this
+        produces `cell.text == value` on read-back.
+
+        For cells that already contain text, callers who truly want "replace"
+        semantics should first resolve the cell's paragraph via `doc.find`
+        and delete it — see _Cell.clear() (Phase 3).
+        """
+        cell_id = self._cell_id()
+        session = self._table._session
+        cell_target: dict = {
+            "kind": "block",
+            "nodeType": "tableCell",
+            "nodeId": cell_id,
+        }
+        # Superdoc only accepts block-typed fragments at the top level
+        # (paragraph/heading/table/image/list/sectionBreak/sdt/tableOfContents).
+        # We convert the plain-text value through `doc.markdownToFragment`
+        # to get a guaranteed-valid `{kind:"paragraph", paragraph:{inlines:[...]}}`
+        # shape, then doc.insert appends its inline runs into the cell's
+        # existing paragraph (rather than adding a sibling paragraph).
+        #
+        # Confirmed against real staging Superdoc. This is the ONLY shape
+        # that actually lands text inside a tableCell:
+        #   - text mode + placement  → rejected ("placement only valid
+        #     with structural content")
+        #   - doc.replace + tableCell target → replaces the cell itself,
+        #     destroying the table structure
+        try:
+            frag_result: object = run_sync(
+                session.doc.markdown_to_fragment({"markdown": value or ""}),
             )
-        # Replace the FIRST paragraph's text, and clear the others.
-        first = ids[0]
-        current = _node_text(self._table._session, first)
-        run_sync(
-            self._table._session.doc.replace(
-                {
-                    "target": {
-                        "kind": "selection",
-                        "start": {
-                            "kind": "text",
-                            "blockId": first,
-                            "offset": 0,
-                        },
-                        "end": {
-                            "kind": "text",
-                            "blockId": first,
-                            "offset": len(current),
-                        },
+            fragment: object = (
+                frag_result.get("fragment")
+                if isinstance(frag_result, dict)
+                else None
+            )
+            # Fall back to a hand-built fragment with Superdoc's native
+            # shape if markdownToFragment is unavailable.
+            if not isinstance(fragment, dict):
+                fragment = {
+                    "kind": "paragraph",
+                    "paragraph": {
+                        "inlines": (
+                            [{"kind": "run", "run": {"text": value}}]
+                            if value
+                            else []
+                        ),
                     },
-                    "text": value,
-                },
-            ),
-        )
-        for extra in ids[1:]:
-            # Blank the rest of the paragraphs.
-            existing = _node_text(self._table._session, extra)
-            if existing:
-                run_sync(
-                    self._table._session.doc.replace(
-                        {
-                            "target": {
-                                "kind": "selection",
-                                "start": {
-                                    "kind": "text",
-                                    "blockId": extra,
-                                    "offset": 0,
-                                },
-                                "end": {
-                                    "kind": "text",
-                                    "blockId": extra,
-                                    "offset": len(existing),
-                                },
-                            },
-                            "text": "",
-                        },
-                    ),
-                )
+                }
+            run_sync(
+                session.doc.insert(
+                    {
+                        "target": cell_target,
+                        "placement": "insideEnd",
+                        "content": fragment,
+                    },
+                ),
+            )
+            return
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to set _Cell.text on cell ({self._row}, {self._col}) "
+                f"of table {self._table._fresh_node_id()}: {e!r}",
+            ) from e
 
     @property
     def paragraphs(self) -> list["Paragraph"]:
         from docx.text.paragraph import Paragraph
 
         return [
-            Paragraph(session=self._table._session, node_id=pid)
+            Paragraph(
+                session=self._table._session,
+                node_id=pid,
+                node_type="paragraph",
+            )
             for pid in self._inner_paragraph_ids()
         ]
 
@@ -682,7 +777,11 @@ class _Cell:
             raise RuntimeError(
                 f"Superdoc did not return nodeId for _Cell.add_paragraph: {result!r}",
             )
-        para = Paragraph(session=self._table._session, node_id=node_id)
+        para = Paragraph(
+            session=self._table._session,
+            node_id=node_id,
+            node_type="paragraph",
+        )
         if style:
             para.style = style
         return para

{athena_python_docx-0.2.0 → athena_python_docx-0.2.2}/docx/text/paragraph.py

@@ -76,9 +76,20 @@ def _walk_inlines(info: object) -> list[dict]:
 class Paragraph:
     """A paragraph block in a Word document."""
 
-    def __init__(self, *, session: "Session", node_id: str) -> None:
+    def __init__(
+        self,
+        *,
+        session: "Session",
+        node_id: str,
+        node_type: str = "paragraph",
+    ) -> None:
         self._session: "Session" = session
         self._node_id: str = node_id
+        # Track node_type at creation so paragraph-level ops can skip a
+        # getNodeById round-trip (which raced against Superdoc mutation
+        # commits and raised "Block X was not found" for freshly-created
+        # blocks). "paragraph" | "heading" | "listItem".
+        self._node_type: str = node_type
 
     @property
     def text(self) -> str:
@@ -290,20 +301,16 @@ class Paragraph:
         return "\f" in self.text
 
     def _block_target(self) -> dict:
-        """Build a {kind, nodeType, nodeId} target for paragraph-level ops."""
-        info: object = run_sync(
-            self._session.doc.get_node_by_id({"id": self._node_id}),
-        )
-        node_type: str = "paragraph"
-        if isinstance(info, dict):
-            node_obj: object = info.get("node")
-            if isinstance(node_obj, dict):
-                raw: object = node_obj.get("nodeType")
-                if isinstance(raw, str) and raw:
-                    node_type = raw
+        """Build a {kind, nodeType, nodeId} target for paragraph-level ops.
+
+        Uses the node_type cached at construction. This avoids an extra
+        getNodeById round-trip that previously raced with Superdoc's
+        mutation-commit pipeline and raised "Block X was not found" for
+        blocks that had just been created by the same session.
+        """
         return {
             "kind": "block",
-            "nodeType": node_type,
+            "nodeType": self._node_type,
             "nodeId": self._node_id,
         }
 
@@ -381,7 +388,9 @@ class Paragraph:
             raise RuntimeError(
                 f"Superdoc did not return nodeId for insert_paragraph_before: {result!r}",
             )
-        new_para = Paragraph(session=self._session, node_id=node_id)
+        new_para = Paragraph(
+            session=self._session, node_id=node_id, node_type="paragraph",
+        )
         if style:
             new_para.style = style
         return new_para

{athena_python_docx-0.2.0 → athena_python_docx-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.2.0"
+version = "0.2.2"
 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.2.2/tests/fidelity/METHODOLOGY.md

@@ -0,0 +1,107 @@
+# Fidelity Testing Methodology
+
+A multi-layer strategy to reach 100% coverage of the python-docx API surface
+that `athena-python-docx` claims to replicate. Each layer catches a different
+class of drift between our Superdoc-backed implementation and stock python-docx.
+
+## Layers
+
+| # | Layer | Catches | Runtime |
+|---|---|---|---|
+| L1 | **Import surface parity** — tests that every public class/method/property python-docx exposes is importable from our SDK. | Missing API surface (AttributeError in user code). | <1s, local. |
+| L2 | **Signature parity** — inspect.signature on every public callable must match python-docx (or be a documented deviation). | Parameter renames, missing optional args. | <1s, local. |
+| L3 | **Enum value parity** — every WD_* enum has matching member names + values. | Silent failure when agent passes `WD_ALIGN_PARAGRAPH.DISTRIBUTE`. | <1s, local. |
+| L4 | **Local behavior (fake-session)** — 147 cases in `complex_cases/real_world_cases/extreme_cases/mega_cases` run through our SDK with `FakeSession` recording every Superdoc op. | NotImplementedError stubs, AttributeError, logic errors. | ~10s, local. |
+| L5 | **Op-trace snapshot** — each case's recorded Superdoc-op sequence is pinned. Regressions show up as op-count or op-sequence diffs. | Refactor drift (e.g. switching from `doc.replace` to `doc.insert`). | <1s, local. |
+| L6 | **Property round-trip** — for every setter, the getter returns the value (or a normalized form). | Cosmetic read/write asymmetry. | ~10s, local. |
+| L7 | **Binary round-trip vs stock python-docx** — each case's script is run by stock python-docx to produce a reference `.docx` and by our SDK's fake session to produce an in-memory model. Extracted features (para text, style, runs + formatting, table cells, alignment, indent, spacing) are diff'd. | Structural differences not caught by op-tracing. | ~20s, local. |
+| L8 | **Daytona + real Keryx** (`runner.py`) — our SDK runs inside a document-exec sandbox against a live Superdoc doc, exports the resulting `.docx`, and that `.docx` is diff'd against the stock-generated reference. | Protocol/server mismatches (like the `_Cell.text` `getNodeById` walker that worked in the fake but failed against real Superdoc). | ~3m, network. |
+| L9 | **Real exported-docx feature diff** — exports both sides' `.docx` files open them with stock python-docx and compare the extracted semantic feature set (runs, fonts, tables, sections, headers). | Visual drift after Superdoc's OOXML serialization. | ~30s incremental. |
+| L10 | **Agent-in-the-loop replay** — pull failing LangSmith sessions, extract the `code` the agent tried to run, and replay each against the current SDK + Daytona. | Real-world failures we missed in design. | ~1m per session. |
+
+## Roadmap to 100% python-docx coverage
+
+### Phase 1: Inventory
+
+Crawl stock python-docx and produce the exhaustive list of callables and
+properties to cover. Use `inspect.getmembers` + `typing.get_type_hints`.
+
+Output: `tests/fidelity/parity_spec.json` — one entry per `(module.path,
+member)` tuple with signature, docstring, return type.
+
+### Phase 2: Surface-coverage tracker
+
+Per-member status in a spreadsheet-like JSON:
+
+```json
+{
+  "docx.text.paragraph.Paragraph.alignment": {
+    "status": "implemented",
+    "signature_match": true,
+    "round_trip_tested": true,
+    "binary_diff_ok": true,
+    "live_daytona_ok": true,
+    "first_shipped": "0.2.0"
+  },
+  "docx.text.font.Font.highlight_color": {
+    "status": "implemented",
+    ...
+  },
+  "docx.section.Section.first_page_footer": {
+    "status": "stub",
+    "signature_match": true,
+    "round_trip_tested": false,
+    "blocker": "Header/Footer paragraph iteration requires doc.headerFooters.parts.list + per-part getNodeById, not yet wired."
+  }
+}
+```
+
+A CI job blocks merges that decrease coverage.
+
+### Phase 3: Generated cases
+
+For every python-docx public method, auto-generate a minimum-viable test
+case from its signature: "call with each required param filled by a
+representative value, assert no exception, assert getter round-trip where
+applicable." ~200 cases generated automatically.
+
+### Phase 4: Property-based tests
+
+Use `hypothesis` to fuzz lengths, unicode, nested tables, merge cells,
+margin values — the kind of inputs that production agents generate but
+hand-written tests miss.
+
+### Phase 5: Docx corpus replay
+
+Collect a corpus of real-world .docx files from:
+- python-docx's test fixtures on GitHub
+- Tutorials that emit full documents (MSDN, textbook samples)
+- Agora's staging assets exported to .docx
+
+For each: run `Document.from_file(path)` (Phase 2 feature), mutate via
+our SDK, re-export, compare.
+
+### Phase 6: Agent behavioral replay
+
+Daily job scans the last 24h of `agora-staging` and `agora-production`
+langsmith traces for `execute_word_document_code` tool calls. Extracts
+the `code` argument, deduplicates by script fingerprint, and runs each
+through the Daytona-backed runner. Any new failure is opened as a gap.
+
+### Phase 7: Coverage percentage
+
+The scorecard reports:
+```
+python-docx API coverage:
+  Classes:     28 / 30  (93%)
+  Methods:     142 / 156  (91%)
+  Properties:  287 / 302  (95%)
+  Enum values: 67 / 73  (92%)
+
+Round-trip fidelity:
+  Binary match rate:    112 / 112  (100%)
+  Live Daytona pass:    15 / 15  (100%)
+  Property getter/setter round-trips: 82 / 85  (96%)
+```
+
+Target: every row at 100%, with deviations documented in CLAUDE.md.

{athena_python_docx-0.2.0 → athena_python_docx-0.2.2}/tests/fidelity/cases.py

@@ -141,13 +141,12 @@ CASES: list[Case] = [
     ),
     Case(
         name="cell_text_setter",
-        description="Set cell(0,0).text on a 2x2 table — known NotImplementedError (Phase 2 stub).",
+        description="Set cell(0,0).text on a 2x2 table — now supported via 3-strategy fallback.",
         script=(
             "t = doc.add_table(rows=2, cols=2)\n"
             't.cell(0, 0).text = "A1"'
         ),
-        expected_athena_exc="NotImplementedError",
-        tags=("table", "stub"),
+        tags=("table",),
     ),
     # ---- Structural ops ------------------------------------------------------
     Case(