athena-python-docx 0.2.1__tar.gz → 0.2.3__tar.gz

{athena_python_docx-0.2.1 → athena_python_docx-0.2.3}/PKG-INFO

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

@@ -6,11 +6,21 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.2.1"
+__version__ = "0.2.3"
 
 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.1 → athena_python_docx-0.2.3}/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
@@ -101,7 +115,6 @@ class Document:
     @property
     def sections(self):
         """Return the document's sections collection."""
-        from docx.section import Sections
 
         self._ensure_open()
         return Sections(session=self._session)
@@ -204,7 +217,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 +254,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 +270,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,
@@ -372,8 +396,6 @@ class Document:
         Mirrors python-docx: creating a section adds a trailing empty
         paragraph that marks the section boundary.
         """
-        from docx.enum.section import WD_SECTION_START
-        from docx.section import Section
 
         self._ensure_open()
         # python-docx always inserts an anchor paragraph at the section break

{athena_python_docx-0.2.1 → athena_python_docx-0.2.3}/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.1 → athena_python_docx-0.2.3}/docx/section.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from docx._batching import run_sync
-from docx.shared import Emu, Length, Pt
+from docx.shared import Length, Pt
 
 if TYPE_CHECKING:
     from docx.client import Session

{athena_python_docx-0.2.1 → athena_python_docx-0.2.3}/docx/shape.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from docx._batching import run_sync
-from docx.shared import Emu, Length, Pt
+from docx.shared import Length, Pt
 
 if TYPE_CHECKING:
     from docx.client import Session

{athena_python_docx-0.2.1 → athena_python_docx-0.2.3}/docx/table.py

@@ -60,7 +60,11 @@ 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.
 
-    Tolerates several shapes that Superdoc has emitted over versions:
+    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": ...}
@@ -69,11 +73,22 @@ def _collect_paragraph_ids(obj: object, out: list[str]) -> None:
     seen: set[str] = set(out)
 
     def _add(nid: object) -> None:
-        if isinstance(nid, str) and nid and nid not in seen:
-            seen.add(nid)
-            out.append(nid)
+        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"):
@@ -611,118 +626,73 @@ class _Cell:
     def text(self, value: str) -> None:
         """Set the cell's text content.
 
-        Tries three strategies in order:
-          1. Text-range replace on the inner paragraph (fastest, preserves
-             paragraph-level formatting like alignment, style).
-          2. Structural replace of the tableCell with a markdown-derived
-             fragment via doc.markdownToFragment → doc.replace.
-          3. Structural replace of the tableCell with a hand-built
-             prosemirror paragraph fragment as last resort.
-        """
-        from docx.text.paragraph import _node_text
+        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
-
-        # --- Strategy 1: inner paragraph + text-range replace ---
-        ids = self._inner_paragraph_ids()
-        if ids:
-            first = ids[0]
-            current = _node_text(session, first)
-            try:
-                run_sync(
-                    session.doc.replace(
-                        {
-                            "target": {
-                                "kind": "selection",
-                                "start": {
-                                    "kind": "text",
-                                    "blockId": first,
-                                    "offset": 0,
-                                },
-                                "end": {
-                                    "kind": "text",
-                                    "blockId": first,
-                                    "offset": len(current),
-                                },
-                            },
-                            "text": value,
-                        },
-                    ),
-                )
-                for extra in ids[1:]:
-                    existing = _node_text(session, extra)
-                    if existing:
-                        run_sync(
-                            session.doc.replace(
-                                {
-                                    "target": {
-                                        "kind": "selection",
-                                        "start": {
-                                            "kind": "text",
-                                            "blockId": extra,
-                                            "offset": 0,
-                                        },
-                                        "end": {
-                                            "kind": "text",
-                                            "blockId": extra,
-                                            "offset": len(existing),
-                                        },
-                                    },
-                                    "text": "",
-                                },
-                            ),
-                        )
-                return
-            except Exception as e:
-                _log_warn(
-                    f"_Cell.text text-range replace failed on paragraph "
-                    f"{first}: {e!r}; falling back to structural replace.",
-                )
-
-        # --- Strategy 2: markdownToFragment + structural replace ---
         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 ""}),
             )
-            fragment: object = None
-            if isinstance(frag_result, dict):
-                fragment = frag_result.get("fragment")
-            if fragment is not None:
-                run_sync(
-                    session.doc.replace(
-                        {"target": cell_target, "content": fragment},
-                    ),
-                )
-                return
-        except Exception as e:
-            _log_warn(
-                f"_Cell.text markdownToFragment/replace failed: {e!r}; "
-                f"falling back to prosemirror fragment.",
+            fragment: object = (
+                frag_result.get("fragment")
+                if isinstance(frag_result, dict)
+                else None
             )
-
-        # --- Strategy 3: hand-built prosemirror paragraph fragment ---
-        pm_fragment: dict = {
-            "type": "paragraph",
-            "content": [{"type": "text", "text": value}] if value else [],
-        }
-        try:
+            # 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 []
+                        ),
+                    },
+                }
             run_sync(
-                session.doc.replace(
-                    {"target": cell_target, "content": pm_fragment},
+                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()}: all three strategies "
-                f"failed. Last error: {e!r}",
+                f"of table {self._table._fresh_node_id()}: {e!r}",
             ) from e
 
     @property
@@ -730,7 +700,11 @@ class _Cell:
         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()
         ]
 
@@ -803,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.1 → athena_python_docx-0.2.3}/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.1 → athena_python_docx-0.2.3}/docx/text/parfmt.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from docx._batching import run_sync
-from docx.shared import Length, Pt, Twips
+from docx.shared import Length, Twips
 
 if TYPE_CHECKING:
     from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_LINE_SPACING

{athena_python_docx-0.2.1 → athena_python_docx-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.2.1"
+version = "0.2.3"
 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.3/scripts/release.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Tag + push a new athena-python-docx release. CI handles the rest:
+# PyPI publish, Docker image rebuild, Daytona snapshot creation, Doppler
+# flip in agora dev + stg. See
+# .github/workflows/athena-python-docx-release.yml for the full flow.
+#
+# Usage:
+#   ./scripts/release.sh <version>
+#
+# e.g. ./scripts/release.sh 0.2.3 — releases athena-python-docx==0.2.3
+# by:
+#   1. Updating pyproject.toml + docx/__init__.py
+#   2. Committing the version bump
+#   3. Tagging athena-python-docx-v<version>
+#   4. Pushing the commit + tag to origin
+#
+# CI trigger fires on the tag push and runs the full release pipeline.
+
+set -euo pipefail
+
+if [ $# -ne 1 ]; then
+  echo "Usage: $0 <version> (e.g., 0.2.3)" >&2
+  exit 1
+fi
+
+VERSION="$1"
+if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(\.(dev|rc|a|b)[0-9]+)?$ ]]; then
+  echo "ERROR: version '$VERSION' is not a valid semver-ish" >&2
+  exit 1
+fi
+
+SDK_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+REPO_ROOT="$(git -C "$SDK_DIR" rev-parse --show-toplevel)"
+
+# Require clean working tree so the commit captures only the version bump.
+if ! git -C "$REPO_ROOT" diff --quiet || ! git -C "$REPO_ROOT" diff --cached --quiet; then
+  echo "ERROR: working tree is dirty. Commit or stash first." >&2
+  git -C "$REPO_ROOT" status --short >&2
+  exit 1
+fi
+
+# Bump pyproject.toml
+sed -i.bak "s/^version = \".*\"/version = \"$VERSION\"/" "$SDK_DIR/pyproject.toml"
+rm -f "$SDK_DIR/pyproject.toml.bak"
+
+# Bump docx/__init__.py
+sed -i.bak "s/^__version__ = \".*\"/__version__ = \"$VERSION\"/" "$SDK_DIR/docx/__init__.py"
+rm -f "$SDK_DIR/docx/__init__.py.bak"
+
+# Show the diff so the operator sees what will be committed.
+echo "=== Version bump diff ==="
+git -C "$REPO_ROOT" diff "$SDK_DIR/pyproject.toml" "$SDK_DIR/docx/__init__.py"
+echo "========================="
+
+TAG="athena-python-docx-v$VERSION"
+
+# Commit + tag + push.
+git -C "$REPO_ROOT" add "$SDK_DIR/pyproject.toml" "$SDK_DIR/docx/__init__.py"
+git -C "$REPO_ROOT" commit -m "chore(docx-sdk): bump version to $VERSION"
+git -C "$REPO_ROOT" tag "$TAG"
+git -C "$REPO_ROOT" push
+git -C "$REPO_ROOT" push origin "$TAG"
+
+cat <<EOF
+
+Tagged $TAG and pushed. CI is now running the full release pipeline:
+
+  1. PyPI publish        → https://pypi.org/project/athena-python-docx/$VERSION/
+  2. Docker image rebuild → athenaintel/daytona-document:$VERSION
+  3. Daytona snapshot    → document-exec:$VERSION
+  4. Doppler flip        → agora/dev + agora/stg
+
+Watch the run:
+  https://github.com/Athena-Intel/demo-app-monorepo/actions/workflows/athena-python-docx-release.yml
+
+For prd rollout, after canary verification:
+  doppler secrets set --project agora --config prd \\
+    DAYTONA_DOCUMENT_EXEC_SNAPSHOT=document-exec:$VERSION
+
+EOF