athena-python-docx 0.1.0__tar.gz

athena_python_docx-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+node_modules/
+dist/
+.env
+.env.local
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+env/
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Editors
+.vscode/
+.idea/

athena_python_docx-0.1.0/CLAUDE.md

@@ -0,0 +1,63 @@
+# athena-python-docx SDK — Claude Instructions
+
+## API Parity Rule (MANDATORY)
+
+**This SDK MUST be a 100% exact replica of the standard [python-docx](https://python-docx.readthedocs.io/) API.**
+
+Every class, method, property, and parameter name must match python-docx exactly. The goal is that any code written for python-docx works identically with this SDK — no surprises, no differences.
+
+### What this means in practice
+
+- **Do NOT add new methods** that don't exist in python-docx
+- **Do NOT add new properties** that don't exist in python-docx
+- **Do NOT rename parameters** — use the exact same parameter names as python-docx
+- **Do NOT change method signatures** — if python-docx's `add_heading()` takes `(text, level=1)`, ours must too
+- **Do NOT change return types** — if python-docx's `paragraph.runs` returns `list[Run]`, ours must too
+
+### How to verify parity
+
+Before adding or modifying any API surface:
+
+1. Check the [python-docx documentation](https://python-docx.readthedocs.io/)
+2. Check the [python-docx source code](https://github.com/python-openxml/python-docx)
+3. Confirm the method/property/parameter exists with the same name and signature
+4. If it doesn't exist in python-docx, **do not add it** without explicit user approval
+
+Run `uv run pytest tests/test_python_docx_api_parity.py -v -s` to verify parity.
+
+### Intentionally omitted (Superdoc SDK limitations)
+
+These standard python-docx members don't apply to a Superdoc-backed SDK:
+
+- `Paragraph._p`, `Run._r` — XML element access (no local XML)
+- `Document.part`, `Paragraph.part`, `Run.part` — package part access
+- `Document.core_properties.last_modified_by` — we use Keryx attribution instead
+- `Document.settings` — Word app settings (not surfaced by Superdoc)
+- `InlineShape.chart` — charts (Phase 2+)
+
+### If you need a deviation
+
+If there is a genuine technical reason why a deviation from python-docx is necessary:
+
+1. **Stop and ask the user** before implementing
+2. Explain what the deviation is and why it's needed
+3. Get explicit confirmation that the deviation is acceptable
+4. Document the deviation in the "Intentionally omitted" list above
+
+## Architecture
+
+This is an **async-Superdoc-SDK-backed client** that mimics the sync python-docx API.
+
+- Sync façade (matches python-docx) — `doc.save()`, `paragraph.add_run()`
+- Under the hood, a persistent event-loop thread in `_batching.py` runs `AsyncSuperDocClient` coroutines
+- No XML manipulation — calls translate to Superdoc SDK ops (insert, find, replace, tables.*, format.apply, create.image, hyperlinks.wrap)
+- Mutations write directly to Keryx Y.Doc; users and other agents see them live
+
+## Development
+
+```bash
+uv venv
+uv pip install -e ".[dev]"
+uv run pytest tests/ -x -q
+uv run pytest tests/test_python_docx_api_parity.py -v
+```

athena_python_docx-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: athena-python-docx
+Version: 0.1.0
+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>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: superdoc-sdk>=1.6.0.dev6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-docx>=1.1; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# athena-python-docx
+
+Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Superdoc + Keryx collaborative document stack.
+
+## Quick start
+
+```python
+from docx import Document
+from docx.shared import Inches, Pt, RGBColor
+
+# Open an existing SuperDoc asset by its Athena asset_id
+with Document("asset_abc123") as doc:
+    doc.add_heading("Market Analysis", level=1)
+
+    p = doc.add_paragraph()
+    r = p.add_run("Revenue grew ")
+    highlight = p.add_run("12.3% year-over-year")
+    highlight.bold = True
+    highlight.font.color.rgb = RGBColor(0x00, 0x80, 0x00)
+    p.add_run(".")
+
+    t = doc.add_table(rows=2, cols=2, style="TableGrid")
+    t.cell(0, 0).text = "Segment"
+    t.cell(0, 1).text = "Revenue"
+    t.cell(1, 0).text = "Enterprise"
+    t.cell(1, 1).text = "$4.3M"
+
+    doc.save()
+```
+
+## API parity rule
+
+This SDK mirrors python-docx's public API **exactly**. See `CLAUDE.md` for the full contract.
+
+## Development
+
+```bash
+uv venv
+uv pip install -e ".[dev]"
+uv run pytest tests/ -x
+```
+
+## Environment variables
+
+Required when connecting to Keryx (set by Athena backend when executing in Daytona):
+
+- `SUPERDOC_COLLAB_TOKEN` — short-lived Keryx JWT
+- `KERYX_WS_URL` — Keryx WebSocket base URL
+- `ATHENA_WORKSPACE_ID` — workspace routing segment
+
+## License
+
+MIT

athena_python_docx-0.1.0/README.md

@@ -0,0 +1,53 @@
+# athena-python-docx
+
+Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Superdoc + Keryx collaborative document stack.
+
+## Quick start
+
+```python
+from docx import Document
+from docx.shared import Inches, Pt, RGBColor
+
+# Open an existing SuperDoc asset by its Athena asset_id
+with Document("asset_abc123") as doc:
+    doc.add_heading("Market Analysis", level=1)
+
+    p = doc.add_paragraph()
+    r = p.add_run("Revenue grew ")
+    highlight = p.add_run("12.3% year-over-year")
+    highlight.bold = True
+    highlight.font.color.rgb = RGBColor(0x00, 0x80, 0x00)
+    p.add_run(".")
+
+    t = doc.add_table(rows=2, cols=2, style="TableGrid")
+    t.cell(0, 0).text = "Segment"
+    t.cell(0, 1).text = "Revenue"
+    t.cell(1, 0).text = "Enterprise"
+    t.cell(1, 1).text = "$4.3M"
+
+    doc.save()
+```
+
+## API parity rule
+
+This SDK mirrors python-docx's public API **exactly**. See `CLAUDE.md` for the full contract.
+
+## Development
+
+```bash
+uv venv
+uv pip install -e ".[dev]"
+uv run pytest tests/ -x
+```
+
+## Environment variables
+
+Required when connecting to Keryx (set by Athena backend when executing in Daytona):
+
+- `SUPERDOC_COLLAB_TOKEN` — short-lived Keryx JWT
+- `KERYX_WS_URL` — Keryx WebSocket base URL
+- `ATHENA_WORKSPACE_ID` — workspace routing segment
+
+## License
+
+MIT

athena_python_docx-0.1.0/docx/__init__.py

@@ -0,0 +1,16 @@
+"""athena-python-docx — drop-in replacement for python-docx.
+
+Calls translate into Superdoc SDK operations against a Keryx Y.Doc.
+See CLAUDE.md for the API parity contract.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from docx.api import Document
+
+__all__ = [
+    "Document",
+    "__version__",
+]

athena_python_docx-0.1.0/docx/_batching.py

@@ -0,0 +1,86 @@
+"""Sync→async bridge. Runs a single event loop in a background thread
+and dispatches coroutines from sync callers.
+
+This is the only place in the SDK that uses threading.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from typing import Any, Coroutine, TypeVar
+
+T = TypeVar("T")
+
+# Default per-op timeout. Individual Superdoc SDK calls should complete well
+# under this — the value is a safety net so a WebSocket stall or Keryx
+# downtime surfaces a TimeoutError instead of wedging the calling thread
+# until the outer Daytona INSTRUCTION_TIMEOUT_SECONDS kill.
+DEFAULT_OP_TIMEOUT_SECONDS: float = 60.0
+
+_loop: asyncio.AbstractEventLoop | None = None
+_thread: threading.Thread | None = None
+_lock = threading.Lock()
+
+
+def _ensure_loop() -> asyncio.AbstractEventLoop:
+    """Return the persistent background event loop. Starts it lazily."""
+    global _loop, _thread
+
+    with _lock:
+        if _loop is not None and _loop.is_running():
+            return _loop
+
+        loop = asyncio.new_event_loop()
+        loop_ready = threading.Event()
+
+        def _run() -> None:
+            asyncio.set_event_loop(loop)
+            loop_ready.set()
+            loop.run_forever()
+
+        thread = threading.Thread(
+            target=_run,
+            name="docx-sdk-loop",
+            daemon=True,
+        )
+        thread.start()
+        loop_ready.wait(timeout=5)
+        _loop = loop
+        _thread = thread
+        return loop
+
+
+def run_sync(
+    coro: Coroutine[Any, Any, T],
+    *,
+    timeout: float | None = DEFAULT_OP_TIMEOUT_SECONDS,
+) -> T:
+    """Run a coroutine on the background loop and block until it returns.
+
+    Args:
+        coro: The coroutine to execute.
+        timeout: Maximum seconds to wait. ``None`` blocks indefinitely
+            (use sparingly — prefer the default so stalls surface early).
+
+    Raises:
+        concurrent.futures.TimeoutError: if the coroutine does not
+            complete within `timeout` seconds.
+        The coroutine's exception, re-raised in the calling thread.
+    """
+    loop = _ensure_loop()
+    future = asyncio.run_coroutine_threadsafe(coro, loop)
+    return future.result(timeout=timeout)
+
+
+def shutdown() -> None:
+    """Stop the background event loop. For test teardown."""
+    global _loop, _thread
+    with _lock:
+        if _loop is None:
+            return
+        _loop.call_soon_threadsafe(_loop.stop)
+        if _thread is not None:
+            _thread.join(timeout=5)
+        _loop = None
+        _thread = None

athena_python_docx-0.1.0/docx/api.py

@@ -0,0 +1,41 @@
+"""The `Document` factory — matches python-docx's `docx.Document(path)`.
+
+python-docx signature:
+    Document(docx=None) -> Document
+
+Our signature deviates from the path-based one because we don't open
+.docx files from disk — we open Y.Doc assets from Keryx. The parameter
+is reused: you pass an asset_id string where python-docx would take a
+file path.
+
+If the caller truly needs to load a local .docx (rare inside Daytona),
+they can upload it first via the apps/api upload route (Phase 2+) or
+use the existing `replaceFile` flow from the Olympus side.
+"""
+
+from __future__ import annotations
+
+from docx.document import Document as _Document
+
+
+def Document(docx: str | None = None) -> _Document:
+    """Open a Word document for editing.
+
+    Args:
+        docx: Athena asset_id of the SuperDoc document to open.
+              In python-docx this takes a file path; here it takes
+              an asset_id. None is not supported in Phase 1.
+
+    Returns:
+        A Document instance bound to the asset.
+
+    Raises:
+        ValueError: if `docx` is None or empty.
+    """
+    if not docx:
+        raise ValueError(
+            "athena-python-docx requires an asset_id. "
+            "Pass the SuperDoc asset ID as the first argument: "
+            "Document('asset_xxx...')",
+        )
+    return _Document(asset_id=docx)

athena_python_docx-0.1.0/docx/client.py

@@ -0,0 +1,230 @@
+"""Superdoc SDK session wrapper — auth, open/close lifecycle, error mapping.
+
+This module is the only place in the SDK that talks to `superdoc_sdk`
+directly. All other classes (Document, Paragraph, Run, Table) go
+through a `Session` instance.
+
+Environment variables expected inside Daytona:
+    SUPERDOC_COLLAB_TOKEN: short-lived Keryx JWT (signed by Athena backend)
+    KERYX_WS_URL:          Keryx WebSocket base URL (e.g. "wss://keryx.athena...")
+    ATHENA_WORKSPACE_ID:   workspace routing path segment
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any
+
+from docx.errors import (
+    AuthenticationError,
+    DocumentClosedError,
+    SessionError,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+_TOKEN_ENV = "SUPERDOC_COLLAB_TOKEN"  # noqa: S105
+_WS_URL_ENV = "KERYX_WS_URL"
+_WORKSPACE_ENV = "ATHENA_WORKSPACE_ID"
+
+
+def _log_info(msg: str) -> None:
+    """Minimal stderr logger. We avoid loguru here to keep the SDK
+    runtime dependency tree small — this code runs inside Daytona sandboxes.
+    """
+    import sys
+
+    print(f"[docx-sdk] {msg}", file=sys.stderr)
+
+
+def _log_warning(msg: str) -> None:
+    import sys
+
+    print(f"[docx-sdk] WARN: {msg}", file=sys.stderr)
+
+
+class Session:
+    """Manages the lifecycle of an AsyncSuperDocClient session.
+
+    Lifecycle:
+        create Session (does NOT open yet) → first op triggers open() →
+        subsequent ops reuse the same client → save() flushes → close()
+        disposes.
+
+    Thread safety: NOT thread-safe. Each Document should have its own
+    Session. The sync facade serializes all calls through a single
+    event-loop thread (see _batching.py).
+    """
+
+    def __init__(
+        self,
+        *,
+        asset_id: str,
+        user_info: dict[str, str] | None = None,
+    ) -> None:
+        self._asset_id: str = asset_id
+        self._user_info: dict[str, str] = user_info or {
+            "name": "Athena Agent",
+            "email": "agent@athenaintel.com",
+        }
+        self._client: Any | None = None
+        self._doc_handle: Any | None = None
+        self._opened: bool = False
+        self._closed: bool = False
+
+    @property
+    def asset_id(self) -> str:
+        return self._asset_id
+
+    @property
+    def is_open(self) -> bool:
+        return self._opened and not self._closed
+
+    async def open(self) -> None:
+        """Open the Superdoc SDK session against Keryx.
+
+        Raises:
+            AuthenticationError: if SUPERDOC_COLLAB_TOKEN is missing/invalid.
+            SessionError: on any other open-time failure.
+        """
+        if self._closed:
+            raise DocumentClosedError(
+                f"Session for asset {self._asset_id} was already closed.",
+            )
+        if self._opened:
+            return
+
+        token: str | None = os.environ.get(_TOKEN_ENV)
+        ws_url: str | None = os.environ.get(_WS_URL_ENV)
+        workspace_id: str | None = os.environ.get(_WORKSPACE_ENV)
+
+        if not token:
+            raise AuthenticationError(
+                f"Missing environment variable {_TOKEN_ENV}. "
+                "The Athena backend must mint a short-lived Keryx JWT "
+                "and inject it into the Daytona sandbox.",
+            )
+        if not ws_url:
+            raise SessionError(
+                f"Missing environment variable {_WS_URL_ENV}.",
+            )
+        if not workspace_id:
+            raise SessionError(
+                f"Missing environment variable {_WORKSPACE_ENV}.",
+            )
+
+        # Lazy import so `import docx` doesn't pay for superdoc_sdk init cost
+        from superdoc import AsyncSuperDocClient
+        from superdoc.generated.client import (
+            DocOpenParams,
+            DocOpenParamsCollaborationVariant1,
+        )
+
+        collab_base_url: str = f"{ws_url}/ws/{workspace_id}"
+        self._client = AsyncSuperDocClient(
+            user=self._user_info,
+            env={_TOKEN_ENV: token},
+            request_timeout_ms=30_000,
+            watchdog_timeout_ms=60_000,
+        )
+
+        collab_config: DocOpenParamsCollaborationVariant1 = {
+            "url": collab_base_url,
+            "documentId": self._asset_id,
+            "tokenEnv": _TOKEN_ENV,
+            "providerType": "y-websocket",
+        }
+        open_params: DocOpenParams = {"collaboration": collab_config}
+
+        try:
+            self._doc_handle = await self._client.open(open_params)
+        except Exception as e:
+            msg: str = str(e).lower()
+            if "401" in msg or "unauthorized" in msg or "forbidden" in msg:
+                raise AuthenticationError(
+                    f"Keryx rejected the collab token: {e}",
+                ) from e
+            raise SessionError(
+                f"Failed to open Superdoc session for {self._asset_id}: {e}",
+            ) from e
+
+        self._opened = True
+        _log_info(f"Opened {self._asset_id}")
+
+    @property
+    def doc(self) -> Any:
+        """Return the opened Superdoc doc handle.
+
+        Lazy-opens on first access. Blocks on the event-loop thread
+        via the sync bridge; do not call this from inside a coroutine.
+        """
+        if not self._opened:
+            raise SessionError(
+                "Session not yet opened; call await session.open() first "
+                "or use the sync facade via Document().",
+            )
+        if self._closed:
+            raise DocumentClosedError(
+                f"Session for asset {self._asset_id} is closed.",
+            )
+        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().
+        """
+        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}")
+
+    async def close(self) -> None:
+        """Close the Superdoc session. Idempotent."""
+        if self._closed:
+            return
+
+        if self._opened and self._doc_handle is not None:
+            try:
+                # Match the 1-second flush delay from superdoc_write_utils
+                # before tearing down the WebSocket
+                await asyncio.sleep(1)
+                await self._doc_handle.close({"discard": True})
+            except Exception as close_err:
+                _log_warning(
+                    f"Doc close failed for {self._asset_id}: {close_err}",
+                )
+
+        if self._client is not None:
+            try:
+                await self._client.dispose()
+            except Exception as dispose_err:
+                _log_warning(
+                    f"Client dispose failed for {self._asset_id}: {dispose_err}",
+                )
+
+        self._closed = True
+        _log_info(f"Closed {self._asset_id}")
+
+
+@asynccontextmanager
+async def open_session(
+    *,
+    asset_id: str,
+    user_info: dict[str, str] | None = None,
+) -> "AsyncIterator[Session]":
+    """Async context manager for a Session. Yields an opened session."""
+    session = Session(asset_id=asset_id, user_info=user_info)
+    try:
+        await session.open()
+        yield session
+    finally:
+        await session.close()