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

docx/table.py

@@ -0,0 +1,213 @@
+"""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)
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from docx._batching import run_sync
+from docx.errors import ValidationError
+
+if TYPE_CHECKING:
+    from docx.client import Session
+
+
+def _log_warn(msg: str) -> None:
+    print(f"[docx-sdk] WARN: {msg}", file=sys.stderr)
+
+
+class Table:
+    def __init__(self, *, session: "Session", node_id: str) -> None:
+        self._session: "Session" = session
+        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(
+            self._session.doc.find({"type": "table"}),
+        )
+        items: list[dict] = find_result.get("items", [])
+        for item in items:
+            addr: dict = item.get("address", {}) if isinstance(item, dict) else {}
+            if 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 {}
+            )
+            new_id: str = str(last_addr.get("nodeId", ""))
+            if new_id:
+                _log_warn(
+                    f"Table nodeId rotated: {self._node_id} -> {new_id}",
+                )
+                self._node_id = new_id
+        return self._node_id
+
+    @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: 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: 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":
+        return _Cell(table=self, row=row_idx, col=col_idx)
+
+    def add_row(self) -> "_Row":
+        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}",
+            )
+        run_sync(
+            self._session.doc.tables.insert_row(
+                {
+                    "tableNodeId": nid,
+                    "rowIndex": row_count - 1,
+                    "position": "below",
+                },
+            ),
+        )
+        return _Row(table=self, index=row_count)
+
+    def add_column(self) -> "_Column":
+        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}",
+            )
+        run_sync(
+            self._session.doc.tables.insert_column(
+                {
+                    "tableNodeId": nid,
+                    "columnIndex": col_count - 1,
+                    "position": "right",
+                },
+            ),
+        )
+        return _Column(table=self, index=col_count)
+
+    @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
+
+    @style.setter
+    def style(self, value: str | None) -> None:
+        nid: str = self._fresh_node_id()
+        run_sync(
+            self._session.doc.tables.set_style(
+                {"nodeId": nid, "styleId": value or "TableGrid"},
+            ),
+        )
+
+
+class _Row:
+    def __init__(self, *, table: Table, index: int) -> None:
+        self._table: Table = table
+        self._index: int = index
+
+    @property
+    def cells(self) -> list["_Cell"]:
+        col_count: int = len(self._table.columns)
+        return [
+            _Cell(table=self._table, row=self._index, col=j)
+            for j in range(col_count)
+        ]
+
+
+class _Column:
+    def __init__(self, *, table: Table, index: int) -> None:
+        self._table: Table = table
+        self._index: int = index
+
+    @property
+    def cells(self) -> list["_Cell"]:
+        row_count: int = len(self._table.rows)
+        return [
+            _Cell(table=self._table, row=i, col=self._index)
+            for i in range(row_count)
+        ]
+
+
+class _Cell:
+    def __init__(self, *, table: Table, row: int, col: int) -> None:
+        self._table: Table = table
+        self._row: int = row
+        self._col: int = col
+
+    @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},
+            ),
+        )
+        if not isinstance(cell_obj, dict):
+            return ""
+        return str(cell_obj.get("text", ""))
+
+    @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 merge(self, other: "_Cell") -> "_Cell":
+        if other._table is not self._table:
+            raise ValidationError(
+                "Cannot merge cells from different tables.",
+            )
+        nid: str = self._table._fresh_node_id()
+        run_sync(
+            self._table._session.doc.tables.merge_cells(
+                {
+                    "tableNodeId": nid,
+                    "startRow": self._row,
+                    "startCol": self._col,
+                    "endRow": other._row,
+                    "endCol": other._col,
+                },
+            ),
+        )
+        return self

docx/text/__init__.py

@@ -0,0 +1,8 @@
+"""Text submodule — Paragraph and Run (mirrors python-docx.text)."""
+
+from __future__ import annotations
+
+from docx.text.paragraph import Paragraph
+from docx.text.run import Run
+
+__all__ = ["Paragraph", "Run"]

docx/text/paragraph.py

@@ -0,0 +1,141 @@
+"""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),
+        )

docx/text/run.py

@@ -0,0 +1,187 @@
+"""Run and Font — matches python-docx's run.Run and text.font.Font."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docx._batching import run_sync
+from docx.shared import Pt, RGBColor
+
+if TYPE_CHECKING:
+    from docx.client import Session
+
+
+class Run:
+    """A text run — a contiguous span with uniform formatting."""
+
+    def __init__(
+        self,
+        *,
+        session: "Session",
+        block_id: str,
+        range_: tuple[int, int],
+    ) -> None:
+        self._session: "Session" = session
+        self._block_id: str = block_id
+        self._range: tuple[int, int] = range_
+
+    @property
+    def _text_range(self) -> dict:
+        return {
+            "kind": "text",
+            "blockId": self._block_id,
+            "range": {"start": self._range[0], "end": self._range[1]},
+        }
+
+    @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 ""
+        )
+        return full[self._range[0] : self._range[1]]
+
+    @text.setter
+    def text(self, value: str) -> None:
+        run_sync(
+            self._session.doc.replace(
+                {"target": self._text_range, "text": value},
+            ),
+        )
+        new_end: int = self._range[0] + len(value)
+        self._range = (self._range[0], new_end)
+
+    def _apply_inline(self, **kwargs: object) -> None:
+        run_sync(
+            self._session.doc.format.apply(
+                {"target": self._text_range, "inline": kwargs},
+            ),
+        )
+
+    @property
+    def bold(self) -> bool | None:
+        return self._get_inline_bool("bold")
+
+    @bold.setter
+    def bold(self, value: bool | None) -> None:
+        if value is None:
+            return
+        self._apply_inline(bold=value)
+
+    @property
+    def italic(self) -> bool | None:
+        return self._get_inline_bool("italic")
+
+    @italic.setter
+    def italic(self, value: bool | None) -> None:
+        if value is None:
+            return
+        self._apply_inline(italic=value)
+
+    @property
+    def underline(self) -> bool | None:
+        return self._get_inline_bool("underline")
+
+    @underline.setter
+    def underline(self, value: bool | None) -> None:
+        if value is None:
+            return
+        self._apply_inline(underline=value)
+
+    @property
+    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.
+    """
+
+    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
+
+    @name.setter
+    def name(self, value: str | None) -> None:
+        if value is None:
+            return
+        self._run._apply_inline(fontFamily=value)
+
+    @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
+
+    @size.setter
+    def size(self, value: "Pt | int | None") -> None:
+        if value is None:
+            return
+        pt_value: float = (
+            float(value.pt) if hasattr(value, "pt") else float(value)
+        )
+        self._run._apply_inline(fontSize=pt_value)
+
+    @property
+    def color(self) -> "_ColorProxy":
+        return _ColorProxy(self._run)
+
+
+class _ColorProxy:
+    """Matches python-docx's `run.font.color` property, which returns a
+    ColorFormat object with `.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
+
+    @rgb.setter
+    def rgb(self, value: "RGBColor | None") -> None:
+        if value is None:
+            return
+        self._run._apply_inline(color=str(value))

docx/typing.py

@@ -0,0 +1,30 @@
+"""Internal TypedDicts shared across the SDK."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class UserInfo(TypedDict):
+    """Identity info passed to AsyncSuperDocClient for activity log attribution."""
+
+    name: str
+    email: str
+
+
+class TextRange(TypedDict):
+    """A Superdoc text range target.
+
+    Used in format.apply, replace, hyperlinks.wrap, etc.
+    """
+
+    kind: str
+    blockId: str
+    range: "CharRange"
+
+
+class CharRange(TypedDict):
+    """Start/end character offsets within a block."""
+
+    start: int
+    end: int