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

{athena_python_pptx-0.3.0 → athena_python_pptx-0.4.0}/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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-pptx
-Version: 0.3.0
+Version: 0.4.0
 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.4.0}/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.4.0}/pptx/__init__.py

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

{athena_python_pptx-0.3.0 → athena_python_pptx-0.4.0}/pptx/client.py

@@ -72,7 +72,11 @@ class Client:
             base_url: Base URL of the API (e.g., "https://api.pptx-studio.com").
                      If not provided, uses ATHENA_PPTX_BASE_URL environment variable.
             api_key: Optional API key for authentication.
-                    If not provided, uses ATHENA_PPTX_API_KEY environment variable.
+                    If not provided, falls back to the ATHENA_PPTX_API_KEY
+                    environment variable, then to ATHENA_API_KEY (the canonical
+                    Athena user API key — same value, accepted as a fallback so
+                    code running in sandboxes that only inject ATHENA_API_KEY
+                    still authenticates).
             timeout: Request timeout in seconds
 
         Raises:
@@ -83,11 +87,13 @@ class Client:
             base_url = os.environ.get("ATHENA_PPTX_BASE_URL")
             if base_url is None:
                 raise ValueError(
-                    "base_url must be provided or ATHENA_PPTX_BASE_URL environment variable must be set"
+                    "base_url must be provided or the ATHENA_PPTX_BASE_URL "
+                    "environment variable must be set. Example: "
+                    'ATHENA_PPTX_BASE_URL="https://pptx-studio.prd.athenaintel.com".'
                 )
 
         if api_key is None:
-            api_key = os.environ.get("ATHENA_PPTX_API_KEY")
+            api_key = os.environ.get("ATHENA_PPTX_API_KEY") or os.environ.get("ATHENA_API_KEY")
 
         self.base_url = base_url.rstrip("/")
         self.api_key = api_key
@@ -129,7 +135,18 @@ class Client:
     def _handle_response(self, response: requests.Response) -> Any:
         """Handle API response, raising appropriate errors."""
         if response.status_code == 401:
-            raise AuthenticationError("Invalid or expired API key")
+            if not self.api_key:
+                raise AuthenticationError(
+                    "No API key was sent. Pass api_key= to Presentation(...) "
+                    "or set ATHENA_PPTX_API_KEY (or ATHENA_API_KEY as a "
+                    "fallback) in the environment."
+                )
+            raise AuthenticationError(
+                "Invalid or expired API key. The pptx-studio API rejected the "
+                "credentials. Verify ATHENA_PPTX_API_KEY (or the ATHENA_API_KEY "
+                "fallback) is set to a valid Athena user API key for the "
+                "current workspace."
+            )
 
         if response.status_code == 409:
             data = response.json() if response.text else {}
@@ -416,7 +433,7 @@ class Client:
         if name is None:
             name = os.path.basename(file_path)
             # Remove extension
-            if name.endswith('.pptx') or name.endswith('.potx'):
+            if name.endswith(".pptx") or name.endswith(".potx"):
                 name = name[:-5]
 
         # Step 1: Create deck to get presigned URL
@@ -496,7 +513,7 @@ class Client:
         # Use filename as name if not provided
         if name is None:
             name = os.path.basename(file_path)
-            if name.endswith('.pptx') or name.endswith('.potx'):
+            if name.endswith(".pptx") or name.endswith(".potx"):
                 name = name[:-5]
 
         # Step 1: Create deck to get presigned URL
@@ -800,9 +817,7 @@ class Client:
                 return self._download(download_url)
 
             if status["status"] in ("failed", "error"):
-                raise ExportError(
-                    status.get("error", "Export failed"), job_id
-                )
+                raise ExportError(status.get("error", "Export failed"), job_id)
 
             time.sleep(poll_interval)
 
@@ -870,9 +885,7 @@ class Client:
                 return self._download(image_url)
 
             if status["status"] in ("failed", "error"):
-                raise RenderError(
-                    status.get("error", "Render failed"), job_id
-                )
+                raise RenderError(status.get("error", "Render failed"), job_id)
 
             time.sleep(poll_interval)
 

{athena_python_pptx-0.3.0 → athena_python_pptx-0.4.0}/pptx/commands.py

@@ -1464,6 +1464,23 @@ class SetGradientFill(Command):
                         "stops"
                     )
 
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize, camelCasing each stop's ``color_hex`` to ``colorHex`` for the server schema."""
+        result = super().to_dict()
+        if self.stops is not None:
+            camel_stops: list[dict[str, Any]] = []
+            for stop in self.stops:
+                camel: dict[str, Any] = {
+                    "position": stop.get("position"),
+                    "colorHex": stop.get("color_hex"),
+                }
+                transparency = stop.get("transparency")
+                if transparency is not None:
+                    camel["transparency"] = transparency
+                camel_stops.append(camel)
+            result["stops"] = camel_stops
+        return result
+
 
 @dataclass
 class SetShapeZOrder(Command):