athena-python-pptx 0.1.54__tar.gz → 0.1.56__tar.gz

athena_python_pptx-0.1.56/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `athena-python-pptx` are documented in this file.
+
+## 0.1.56
+
+- **Charts: end-to-end author + edit support** for column / bar / line / area / pie / doughnut (including all stacked variants).
+  - `slide.shapes.add_chart(chart_type, left, top, width, height, chart_data)` now authors a fresh chart from scratch — previously raised `UnsupportedFeatureError`. Returns a `GraphicFrame` whose `.chart` property exposes the resulting `Chart` object. Supported types: `XL_CHART_TYPE.COLUMN_CLUSTERED`, `COLUMN_STACKED`, `COLUMN_STACKED_100`, `BAR_CLUSTERED`, `BAR_STACKED`, `BAR_STACKED_100`, `LINE`, `LINE_MARKERS`, `LINE_STACKED`, `LINE_STACKED_100`, `AREA`, `AREA_STACKED`, `AREA_STACKED_100`, `PIE`, `DOUGHNUT`. 3-D / scatter / bubble / radar / stock / surface / combo still raise `UnsupportedFeatureError` with a clearer message listing the supported set.
+  - `placeholder.insert_chart(chart_type, chart_data)` now wires up the same path — previously raised `NotImplementedError`.
+  - `Chart.replace_data(chart_data)` now emits `UpdateChartData` patches against an existing chart (ingested or just-authored) — previously raised `UnsupportedFeatureError`. Rewrites series values, series names, and category labels in place; embedded `.xlsx` workbook stays in sync.
+  - New `Chart.chart_title` setter and `Chart.has_legend` setter emit `SetChartTitle` and `SetLegendVisible` patches respectively.
+  - `CategoryChartData.add_series()` and `XyChartData` / `BubbleChartData` now capture data client-side instead of raising eagerly. (Authoring scatter / bubble charts still raises at `add_chart()` time.)
+  - `GraphicFrame` extended to host a `Chart` (in addition to `Table`), so `gf.chart` and `gf.has_chart` work.
+
+## 0.1.55
+
+- Internal: bumped version coordinated with the `Presentation.create()` server-side fix (#19270). No SDK API change.
+
+## 0.1.54
+
+- `RemoteError.__str__` now includes the HTTP status code (e.g., `[HTTP 400] Invalid request body: ...`) so the status is visible in tracebacks without unpacking `exc.status_code`.
+
+## 0.1.39
+
+- Added SDK support for `slide.shapes.add_table(...)` and table creation command wiring.
+- Added `slide.notes_slide.notes_text_frame.text` compatibility adapter for python-pptx style notes access.
+- Added support for auto-shape text frame access (`shape.text_frame`) to match python-pptx behavior.
+- Added smoke/integration tests for table creation/cell updates, notes slide adapter, and shape text-frame regression.
+- Updated README examples for notes slide adapter and auto-shape text support.

{athena_python_pptx-0.1.54 → athena_python_pptx-0.1.56}/PKG-INFO

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

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

athena_python_pptx-0.1.56/pptx/chart/data.py

@@ -0,0 +1,117 @@
+"""
+Chart data classes matching python-pptx.
+
+These classes capture series data client-side. The actual server-side
+materialization happens via:
+
+  * `Shape.chart.replace_data(chart_data)` for ingested charts — emits
+    `UpdateSeriesValue` / `UpdateCategoryLabel` patches against the existing
+    chart part.
+  * `slide.shapes.add_chart(chart_type, ..., chart_data)` for SDK-authored
+    charts — sends an `AddChart` command that the export-worker
+    materializes via `@pptx/chart-ooxml/export/author.ts`.
+"""
+
+from __future__ import annotations
+from typing import Any, Sequence
+
+from ..errors import UnsupportedFeatureError
+
+
+class CategoryChartData:
+    """
+    Chart data for category-based charts (column, bar, line, area, pie,
+    doughnut). Matches python-pptx's `CategoryChartData` API.
+    """
+
+    def __init__(self) -> None:
+        self._categories: list[str] = []
+        self._series: list[tuple[str, list[float | None]]] = []
+
+    @property
+    def categories(self) -> list[str]:
+        """Category labels (x-axis tick labels)."""
+        return self._categories
+
+    @categories.setter
+    def categories(self, value: Sequence[str]) -> None:
+        """Set category labels."""
+        self._categories = [str(v) for v in value]
+
+    def add_series(
+        self,
+        name: str,
+        values: Sequence[float | None],
+        number_format: str = "",
+    ) -> None:
+        """Add a data series.
+
+        `number_format` is accepted for python-pptx parity but is not
+        currently propagated to the chart spec — the embedded workbook's
+        format string controls display formatting.
+        """
+        self._series.append((name, [None if v is None else float(v) for v in values]))
+
+    def to_series_payload(self) -> list[dict[str, Any]]:
+        """Internal: convert to the wire shape used by AddChart / patches."""
+        return [{"name": name, "values": list(values)} for name, values in self._series]
+
+    def __len__(self) -> int:
+        return len(self._series)
+
+
+# Alias for compatibility with python-pptx (which exposes both names).
+ChartData = CategoryChartData
+
+
+class _XySeries:
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.points: list[tuple[float, float]] = []
+
+    def add_data_point(self, x: float, y: float) -> None:
+        self.points.append((float(x), float(y)))
+
+
+class XyChartData:
+    """Chart data for XY (scatter) charts. Captured client-side; authoring
+    these via the SDK is gated on the chart-ooxml authoring path adding
+    scatter support — currently raises `UnsupportedFeatureError` from
+    `add_chart()` for scatter types. The data structure itself is
+    populated for parity with python-pptx code."""
+
+    def __init__(self) -> None:
+        self._series: list[_XySeries] = []
+
+    def add_series(self, name: str, values: Any = None) -> _XySeries:
+        series = _XySeries(name)
+        if values is not None:
+            for point in values:
+                if isinstance(point, (tuple, list)) and len(point) == 2:
+                    series.add_data_point(point[0], point[1])
+        self._series.append(series)
+        return series
+
+
+class _BubbleSeries(_XySeries):
+    def __init__(self, name: str) -> None:
+        super().__init__(name)
+        self.sizes: list[float] = []
+
+    def add_data_point(self, x: float, y: float, size: float = 1.0) -> None:  # type: ignore[override]
+        super().add_data_point(x, y)
+        self.sizes.append(float(size))
+
+
+class BubbleChartData:
+    """Chart data for bubble charts. Same status as `XyChartData` — captured
+    client-side, but `add_chart()` for bubble type is unsupported until the
+    chart-ooxml authoring path covers bubble plots."""
+
+    def __init__(self) -> None:
+        self._series: list[_BubbleSeries] = []
+
+    def add_series(self, name: str, values: Any = None) -> _BubbleSeries:
+        series = _BubbleSeries(name)
+        self._series.append(series)
+        return series

{athena_python_pptx-0.1.54 → athena_python_pptx-0.1.56}/pptx/client.py

@@ -201,6 +201,7 @@ class Client:
         path: str,
         json: Optional[dict] = None,
         params: Optional[dict] = None,
+        timeout: Optional[float] = None,
     ) -> Any:
         """Make an HTTP request."""
         url = urljoin(self.base_url + "/", path.lstrip("/"))
@@ -218,7 +219,7 @@ class Client:
                 json=json,
                 params=params,
                 headers=headers,
-                timeout=self.timeout,
+                timeout=timeout if timeout is not None else self.timeout,
             )
             return self._handle_response(response)
         except requests.ConnectionError as e:
@@ -260,21 +261,70 @@ class Client:
         payload = {"name": name} if name else None
         return self._request("POST", "/decks", json=payload)
 
-    def create_empty_deck(self, name: Optional[str] = None) -> dict[str, Any]:
+    def create_empty_deck(
+        self,
+        name: Optional[str] = None,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        max_attempts: int = 240,
+    ) -> dict[str, Any]:
         """
-        Create a new empty deck that's immediately ready.
+        Create a new empty deck and wait until it is ready.
 
         Unlike create_deck(), this creates a deck without requiring an upload.
-        The deck is immediately usable with no slides.
+        The server provisions a blank PPTX template and runs it through the
+        ingest pipeline; this method blocks until ingest is finished.
+
+        The server may return either:
+          * 201 with status="ready" if ingest finishes within its synchronous
+            poll window, or
+          * 202 with status="processing" if ingest is still in progress.
+
+        In the 202 case we poll GET /decks/:id at ``poll_interval`` until the
+        status flips to "ready" (or "error", in which case we raise). The
+        initial POST uses an extended timeout so it doesn't race the server's
+        own poll loop.
 
         Args:
             name: Optional name for the deck
+            poll_interval: Seconds between status polls
+            max_attempts: Maximum number of poll attempts (default 240 ≈ 2 min)
 
         Returns:
-            Dictionary with id, name, status, slideCount, createdAt
+            Dictionary with id, name, status="ready", slideCount, createdAt
+
+        Raises:
+            UploadError: If ingest reports an error or never reaches "ready".
         """
         payload = {"name": name} if name else None
-        return self._request("POST", "/decks/empty", json=payload)
+        # Use an extended timeout so we don't race the server's synchronous
+        # poll window (the server may hold the request open for up to ~30s
+        # waiting for ingest to complete before returning 202).
+        result = self._request("POST", "/decks/empty", json=payload, timeout=120)
+
+        deck_id = result.get("id")
+        status = result.get("status")
+        if status == "ready":
+            return result
+        if not deck_id:
+            raise UploadError(
+                "Server did not return a deck id from POST /decks/empty",
+                None,
+            )
+
+        # Poll until ingest finishes.
+        for _ in range(max_attempts):
+            deck = self.get_deck(deck_id)
+            current_status = deck.get("status")
+            if current_status == "ready":
+                return deck
+            if current_status == "error":
+                raise UploadError("Empty deck ingest failed", deck_id)
+            time.sleep(poll_interval)
+
+        raise UploadError(
+            "Empty deck ingest timed out before reaching 'ready'",
+            deck_id,
+        )
 
     def delete_deck(self, deck_id: str) -> None:
         """Delete a deck."""

{athena_python_pptx-0.1.54 → athena_python_pptx-0.1.56}/pptx/commands.py

@@ -1371,6 +1371,101 @@ class SubstitutePlaceholder(Command):
             raise ValidationError("rows and cols required for table", "rows")
 
 
+@dataclass
+class UpdateChartData(Command):
+    """
+    Append `ChartPatch` intents to a chart shape's mutation queue.
+
+    The export-worker drains the queue at export time and applies each
+    patch to the underlying chart-part XML via
+    @pptx/chart-ooxml/export/patcher.ts. Supported patch ops mirror the
+    chart-core ChartPatch discriminated union: UpdateSeriesValue,
+    UpdateSeriesName, UpdateCategoryLabel, SetChartTitle,
+    SetLegendVisible, SetSeriesColor.
+    """
+
+    shape_id: ShapeId
+    patches: list[dict[str, Any]] = field(default_factory=list)
+
+    @property
+    def command_type(self) -> str:
+        return "UpdateChartData"
+
+    def validate(self) -> None:
+        if not self.shape_id:
+            raise ValidationError("shape_id is required", "shape_id")
+        if not self.patches:
+            raise ValidationError("at least one patch is required", "patches")
+        valid_ops = {
+            "UpdateSeriesValue",
+            "UpdateSeriesName",
+            "UpdateCategoryLabel",
+            "SetChartTitle",
+            "SetLegendVisible",
+            "SetSeriesColor",
+        }
+        for i, p in enumerate(self.patches):
+            if not isinstance(p, dict) or p.get("op") not in valid_ops:
+                raise ValidationError(
+                    f"patches[{i}].op must be one of {sorted(valid_ops)}",
+                    f"patches[{i}]",
+                )
+
+
+@dataclass
+class AddChart(Command):
+    """
+    Author a brand-new chart from scratch on a slide.
+
+    The chart element is created with provenance='sdk' and no chartPartRef;
+    the export-worker materializes the chart-part XML, embedded workbook,
+    and slide-level relationships via @pptx/chart-ooxml/export/author.ts
+    on the next export.
+    """
+
+    slide_index: int
+    chart_type: str  # 'column' | 'bar' | 'line' | 'area' | 'pie' | 'doughnut'
+    x_emu: int
+    y_emu: int
+    w_emu: int
+    h_emu: int
+    categories: list[str] = field(default_factory=list)
+    series: list[dict[str, Any]] = field(default_factory=list)
+    title: Optional[str] = None
+    grouping: Optional[str] = None  # 'clustered' | 'stacked' | 'percentStacked'
+    name: Optional[str] = None
+    client_id: Optional[str] = None
+
+    @property
+    def command_type(self) -> str:
+        return "AddChart"
+
+    def validate(self) -> None:
+        if self.slide_index < 0:
+            raise ValidationError("slide_index must be >= 0", "slide_index")
+        valid_types = {"column", "bar", "line", "area", "pie", "doughnut"}
+        if self.chart_type not in valid_types:
+            raise ValidationError(
+                f"chart_type must be one of {sorted(valid_types)}",
+                "chart_type",
+            )
+        if self.w_emu <= 0:
+            raise ValidationError("w_emu must be positive", "w_emu")
+        if self.h_emu <= 0:
+            raise ValidationError("h_emu must be positive", "h_emu")
+        if not self.series:
+            raise ValidationError("at least one series is required", "series")
+        if self.grouping is not None and self.grouping not in (
+            "clustered",
+            "stacked",
+            "percentStacked",
+        ):
+            raise ValidationError(
+                "grouping must be 'clustered', 'stacked', or 'percentStacked'",
+                "grouping",
+            )
+
+
 # Type alias for any command
 AnyCommand = Union[
     AddTextBox,
@@ -1411,4 +1506,7 @@ AnyCommand = Union[
     SetShapeAdjustments,
     FitText,
     SubstitutePlaceholder,
+    # Charts
+    UpdateChartData,
+    AddChart,
 ]

{athena_python_pptx-0.1.54 → athena_python_pptx-0.1.56}/pptx/shapes.py

@@ -19,7 +19,9 @@ from .commands import (
     SetShapeAdjustments, MergeCells as MergeCellsCmd,
     SplitCell as SplitCellCmd, SetCellMargins, SetColWidth, SetRowHeight,
     SetShapeAdjustments, SubstitutePlaceholder,
+    UpdateChartData as UpdateChartDataCmd, AddChart as AddChartCmd,
 )
+from .chart.data import CategoryChartData, ChartData
 from .dml.color import RGBColor, ColorFormat
 from .errors import UnsupportedFeatureError
 from .text import TextFrame
@@ -35,6 +37,75 @@ if TYPE_CHECKING:
 # ``from pptx.shapes import MSO_SHAPE`` and
 # ``from pptx.enum.shapes import MSO_SHAPE`` resolve to the same IntEnum.
 from .enum.shapes import MSO_SHAPE  # noqa: F811
+from .enum.chart import XL_CHART_TYPE
+
+
+# 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
+# values so callers can switch between python-pptx and athena-python-pptx
+# without code changes for the supported subset.
+_CHART_TYPE_MAP: dict[int, tuple[str, Optional[str]]] = {
+    XL_CHART_TYPE.COLUMN_CLUSTERED: ("column", "clustered"),
+    XL_CHART_TYPE.COLUMN_STACKED: ("column", "stacked"),
+    XL_CHART_TYPE.COLUMN_STACKED_100: ("column", "percentStacked"),
+    XL_CHART_TYPE.BAR_CLUSTERED: ("bar", "clustered"),
+    XL_CHART_TYPE.BAR_STACKED: ("bar", "stacked"),
+    XL_CHART_TYPE.BAR_STACKED_100: ("bar", "percentStacked"),
+    XL_CHART_TYPE.LINE: ("line", "clustered"),
+    XL_CHART_TYPE.LINE_MARKERS: ("line", "clustered"),
+    XL_CHART_TYPE.LINE_STACKED: ("line", "stacked"),
+    XL_CHART_TYPE.LINE_STACKED_100: ("line", "percentStacked"),
+    XL_CHART_TYPE.AREA: ("area", "clustered"),
+    XL_CHART_TYPE.AREA_STACKED: ("area", "stacked"),
+    XL_CHART_TYPE.AREA_STACKED_100: ("area", "percentStacked"),
+    XL_CHART_TYPE.PIE: ("pie", None),
+    XL_CHART_TYPE.DOUGHNUT: ("doughnut", None),
+}
+
+
+def _split_chart_type(chart_type: Any) -> tuple[str, Optional[str]]:
+    """
+    Resolve a `XL_CHART_TYPE` (or matching int / str) into the server's
+    `(chart_type, grouping)` pair. Raises `UnsupportedFeatureError` for
+    chart types the author.ts path does not yet emit (3-D variants,
+    scatter, bubble, radar, stock, combo, surface).
+    """
+    if isinstance(chart_type, str):
+        normalized = chart_type.lower().strip()
+        if normalized in {"column", "bar", "line", "area"}:
+            return normalized, "clustered"
+        if normalized in {"pie", "doughnut"}:
+            return normalized, None
+        raise UnsupportedFeatureError(
+            "add_chart",
+            f"Unsupported chart type string '{chart_type}'. "
+            "Use one of: 'column', 'bar', 'line', 'area', 'pie', 'doughnut'.",
+        )
+    try:
+        key = int(chart_type)
+    except (TypeError, ValueError):
+        raise UnsupportedFeatureError(
+            "add_chart",
+            f"Unsupported chart_type value: {chart_type!r}",
+        )
+    mapped = _CHART_TYPE_MAP.get(key)
+    if mapped is None:
+        raise UnsupportedFeatureError(
+            "add_chart",
+            f"Chart type {chart_type!r} is not supported by the SDK author "
+            "path. Supported XL_CHART_TYPE values: COLUMN_CLUSTERED, "
+            "COLUMN_STACKED, COLUMN_STACKED_100, BAR_CLUSTERED, BAR_STACKED, "
+            "BAR_STACKED_100, LINE, LINE_MARKERS, LINE_STACKED, "
+            "LINE_STACKED_100, AREA, AREA_STACKED, AREA_STACKED_100, PIE, "
+            "DOUGHNUT.",
+        )
+    return mapped
+
+
+def _coerce_chart_type(chart_type: Any) -> str:
+    """Backward-compatible single-string accessor."""
+    return _split_chart_type(chart_type)[0]
 
 
 class PlaceholderFormat:
@@ -844,10 +915,13 @@ class ClickAction:
 
 class Chart:
     """
-    Minimal chart proxy for python-pptx compatibility.
+    Chart proxy for python-pptx compatibility.
 
-    Chart creation/editing is not implemented yet, but this proxy allows
-    `shape.chart` access patterns to fail with explicit unsupported messages.
+    Wraps a chart Shape and exposes the python-pptx chart edit surface.
+    Edits emit `UpdateChartData` commands that append `ChartPatch` intents
+    onto the chart element's `chartPatches` queue; the export-worker drains
+    the queue and applies each patch via
+    `@pptx/chart-ooxml/export/patcher.ts` on the next export.
     """
 
     def __init__(self, shape: "Shape"):
@@ -858,12 +932,115 @@ class Chart:
         """Best-effort chart type if available in element properties."""
         return self._shape._properties.get("chartType")
 
+    @property
+    def has_title(self) -> bool:
+        """python-pptx parity: True if the underlying chart has a title."""
+        return bool(self._shape._properties.get("title"))
+
     def replace_data(self, chart_data: Any) -> None:
-        """Replace chart data (not yet supported)."""
-        raise UnsupportedFeatureError(
-            "shape.chart.replace_data",
-            "Chart editing is not yet supported",
-        )
+        """
+        Replace this chart's series data with the values in `chart_data`.
+
+        Mirrors python-pptx semantics: existing series are kept in place
+        and their values are overwritten in series order. The category
+        labels are also rewritten.
+
+        Implementation: emits `UpdateSeriesValue` patches (one per data
+        point) plus `UpdateSeriesName` and `UpdateCategoryLabel` patches.
+        Server queues them on the chart element's `chartPatches`; the
+        export-worker applies them to the chart-part XML on export.
+        """
+        if not isinstance(chart_data, CategoryChartData):
+            raise TypeError(
+                "replace_data() requires a CategoryChartData instance "
+                f"(got {type(chart_data).__name__})"
+            )
+
+        chart_id = self._shape.shape_id
+        existing_spec = self._shape._properties.get("chartSpec") or {}
+        existing_plots = existing_spec.get("plots") or []
+        existing_series_ids: list[str] = []
+        if existing_plots:
+            for s in (existing_plots[0].get("series") or []):
+                existing_series_ids.append(str(s.get("id") or ""))
+
+        patches: list[dict[str, Any]] = []
+
+        for s_idx, (name, values) in enumerate(zip(
+            [n for n, _ in chart_data._series],
+            [v for _, v in chart_data._series],
+        )):
+            series_id = (
+                existing_series_ids[s_idx]
+                if s_idx < len(existing_series_ids)
+                else f"series-{s_idx}"
+            )
+            patches.append({
+                "op": "UpdateSeriesName",
+                "chartId": chart_id,
+                "seriesId": series_id,
+                "name": name,
+            })
+            for i, v in enumerate(values):
+                patches.append({
+                    "op": "UpdateSeriesValue",
+                    "chartId": chart_id,
+                    "seriesId": series_id,
+                    "index": i,
+                    "value": v,
+                })
+
+        for i, label in enumerate(chart_data.categories):
+            patches.append({
+                "op": "UpdateCategoryLabel",
+                "chartId": chart_id,
+                "index": i,
+                "label": label,
+            })
+
+        if not patches:
+            return
+
+        if self._shape._buffer is not None:
+            self._shape._buffer.add(UpdateChartDataCmd(
+                shape_id=chart_id,
+                patches=patches,
+            ))
+
+    @property
+    def chart_title(self) -> Optional[str]:
+        return self._shape._properties.get("title")
+
+    @chart_title.setter
+    def chart_title(self, value: str) -> None:
+        if self._shape._buffer is None:
+            return
+        self._shape._buffer.add(UpdateChartDataCmd(
+            shape_id=self._shape.shape_id,
+            patches=[{
+                "op": "SetChartTitle",
+                "chartId": self._shape.shape_id,
+                "title": str(value),
+            }],
+        ))
+
+    @property
+    def has_legend(self) -> bool:
+        legend = self._shape._properties.get("legend") or {}
+        return bool(legend.get("visible"))
+
+    @has_legend.setter
+    def has_legend(self, value: bool) -> None:
+        if self._shape._buffer is None:
+            return
+        self._shape._buffer.add(UpdateChartDataCmd(
+            shape_id=self._shape.shape_id,
+            patches=[{
+                "op": "SetLegendVisible",
+                "chartId": self._shape.shape_id,
+                "visible": bool(value),
+            }],
+        ))
 
 
 class _ElementParentProxy:
@@ -2303,21 +2480,53 @@ class Shape:
         """
         Insert a chart into this placeholder.
 
-        .. note::
-           Chart insertion is not yet supported in the REST SDK.
-           This method exists for API parity with python-pptx.
-
-        Raises:
-            NotImplementedError: Chart insertion is not yet supported.
+        Authoring path: emits an `AddChart` command targeted at the
+        placeholder's slide and uses the placeholder's anchor as the chart
+        bounding box. The export-worker materializes the chart-part XML
+        and embedded workbook on the next export via
+        `@pptx/chart-ooxml/export/author.ts`.
         """
         if not self.is_placeholder:
             raise ValueError("insert_chart() is only valid on placeholder shapes")
-        raise NotImplementedError(
-            "Chart insertion into placeholders is not yet supported by athena-python-pptx. "
-            "Do NOT retry this method — it will always fail. "
-            "Alternatives: substitute the placeholder with a picture (pre-rendered chart image) "
-            "via add_picture(), or with a table via add_table(). "
-            "Chart authoring is Phase 5 of the charting refactor."
+        if not isinstance(chart_data, CategoryChartData):
+            raise TypeError(
+                "insert_chart() requires a CategoryChartData instance "
+                f"(got {type(chart_data).__name__})"
+            )
+
+        chart_type_str, grouping = _split_chart_type(chart_type)
+
+        transform = self._transform
+        x_emu = int(ensure_emu(self.left)) if transform else 0
+        y_emu = int(ensure_emu(self.top)) if transform else 0
+        w_emu = int(ensure_emu(self.width)) if transform else 6_858_000
+        h_emu = int(ensure_emu(self.height)) if transform else 4_572_000
+
+        if self._buffer is not None:
+            self._buffer.add(AddChartCmd(
+                slide_index=self._slide.slide_index,
+                chart_type=chart_type_str,
+                x_emu=x_emu, y_emu=y_emu, w_emu=w_emu, h_emu=h_emu,
+                categories=list(chart_data.categories),
+                series=chart_data.to_series_payload(),
+                grouping=grouping,
+            ))
+
+        host_shape = Shape(
+            shape_id=self._shape_id,
+            slide=self._slide,
+            buffer=self._buffer,
+            element_type="chart",
+            transform=Transform(x=x_emu, y=y_emu, w=w_emu, h=h_emu),
+            properties={"chartType": chart_type_str},
+            source="sdk",
+        )
+        return GraphicFrame(
+            shape_id=self._shape_id,
+            slide=self._slide,
+            buffer=self._buffer,
+            chart=Chart(host_shape),
+            transform=Transform(x=x_emu, y=y_emu, w=w_emu, h=h_emu),
         )
 
     def __repr__(self) -> str:
@@ -2908,20 +3117,81 @@ class Shapes:
         width: Length,
         height: Length,
         chart_data: Any,
-    ) -> Any:
-        """Add a chart (not yet supported in this SDK)."""
-        raise UnsupportedFeatureError(
-            "shapes.add_chart",
-            (
-                "Chart authoring from scratch is not supported by athena-python-pptx yet. "
-                "Do NOT retry add_chart() — it will always fail. "
-                "Supported alternatives: "
-                "(1) render the chart to a PNG/JPEG externally (e.g. matplotlib, chart.js-node, or an external service) and use shapes.add_picture() to insert it; "
-                "(2) represent the data as a table via shapes.add_table(); "
-                "(3) describe the chart in text via shapes.add_textbox(). "
-                "Chart ingest round-trip is supported for existing charts in uploaded PPTX decks, but creation is tracked under Phase 5 of the charting refactor (see pptx-studio/docs/CHARTING_REFACTOR_PLAN_2026-04-21.md)."
-            ),
+    ) -> "GraphicFrame":
+        """
+        Author a brand-new chart on this slide.
+
+        Mirrors python-pptx's `SlideShapes.add_chart()`. Returns a
+        `GraphicFrame` whose `.chart` property exposes the resulting
+        `Chart` proxy. Edits via `chart.replace_data()` / `chart.chart_title`
+        / `chart.has_legend` are emitted as `UpdateChartData` patches and
+        applied on export.
+
+        Supported chart types: `XL_CHART_TYPE.COLUMN_CLUSTERED`,
+        `BAR_CLUSTERED`, `BAR_STACKED`, `BAR_STACKED_100`,
+        `COLUMN_STACKED`, `COLUMN_STACKED_100`, `LINE`, `LINE_STACKED`,
+        `LINE_STACKED_100`, `AREA`, `AREA_STACKED`, `AREA_STACKED_100`,
+        `PIE`, `DOUGHNUT`. Other types raise `UnsupportedFeatureError`.
+        """
+        import uuid
+
+        if not isinstance(chart_data, CategoryChartData):
+            raise TypeError(
+                "add_chart() requires a CategoryChartData instance "
+                f"(got {type(chart_data).__name__})"
+            )
+
+        chart_type_str, grouping = _split_chart_type(chart_type)
+
+        x_emu = int(ensure_emu(left))
+        y_emu = int(ensure_emu(top))
+        w_emu = int(ensure_emu(width))
+        h_emu = int(ensure_emu(height))
+
+        client_id = f"cht_{uuid.uuid4().hex[:8]}"
+        shape_id = client_id
+
+        if self._buffer:
+            cmd = AddChartCmd(
+                slide_index=self._slide.slide_index,
+                chart_type=chart_type_str,
+                x_emu=x_emu, y_emu=y_emu, w_emu=w_emu, h_emu=h_emu,
+                categories=list(chart_data.categories),
+                series=chart_data.to_series_payload(),
+                title=None,
+                grouping=grouping,
+                client_id=client_id,
+            )
+            response = self._buffer.add(cmd)
+            if response and response.get("created"):
+                shape_ids = response["created"].get("shapeIds", [])
+                if shape_ids:
+                    shape_id = shape_ids[0]
+
+        transform = Transform(x=x_emu, y=y_emu, w=w_emu, h=h_emu)
+
+        host_shape = Shape(
+            shape_id=shape_id,
+            slide=self._slide,
+            buffer=self._buffer,
+            element_type="chart",
+            transform=transform,
+            properties={"chartType": chart_type_str},
+            source="sdk",
         )
+        chart_proxy = Chart(host_shape)
+
+        graphic_frame = GraphicFrame(
+            shape_id=shape_id,
+            slide=self._slide,
+            buffer=self._buffer,
+            chart=chart_proxy,
+            transform=transform,
+        )
+        graphic_frame._source = "sdk"
+        self._shapes.append(graphic_frame)
+        self._shapes_by_id[shape_id] = graphic_frame
+        return graphic_frame
 
     # -------------------------------------------------------------------------
     # Phase 5: Grouping
@@ -4074,11 +4344,12 @@ class _ColumnCollection:
 
 class GraphicFrame(Shape):
     """
-    A graphic frame shape that contains a table.
+    A graphic frame shape that contains a table or chart.
 
     Mirrors python-pptx's GraphicFrame class.
-    In python-pptx, SlideShapes.add_table() returns a GraphicFrame,
-    and the Table is accessed via .table property.
+    In python-pptx, SlideShapes.add_table() returns a GraphicFrame and
+    SlideShapes.add_chart() returns a GraphicFrame whose `.chart` exposes
+    the underlying Chart object.
     """
 
     def __init__(
@@ -4086,25 +4357,27 @@ class GraphicFrame(Shape):
         shape_id: ShapeId,
         slide: "Slide",
         buffer: Optional["CommandBuffer"],
-        table: "Table",
+        table: Optional["Table"] = None,
+        chart: Optional["Chart"] = None,
         transform: Optional[Transform] = None,
     ):
+        if table is None and chart is None:
+            raise ValueError("GraphicFrame requires a table or chart")
         super().__init__(
             shape_id=shape_id,
             slide=slide,
             buffer=buffer,
-            element_type="table",
+            element_type="chart" if chart is not None else "table",
             transform=transform,
         )
         self._table = table
+        self._chart = chart
 
     @property
     def table(self) -> "Table":
-        """
-        The Table object contained in this graphic frame.
-
-        Mirrors python-pptx GraphicFrame.table property.
-        """
+        """The Table object contained in this graphic frame."""
+        if self._table is None:
+            raise ValueError("This GraphicFrame does not contain a table")
         return self._table
 
     @property
@@ -4112,22 +4385,36 @@ class GraphicFrame(Shape):
         """True if this graphic frame contains a table."""
         return self._table is not None
 
+    @property
+    def chart(self) -> "Chart":
+        """The Chart object contained in this graphic frame."""
+        if self._chart is None:
+            raise ValueError("This GraphicFrame does not contain a chart")
+        return self._chart
+
+    @property
+    def has_chart(self) -> bool:
+        """True if this graphic frame contains a chart."""
+        return self._chart is not None
+
     # Passthrough methods so agent code like tbl.cell(0,0) works directly
     def cell(self, row: int, col: int) -> "TableCell":
         """Shortcut: delegates to self.table.cell(row, col)."""
-        return self._table.cell(row, col)
+        return self.table.cell(row, col)
 
     @property
     def rows(self) -> "_RowCollection":
         """Shortcut: delegates to self.table.rows."""
-        return self._table.rows
+        return self.table.rows
 
     @property
     def cols(self) -> int:
         """Shortcut: delegates to self.table.cols."""
-        return self._table.cols
+        return self.table.cols
 
     def __repr__(self) -> str:
+        if self._chart is not None:
+            return f"<GraphicFrame shape_id={self._shape_id} chart>"
         return f"<GraphicFrame shape_id={self._shape_id} table={self._table._rows}x{self._table._cols}>"
 
 

{athena_python_pptx-0.1.54 → athena_python_pptx-0.1.56}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-pptx"
-version = "0.1.54"
+version = "0.1.56"
 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.54/CHANGELOG.md

@@ -1,15 +0,0 @@
-# Changelog
-
-All notable changes to `athena-python-pptx` are documented in this file.
-
-## 0.1.54
-
-- `RemoteError.__str__` now includes the HTTP status code (e.g., `[HTTP 400] Invalid request body: ...`) so the status is visible in tracebacks without unpacking `exc.status_code`.
-
-## 0.1.39
-
-- Added SDK support for `slide.shapes.add_table(...)` and table creation command wiring.
-- Added `slide.notes_slide.notes_text_frame.text` compatibility adapter for python-pptx style notes access.
-- Added support for auto-shape text frame access (`shape.text_frame`) to match python-pptx behavior.
-- Added smoke/integration tests for table creation/cell updates, notes slide adapter, and shape text-frame regression.
-- Updated README examples for notes slide adapter and auto-shape text support.

athena_python_pptx-0.1.54/pptx/chart/data.py

@@ -1,96 +0,0 @@
-"""
-Chart data classes matching python-pptx.
-
-These are stub implementations that raise UnsupportedFeatureError.
-"""
-
-from __future__ import annotations
-from typing import Any, Sequence
-
-from ..errors import UnsupportedFeatureError
-
-
-class CategoryChartData:
-    """
-    Chart data for category-based charts.
-
-    This is a stub implementation - charts are not yet supported.
-    """
-
-    def __init__(self) -> None:
-        self._categories: list[str] = []
-        self._series: list[tuple[str, Sequence[float]]] = []
-
-    @property
-    def categories(self) -> list[str]:
-        """Category labels."""
-        return self._categories
-
-    @categories.setter
-    def categories(self, value: Sequence[str]) -> None:
-        """Set category labels."""
-        self._categories = list(value)
-
-    def add_series(self, name: str, values: Sequence[float], number_format: str = "") -> None:
-        """
-        Add a data series.
-
-        Note: This method stores data but actual chart creation is not yet supported.
-        """
-        self._series.append((name, values))
-
-    def _raise_not_supported(self) -> None:
-        raise UnsupportedFeatureError(
-            "CategoryChartData",
-            "Charts are not yet supported. Data can be stored but charts cannot be created."
-        )
-
-
-# Alias for compatibility
-ChartData = CategoryChartData
-
-
-class XyChartData:
-    """
-    Chart data for XY (scatter) charts.
-
-    This is a stub implementation - charts are not yet supported.
-    """
-
-    def __init__(self) -> None:
-        self._series: list[Any] = []
-
-    def add_series(self, name: str, values: Any = None) -> Any:
-        """
-        Add a data series.
-
-        Raises:
-            UnsupportedFeatureError: Charts are not yet supported
-        """
-        raise UnsupportedFeatureError(
-            "XyChartData.add_series",
-            "XY charts are not yet supported"
-        )
-
-
-class BubbleChartData:
-    """
-    Chart data for bubble charts.
-
-    This is a stub implementation - charts are not yet supported.
-    """
-
-    def __init__(self) -> None:
-        self._series: list[Any] = []
-
-    def add_series(self, name: str, values: Any = None) -> Any:
-        """
-        Add a data series.
-
-        Raises:
-            UnsupportedFeatureError: Charts are not yet supported
-        """
-        raise UnsupportedFeatureError(
-            "BubbleChartData.add_series",
-            "Bubble charts are not yet supported"
-        )