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

{athena_python_pptx-0.1.75 → athena_python_pptx-0.1.77}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.1.76
+
+**Table cell paragraph alignment now round-trips to OOXML (baseline-parity Gap A2).**
+
+`cell.text_frame.paragraphs[0].alignment = PP_ALIGN.X` previously stored
+the value locally for python-pptx parity but never reached the server.
+The setter now translates `PP_PARAGRAPH_ALIGNMENT` enum members (and the
+python-pptx lowercase string aliases) to the OOXML short form
+(`l` / `ctr` / `r` / `just` / `dist` / `thaiDist` / `justLow`) and emits
+a `SetTableCell` command carrying `paragraphAlignment`. The applier
+writes it to every paragraph in the cell's text body; the export worker
+emits a `SetTableCellText` intent whose paragraph alignment lands on
+`<a:pPr algn="…">` in the exported PPTX.
+
+Closes ~52 baseline-parity XML diffs against the 33 fixtures in
+`pptx-studio/tests/baseline-parity/`.
+
 ## 0.1.75
 
 **Critical bug fix — invisible text from `font.size = Pt(X)`.**

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-pptx
-Version: 0.1.75
+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.75 → athena_python_pptx-0.1.77}/pptx/__init__.py

@@ -127,7 +127,7 @@ def flush_all() -> None:
     _active_buffers[:] = alive
 
 
-__version__ = "0.1.75"
+__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.75 → 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.75 → athena_python_pptx-0.1.77}/pptx/commands.py

@@ -476,6 +476,12 @@ class SetTableCell(Command):
         col: Column index (0-based)
         text: Cell text content
         fill_color_hex: Cell background color
+        paragraph_alignment: Horizontal alignment of the cell's text body.
+            Mirrors python-pptx ``cell.text_frame.paragraphs[0].alignment``.
+            Accepts the OOXML short forms ``l``, ``ctr``, ``r``, ``just``,
+            ``dist``, ``thaiDist``. Translated from ``PP_ALIGN`` /
+            ``PP_PARAGRAPH_ALIGNMENT`` by the SDK before emit. Closes
+            baseline-parity Gap A2 (~52 diffs across table fixtures).
     """
 
     shape_id: ShapeId
@@ -486,6 +492,7 @@ class SetTableCell(Command):
     font_size_centipoints: Optional[int] = None
     bold: Optional[bool] = None
     font_color_hex: Optional[str] = None
+    paragraph_alignment: Optional[str] = None
 
     @property
     def command_type(self) -> str:

{athena_python_pptx-0.1.75 → athena_python_pptx-0.1.77}/pptx/shapes/__init__.py

@@ -56,6 +56,57 @@ _ELEMENT_TYPE_TO_MSO_SHAPE_TYPE: dict[str, MSO_SHAPE_TYPE] = {
 }
 
 
+# Map PP_PARAGRAPH_ALIGNMENT enum members and python-pptx string aliases
+# to OOXML <a:pPr algn="..."> short forms. Accepts the IntEnum int values
+# directly so callers can pass ``PP_ALIGN.CENTER`` without importing the
+# enum class. ``None`` clears the attribute.
+_PP_ALIGN_INT_TO_OOXML: dict[int, str] = {
+    1: "l",
+    2: "ctr",
+    3: "r",
+    4: "just",
+    5: "dist",
+    6: "thaiDist",
+    7: "justLow",
+}
+_PP_ALIGN_NAME_TO_OOXML: dict[str, str] = {
+    "left": "l",
+    "center": "ctr",
+    "right": "r",
+    "justify": "just",
+    "distribute": "dist",
+    "thai_distribute": "thaiDist",
+    "justify_low": "justLow",
+    # Already-short forms pass through.
+    "l": "l", "ctr": "ctr", "r": "r",
+    "just": "just", "dist": "dist", "thaiDist": "thaiDist", "justLow": "justLow",
+}
+
+
+def _normalize_pp_align(value: Any) -> Optional[str]:
+    """Translate a PP_ALIGN value to the OOXML short form used by SetTableCell.
+
+    Accepts ``PP_PARAGRAPH_ALIGNMENT`` (or any ``int``) and the lowercased
+    python-pptx string aliases used by ``pptx.text.PP_ALIGN``. Returns
+    ``None`` for ``None`` input so the setter can clear the attribute.
+    """
+    if value is None:
+        return None
+    if isinstance(value, int) and not isinstance(value, bool):
+        try:
+            return _PP_ALIGN_INT_TO_OOXML[int(value)]
+        except KeyError:
+            raise ValueError(f"Unsupported paragraph alignment value: {value!r}")
+    if isinstance(value, str):
+        try:
+            return _PP_ALIGN_NAME_TO_OOXML[value]
+        except KeyError:
+            raise ValueError(f"Unsupported paragraph alignment value: {value!r}")
+    raise TypeError(
+        f"alignment must be a PP_ALIGN enum, int, or string; got {type(value).__name__}"
+    )
+
+
 # Map XL_CHART_TYPE → (server chart_type, grouping). Only the chart types
 # author.ts supports today are listed here; anything else raises
 # UnsupportedFeatureError. Surface area mirrors python-pptx's accepted enum
@@ -5814,15 +5865,13 @@ class _TableCellParagraph:
     For API parity with python-pptx, ``add_run()`` and ``clear()`` are
     supported but operate on the single underlying run — multiple
     ``add_run()`` calls return the *same* ``_TableCellRun`` object, and
-    only the last text/style assignment wins. ``alignment`` is accepted
-    for compatibility but doesn't yet round-trip to OOXML (no per-cell
-    paragraph-alignment command on the applier).
+    only the last text/style assignment wins. ``alignment`` round-trips
+    to ``<a:pPr algn="...">`` on the cell's text body via SetTableCell.
     """
 
     def __init__(self, cell: "TableCell"):
         self._cell = cell
         self._runs = [_TableCellRun(cell)]
-        self._alignment: Optional[Any] = None
 
     @property
     def runs(self) -> list[_TableCellRun]:
@@ -5838,12 +5887,22 @@ class _TableCellParagraph:
 
     @property
     def alignment(self) -> Optional[Any]:
-        return self._alignment
+        """Return the cell's paragraph alignment as the original input value.
+
+        Stored on the parent cell so that text-body re-creation (which
+        rebuilds the paragraph wrapper) doesn't lose the assignment.
+        """
+        return self._cell._paragraph_alignment_input
 
     @alignment.setter
     def alignment(self, value: Any) -> None:
-        # Accepted for python-pptx parity; not yet round-tripped to OOXML.
-        self._alignment = value
+        # Translate PP_ALIGN enum / string to OOXML short form. Stored on
+        # the cell so we can re-emit it inside SetTableCell. Keep the
+        # original input around for the getter to return per python-pptx
+        # semantics (callers expect the same value type back).
+        self._cell._paragraph_alignment_input = value
+        self._cell._paragraph_alignment = _normalize_pp_align(value)
+        self._cell._emit_cell_change()
 
     def add_run(self) -> _TableCellRun:
         """Return the single underlying run.
@@ -5943,6 +6002,10 @@ class TableCell:
         self._margin_top = margin_top
         self._margin_bottom = margin_bottom
         self._vertical_anchor = vertical_anchor
+        # OOXML short form (``l``/``ctr``/``r``/...) sent over the wire and
+        # the caller's original input retained for the python-pptx getter.
+        self._paragraph_alignment: Optional[str] = None
+        self._paragraph_alignment_input: Any = None
 
     @property
     def text(self) -> str:
@@ -6318,6 +6381,7 @@ class TableCell:
                 font_size_centipoints=int(self._font_size_pt * 100) if self._font_size_pt is not None else None,
                 bold=self._bold,
                 font_color_hex=self._font_color_hex,
+                paragraph_alignment=self._paragraph_alignment,
             )
             self._table._buffer.add(cmd)
 

{athena_python_pptx-0.1.75 → 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.75 → 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.75 → athena_python_pptx-0.1.77}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-pptx"
-version = "0.1.75"
+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.75/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"]