athena-python-pptx 0.17.1__tar.gz → 0.18.0__tar.gz

{athena_python_pptx-0.17.1 → athena_python_pptx-0.18.0}/API_PARITY_REPORT.md

@@ -110,7 +110,6 @@ via Tranches R–W:
 | `*.element`, `*.part`, `*.ln`, `*.get_or_add_ln` | XML element / OPC package / direct DML XML access — REST SDK has no local XML or packages |
 | `FillFormat.from_fill_parent()` | Internal XML constructor |
 | `ColorFormat.from_colorchoice_parent()` | Internal XML constructor |
-| `Picture.image.blob` | Image bytes live in the studio's asset store — not materialized into Python |
 
 ## Closed Parity Gaps (added 2026-05-18)
 

{athena_python_pptx-0.17.1 → athena_python_pptx-0.18.0}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.18.0 — chart.chart_area / chart.plot_area format and add_chart(name=)
+
+- `chart.chart_area.format` and `chart.plot_area.format` now round-trip fill
+  and line edits through chart specs, OOXML export, import and preview
+  rendering. Use `fill.background()` for a transparent chart or plot area.
+  `slide.shapes.add_chart(..., name=...)` also accepts an Athena-only shape
+  name.
+- `Picture.image` returns python-pptx's `Image`, so `picture.image.blob`,
+  `.content_type`, `.ext`, `.sha1`, `.size` and `.filename` work. It returned
+  None for every picture, and code reading an existing deck's images had to
+  fetch `image_url` by hand with the sandbox key. A picture added in this
+  session gives back the bytes it was added from; a picture read from the deck
+  fetches its bytes once from the studio's `/media` route with the SDK's own
+  credentials (redirects refused, 50 MB cap) and caches them on the shape. A
+  picture with no media raises `ValueError("no embedded image")`, as
+  python-pptx does.
+
 ## 0.17.1
 
 - `Table.table_style` returns the table's style GUID, the text of

{athena_python_pptx-0.17.1 → athena_python_pptx-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-pptx
-Version: 0.17.1
+Version: 0.18.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.17.1 → athena_python_pptx-0.18.0}/docs/API_PARITY_EXCEPTIONS.md

@@ -1285,6 +1285,24 @@ a later `runs[0].text` edit then wrote the empty run and doubled the text.
 
 These properties/methods were added because LLM agents (Claude, GPT, etc.) frequently generate code using these patterns. Without them, agent-generated table code fails at runtime.
 
+### `Chart.chart_area` and `Chart.plot_area` formatting
+
+python-pptx does not expose chart-area or plot-area fill and line formatting.
+The Athena SDK carries these edits through the chart spec and export patches,
+so a transparent chart background does not require editing private XML:
+
+```python
+chart.chart_area.format.fill.background()
+chart.plot_area.format.fill.background()
+```
+
+Both areas also support solid RGB or theme fills, brightness, line color,
+width and dash style. Use `chart.chart_area` for the whole chart frame and
+`chart.plot_area` for the plotting region.
+These edits apply to classic charts (authored or uploaded); Office 2016
+chartEx charts, such as waterfall and treemap, refuse them
+(`chartExEditsRefusal`).
+
 ### `Font.cap` — PowerPoint-native capitalization mode
 
 The SDK exposes PowerPoint's OOXML run capitalization property as
@@ -1555,10 +1573,13 @@ slide.shapes.add_picture(img.url, Inches(1), Inches(1), width=Inches(6))
 
 ### `Picture.image_url` — owner-scoped media URL for cross-deck image copy
 
-python-pptx upstream exposes `Picture.image` returning an `Image` with
-`.blob` bytes. The REST SDK can't materialize bytes locally, so `.image`
-stays `None` (see the omissions list above). **Additionally**, when a
-picture is loaded from a server snapshot it now carries `image_url`: a
+`Picture.image` returns python-pptx's `Image` (`.blob`, `.content_type`,
+`.ext`, `.filename`, `.sha1`, `.size`, `.dpi`): a picture added in this
+session carries the bytes it was added from, and a picture read from the deck
+fetches its bytes once from the studio's `/media` route with the SDK's own
+credentials (it raises `ValueError("no embedded image")`, as python-pptx
+does, for a picture with no media). **Additionally**, when a
+picture is loaded from a server snapshot it carries `image_url`: a
 stable `{base_url}/media?key=<assetId>` URL that streams the picture's
 bytes. It returns `None` for pictures with no backing media asset (an
 SDK-added picture not yet flushed/refreshed, a placeholder with no image,
@@ -1584,12 +1605,13 @@ dst.save()
 **Portable code that needs to run against stock python-pptx cannot rely
 on `image_url`** — it is an Athena-only accessor.
 
-### `name=` kwarg on `add_textbox()` / `add_shape()` / `add_picture()`
+### `name=` kwarg on `add_textbox()` / `add_shape()` / `add_picture()` / `add_chart()`
 
 Optional keyword for setting a stable shape name at creation. python-pptx
 upstream auto-assigns names like `"Rectangle 47"` and only exposes
 `shape.name = "..."` as a setter; ours additionally accepts `name=` at
-construction. **Portable code that needs to run against stock python-pptx
+construction on `add_textbox()`, `add_shape()`, `add_picture()` and
+`add_chart()`. **Portable code that needs to run against stock python-pptx
 should omit `name=` and assign after the fact.**
 
 When `name=` is omitted, Athena's generated name skips any identical name in
@@ -1607,6 +1629,13 @@ card = slide.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE,
                               name="kpi_card_revenue")
 ```
 
+Charts accept the same keyword:
+
+```python
+frame = slide.shapes.add_chart(chart_type, left, top, width, height, data,
+                               name="quarterly_revenue")
+```
+
 ### `Presentation.reorder_slides(new_order)`
 
 Reorder slides by passing a permutation of indices. Already shipped in

{athena_python_pptx-0.17.1 → athena_python_pptx-0.18.0}/pptx/__init__.py

@@ -327,7 +327,7 @@ def validate_all_touched() -> dict[int, list[str]]:
     return results
 
 
-__version__ = "0.17.1"
+__version__ = "0.18.0"
 
 __all__ = [
     # Main entry point

{athena_python_pptx-0.17.1 → athena_python_pptx-0.18.0}/pptx/_unsupported.py

@@ -335,7 +335,9 @@ _TEXT_FRAME = (
 _SHAPE = "Use the Shape API: text_frame, fill, line, shadow, left / top / width / height, rotation, delete()."
 _CHART = (
     "Use the Chart API: chart.plots, chart.series, chart.replace_data(chart_data), "
-    "chart.has_title / chart.chart_title, chart.value_axis, chart.category_axis."
+    "chart.has_title / chart.chart_title, chart.value_axis, chart.category_axis. "
+    "For the chart's background use chart.chart_area.format / chart.plot_area.format "
+    "(fill.background() makes it transparent)."
 )
 # python-pptx's private lxml attributes that recipes reach for (``series._element``,
 # ``chart._chartSpace``, ...) on objects this SDK has no mirror of. Whatever the

athena_python_pptx-0.18.0/pptx/chart/chart.py

@@ -0,0 +1,7 @@
+"""Shim re-exporting upstream's ``pptx.chart.chart`` surface."""
+
+from __future__ import annotations
+
+from ..shapes import Chart, ChartArea, ChartTitle, PlotArea
+
+__all__ = ["Chart", "ChartArea", "ChartTitle", "PlotArea"]

{athena_python_pptx-0.17.1 → athena_python_pptx-0.18.0}/pptx/client.py

@@ -808,6 +808,54 @@ class Client:
         except requests.RequestException as e:
             raise ConnectionError(f"Failed to download render from {url}: {e}", url=url)
 
+    def _download_media(self, *, key: str, max_bytes: int) -> bytes:
+        """Download one deck media object's bytes with this client's credentials.
+
+        ``/media`` runs the same deck-access check as every deck op, so the
+        bearer stays on the configured API host and a redirect is refused
+        rather than followed. Reads stop at ``max_bytes``.
+        """
+        path = "/media"
+        url = f"{self.base_url.rstrip('/')}{path}?key={quote(key, safe='')}"
+        headers = self._get_headers(path)
+        headers.pop("Content-Type", None)
+        headers["Accept"] = "*/*"
+        try:
+            response = self._session.get(
+                url,
+                headers=headers,
+                timeout=self.timeout,
+                allow_redirects=False,
+                stream=True,
+            )
+            try:
+                if 300 <= response.status_code < 400:
+                    raise RemoteError(
+                        message="Media download redirected; refusing to follow it",
+                        status_code=response.status_code,
+                        error_code="MEDIA_REDIRECT",
+                    )
+                if not response.ok:
+                    self._handle_response(response)
+                chunks: list[bytes] = []
+                received = 0
+                for chunk in response.iter_content(chunk_size=65536):
+                    if not chunk:
+                        continue
+                    received += len(chunk)
+                    if received > max_bytes:
+                        raise RemoteError(
+                            message=f"Media object exceeds the {max_bytes}-byte read cap",
+                            status_code=response.status_code,
+                            error_code="MEDIA_TOO_LARGE",
+                        )
+                    chunks.append(chunk)
+                return b"".join(chunks)
+            finally:
+                response.close()
+        except requests.RequestException as e:
+            raise ConnectionError(f"Failed to download media from {url}: {e}", url=url) from e
+
     # -------------------------------------------------------------------------
     # Deck operations
     # -------------------------------------------------------------------------

{athena_python_pptx-0.17.1 → athena_python_pptx-0.18.0}/pptx/shapes/__init__.py

@@ -78,7 +78,7 @@ from ..enum.chart import (
     XL_TICK_LABEL_POSITION,
     XL_TICK_MARK,
 )
-from ..parts.image import _native_picture_size, _scale_picture_size
+from ..parts.image import Image, _native_picture_size, _scale_picture_size
 
 # ``add_picture`` size for a missing dimension of an image whose header it
 # cannot read (1 inch, the server's own default).
@@ -373,6 +373,16 @@ def _picture_descr(image_file: Any, image_format: str) -> str:
     return f"image.{'jpg' if image_format == 'jpeg' else image_format}"
 
 
+def _loaded_image_filename(image_file: Any) -> Optional[str]:
+    """The file name python-pptx's ``Image.filename`` reports for ``image_file``:
+    the basename of a filesystem path, None for bytes, streams and URLs."""
+    if isinstance(image_file, Path):
+        return image_file.name
+    if isinstance(image_file, str) and not image_file.startswith(("http://", "https://")):
+        return os.path.basename(image_file)
+    return None
+
+
 def _fetch_image_from_url(url: str) -> bytes:
     """Fetch image bytes from a URL.
 
@@ -6683,6 +6693,60 @@ class _ChartElementFormat(ChartFormat):
         return self._line_cached  # type: ignore[return-value]
 
 
+class ChartArea:
+    """Chart-area formatting adapter (Athena extension)."""
+
+    _spec_key = "chartAreaFormat"
+    _patch_op = "SetChartAreaFormat"
+    _label = "chart.chart_area.format"
+
+    def __init__(self, shape: "Shape"):
+        self._shape = shape
+        self._format_cached: Optional[_ChartElementFormat] = None
+
+    @property
+    def format(self) -> ChartFormat:
+        """Fill and line formatting for the chart frame."""
+        if self._format_cached is None:
+            shape = self._shape
+
+            def read() -> Optional[dict[str, Any]]:
+                spec = _chart_spec_dict(shape)
+                element_format = spec.get(self._spec_key) if spec is not None else None
+                return element_format if isinstance(element_format, dict) else None
+
+            def store(element_format: dict[str, Any]) -> None:
+                spec = _chart_spec_dict(shape)
+                if spec is None:
+                    return
+                if element_format:
+                    spec[self._spec_key] = element_format
+                else:
+                    spec.pop(self._spec_key, None)
+
+            def send(edit: dict[str, Any]) -> None:
+                _emit_chart_patches(
+                    shape, [{"op": self._patch_op, "chartId": shape.shape_id, **edit}]
+                )
+
+            self._format_cached = _ChartElementFormat(
+                chart_shape=shape,
+                label=self._label,
+                read=read,
+                store=store,
+                send=send,
+            )
+        return self._format_cached
+
+
+class PlotArea(ChartArea):
+    """Plot-area formatting adapter (Athena extension)."""
+
+    _spec_key = "plotAreaFormat"
+    _patch_op = "SetPlotAreaFormat"
+    _label = "chart.plot_area.format"
+
+
 def _chart_spec_dict(shape: Any) -> Optional[dict[str, Any]]:
     """The chart shape's ``chartSpec`` dict (created empty for a chart that
     has none yet, so a local mirror has somewhere to live)."""
@@ -8024,6 +8088,8 @@ class Chart:
         self._category_axis_cached: Optional[Union[CategoryAxis, ValueAxis]] = None
         self._value_axis_cached: Optional[ValueAxis] = None
         self._legend_cached: Optional[Legend] = None
+        self._chart_area_cached: Optional[ChartArea] = None
+        self._plot_area_cached: Optional[PlotArea] = None
         self._font_cached: Optional[Any] = None
         self._series_cached: Optional[_ChartSeriesCollection] = None
 
@@ -8400,6 +8466,20 @@ class Chart:
         """
         return self._chart_title_obj
 
+    @property
+    def chart_area(self) -> ChartArea:
+        """Fill and line format for the chart frame (Athena extension)."""
+        if self._chart_area_cached is None:
+            self._chart_area_cached = ChartArea(self._shape)
+        return self._chart_area_cached
+
+    @property
+    def plot_area(self) -> PlotArea:
+        """Fill and line format for the plot region (Athena extension)."""
+        if self._plot_area_cached is None:
+            self._plot_area_cached = PlotArea(self._shape)
+        return self._plot_area_cached
+
     @chart_title.setter
     def chart_title(self, value: Any) -> None:
         """Backwards-compat: accept a string and route it through SetChartTitle.
@@ -11401,6 +11481,8 @@ class Shapes:
                 properties={"name": name},
             )
             shape._source = "sdk"
+            shape._added_image_blob = image_data
+            shape._added_image_filename = _loaded_image_filename(image_file)
             self._shapes.append(shape)
             self._shapes_by_id[shape_id] = shape
             return shape
@@ -11413,6 +11495,8 @@ class Shapes:
             properties={"name": name},
         )
         shape._source = "sdk"
+        shape._added_image_blob = image_data
+        shape._added_image_filename = _loaded_image_filename(image_file)
         self._shapes.append(shape)
         self._shapes_by_id[client_id] = shape
         return shape
@@ -12595,12 +12679,15 @@ class Shapes:
         cx: Length,
         cy: Length,
         chart_data: Any,
+        *,
+        name: Optional[str] = None,
     ) -> "GraphicFrame":
         """Author a chart. ``x``/``y``/``cx``/``cy`` mirror python-pptx's
         ``SlideShapes.add_chart`` signature (top-left position and size in EMU).
+        ``name`` is an Athena extension for assigning the shape name.
         """
         left, top, width, height = x, y, cx, cy
-        return self._add_chart_impl(chart_type, left, top, width, height, chart_data)
+        return self._add_chart_impl(chart_type, left, top, width, height, chart_data, name=name)
 
     def _add_chart_impl(
         self,
@@ -12610,6 +12697,8 @@ class Shapes:
         width: Length,
         height: Length,
         chart_data: Any,
+        *,
+        name: Optional[str] = None,
     ) -> "GraphicFrame":
         """
         Author a brand-new chart on this slide.
@@ -12641,7 +12730,7 @@ class Shapes:
         cx_kind = _is_cx_chart_type(chart_type)
         if cx_kind is not None:
             return self._add_chart_2016_impl(
-                cx_kind, left, top, width, height, chart_data,
+                cx_kind, left, top, width, height, chart_data, name=name,
             )
 
         chart_type_str, grouping, markers, categories, series_payload = _sdk_chart_payload(
@@ -12656,7 +12745,7 @@ class Shapes:
         client_id = f"cht_{uuid.uuid4().hex[:8]}"
         shape_id = client_id
         # Mirror python-pptx: "Chart <count_after_add>", as add_table names tables.
-        name = self._next_auto_name("Chart")
+        name = name if name is not None else self._next_auto_name("Chart")
 
         if self._buffer:
             cmd = AddChartCmd(
@@ -12718,6 +12807,8 @@ class Shapes:
         width: Length,
         height: Length,
         chart_data: Any,
+        *,
+        name: Optional[str] = None,
     ) -> "GraphicFrame":
         """Author a 2016+ cx-schema chart.
 
@@ -12763,7 +12854,7 @@ class Shapes:
 
         client_id = f"cht_{uuid.uuid4().hex[:8]}"
         shape_id = client_id
-        name = self._next_auto_name("Chart")
+        name = name if name is not None else self._next_auto_name("Chart")
 
         if self._buffer:
             cmd = AddChart2016(
@@ -15988,6 +16079,11 @@ class Picture(Shape):
         # picture's bytes, when loaded from a server snapshot. Powers
         # ``image_url`` so images can be copied across decks.
         self._asset_id = asset_id
+        # Bytes handed to add_picture()/insert_picture() in this session, and
+        # the Image ``image`` built (fetched once per proxy).
+        self._added_image_blob: Optional[bytes] = None
+        self._added_image_filename: Optional[str] = None
+        self._image: Optional[Image] = None
 
     @property
     def line(self) -> LineFormat:
@@ -16061,19 +16157,33 @@ class Picture(Shape):
             return None
 
     @property
-    def image(self) -> Optional[Any]:
-        """The picture's underlying image (python-pptx parity).
-
-        Stock python-pptx returns an ``Image`` instance with ``.blob`` /
-        ``.content_type`` / ``.filename`` accessors. The REST SDK doesn't
-        materialize image bytes back into Python — bytes live in the
-        studio's asset store, reachable via the rendered URL — so this
-        always returns ``None``. Provided so ``isinstance``-style
-        introspection works without ``AttributeError``. To copy this
-        picture into another deck, pass :attr:`image_url` to
-        ``dst.shapes.add_picture(...)``.
-        """
-        return None
+    def image(self) -> Image:
+        """The picture's image (python-pptx parity): an :class:`Image` with
+        ``blob``, ``content_type``, ``ext``, ``filename``, ``sha1``, ``size``
+        and ``dpi``.
+
+        A picture this session added carries the bytes it was added from. A
+        picture read from the deck fetches its bytes once from the studio's
+        media store, with the SDK's own credentials and the same deck-access
+        check every deck op runs, and caches them on this proxy. Raises
+        ``ValueError("no embedded image")``, as python-pptx does, when the
+        picture has no image (an empty placeholder, or a source with no media
+        asset such as an OLE or movie poster).
+        """
+        cached = getattr(self, "_image", None)
+        if cached is not None:
+            return cached
+        blob = getattr(self, "_added_image_blob", None)
+        filename = getattr(self, "_added_image_filename", None)
+        if blob is None:
+            asset_id = getattr(self, "_asset_id", None)
+            client = getattr(getattr(self._slide, "_presentation", None), "_client", None)
+            if not asset_id or client is None:
+                raise ValueError("no embedded image")
+            blob = client._download_media(key=asset_id, max_bytes=_MAX_URL_IMAGE_BYTES)
+        image = Image(blob=blob, filename=filename)
+        self._image = image
+        return image
 
     @property
     @athena_extension(
@@ -16083,7 +16193,8 @@ class Picture(Shape):
     def image_url(self) -> Optional[str]:
         """Stable HTTP(S) URL that serves this picture's image bytes.
 
-        Athena extension — not in upstream python-pptx. Returns ``None``
+        Athena extension — not in upstream python-pptx; for the bytes
+        themselves read :attr:`image` ``.blob``. Returns ``None``
         when the picture has no backing media asset (an SDK-added picture
         not yet flushed/refreshed, or a placeholder with no image).
         Otherwise returns ``{base_url}/media?key=<assetId>`` where
@@ -16769,6 +16880,8 @@ class PicturePlaceholder(_BaseSlidePlaceholder):
             placeholder=_dc_replace(placeholder, local_transform_override=None) if placeholder else None,
             source=self._source,
         )
+        picture._added_image_blob = image_data
+        picture._added_image_filename = _loaded_image_filename(image_file)
         self._replace_placeholder_with(picture, method="insert_picture")
         if any(crop.values()):
             picture._emit_crop_change(crop)

{athena_python_pptx-0.17.1 → athena_python_pptx-0.18.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-pptx"
-version = "0.17.1"
+version = "0.18.0"
 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.17.1/pptx/chart/chart.py

@@ -1,7 +0,0 @@
-"""Shim re-exporting upstream's ``pptx.chart.chart`` surface."""
-
-from __future__ import annotations
-
-from ..shapes import Chart, ChartTitle
-
-__all__ = ["Chart", "ChartTitle"]