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

athena_python_docx-0.5.0/CLAUDE.md

@@ -0,0 +1,118 @@
+# 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+)
+- `Comment.add_paragraph` / `Comment.add_table` /
+  `Comment.iter_inner_content` / `Comment.paragraphs` /
+  `Comment.tables` — SuperDoc models a comment as a single text body,
+  not a `BlockItemContainer`. Use `Comment.text` instead. The
+  paragraph/table-bearing surface raises `CommentsNotImplementedError`.
+
+### Phase-3b upstream-blocked surface
+
+These are *shipped at the surface* but partially or fully no-op at
+runtime, pending SuperDoc SDK changes outside this repo. The
+upstream constraints have been verified against
+[SuperDoc's published docs](https://docs.superdoc.dev/document-api/reference/styles/apply)
+and the bundled TypeScript types in
+`node_modules/@superdoc-dev/sdk/dist/generated/client.d.ts`. See
+`docx-studio/PYTHON_DOCX_PARITY_GAPS.md` § *What unblocks the
+remaining work* for the exact wire-op shape needed to unblock each.
+
+- **24 setters on `BaseStyle` / `CharacterStyle` / `ParagraphStyle`**
+  (`name`, `style_id`, `hidden`, `locked`, `priority`, `quick_style`,
+  `unhide_when_used`, `base_style`, `next_paragraph_style`) emit
+  `PendingStyleMutationWarning` and stash on `_overrides`.
+  SuperDoc 1.7's `doc.styles.apply` is constrained to
+  `target.scope: "docDefaults"` — no per-style metadata variant.
+  Behavior pinned by `tests/test_style_setters_contract.py` (11
+  tests); when SuperDoc lands a metadata op, those tests will need
+  to flip to assert real bus calls.
+- **`Styles.latent_styles`** returns an empty `_LatentStyles` —
+  `DocInfoResult.styles` only surfaces `paragraphStyles[]` (a flat
+  usage-count list), not the OOXML `<w:latentStyles>` block.
+
+### Intentional deviations (additions / different semantics)
+
+These differ from stock python-docx because the SDK is asset-backed,
+not file-backed. Each is documented in the relevant docstring.
+
+- **`Document.create(name=, base_url=, api_key=, parent_folder_id=, workspace_id=)`**
+  classmethod. Stock python-docx returns a blank in-memory document
+  for `Document(None)`; we can't fabricate a SuperDocument asset
+  client-side, so net-new asset creation is a separate factory that
+  hits `POST {base_url}/docs/empty`. The constructor positional-arg
+  shape (`Document(asset_id)`) is preserved for parity.
+
+### 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 (0.5.0+)
+
+This is a **thin HTTP client** that mimics the sync python-docx API.
+
+- Sync façade (matches python-docx) — `doc.save()`, `paragraph.add_run()`
+- Every internal call constructs a typed `Command` dataclass
+  (`docx.commands`) and ships it through a `CommandBuffer`
+  (`docx._buffer`) which POSTs to docx-studio's `/docs/:id/commands`.
+- HTTP transport: `requests.Session` with a Retry (3 attempts, 0.5s
+  backoff, 429/502/503/504). The legacy `transport="direct"` (embedded
+  Superdoc CLI + y-websocket from Python) was removed in 0.5.0; agent
+  pods no longer embed Superdoc.
+- Batching: queries and response-bearing creates flush eagerly (and
+  drain pending pure mutations in the same batch); pure mutations
+  buffer with a 100 ms idle timer. `Document.save()` and the context
+  manager exit drain explicitly. `docx.flush_all()` is the Daytona
+  prelude hook — flushes every live buffer in the process.
+- The path-proxy in `_http_doc.py` is an internal translation layer:
+  call sites that look like `await self._session.doc.create.paragraph(p)`
+  resolve to `CommandBuffer.call(CreateParagraph(**p))`. Rewriting call
+  sites to construct `Command` dataclasses directly is a possible
+  follow-up — the wire format is typed end-to-end either way.
+
+## 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.2.3 → athena_python_docx-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.2.3
+Version: 0.5.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>
@@ -11,14 +11,18 @@ 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
+Requires-Dist: requests>=2.28
+Requires-Dist: urllib3>=1.26.6
 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: responses>=0.24; extra == 'dev'
 Requires-Dist: ruff>=0.3; extra == 'dev'
+Provides-Extra: fidelity
+Requires-Dist: httpx>=0.27; extra == 'fidelity'
+Requires-Dist: superdoc-sdk>=1.8.0; extra == 'fidelity'
 Description-Content-Type: text/markdown
 
 # athena-python-docx

{athena_python_docx-0.2.3 → athena_python_docx-0.5.0}/docx/__init__.py

@@ -6,9 +6,10 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.2.3"
+__version__ = "0.5.0"
 
 from docx.api import Document
+from docx._buffer import flush_all
 # Re-exports python-docx ships at docx top-level for convenience.
 from docx.shared import Emu, Inches, Pt, Cm, Mm, Twips, Length, RGBColor
 
@@ -22,5 +23,6 @@ __all__ = [
     "Twips",
     "Length",
     "RGBColor",
+    "flush_all",
     "__version__",
 ]

athena_python_docx-0.5.0/docx/_buffer.py

@@ -0,0 +1,248 @@
+"""HTTP command buffer for the docx-studio SDK.
+
+The buffer sits between SDK call sites and the HTTP transport. Every SDK
+mutation routes through it; we flush eagerly for queries and response-bearing
+ops (creates), and idle-batch pure mutations so a burst of setters becomes
+one HTTP request instead of N.
+
+Concurrency model: the SDK serializes calls through ``_batching.run_sync``
+(one persistent event-loop thread), so the buffer's primary thread is the
+loop thread. The auto-flush timer fires on a *different* thread, so we
+guard the pending list with an RLock and treat the timer flush as a
+best-effort coalesce — if the loop thread races us we just flush twice
+(or zero times; the next loop-thread call drains it).
+
+`flush_all` is a process-wide hook used by the Daytona sandbox prelude to
+make sure pending writes hit Keryx before the sandbox is suspended. It walks
+a weak-ref registry so dead Workbook instances don't keep their buffers
+alive.
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+import weakref
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Generator
+
+from docx.commands import Command, must_flush_immediately
+
+if TYPE_CHECKING:
+    from docx._http_doc import HttpClient
+
+
+# ---------------------------------------------------------------------------
+# Process-wide registry for flush_all()
+# ---------------------------------------------------------------------------
+
+_active_buffers: list[weakref.ref["CommandBuffer"]] = []
+_registry_lock = threading.Lock()
+
+
+def _register(buffer: "CommandBuffer") -> None:
+    with _registry_lock:
+        _active_buffers.append(weakref.ref(buffer))
+
+
+def _unregister(buffer: "CommandBuffer") -> None:
+    """Drop ``buffer`` from the active-registry list.
+
+    Called from :meth:`CommandBuffer.close` so a long-lived process that
+    opens and closes many Documents doesn't accumulate dead weak-refs in
+    the registry between ``flush_all`` calls.
+    """
+    with _registry_lock:
+        _active_buffers[:] = [
+            ref
+            for ref in _active_buffers
+            if (b := ref()) is not None and b is not buffer
+        ]
+
+
+def flush_all() -> None:
+    """Flush every live CommandBuffer in this process.
+
+    Used by the Daytona sandbox prelude after user code returns, so
+    buffered mutations make it to Keryx before the sandbox is suspended.
+    Safe to call when no Buffers exist (no-op). Failures are logged and
+    swallowed — we don't want one stuck buffer to mask the rest.
+    """
+    with _registry_lock:
+        snapshot = list(_active_buffers)
+        # Compact dead refs while we hold the lock.
+        live = [ref for ref in snapshot if ref() is not None]
+        _active_buffers[:] = live
+
+    for ref in live:
+        buf = ref()
+        if buf is None:
+            continue
+        try:
+            buf.flush()
+        except Exception as e:  # noqa: BLE001
+            sys.stderr.write(
+                f"[docx-sdk] flush_all: buffer {buf.asset_id} flush failed: {e}\n",
+            )
+
+
+# ---------------------------------------------------------------------------
+# CommandBuffer
+# ---------------------------------------------------------------------------
+
+# Idle window before a pure-mutation buffer auto-flushes. Short by design —
+# the SDK's main consumer is agent code that fires sequential property
+# setters within milliseconds of each other; we just need to coalesce those
+# without holding writes back from Keryx for human-perceptible time.
+DEFAULT_AUTO_FLUSH_SECONDS: float = 0.1
+
+
+class CommandBuffer:
+    """Buffers commands for one Document/asset.
+
+    Behaviour:
+    - Queries and response-bearing mutations (creates, inserts that return
+      ids) flush immediately. Pending pure mutations are flushed in the
+      same batch so ordering is preserved.
+    - Pure mutations (formatters, setters) are queued. An idle timer flushes
+      them after :data:`DEFAULT_AUTO_FLUSH_SECONDS` of inactivity, OR on
+      the next eager call, OR on explicit ``flush()``.
+    """
+
+    def __init__(
+        self,
+        client: "HttpClient",
+        asset_id: str,
+        *,
+        auto_flush_seconds: float = DEFAULT_AUTO_FLUSH_SECONDS,
+    ) -> None:
+        self._client: "HttpClient" = client
+        self._asset_id: str = asset_id
+        self._pending: list[Command] = []
+        self._lock: threading.RLock = threading.RLock()
+        self._timer: threading.Timer | None = None
+        self._auto_flush_seconds: float = auto_flush_seconds
+        self._closed: bool = False
+        _register(self)
+
+    @property
+    def asset_id(self) -> str:
+        return self._asset_id
+
+    @property
+    def pending_count(self) -> int:
+        with self._lock:
+            return len(self._pending)
+
+    def call(self, cmd: Command) -> Any:
+        """Execute or buffer ``cmd``.
+
+        For eager commands (queries, creates), drains the pending queue and
+        runs ``cmd`` in the same batch; returns the per-cmd result dict.
+
+        For pure mutations, appends to the queue, resets the idle timer,
+        and returns ``None``. The caller MUST NOT rely on the return value
+        of a buffered mutation — it's not available until flush.
+        """
+        if self._closed:
+            raise RuntimeError(
+                f"CommandBuffer for {self._asset_id} is closed",
+            )
+
+        if must_flush_immediately(cmd):
+            return self._eager_flush_with(cmd)
+
+        with self._lock:
+            self._pending.append(cmd)
+            self._reset_timer_locked()
+        return None
+
+    def flush(self) -> list[Any]:
+        """Flush pending commands as one HTTP batch.
+
+        Returns the list of per-command result dicts. Empty list if nothing
+        was pending. Cancels any active idle timer.
+        """
+        with self._lock:
+            self._cancel_timer_locked()
+            pending = self._pending
+            self._pending = []
+        if not pending:
+            return []
+        return self._client.execute_batch(self._asset_id, pending)
+
+    @contextmanager
+    def batch(self) -> Generator[None, None, None]:
+        """Group calls into one HTTP batch.
+
+        Inside the ``with`` block, eager commands still flush immediately
+        (we can't buffer reads — the caller is awaiting their result), but
+        pure mutations accumulate without their idle timer firing.
+        On exit, drains anything left.
+        """
+        # Cancel the idle timer for the duration of the block; we'll flush
+        # explicitly on exit. New adds inside the block go straight onto
+        # _pending without rescheduling the timer.
+        with self._lock:
+            self._cancel_timer_locked()
+            old_window = self._auto_flush_seconds
+            self._auto_flush_seconds = 0.0  # disable scheduling
+        try:
+            yield
+        finally:
+            with self._lock:
+                self._auto_flush_seconds = old_window
+            self.flush()
+
+    def close(self) -> None:
+        """Flush and disable. Idempotent."""
+        if self._closed:
+            return
+        try:
+            self.flush()
+        finally:
+            self._closed = True
+            _unregister(self)
+
+    # ----- internals -----
+
+    def _eager_flush_with(self, cmd: Command) -> Any:
+        """Drain pending + run ``cmd`` in one batch; return cmd's result."""
+        with self._lock:
+            self._cancel_timer_locked()
+            pending = self._pending
+            self._pending = []
+        all_cmds: list[Command] = [*pending, cmd]
+        results: list[Any] = self._client.execute_batch(self._asset_id, all_cmds)
+        if not results:
+            return {}
+        return results[-1]
+
+    def _reset_timer_locked(self) -> None:
+        # Caller must hold self._lock.
+        self._cancel_timer_locked()
+        if self._auto_flush_seconds <= 0:
+            return  # disabled (e.g. inside batch())
+        self._timer = threading.Timer(
+            self._auto_flush_seconds,
+            self._auto_flush,
+        )
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _cancel_timer_locked(self) -> None:
+        # Caller must hold self._lock.
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+
+    def _auto_flush(self) -> None:
+        try:
+            self.flush()
+        except Exception as e:  # noqa: BLE001
+            sys.stderr.write(
+                f"[docx-sdk] auto-flush failed for {self._asset_id}: {e}\n",
+            )
+
+
+__all__ = ["CommandBuffer", "flush_all", "DEFAULT_AUTO_FLUSH_SECONDS"]

athena_python_docx-0.5.0/docx/_http.py

@@ -0,0 +1,189 @@
+"""HTTP bootstrap for Document.create().
+
+The SDK's primary transport is y-websocket via Superdoc; this module is
+the *only* HTTP client in the package. It exists solely so that
+``Document.create()`` can hit ``POST /docs/empty`` on docx-studio to
+provision a new SuperDocument asset and receive a collab bundle to open
+the document with.
+
+We use ``urllib`` from stdlib to avoid pulling ``httpx`` / ``requests``
+into the runtime — this code runs in Daytona sandboxes where every MB
+matters, and the existing SDK already keeps its dep tree tight.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import TypedDict
+
+from docx.errors import (
+    AuthenticationError,
+    DocxError,
+    SessionError,
+)
+
+
+class _CollabBundle(TypedDict):
+    """The collab credentials returned alongside a freshly-created asset.
+
+    Note: env-var-shape (matches what ``Session`` reads), even though
+    the wire format from docx-studio uses different key names. The
+    keys are renamed at parse time.
+    """
+
+    SUPERDOC_COLLAB_TOKEN: str
+    KERYX_WS_URL: str
+    ATHENA_WORKSPACE_ID: str
+
+
+class CreateAssetResult(TypedDict):
+    """Parsed response from ``POST /docs/empty``."""
+
+    asset_id: str
+    name: str
+    workspace_id: str
+    collab: _CollabBundle
+
+
+_BASE_URL_ENV = "ATHENA_DOCX_BASE_URL"
+_API_KEY_ENV = "ATHENA_DOCX_API_KEY"  # noqa: S105
+
+
+def create_empty_document(
+    *,
+    base_url: str | None = None,
+    api_key: str | None = None,
+    name: str | None = None,
+    parent_folder_id: str | None = None,
+    workspace_id: str | None = None,
+    timeout: float = 30.0,
+) -> CreateAssetResult:
+    """Call ``POST {base_url}/docs/empty`` and parse the response.
+
+    Args:
+        base_url: docx-studio API base, e.g. ``https://docx-studio.stg.athenaintel.com``.
+            Falls back to ``$ATHENA_DOCX_BASE_URL``.
+        api_key: Athena API key (PropelAuth user API key) or PropelAuth
+            access token. Sent as ``Authorization: Bearer <api_key>``.
+            Falls back to ``$ATHENA_DOCX_API_KEY``.
+        name: Optional display title.
+        parent_folder_id: Optional parent folder; defaults to workspace root.
+        workspace_id: Optional workspace UUID; defaults to caller's
+            current workspace.
+        timeout: Request timeout in seconds.
+
+    Returns:
+        Parsed response dict with the new asset_id and a collab bundle
+        ready to feed into ``Session(..., bundle=...)``.
+
+    Raises:
+        SessionError: missing base_url or unparseable response.
+        AuthenticationError: missing api_key, or the server returned 401/403.
+        DocxError: any other 4xx/5xx from the server.
+    """
+    resolved_base: str | None = base_url or os.environ.get(_BASE_URL_ENV)
+    resolved_key: str | None = api_key or os.environ.get(_API_KEY_ENV)
+
+    if not resolved_base:
+        raise SessionError(
+            f"Missing base_url and {_BASE_URL_ENV} env var. "
+            "Pass base_url= to Document.create() or set the env var.",
+        )
+    if not resolved_key:
+        raise AuthenticationError(
+            f"Missing api_key and {_API_KEY_ENV} env var. "
+            "Pass api_key= to Document.create() or set the env var.",
+        )
+
+    url: str = resolved_base.rstrip("/") + "/docs/empty"
+    body: dict[str, str] = {}
+    if name is not None:
+        body["name"] = name
+    if parent_folder_id is not None:
+        body["parentFolderId"] = parent_folder_id
+    if workspace_id is not None:
+        body["workspaceId"] = workspace_id
+
+    # Lazy import — _http is loaded lazily by Document.create(), so the
+    # package is fully initialized by the time we reach this code.
+    from docx import __version__
+
+    payload: bytes = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(  # noqa: S310
+        url,
+        data=payload,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {resolved_key}",
+            "Accept": "application/json",
+            "User-Agent": f"athena-python-docx/{__version__}",
+        },
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+            raw: bytes = resp.read()
+    except urllib.error.HTTPError as e:
+        err_body: str = ""
+        try:
+            err_body = e.read().decode("utf-8", errors="replace")
+        except Exception:  # noqa: BLE001
+            pass
+        if e.code in (401, 403):
+            raise AuthenticationError(
+                f"docx-studio rejected the API key (HTTP {e.code}): {err_body}",
+            ) from e
+        raise DocxError(
+            f"docx-studio /docs/empty returned HTTP {e.code}: {err_body}",
+        ) from e
+    except urllib.error.URLError as e:
+        raise SessionError(
+            f"Unable to reach docx-studio at {url}: {e.reason}",
+        ) from e
+
+    try:
+        parsed: dict = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as e:
+        raise SessionError(
+            f"docx-studio returned non-JSON response: {raw[:200]!r}",
+        ) from e
+
+    asset_id_obj = parsed.get("assetId")
+    name_obj = parsed.get("name")
+    ws_obj = parsed.get("workspaceId")
+    collab_obj = parsed.get("collab")
+    if not (
+        isinstance(asset_id_obj, str)
+        and isinstance(name_obj, str)
+        and isinstance(ws_obj, str)
+        and isinstance(collab_obj, dict)
+    ):
+        raise SessionError(
+            f"docx-studio response is missing required fields: {parsed!r}",
+        )
+    token_obj = collab_obj.get("token")
+    ws_url_obj = collab_obj.get("wsUrl")
+    bundle_ws_obj = collab_obj.get("workspaceId")
+    if not (
+        isinstance(token_obj, str)
+        and isinstance(ws_url_obj, str)
+        and isinstance(bundle_ws_obj, str)
+    ):
+        raise SessionError(
+            f"docx-studio collab bundle is malformed: {collab_obj!r}",
+        )
+
+    return CreateAssetResult(
+        asset_id=asset_id_obj,
+        name=name_obj,
+        workspace_id=ws_obj,
+        collab=_CollabBundle(
+            SUPERDOC_COLLAB_TOKEN=token_obj,
+            KERYX_WS_URL=ws_url_obj,
+            ATHENA_WORKSPACE_ID=bundle_ws_obj,
+        ),
+    )