athena-python-pptx 0.3.0__tar.gz → 0.3.1__tar.gz

{athena_python_pptx-0.3.0 → athena_python_pptx-0.3.1}/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.3.1
+
+**Chart title runs, slide insertion, and shape-delete local state — Insight
+Partners session feedback batch.**
+
+Investigated [thread_7b324723-…](https://app.athenaintel.com/dashboard/spaces/?session_id=thread_7b324723-a478-4e99-ac8f-6e7a69766292)
+where an agent built a 15-slide LP pitch deck and tripped over three
+SDK rough edges. Each is addressed below.
+
+- **`chart.chart_title.text_frame.paragraphs[0].runs[0].font` now works.**
+  The `_ChartTitleTextFrame` previously exposed only `text`; iterating
+  `paragraphs` raised `AttributeError`, and the agent fell back to
+  unstyled titles. The text frame now carries paragraph and run
+  proxies; per-run font writes coalesce into a single
+  `SetChartTitleRich` patch on the next flush. The simple
+  `text_frame.text = "..."` path still uses the cheaper `SetChartTitle`
+  patch — no wire-size regression on the no-formatting case.
+
+- **`prs.slides.insert(idx, layout)` added.** Previously, placing a new
+  slide between two existing slides required `add_slide()` followed by
+  `clone(target_index=...)` to shuffle the list — a workaround that
+  cloned 11 shapes onto the new slide and then couldn't fully clear
+  them. `insert()` emits a single `AddSlide(index=...)` and refreshes
+  the local collection.
+
+- **`shape.delete()` updates the local `slide.shapes` view immediately.**
+  The buffered delete left `len(slide.shapes)` stale, so the
+  "Before: 33, After: 33" symptom appeared even when the delete was
+  going through correctly server-side. `delete()` now removes the
+  shape from the parent `Shapes` collection in addition to queueing
+  the `DeleteShape` command. Layout-inherited shapes
+  (`source == "layout"`) no-op rather than queue a guaranteed-to-fail
+  delete.
+
+- **Toolkit prompt updated** to surface the working chart APIs —
+  `series.format.fill.solid()` + `series.format.fill.fore_color.rgb`,
+  `chart.legend.position`, doughnut/pie chart enums — and the new
+  `slide.clear_shapes()` / `prs.slides.insert()` helpers. The
+  Insight Partners agent assumed series styling was unsupported and
+  skipped per-series brand colors entirely.
+
 ## 0.1.76
 
 **Table cell paragraph alignment now round-trips to OOXML (baseline-parity Gap A2).**

{athena_python_pptx-0.3.0 → athena_python_pptx-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-pptx
-Version: 0.3.0
+Version: 0.3.1
 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.3.0 → athena_python_pptx-0.3.1}/docs/API_PARITY_EXCEPTIONS.md

@@ -830,6 +830,67 @@ The default `fit=None` preserves stock python-pptx behaviour. The only
 other accepted value is `"contain"`; passing anything else raises
 `ValueError` to fail loudly rather than silently no-op.
 
+## `Shapes.add_athena_anchor()` — Athena-only cross-asset screenshot insert
+
+Athena extension with no python-pptx analogue. Renders an Athena
+`Anchor` (a structured reference to a region of another asset — sheet
+cells, sheet ranges, etc.) to a PNG and inserts it as a regular
+`Picture` shape on the current slide. The result is a one-shot raster
+snapshot, **not** a live-linked binding — use `add_linked_table()` /
+`add_linked_ole_object()` for refreshable bindings.
+
+```python
+from pptx._references import AssetReference, SheetRangeAnchor
+
+slide.shapes.add_athena_anchor(
+    AssetReference(id="asset_20880ea3-95fb-4577-9a2e-ad11b7773939"),
+    SheetRangeAnchor(sheet_id=1, range="A1:F20"),
+    Inches(1), Inches(1),
+    width=Inches(8),
+)
+```
+
+Signature:
+
+```python
+add_athena_anchor(
+    source: AssetReference,
+    anchor: Anchor,
+    left: Length,
+    top: Length,
+    width: Length | None = None,
+    height: Length | None = None,
+    *,
+    name: str | None = None,
+    fit: str | None = None,  # "contain" — same semantics as add_picture
+) -> Shape
+```
+
+Supported anchor types today:
+
+| Anchor type        | Behaviour                                                |
+|--------------------|----------------------------------------------------------|
+| `SheetCellAnchor`  | Renders the single cell as a 1×1 range PNG.              |
+| `SheetRangeAnchor` | Renders the A1 range via xlsx-studio's screenshot.png.   |
+| `SheetTableAnchor` | Raises `NotImplementedError` (resolve to A1 + retry).    |
+| `SlideAnchor`      | Raises `NotImplementedError` (no slide-snapshot route).  |
+| anything else      | Raises `NotImplementedError`.                            |
+
+Sheet anchors route through `GET {ATHENA_XLSX_BASE_URL}/workbooks/:id/screenshot.png`
+with the sandbox's `ATHENA_XLSX_API_KEY` forwarded as a Bearer token —
+xlsx-studio's ownership middleware checks that the calling workspace
+can read the source workbook. Render scale is fixed at 3 (matches
+xlsx-studio's `range-as-asset` default — slide inserts sit at 6–9″
+widths where scale=2 leaves text soft). When `ATHENA_XLSX_BASE_URL` /
+`ATHENA_XLSX_API_KEY` aren't set (e.g. running outside a Daytona
+presentation_exec sandbox), the call raises `ValueError` rather than
+producing a broken picture.
+
+For finer control (custom scale, `include_headers`, off-snapshot
+post-processing), fetch the PNG bytes directly via athena-openpyxl's
+`Worksheet.export_range_sync()` and call `add_picture(bytes, …)`
+yourself.
+
 ---
 
 ## `Shapes.add_linked_table()` — Athena studio-linking extension (added in Phase 3)

{athena_python_pptx-0.3.0 → athena_python_pptx-0.3.1}/pptx/__init__.py

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

{athena_python_pptx-0.3.0 → athena_python_pptx-0.3.1}/pptx/shapes/__init__.py

@@ -88,6 +88,137 @@ def _is_athena_url(url: str) -> bool:
     return any(host == suffix or host.endswith("." + suffix) for suffix in _ATHENA_URL_SUFFIXES)
 
 
+# Default render scale for xlsx-range screenshots embedded in slides.
+# scale=3 matches xlsx-studio's ``range-as-asset`` default — slide inserts
+# sit at 6–9″ widths, where scale=2 leaves text visibly soft.
+_XLSX_RANGE_DEFAULT_SCALE = 3
+
+
+def _fetch_xlsx_range_as_png(
+    asset_id: str,
+    *,
+    sheet_id: Optional[int] = None,
+    sheet_name: Optional[str] = None,
+    cell_range: Optional[str] = None,
+    scale: int = _XLSX_RANGE_DEFAULT_SCALE,
+) -> bytes:
+    """Fetch a PNG screenshot of an xlsx workbook range.
+
+    Hits xlsx-studio's ``GET /workbooks/:id/screenshot.png`` endpoint with
+    the sandbox's ``ATHENA_XLSX_API_KEY`` as a Bearer token. The endpoint
+    resolves ownership against the workspace tied to the API key, so the
+    caller must own (or have ABAC read on) the source workbook asset.
+
+    Exactly one of ``sheet_id`` / ``sheet_name`` may be supplied (or
+    neither — the server falls back to the first sheet). ``cell_range``
+    is optional; when omitted the server auto-detects the data bounds
+    for that sheet (max 100 rows × 20 cols).
+    """
+    base_url = os.environ.get("ATHENA_XLSX_BASE_URL")
+    api_key = os.environ.get("ATHENA_XLSX_API_KEY")
+    if not base_url or not api_key:
+        raise ValueError(
+            "Fetching an xlsx range as a picture requires the "
+            "ATHENA_XLSX_BASE_URL and ATHENA_XLSX_API_KEY env vars to be "
+            "set in the sandbox. Re-run from a presentation_exec sandbox "
+            "created after the env-var rollout, or fetch the PNG via the "
+            "athena-openpyxl SDK's Worksheet.export_range_sync() and pass "
+            "the bytes to add_picture() directly."
+        )
+
+    if sheet_id is not None and sheet_name is not None:
+        raise ValueError(
+            "Pass only one of sheet_id or sheet_name to _fetch_xlsx_range_as_png; "
+            "the xlsx-studio screenshot endpoint rejects both at once."
+        )
+
+    params: dict[str, Any] = {"scale": scale}
+    if sheet_id is not None:
+        params["sheet_id"] = int(sheet_id)
+    if sheet_name is not None:
+        params["sheet_name"] = sheet_name
+    if cell_range is not None:
+        params["range"] = cell_range
+
+    url = f"{base_url.rstrip('/')}/workbooks/{asset_id}/screenshot.png"
+    headers = {"Authorization": f"Bearer {api_key}"}
+    try:
+        with requests.get(
+            url, headers=headers, params=params, timeout=60, stream=True
+        ) as response:
+            response.raise_for_status()
+            chunks: list[bytes] = []
+            received = 0
+            for chunk in response.iter_content(chunk_size=65536):
+                if not chunk:
+                    continue
+                received += len(chunk)
+                if received > _MAX_URL_IMAGE_BYTES:
+                    raise ValueError(
+                        f"xlsx-studio response for asset "
+                        f"{asset_id!r} exceeds the {_MAX_URL_IMAGE_BYTES}-byte cap"
+                    )
+                chunks.append(chunk)
+    except requests.RequestException as e:
+        raise ValueError(
+            f"failed to fetch xlsx range as PNG for asset {asset_id!r} "
+            f"(sheet_id={sheet_id!r}, sheet_name={sheet_name!r}, "
+            f"range={cell_range!r}): {e}"
+        ) from e
+    return b"".join(chunks)
+
+
+def _try_convert_to_png(data: bytes, image_format: str) -> Optional[bytes]:
+    """Convert non-PNG image bytes (WebP, SVG) to PNG.
+
+    Returns the PNG bytes on success, ``None`` if the required converter
+    isn't installed in the runtime. Pptx-studio's renderer doesn't
+    decode WebP or SVG today, so add_picture has to either convert
+    upstream or fail loudly — silently sending the bytes through
+    produces a broken-image placeholder on the slide.
+
+    WebP → PNG: requires ``Pillow`` (transitively included via
+    ``matplotlib`` in the presentation_exec Daytona snapshot, so this
+    just works in the standard agent runtime).
+
+    SVG → PNG: requires ``svglib`` + ``reportlab``. Neither is in the
+    snapshot today, so SVG falls through to the caller's error path.
+    Direct ``cairosvg`` would be lighter but pulls a C dep.
+    """
+    from io import BytesIO
+
+    if image_format == "webp":
+        try:
+            from PIL import Image  # type: ignore[import-not-found]
+        except ImportError:
+            return None
+        try:
+            with Image.open(BytesIO(data)) as im:
+                out = BytesIO()
+                im.convert("RGBA").save(out, format="PNG")
+                return out.getvalue()
+        except Exception:
+            return None
+
+    if image_format == "svg":
+        try:
+            from svglib.svglib import svg2rlg  # type: ignore[import-not-found]
+            from reportlab.graphics import renderPM  # type: ignore[import-not-found]
+        except ImportError:
+            return None
+        try:
+            drawing = svg2rlg(BytesIO(data))
+            if drawing is None:
+                return None
+            out = BytesIO()
+            renderPM.drawToFile(drawing, out, fmt="PNG")
+            return out.getvalue()
+        except Exception:
+            return None
+
+    return None
+
+
 def _fetch_image_from_url(url: str) -> bytes:
     """Fetch image bytes from a URL.
 
@@ -1495,26 +1626,291 @@ class ClickAction:
             return f"<ClickAction action={self._action_type}>"
 
 
+class _ChartTitleRun:
+    """A run inside the chart title's text frame.
+
+    Exposes ``text`` and ``font`` so the python-pptx pattern
+    ``run.text = "..."; run.font.size = Pt(11); run.font.bold = True;
+    run.font.color.rgb = RGBColor(...)`` works end-to-end. Mutations
+    are coalesced by the owning text frame into a single
+    :class:`SetChartTitleRich` patch.
+    """
+
+    def __init__(
+        self,
+        paragraph: "_ChartTitleParagraph",
+        text: str = "",
+        font: Optional[Any] = None,
+    ):
+        from ..text import Font
+        from ..units import EMU_PER_PT
+
+        self._paragraph = paragraph
+        self._text = text
+        self._emu_per_pt = EMU_PER_PT
+        if font is None:
+            font = Font(
+                run=None,  # type: ignore[arg-type]
+                change_listener=self._on_font_changed,
+            )
+        else:
+            font._change_listener = self._on_font_changed
+        self._font: Any = font
+
+    @property
+    def text(self) -> str:
+        return self._text
+
+    @text.setter
+    def text(self, value: str) -> None:
+        self._text = str(value)
+        self._paragraph._notify_change()
+
+    @property
+    def font(self) -> Any:
+        return self._font
+
+    def _on_font_changed(self, _font: Any) -> None:
+        self._paragraph._notify_change()
+
+
+class _ChartTitleParagraph:
+    """A paragraph inside the chart title's text frame.
+
+    Holds a list of :class:`_ChartTitleRun` objects. Iterating ``runs``
+    after setting ``text_frame.text`` yields a single run carrying the
+    title text, enabling per-run font styling. Setting paragraph-level
+    ``font`` on a paragraph with no runs creates an empty run and
+    attaches the font to it (python-pptx parity for the default-paragraph
+    case).
+    """
+
+    def __init__(self, text_frame: "_ChartTitleTextFrame"):
+        self._text_frame = text_frame
+        self._runs: list[_ChartTitleRun] = []
+        self._alignment: Optional[Any] = None
+        # Lazily-created paragraph-level font; in python-pptx the
+        # paragraph font supplies defaults for runs without explicit
+        # rPr. For SetChartTitleRich we don't have a separate paragraph
+        # bucket on the wire, so we mirror the value onto the first run
+        # when needed.
+        self._para_font: Optional[Any] = None
+
+    @property
+    def runs(self) -> list[_ChartTitleRun]:
+        return list(self._runs)
+
+    @property
+    def text(self) -> str:
+        return "".join(r._text for r in self._runs)
+
+    @text.setter
+    def text(self, value: str) -> None:
+        self._runs = [_ChartTitleRun(self, text=str(value))]
+        self._notify_change()
+
+    @property
+    def alignment(self) -> Optional[Any]:
+        return self._alignment
+
+    @alignment.setter
+    def alignment(self, value: Optional[Any]) -> None:
+        # Stored locally; the SetChartTitleRich patch model doesn't carry
+        # per-paragraph alignment yet, but accepting the assignment keeps
+        # python-pptx-style code paths from raising.
+        self._alignment = value
+
+    @property
+    def font(self) -> Any:
+        """Paragraph-level font. Mirrors python-pptx — defaults for any
+        run that doesn't set its own properties. We surface this as a
+        Font hooked to the same change listener so callers can write
+        ``paragraphs[0].font.size = Pt(20)`` and have the value flow
+        through to the underlying SetChartTitleRich patch.
+
+        When there's at least one run, returns the first run's font so
+        subsequent reads see writes (python-pptx behavior for the
+        single-run case). When empty, creates a tracked Font that's
+        promoted onto an empty run when a write happens.
+        """
+        if self._runs:
+            return self._runs[0].font
+        if self._para_font is None:
+            from ..text import Font
+
+            self._para_font = Font(
+                run=None,  # type: ignore[arg-type]
+                change_listener=self._on_para_font_changed,
+            )
+        return self._para_font
+
+    def add_run(self) -> _ChartTitleRun:
+        run = _ChartTitleRun(self, text="")
+        self._runs.append(run)
+        return run
+
+    def clear(self) -> None:
+        self._runs = []
+        self._notify_change()
+
+    def _on_para_font_changed(self, font: Any) -> None:
+        # Promote the paragraph-level font onto an empty run so its
+        # properties show up in the next SetChartTitleRich emission.
+        if not self._runs:
+            run = _ChartTitleRun(self, text="", font=font)
+            self._runs.append(run)
+        else:
+            # Copy any newly-set fields onto run[0]'s font.
+            target = self._runs[0]._font
+            for attr in ("_size", "_color_hex", "_theme_color_name", "_bold",
+                         "_italic", "_name", "_underline", "_strike",
+                         "_baseline", "_language_id", "_spacing_pt"):
+                v = getattr(font, attr, None)
+                if v is not None:
+                    setattr(target, attr, v)
+        self._notify_change()
+
+    def _notify_change(self) -> None:
+        self._text_frame._emit_rich()
+
+
 class _ChartTitleTextFrame:
     """python-pptx-compatible ``TextFrame`` adapter for ``chart.chart_title``.
 
-    Real python-pptx returns a full ``TextFrame`` with paragraphs/runs.
-    Athena's chart-title pipeline only persists a single string title
-    (``SetChartTitle`` patch), so this shim collapses the ``text_frame.
-    text = ...`` form down to that same patch. Multi-paragraph chart
-    titles aren't supported on the export side yet.
+    Exposes ``text``, ``paragraphs``, ``add_paragraph``, ``clear`` and
+    ``word_wrap`` for python-pptx parity. ``text``-only writes route
+    through the simpler :class:`SetChartTitle` patch (1 byte on the
+    wire); paragraph / run / font mutations route through
+    :class:`SetChartTitleRich`, which carries structured runs and lets
+    the export-worker preserve per-run formatting.
+
+    Local paragraph state is initialised lazily on first read from the
+    server-side title string so the read-modify-write pattern
+    (``tf.text = "X"; tf.paragraphs[0].runs[0].font.bold = True``) works
+    without an explicit ``has_title`` toggle first.
     """
 
     def __init__(self, chart_title: "_ChartTitle"):
         self._chart_title = chart_title
+        self._paragraphs: list[_ChartTitleParagraph] = []
+        self._paragraphs_initialised: bool = False
+        # Suppress rich emits while we're applying the initial
+        # ``text = ...`` setter so the simpler SetChartTitle patch is
+        # used for the common no-formatting case.
+        self._suppress_emit: bool = False
+        # Optional word-wrap state — accepted but not currently
+        # propagated through the patch (SetChartTitleRich doesn't carry
+        # a wrap flag).
+        self._word_wrap: Optional[bool] = None
+
+    def _ensure_paragraphs(self) -> list[_ChartTitleParagraph]:
+        """Lazy-init the paragraph list from the current server-side title."""
+        if not self._paragraphs_initialised:
+            existing = self._chart_title._text
+            para = _ChartTitleParagraph(self)
+            if existing:
+                # ``_ChartTitleRun.__init__`` calls Font(..., change_listener=…)
+                # which we don't want to fire at construction time, so build
+                # the run directly under ``_suppress_emit``.
+                self._suppress_emit = True
+                try:
+                    para._runs = [_ChartTitleRun(para, text=existing)]
+                finally:
+                    self._suppress_emit = False
+            self._paragraphs = [para]
+            self._paragraphs_initialised = True
+        return self._paragraphs
 
     @property
     def text(self) -> str:
+        if self._paragraphs_initialised:
+            return "\n".join(p.text for p in self._paragraphs)
         return self._chart_title._text or ""
 
     @text.setter
     def text(self, value: str) -> None:
-        self._chart_title._emit(value)
+        # Reset local state to a single paragraph / single run with the
+        # given text and emit the simpler SetChartTitle patch. The
+        # paragraph collection is now initialised so subsequent reads
+        # off ``paragraphs`` reflect the new state.
+        value_str = str(value)
+        para = _ChartTitleParagraph(self)
+        self._suppress_emit = True
+        try:
+            para._runs = [_ChartTitleRun(para, text=value_str)]
+        finally:
+            self._suppress_emit = False
+        self._paragraphs = [para]
+        self._paragraphs_initialised = True
+        self._chart_title._emit(value_str)
+
+    @property
+    def paragraphs(self) -> list[_ChartTitleParagraph]:
+        return self._ensure_paragraphs()
+
+    def add_paragraph(self) -> _ChartTitleParagraph:
+        paragraphs = self._ensure_paragraphs()
+        para = _ChartTitleParagraph(self)
+        paragraphs.append(para)
+        return para
+
+    def clear(self) -> None:
+        # python-pptx ``TextFrame.clear()`` resets to one empty paragraph
+        # with no runs. Mirror that for parity, even though chart titles
+        # in OOXML always require at least one run on export.
+        self._paragraphs = [_ChartTitleParagraph(self)]
+        self._paragraphs_initialised = True
+        self._emit_rich()
+
+    @property
+    def word_wrap(self) -> Optional[bool]:
+        return self._word_wrap
+
+    @word_wrap.setter
+    def word_wrap(self, value: Optional[bool]) -> None:
+        self._word_wrap = None if value is None else bool(value)
+
+    def _emit_rich(self) -> None:
+        """Build and emit a :class:`SetChartTitleRich` patch for the
+        current paragraph/run state.
+
+        ``_suppress_emit`` guards against re-entrant emits during the
+        initial paragraph hydration so we don't fire a spurious rich
+        patch for the no-formatting case.
+        """
+        if self._suppress_emit:
+            return
+        shape = self._chart_title._chart._shape
+        if shape._buffer is None:
+            return
+        runs_data: list[dict[str, Any]] = []
+        for para in self._paragraphs:
+            for r in para._runs:
+                if not r._text:
+                    continue
+                style: dict[str, Any] = {"text": r._text}
+                font = r._font
+                if font._size is not None:
+                    style["fontSizePt"] = font._size / r._emu_per_pt
+                if font._color_hex is not None:
+                    style["fontColorHex"] = font._color_hex
+                if font._bold is not None:
+                    style["fontBold"] = bool(font._bold)
+                if font._italic is not None:
+                    style["fontItalic"] = bool(font._italic)
+                if font._name is not None:
+                    style["fontName"] = font._name
+                runs_data.append(style)
+        if not runs_data:
+            return
+        shape._buffer.add(UpdateChartDataCmd(
+            shape_id=shape.shape_id,
+            patches=[{
+                "op": "SetChartTitleRich",
+                "chartId": shape.shape_id,
+                "runs": runs_data,
+            }],
+        ))
 
 
 class _ChartTitle:
@@ -5396,10 +5792,38 @@ class Shape:
             self._buffer.add(cmd)
 
     def delete(self) -> None:
-        """Delete this shape from the slide."""
+        """Delete this shape from the slide.
+
+        Emits a ``DeleteShape`` command and also removes the shape from
+        the parent :class:`Shapes` collection's local view. Without the
+        local mutation, ``len(slide.shapes)`` stays stale even after
+        commands flush — agents repeatedly hit "Before: 33, After: 33"
+        and assumed the delete had been silently dropped.
+
+        Inherited layout-level shapes (``shape._source == 'layout'``)
+        are skipped — the server rejects deletes on them with a 400
+        ("Cannot delete inherited layout element"), and python-pptx
+        doesn't surface inherited content in ``slide.shapes`` at all,
+        so the SDK matches that contract by no-oping rather than
+        queuing an op that's guaranteed to fail at flush.
+        """
+        if self._source == "layout":
+            return
         if self._buffer:
             cmd = DeleteShape(shape_id=self._shape_id)
             self._buffer.add(cmd)
+        slide = getattr(self, "_slide", None)
+        shapes_coll = getattr(slide, "_shapes", None) if slide is not None else None
+        if shapes_coll is not None:
+            shapes_list = getattr(shapes_coll, "_shapes", None)
+            if isinstance(shapes_list, list):
+                try:
+                    shapes_list.remove(self)
+                except ValueError:
+                    pass
+            by_id = getattr(shapes_coll, "_shapes_by_id", None)
+            if isinstance(by_id, dict):
+                by_id.pop(self._shape_id, None)
 
     # -------------------------------------------------------------------------
     # Fill and line styling
@@ -7012,7 +7436,6 @@ class Shapes:
         w_emu = int(ensure_emu(width)) if width else None
         h_emu = int(ensure_emu(height)) if height else None
 
-        # Read image data and determine format
         if isinstance(image_file, bytes):
             image_data = image_file
         elif isinstance(image_file, BytesIO):
@@ -7029,6 +7452,30 @@ class Shapes:
 
         image_format = self._detect_image_format(image_data)
 
+        # pptx-studio's renderer (CanvasKit + @napi-rs/canvas) only decodes
+        # ``png/jpeg/gif/bmp/tiff``. WebP, SVG, and other modern formats
+        # need to be converted to PNG before they hit the wire — otherwise
+        # the renderer can't decode and the slide shows the broken-image
+        # placeholder, OR the AddPicture command's image_format validator
+        # rejects with a cryptic "must be 'png', 'jpeg', ..." message that
+        # gives no hint about the actual cause.
+        if image_format in ("webp", "svg"):
+            converted = _try_convert_to_png(image_data, image_format)
+            if converted is not None:
+                image_data = converted
+                image_format = "png"
+            else:
+                _convert_hint = (
+                    "Install Pillow (and svglib for SVG) in the sandbox, or "
+                    "fetch a PNG URL directly. For placeholder URLs use a "
+                    "`.png` suffix (e.g. `placehold.co/600x400.png`, NOT "
+                    "`placehold.co/600x400` which serves SVG by default)."
+                )
+                raise ValueError(
+                    f"add_picture: detected image_format={image_format!r}, "
+                    f"which pptx-studio cannot decode. {_convert_hint}"
+                )
+
         if (w_emu is None) != (h_emu is None):
             native = self._read_image_pixel_size(image_data, image_format)
             if native is not None:
@@ -7121,6 +7568,116 @@ class Shapes:
         self._shapes_by_id[client_id] = shape
         return shape
 
+    @athena_extension(
+        since="0.4.0",
+        description=(
+            "Shapes.add_athena_anchor — insert a rendered screenshot of an "
+            "Athena anchor (currently SheetCellAnchor / SheetRangeAnchor) "
+            "as a picture on the slide."
+        ),
+    )
+    def add_athena_anchor(
+        self,
+        source: "AssetReference",
+        anchor: "Anchor",
+        left: Length,
+        top: Length,
+        width: Optional[Length] = None,
+        height: Optional[Length] = None,
+        *,
+        name: Optional[str] = None,
+        fit: Optional[str] = None,
+    ) -> Shape:
+        """Insert a rendered screenshot of an Athena anchor as a picture.
+
+        Routes through the appropriate studio's screenshot endpoint based
+        on the anchor type and inserts the PNG via the standard
+        ``add_picture`` command path so the result is a regular ``Picture``
+        shape (selectable, movable, resizable). The picture is NOT a
+        live-linked binding — it is a one-shot raster snapshot.
+
+        Currently supports:
+
+        - ``SheetCellAnchor`` — renders a single cell from xlsx-studio.
+        - ``SheetRangeAnchor`` — renders an A1-style range from xlsx-studio.
+
+        Other anchor types (``SheetTableAnchor``, ``SlideAnchor``, …)
+        raise ``NotImplementedError``.
+
+        Args:
+            source: Athena ``AssetReference`` pointing at the source asset
+                (e.g. an xlsx workbook).
+            anchor: ``Anchor`` describing the region to render. Sheet
+                anchors carry a numeric ``sheet_id``.
+            left, top: Position of the resulting picture.
+            width, height: Optional dimensions. Same aspect-ratio
+                derivation rules as :meth:`add_picture`.
+            name: Optional stable shape name.
+            fit: Optional ``"contain"`` to clamp the picture to slide
+                bounds. Same semantics as :meth:`add_picture`.
+
+        Returns:
+            The newly created picture ``Shape``.
+
+        Note (Athena extension):
+            Not in python-pptx. See ``docs/API_PARITY_EXCEPTIONS.md``.
+        """
+        from .._references import (
+            AssetReference,
+            SheetCellAnchor,
+            SheetRangeAnchor,
+            SheetTableAnchor,
+            SlideAnchor,
+        )
+
+        if not isinstance(source, AssetReference):
+            raise TypeError(
+                f"source must be an AssetReference; got {type(source).__name__}"
+            )
+
+        if isinstance(anchor, SheetCellAnchor):
+            cell_range = f"{anchor.cell}:{anchor.cell}"
+            png_bytes = _fetch_xlsx_range_as_png(
+                source.id,
+                sheet_id=anchor.sheet_id,
+                cell_range=cell_range,
+            )
+        elif isinstance(anchor, SheetRangeAnchor):
+            png_bytes = _fetch_xlsx_range_as_png(
+                source.id,
+                sheet_id=anchor.sheet_id,
+                cell_range=anchor.range,
+            )
+        elif isinstance(anchor, SheetTableAnchor):
+            raise NotImplementedError(
+                "add_athena_anchor does not yet support SheetTableAnchor. "
+                "Resolve the table to an A1 range and pass SheetRangeAnchor "
+                "instead, or use add_linked_table() for a live-linked table."
+            )
+        elif isinstance(anchor, SlideAnchor):
+            raise NotImplementedError(
+                "add_athena_anchor does not yet support SlideAnchor — "
+                "rendering a slide screenshot from a source deck is not "
+                "wired up. Use the source deck's render_slide() and pass "
+                "the bytes to add_picture() directly."
+            )
+        else:
+            raise NotImplementedError(
+                f"add_athena_anchor: unsupported anchor type "
+                f"{type(anchor).__name__!r}. Supported today: "
+                "SheetCellAnchor, SheetRangeAnchor."
+            )
+
+        return self.add_picture(
+            png_bytes,
+            left,
+            top,
+            width=width,
+            height=height,
+            name=name,
+            fit=fit,
+        )
+
     @staticmethod
     def _read_image_pixel_size(
         data: bytes, image_format: str
@@ -7682,10 +8239,24 @@ class Shapes:
             return 'bmp'
         elif data[:4] in (b'II*\x00', b'MM\x00*'):
             return 'tiff'
+        # WebP: ``RIFF`` + 4 bytes filesize + ``WEBP``. Previously fell
+        # through to the PNG default below, which sent invalid bytes to
+        # pptx-studio and rendered as the broken-image placeholder; now
+        # detected explicitly so the upper-layer auto-convert path can
+        # fire (or a clear error surface).
+        elif (
+            len(data) >= 12
+            and data[:4] == b'RIFF'
+            and data[8:12] == b'WEBP'
+        ):
+            return 'webp'
         elif self._looks_like_svg(data):
             # SVG (text-based). PowerPoint 2016+ supports native SVG via
-            # the ``<p:pic>`` extension list — closes python-pptx#1112,
-            # which reports SVG raising "cannot identify image file".
+            # the ``<p:pic>`` extension list — closes python-pptx#1112.
+            # pptx-studio's renderer doesn't decode SVG today, so the
+            # upper-layer auto-convert path turns SVG → PNG via Pillow
+            # when available; we still return ``'svg'`` here so that
+            # path can recognize it.
             return 'svg'
         else:
             # Default to PNG

{athena_python_pptx-0.3.0 → athena_python_pptx-0.3.1}/pptx/slides.py

@@ -2105,6 +2105,102 @@ class Slides:
         """
         return self.add_slide(slide_layout=6)
 
+    @athena_only(
+        description="Insert a slide at an arbitrary index without cloning",
+        since="0.3.1",
+    )
+    def insert(self, index: int, layout: Any = None) -> Slide:
+        """Insert a slide at ``index``.
+
+        Athena extension — python-pptx's ``Slides`` collection only
+        supports appending via :meth:`add_slide`. When a caller needs to
+        place a new slide at a specific position (for example, between
+        two existing slides), the previous workaround was to
+        ``add_slide()`` then ``clone(target_index=...)`` an unrelated
+        slide to shift the list — fragile, leaks the cloned shapes, and
+        surfaced in the Insight Partners session as a 33-shape ghost
+        cover that ``slide.shapes`` couldn't clear.
+
+        ``insert(index, layout)`` issues a single ``AddSlide(index=...)``
+        command. The server returns the new slide id and the local
+        collection is refreshed via :meth:`Presentation.refresh`.
+
+        Args:
+            index: Zero-based position for the new slide. Clamped to
+                ``[0, len(self)]``. ``index == len(self)`` is equivalent
+                to :meth:`add_slide`.
+            layout: Slide layout — :class:`SlideLayout`, integer, or
+                ``None`` for the presentation default.
+
+        Returns:
+            The newly created :class:`Slide`.
+
+        Example:
+            >>> prs.slides.insert(10, prs.slide_layouts[6])
+        """
+        bounded = max(0, min(int(index), len(self._slides)))
+        layout_index: Optional[int] = None
+        layout_name: Optional[str] = None
+        if layout is not None:
+            if isinstance(layout, int):
+                layout_index = layout
+            elif hasattr(layout, '_index'):
+                layout_index = layout._index
+                layout_name = getattr(layout, "name", None)
+
+        cmd = AddSlide(index=bounded, layout_index=layout_index)
+
+        response = None
+        slide_id: Optional[str] = None
+
+        def extract_created_slide_id(raw_response: object) -> Optional[str]:
+            if not isinstance(raw_response, dict):
+                return None
+            created = raw_response.get("created")
+            if not isinstance(created, dict):
+                return None
+            slide_ids = created.get("slideIds", [])
+            if not isinstance(slide_ids, list) or not slide_ids:
+                return None
+            first = slide_ids[0]
+            return first if isinstance(first, str) else None
+
+        if self._buffer:
+            response = self._buffer.add(cmd)
+            slide_id = extract_created_slide_id(response)
+
+        if self._buffer and not self._buffer.is_batching:
+            if response is None:
+                flushed_response = self._buffer.flush()
+                slide_id = slide_id or extract_created_slide_id(flushed_response)
+            self._presentation.refresh()
+            if slide_id:
+                refreshed = self._slides_by_id.get(slide_id)
+                if refreshed is not None:
+                    return refreshed
+            if 0 <= bounded < len(self._slides):
+                return self._slides[bounded]
+
+        if not slide_id:
+            import uuid
+            slide_id = f"sld_{uuid.uuid4().hex[:8]}"
+
+        slide = Slide(
+            presentation=self._presentation,
+            slide_id=slide_id,
+            slide_index=bounded,
+            buffer=self._buffer,
+            element_ids=[],
+            elements={},
+            layout_index=layout_index,
+            layout_name=layout_name,
+        )
+        self._slides.insert(bounded, slide)
+        self._slides_by_id[slide_id] = slide
+        for i, s in enumerate(self._slides):
+            s._slide_index = i
+        return slide
+
     def index(self, slide: Slide) -> int:
         """Get the index of a slide."""
         return self._slides.index(slide)

{athena_python_pptx-0.3.0 → athena_python_pptx-0.3.1}/pyproject.toml

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