athena-python-pptx 0.1.76__tar.gz → 0.1.77__tar.gz

{athena_python_pptx-0.1.76 → athena_python_pptx-0.1.77}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-pptx
-Version: 0.1.76
+Version: 0.1.77
 Summary: Drop-in replacement for python-pptx that connects to PPTX Studio for real-time collaboration
 Project-URL: Homepage, https://github.com/pptx-studio/python-sdk
 Project-URL: Documentation, https://docs.pptx-studio.com/sdk/python

{athena_python_pptx-0.1.76 → athena_python_pptx-0.1.77}/pptx/__init__.py

@@ -127,7 +127,7 @@ def flush_all() -> None:
     _active_buffers[:] = alive
 
 
-__version__ = "0.1.76"
+__version__ = "0.1.77"
 
 __all__ = [
     # Main entry point

athena_python_pptx-0.1.77/pptx/_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_pptx-0.1.76 → athena_python_pptx-0.1.77}/pptx/batching.py

@@ -130,6 +130,7 @@ class CommandBuffer:
             command._ptc_call_id = _ptc.emit_begin(  # type: ignore[attr-defined]
                 type(command).__name__,
                 command.to_dict(),
+                asset_id=self._deck_id,
             )
         except Exception:  # noqa: BLE001
             pass

{athena_python_pptx-0.1.76 → athena_python_pptx-0.1.77}/pptx/slides.py

@@ -6,6 +6,7 @@ Provides python-pptx-compatible Slide and Slides collection abstractions.
 
 from __future__ import annotations
 import re
+import warnings
 from typing import TYPE_CHECKING, Any, Iterator, Optional, Union
 
 if TYPE_CHECKING:
@@ -2105,7 +2106,9 @@ class SlideLayout:
 
         If this layout is attached to a concrete slide, returns that slide's
         placeholders. Otherwise, best-effort resolves placeholders from the
-        first slide using this layout index.
+        first slide using this layout index. When no such slide exists yet,
+        emits a ``RuntimeWarning`` and returns an empty collection — the REST
+        snapshot does not materialize layout-level placeholders standalone.
         """
         if self._slide is not None:
             return self._slide.placeholders
@@ -2115,6 +2118,15 @@ class SlideLayout:
                 if slide._layout_index == self._index:
                     return slide.placeholders
 
+        warnings.warn(
+            f"SlideLayout[{self._index}] ({self.name!r}) has no placeholders to "
+            f"enumerate yet — the REST snapshot only exposes layout placeholders "
+            f"through a slide that uses the layout. Call "
+            f"prs.slides.add_slide(layout) and prs.refresh(), then read "
+            f"slide.placeholders to see the inherited placeholder set.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
         return SlidePlaceholders({})
 
     @property

{athena_python_pptx-0.1.76 → athena_python_pptx-0.1.77}/pptx/text/__init__.py

@@ -1428,6 +1428,17 @@ class TextFrame:
 
         Returns None when all paragraphs have a single run with no hyperlinks,
         so the server falls back to the simpler text-split behaviour.
+
+        Note on empty paragraphs (Gap-3): when a paragraph has zero runs
+        (post ``clear()`` or freshly added via ``add_paragraph()``) we
+        intentionally stay on the plain-text path. The server's plain-text
+        SetText creates one empty run per paragraph, which matches what
+        ``add_run()`` + ``run.text = …`` would have created and keeps
+        downstream ``SetRunStyle(p, r=0)`` commands valid even before the
+        local SDK has emitted any run-level text. Switching to rich-content
+        with ``runs: []`` here would break the safe ``clear() →
+        add_run() → run.font.size = …`` ordering because ``SetRunStyle``
+        would target a non-existent server run.
         """
         needs_rich = False
         for para in self._paragraphs:
@@ -1458,7 +1469,10 @@ class TextFrame:
                 if run._hyperlink._address:
                     run_data["hyperlinkUrl"] = run._hyperlink._address
                 runs.append(run_data)
-            # Ensure at least one run per paragraph
+            # When a paragraph carries no runs locally (post-clear / freshly
+            # added) the plain-text fallback would create one empty run on
+            # the server. Mirror that here so a rich-content emit doesn't
+            # regress to zero runs and break later SetRunStyle calls.
             if not runs:
                 runs.append({"text": ""})
             paragraphs.append({"runs": runs})

{athena_python_pptx-0.1.76 → athena_python_pptx-0.1.77}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-pptx"
-version = "0.1.76"
+version = "0.1.77"
 description = "Drop-in replacement for python-pptx that connects to PPTX Studio for real-time collaboration"
 readme = "README.md"
 license = "MIT"

athena_python_pptx-0.1.76/pptx/_ptc.py

@@ -1,173 +0,0 @@
-"""Programmatic Tool Calling (PTC) — client side, docx SDK.
-
-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* duplicated into the pptx and xlsx SDKs
-— the three SDKs have no shared base. Keeping it byte-identical
-(modulo ``_LIB_NAME``) makes diffs trivial.
-"""
-
-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
-
-_LIB_NAME = "pptx"
-
-_MAX_QUEUE = 4096
-_MAX_BODY = 64 * 1024
-_HTTP_TIMEOUT = 2.0
-
-_PTC_URL_ENV = "ATHENA_PTC_URL"
-
-
-def _read_url() -> str | None:
-    url = os.environ.get(_PTC_URL_ENV)
-    return url if url else None
-
-
-def _utcnow_iso() -> str:
-    return time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime())
-
-
-class _PTCClient:
-    def __init__(self) -> None:
-        # Lazy: don't snapshot URL at import time; runs change between
-        # sandbox executions and the module is cached in sys.modules.
-        self._q: queue.Queue[tuple[str, dict[str, Any]] | None] = queue.Queue(
-            maxsize=_MAX_QUEUE,
-        )
-        self._started = False
-        self._lock = threading.Lock()
-        # call_id -> URL snapshot at begin time. Lets emit_end target
-        # the original run's endpoint even if env changed since.
-        self._call_url: dict[str, str] = {}
-
-    def _ensure_started(self) -> None:
-        if self._started:
-            return
-        with self._lock:
-            if self._started:
-                return
-            t = threading.Thread(
-                target=self._drain,
-                name=f"athena-{_LIB_NAME}-ptc",
-                daemon=True,
-            )
-            t.start()
-            self._started = True
-
-    def emit_begin(self, tool_name: str, args: dict[str, Any]) -> str:
-        call_id = uuid.uuid4().hex
-        url = _read_url()
-        if url is None:
-            return call_id
-        self._call_url[call_id] = url
-        self._ensure_started()
-        body = {
-            "callId": call_id,
-            "toolName": f"{_LIB_NAME}.{tool_name}",
-            "phase": "begin",
-            "args": args,
-            "ts": _utcnow_iso(),
-        }
-        self._enqueue(url, body)
-        return call_id
-
-    def emit_end(
-        self,
-        *,
-        call_id: str,
-        tool_name: str,
-        result: dict[str, Any] | None,
-        is_error: bool,
-    ) -> None:
-        url = self._call_url.pop(call_id, None)
-        if url is None:
-            return  # PTC was disabled at begin, or begin wasn't emitted
-        body = {
-            "callId": call_id,
-            "toolName": f"{_LIB_NAME}.{tool_name}",
-            "phase": "end",
-            "result": result,
-            "isError": is_error,
-            "ts": _utcnow_iso(),
-        }
-        self._enqueue(url, body)
-
-    def _enqueue(self, url: str, body: dict[str, Any]) -> None:
-        try:
-            self._q.put_nowait((url, body))
-        except queue.Full:
-            pass  # drop on backpressure; never block user code
-
-    def _drain(self) -> None:
-        while True:
-            item = self._q.get()
-            if item is None:
-                return
-            url, body = item
-            try:
-                raw = json.dumps(body).encode("utf-8")
-                if len(raw) > _MAX_BODY:
-                    truncated_key = "args" if body.get("phase") == "begin" else "result"
-                    body[truncated_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
-
-
-_CLIENT = _PTCClient()
-
-
-def emit_begin(tool_name: str, args: dict[str, Any]) -> str:
-    return _CLIENT.emit_begin(tool_name, args)
-
-
-def emit_end(
-    *,
-    call_id: str,
-    tool_name: str,
-    result: dict[str, Any] | None,
-    is_error: bool,
-) -> None:
-    _CLIENT.emit_end(
-        call_id=call_id,
-        tool_name=tool_name,
-        result=result,
-        is_error=is_error,
-    )
-
-
-__all__ = ["emit_begin", "emit_end"]