athena-python-docx 0.6.1__tar.gz → 0.6.2__tar.gz

{athena_python_docx-0.6.1 → athena_python_docx-0.6.2}/PKG-INFO

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

@@ -6,7 +6,7 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.6.1"
+__version__ = "0.6.2"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.6.1 → athena_python_docx-0.6.2}/docx/_buffer.py

@@ -278,7 +278,11 @@ class CommandBuffer:
         # PTC begin: one event per user-facing method call, before any
         # batching. Failures here can't crash the user's code path.
         try:
-            cmd._ptc_call_id = _ptc.emit_begin(type(cmd).__name__, cmd.to_dict())  # type: ignore[attr-defined]
+            cmd._ptc_call_id = _ptc.emit_begin(  # type: ignore[attr-defined]
+                type(cmd).__name__,
+                cmd.to_dict(),
+                asset_id=self._asset_id,
+            )
         except Exception:  # noqa: BLE001
             pass
 

{athena_python_docx-0.6.1 → athena_python_docx-0.6.2}/docx/_http_doc.py

@@ -68,6 +68,8 @@ from docx.commands import (
     Insert,
     InsertLineBreak,
     InsertTab,
+    ListsAttach,
+    ListsCreate,
     ListsMerge,
     ListsSplit,
     MarkdownToFragment,
@@ -503,9 +505,14 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "header_footers.get": HeaderFootersGet,
     "header_footers.resolve": HeaderFootersResolve,
     "header_footers.refs.set_linked_to_previous": HeaderFootersRefsSetLinkedToPrevious,
-    # Lists & Selection (SuperDoc 1.8.1 additions; not exposed on the
-    # python-docx parity surface — registered here for typed-bus
-    # completeness when advanced callers reach for them).
+    # Lists & Selection. ``lists.create`` and ``lists.attach`` are
+    # consumed internally by ``Document.add_paragraph`` to make
+    # ``style="List Bullet" | "List Number"`` produce real list
+    # structure (not just a style attribute on a flat paragraph).
+    # ``lists.merge``/``lists.split`` stay typed-bus-only — no
+    # python-docx parity surface for them.
+    "lists.create": ListsCreate,
+    "lists.attach": ListsAttach,
     "lists.merge": ListsMerge,
     "lists.split": ListsSplit,
     "selection.current": SelectionCurrent,

athena_python_docx-0.6.2/docx/_ptc.py

@@ -0,0 +1,138 @@
+"""Programmatic Tool Calling (PTC) — client side.
+
+Activated only when ``ATHENA_PTC_URL`` is set. The URL is a presigned
+endpoint URL with an HMAC-signed token embedded as ``?t=…``; the token
+carries the (thread, parent_tool_call_id, run) triple and an expiry.
+The SDK doesn't need to know that triple — it just POSTs to the URL
+verbatim, and the server derives identity from the token.
+
+Without ``ATHENA_PTC_URL`` set, every call here is a no-op.
+
+Emits are fire-and-forget on a background daemon thread:
+
+- Never raise into user code.
+- Never block the calling thread.
+- Re-read ``ATHENA_PTC_URL`` on every emit so updates between sandbox
+  executions take effect immediately (the SDK module itself is cached
+  across runs).
+- Snapshot the URL at ``emit_begin`` time and carry it to ``emit_end``
+  so late end events can't be misattributed if a new sandbox run
+  swapped in a different URL between begin and end.
+
+This module is *intentionally byte-identical* across the docx / pptx /
+xlsx SDKs — the three SDKs have no shared base. Duplicating ~100 LOC
+of stdlib code is cheaper than spinning up a 4th release pipeline.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import queue
+import threading
+import time
+import urllib.error
+import urllib.request
+import uuid
+from typing import Any
+
+_MAX_QUEUE = 4096
+_MAX_BODY = 64 * 1024
+_HTTP_TIMEOUT = 2.0
+
+# Singleton state. PTC has exactly one outbox per process.
+_outbox: queue.Queue[tuple[str, dict[str, Any]]] = queue.Queue(maxsize=_MAX_QUEUE)
+_thread_lock = threading.Lock()
+_thread_started = False
+# call_id -> URL snapshot at begin time; lets emit_end target the
+# original run's endpoint even if ATHENA_PTC_URL changed since.
+_call_url: dict[str, str] = {}
+
+
+def _drain() -> None:
+    while True:
+        item = _outbox.get()
+        if item is None:
+            return
+        url, body = item
+        try:
+            raw = json.dumps(body).encode("utf-8")
+            if len(raw) > _MAX_BODY:
+                key = "args" if body.get("phase") == "begin" else "result"
+                body[key] = {"__truncated__": True}
+                raw = json.dumps(body).encode("utf-8")
+            req = urllib.request.Request(
+                url,
+                data=raw,
+                method="POST",
+                headers={"Content-Type": "application/json"},
+            )
+            urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT).close()
+        except (urllib.error.URLError, OSError, ValueError):
+            pass  # never propagate
+
+
+def _ensure_thread() -> None:
+    global _thread_started
+    if _thread_started:
+        return
+    with _thread_lock:
+        if _thread_started:
+            return
+        threading.Thread(target=_drain, name="athena-ptc", daemon=True).start()
+        _thread_started = True
+
+
+def _send(url: str, body: dict[str, Any]) -> None:
+    _ensure_thread()
+    try:
+        _outbox.put_nowait((url, body))
+    except queue.Full:
+        pass  # drop on backpressure; never block user code
+
+
+def emit_begin(
+    tool_name: str,
+    args: dict[str, Any],
+    *,
+    asset_id: str | None = None,
+) -> str:
+    call_id = uuid.uuid4().hex
+    url = os.environ.get("ATHENA_PTC_URL")
+    if not url:
+        return call_id
+    _call_url[call_id] = url
+    body: dict[str, Any] = {
+        "callId": call_id,
+        "toolName": tool_name,
+        "phase": "begin",
+        "args": args,
+        "ts": time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime()),
+    }
+    if asset_id is not None:
+        body["assetId"] = asset_id
+    _send(url, body)
+    return call_id
+
+
+def emit_end(
+    *,
+    call_id: str,
+    tool_name: str,
+    result: dict[str, Any] | None,
+    is_error: bool,
+) -> None:
+    url = _call_url.pop(call_id, None)
+    if url is None:
+        return  # PTC was disabled at begin, or begin wasn't emitted
+    _send(
+        url,
+        {
+            "callId": call_id,
+            "toolName": tool_name,
+            "phase": "end",
+            "result": result,
+            "isError": is_error,
+            "ts": time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime()),
+        },
+    )

{athena_python_docx-0.6.1 → athena_python_docx-0.6.2}/docx/commands.py

@@ -619,6 +619,40 @@ class HeaderFootersRefsSetLinkedToPrevious(Command):
 # every other op.
 
 
+@dataclass
+class ListsCreate(Command):
+    """Create a new list — either an empty list at an anchor, or by
+    converting an existing paragraph (range) into a list.
+
+    SuperDoc: ``doc.lists.create``.
+
+    - ``mode="empty"`` requires ``at`` (BlockAddress).
+    - ``mode="fromParagraphs"`` requires ``target`` (BlockAddressOrRange).
+    - ``kind`` is ``"bullet"`` or ``"ordered"``.
+    """
+
+    mode: str = "fromParagraphs"
+    at: dict[str, Any] | None = None
+    target: dict[str, Any] | None = None
+    kind: str | None = None
+    level: int | None = None
+    preset: str | None = None
+
+
+@dataclass
+class ListsAttach(Command):
+    """Attach an existing paragraph to an existing list as a new item.
+
+    SuperDoc: ``doc.lists.attach``. ``attach_to`` is the list item to
+    attach next to (defines list membership); ``target`` is the
+    paragraph being converted.
+    """
+
+    attach_to: dict[str, Any] = dataclasses.field(default_factory=dict)
+    target: dict[str, Any] = dataclasses.field(default_factory=dict)
+    level: int | None = None
+
+
 @dataclass
 class ListsMerge(Command):
     """Merge a list item with an adjacent list / list item.
@@ -768,6 +802,12 @@ _RESPONSE_BEARING_TYPES: frozenset[str] = frozenset(
         # describing the entities affected by accept/reject — callers
         # need that synchronously to invalidate their Revision proxies.
         "TrackChangesDecide",
+        # ListsCreate / ListsAttach return {item: {nodeId: <listItemId>}}.
+        # Document.add_paragraph reads listItemId to (1) update the
+        # Paragraph proxy's node_id so subsequent ops target the
+        # listItem, and (2) chain the next list item via lists.attach.
+        "ListsCreate",
+        "ListsAttach",
     }
 )
 

{athena_python_docx-0.6.1 → athena_python_docx-0.6.2}/docx/document.py

@@ -79,6 +79,49 @@ class _InlineShapeIdAdapter:
         )
 
 
+def _classify_list_style(style_id: str | None) -> tuple[str, int] | None:
+    """Map a python-docx list-style id to a SuperDoc (kind, level) pair.
+
+    Returns ``None`` for non-list styles. Recognized styles:
+
+    - ``"List Bullet"``    → ``("bullet", 0)``
+    - ``"List Bullet 2"``  → ``("bullet", 1)``     (... up to ``5`` → level 4)
+    - ``"List Number"``    → ``("ordered", 0)``
+    - ``"List Number 2"``  → ``("ordered", 1)``    (... up to ``5`` → level 4)
+
+    Accepts both display-name (``"List Bullet 2"``) and style-id
+    (``"ListBullet2"``) forms. ``"List Paragraph"`` and ``"List Continue"``
+    are intentionally NOT classified as bullet/number lists — those styles
+    indicate "indented body text", not a numbered/bulleted list, and Word
+    renders them without a marker. Callers wanting those effects should
+    use the style as-is via the generic ``setStyle`` path.
+    """
+    if not isinstance(style_id, str) or not style_id:
+        return None
+    # Normalize: lower-case, strip spaces.
+    norm = style_id.lower().replace(" ", "")
+    if norm.startswith("listbullet"):
+        suffix = norm[len("listbullet"):]
+        kind = "bullet"
+    elif norm.startswith("listnumber"):
+        suffix = norm[len("listnumber"):]
+        kind = "ordered"
+    else:
+        return None
+    if suffix == "":
+        level = 0
+    else:
+        try:
+            n = int(suffix)
+        except ValueError:
+            return None
+        if n < 1 or n > 9:
+            return None
+        # "List Bullet 2" → level 1 (zero-indexed depth).
+        level = n - 1
+    return (kind, level)
+
+
 class IgnoredSaveTargetWarning(UserWarning):
     """Emitted when ``Document.save(path_or_stream=...)`` is called with a
     non-None argument.
@@ -123,6 +166,13 @@ class Document:
         self._pending_user_name: str | None = user_name
         self._pending_user_email: str | None = user_email
         self._pending_track_revisions: bool = bool(track_revisions)
+        # List-chain state. When the most-recent ``add_paragraph`` call
+        # produced a list item, subsequent ``add_paragraph(..., style="List
+        # Bullet"|"List Number")`` calls attach to it (lists.attach)
+        # instead of starting a new list (lists.create). Any non-list
+        # ``add_paragraph`` / ``add_heading`` / ``add_table`` resets this.
+        self._last_list_item_id: str | None = None
+        self._last_list_kind: str | None = None
 
     @classmethod
     def create(
@@ -689,8 +739,142 @@ class Document:
             # or transport error otherwise leaves the user with a
             # paragraph that quietly missed the style they asked for.
             para.style = style_str
+
+        # python-docx parity: ``add_paragraph(text, style="List Bullet")``
+        # is the canonical way to author a bulleted/numbered list (the
+        # upstream library exposes no separate list primitive — the style
+        # is the list). On Word/OOXML the style's ``<w:numPr/>`` makes
+        # bullets appear; on SuperDoc/ProseMirror the style attribute
+        # alone does NOT, because lists are a distinct node type
+        # (``bulletList > listItem > paragraph``) rather than a flat
+        # paragraph with a style.
+        #
+        # To make the python-docx contract render correctly we follow
+        # up the paragraph create + setStyle with SuperDoc's
+        # ``doc.lists.create`` / ``doc.lists.attach`` so the paragraph
+        # is structurally converted into a list item under a real
+        # bulletList / orderedList node. Consecutive list-styled
+        # ``add_paragraph`` calls (of the same kind) chain into a
+        # single list via ``lists.attach``; the first one starts a new
+        # list via ``lists.create(mode="fromParagraphs")``.
+        list_info = _classify_list_style(style_str)
+        if list_info is not None:
+            kind, level = list_info
+            self._convert_paragraph_to_list_item(
+                paragraph_node_id=node_id,
+                kind=kind,
+                level=level,
+            )
+        else:
+            # Any non-list paragraph breaks the chain — the next list
+            # item will start a fresh list.
+            self._last_list_item_id = None
+            self._last_list_kind = None
         return para
 
+    def _convert_paragraph_to_list_item(
+        self,
+        *,
+        paragraph_node_id: str,
+        kind: str,
+        level: int,
+    ) -> None:
+        """Promote a flat paragraph into a list item.
+
+        Chains with the previous list (same ``kind``) via
+        ``lists.attach``; otherwise starts a new list via
+        ``lists.create(mode="fromParagraphs")``. Updates the
+        ``_last_list_item_id`` / ``_last_list_kind`` chain state so the
+        next list-styled ``add_paragraph`` call attaches to this item.
+
+        Failures don't raise — the paragraph + setStyle already
+        landed, and surfacing a structural-promotion error here would
+        roll back work the caller can't undo. We emit a console warning
+        and reset the chain so subsequent items start fresh rather than
+        attaching to an orphaned id.
+        """
+        para_target: dict = {
+            "kind": "block",
+            "nodeType": "paragraph",
+            "nodeId": paragraph_node_id,
+        }
+        try:
+            if (
+                self._last_list_item_id is not None
+                and self._last_list_kind == kind
+            ):
+                result = run_sync(
+                    self._session.doc.lists.attach(
+                        {
+                            "attach_to": {
+                                "kind": "block",
+                                "nodeType": "listItem",
+                                "nodeId": self._last_list_item_id,
+                            },
+                            "target": para_target,
+                            "level": level,
+                        },
+                    ),
+                )
+            else:
+                result = run_sync(
+                    self._session.doc.lists.create(
+                        {
+                            "mode": "fromParagraphs",
+                            "target": para_target,
+                            "kind": kind,
+                            "level": level,
+                        },
+                    ),
+                )
+        except Exception as e:  # noqa: BLE001
+            _log_warn(
+                f"list-item promotion failed for paragraph "
+                f"{paragraph_node_id!r} ({kind}, level {level}): {e}; "
+                f"paragraph remains flat with the style attribute set.",
+            )
+            self._last_list_item_id = None
+            self._last_list_kind = None
+            return
+
+        item_id = self._extract_list_item_id(result)
+        if item_id:
+            self._last_list_item_id = item_id
+            self._last_list_kind = kind
+        else:
+            # Couldn't read back the listItem id — break the chain so the
+            # next call doesn't attach to a stale or missing target.
+            _log_warn(
+                f"list op returned no item.nodeId for paragraph "
+                f"{paragraph_node_id!r}; list chain reset. Response: "
+                f"{result!r}",
+            )
+            self._last_list_item_id = None
+            self._last_list_kind = None
+
+    def _reset_list_chain(self) -> None:
+        """Break the consecutive-list-items chain. Called by any block
+        insertion that isn't a list-styled paragraph (heading, table,
+        picture, page break, section break) so the next list item
+        starts a fresh list rather than attaching to a stale predecessor.
+        """
+        self._last_list_item_id = None
+        self._last_list_kind = None
+
+    @staticmethod
+    def _extract_list_item_id(result: object) -> str | None:
+        """Pull ``item.nodeId`` out of a ``lists.create`` / ``lists.attach``
+        SuperDoc response. Returns ``None`` if the shape is unexpected."""
+        if not isinstance(result, dict):
+            return None
+        item = result.get("item")
+        if not isinstance(item, dict):
+            return None
+        node_id = item.get("nodeId") or item.get("node_id")
+        if isinstance(node_id, str) and node_id:
+            return node_id
+        return None
+
     def add_heading(
         self,
         text: str = "",
@@ -700,6 +884,7 @@ class Document:
         from docx.text.paragraph import Paragraph
 
         self._ensure_open()
+        self._reset_list_chain()
         if not 0 <= level <= 9:
             raise ValidationError(
                 f"level must be in 0..9; got {level}",
@@ -796,6 +981,7 @@ class Document:
         from docx.table import Table
 
         self._ensure_open()
+        self._reset_list_chain()
         if rows < 1 or cols < 1:
             raise ValidationError(
                 f"rows and cols must be >= 1; got rows={rows} cols={cols}",
@@ -883,6 +1069,7 @@ class Document:
         from docx.text.run import _build_inline_shape_info
 
         self._ensure_open()
+        self._reset_list_chain()
 
         image_bytes: bytes
         fallback_path: str = ""

{athena_python_docx-0.6.1 → athena_python_docx-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.6.1"
+version = "0.6.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.6.1 → athena_python_docx-0.6.2}/tests/fidelity/fake_session.py

@@ -686,6 +686,40 @@ class FakeDocState:
         if op.startswith("styles."):
             return {"ok": True}
 
+        # ---- lists ----
+        # lists.create / lists.attach return ``{success, item: {nodeId, ...}}``.
+        # The fake doesn't model the ProseMirror list tree faithfully — it
+        # only mints a deterministic listItem id keyed off the paragraph id
+        # so consecutive ``add_paragraph(style="List Bullet")`` calls in
+        # ``Document._convert_paragraph_to_list_item`` produce the chained
+        # ``lists.create → lists.attach → lists.attach`` op sequence that
+        # the op-snapshot tests pin.
+        if op == "lists.create":
+            target = params.get("target") or {}
+            pid = str(target.get("nodeId") or "")
+            return {
+                "success": True,
+                "listId": f"list-{pid}",
+                "item": {
+                    "kind": "block",
+                    "nodeType": "listItem",
+                    "nodeId": f"li-{pid}",
+                },
+            }
+        if op == "lists.attach":
+            target = params.get("target") or {}
+            pid = str(target.get("nodeId") or "")
+            return {
+                "success": True,
+                "item": {
+                    "kind": "block",
+                    "nodeType": "listItem",
+                    "nodeId": f"li-{pid}",
+                },
+            }
+        if op.startswith("lists."):
+            return {"ok": True}
+
         # ---- tables ----
         if op == "tables.get":
             tid = params.get("nodeId")

{athena_python_docx-0.6.1 → athena_python_docx-0.6.2}/tests/fidelity/op_snapshots/rw01_official_quickstart.json

@@ -12,8 +12,10 @@
   "styles.paragraph.setStyle",
   "create.paragraph",
   "styles.paragraph.setStyle",
+  "lists.create",
   "create.paragraph",
   "styles.paragraph.setStyle",
+  "lists.create",
   "create.table",
   "tables.get",
   "tables.get",

{athena_python_docx-0.6.1 → athena_python_docx-0.6.2}/tests/fidelity/op_snapshots/rw02_paragraph_style_list.json

@@ -1,12 +1,17 @@
 [
   "create.paragraph",
   "styles.paragraph.setStyle",
+  "lists.create",
   "create.paragraph",
   "styles.paragraph.setStyle",
+  "lists.attach",
   "create.paragraph",
   "styles.paragraph.setStyle",
+  "lists.attach",
   "create.paragraph",
   "styles.paragraph.setStyle",
+  "lists.attach",
   "create.paragraph",
-  "styles.paragraph.setStyle"
+  "styles.paragraph.setStyle",
+  "lists.attach"
 ]