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

athena_python_pptx-0.1.54/API_PARITY_REPORT.md

@@ -0,0 +1,51 @@
+# API Parity Report: athena-python-pptx vs python-pptx
+
+**Generated:** 2026-03-23
+**athena-python-pptx version:** 0.1.52
+**python-pptx version:** 1.0.2
+**Test script:** `tests/test_python_pptx_api_parity.py`
+**Classes tested:** 8
+
+---
+
+## Summary
+
+**0 unexpected missing, 0 unexpected extras, 0 param mismatches across all tested classes.**
+
+| Class | Standard Members | Missing | Extra | Status |
+|-------|---------|---------|-------|--------|
+| FillFormat | solid, background, gradient, patterned, fore_color, back_color, pattern, type | 1 (internal) | 2 (gradient props) | PASS |
+| LineFormat | color, dash_style, fill, width | 0 | 2 (is_dashed, is_solid) | PASS |
+| RGBColor | from_string, count, index, __iter__, __len__, __getitem__ | 0 | 0 | PASS |
+| ColorFormat | rgb, theme_color, brightness, type | 1 (internal) | 0 | PASS |
+| Font | bold, italic, underline, size, name, color | 2 (fill, language_id) | 0 | PASS |
+| TextFrame | text, paragraphs, margins, auto_size, word_wrap, add_paragraph, clear, fit_text | 1 (part) | 47 (convenience) | PASS |
+| Paragraph | alignment, font, level, line_spacing, runs, space_after/before, add_run, clear | 1 (part) | 30 (convenience) | PASS |
+| Run | text, font, hyperlink | 1 (part) | 20 (convenience) | PASS |
+
+## Intentionally Omitted
+
+| Member | Reason |
+|--------|--------|
+| `*.part` | Package part — REST SDK has no local XML packages |
+| `FillFormat.from_fill_parent()` | Internal XML constructor |
+| `ColorFormat.from_colorchoice_parent()` | Internal XML constructor |
+| `Font.fill` | Font fill format — not commonly used |
+| `Font.language_id` | Not yet implemented |
+
+## Non-Standard Extras (Candidates for Future Cleanup)
+
+**Core classes (FillFormat, LineFormat, RGBColor, ColorFormat, Font):** Fully cleaned — no non-standard methods.
+
+**TextFrame:** 47 convenience methods (to_html, to_markdown, word_count, capitalize, etc.)
+**Paragraph:** 30 convenience methods (bullet helpers, string ops, to_dict, etc.)
+**Run:** 20 convenience methods (string ops, is_bold, has_hyperlink, etc.)
+
+These extras are additive (don't break standard code) but should be removed in a future pass to match the same parity standard as the core classes.
+
+## How to Run
+
+```bash
+pip install python-pptx --target /tmp/pptx-standard
+python -m pytest tests/test_python_pptx_api_parity.py -v -s
+```

{athena_python_pptx-0.1.51 → athena_python_pptx-0.1.54}/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 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.

athena_python_pptx-0.1.54/CLAUDE.md

@@ -0,0 +1,73 @@
+# athena-python-pptx SDK — Claude Instructions
+
+## API Parity Rule (MANDATORY)
+
+**This SDK MUST be a 100% exact replica of the standard [python-pptx](https://python-pptx.readthedocs.io/) API.**
+
+Every class, method, property, and parameter name must match python-pptx exactly. The goal is that any code written for python-pptx works identically with this SDK — no surprises, no differences.
+
+### What this means in practice
+
+- **Do NOT add new methods** that don't exist in python-pptx (e.g., `fill.set_color()`, `line.no_fill()`, `fill.solid_fill()`)
+- **Do NOT add new properties** that don't exist in python-pptx (e.g., `fill.color_hex`, `line.color_hex`, `line.width_pt`)
+- **Do NOT rename parameters** — use the exact same parameter names as python-pptx (e.g., `autoshape_type_id`, not `autoshape_type`)
+- **Do NOT change method signatures** — if python-pptx's `fill.solid()` takes no arguments, ours must also take no arguments
+- **Do NOT change return types** — if python-pptx's `font.color` returns a `ColorFormat`, ours must too (never `None`)
+
+### How to verify parity
+
+Before adding or modifying any API surface:
+
+1. Check the [python-pptx documentation](https://python-pptx.readthedocs.io/)
+2. Check the [python-pptx source code](https://github.com/scanny/python-pptx)
+3. Confirm the method/property/parameter exists with the same name and signature
+4. If it doesn't exist in python-pptx, **do not add it** without explicit user approval
+
+### Current status (v0.1.52)
+
+**Core classes are at 1:1 parity** with python-pptx: FillFormat, LineFormat, RGBColor, ColorFormat, Font. All legacy convenience methods on these classes have been removed.
+
+**TextFrame, Paragraph, and Run** still have non-standard convenience extras (e.g., `to_dict()`, `word_count`, `capitalize()`, string helpers). These are candidates for removal in a future cleanup pass.
+
+Run `python -m pytest tests/test_python_pptx_api_parity.py -v -s` to verify parity across 8 classes.
+
+### Intentionally omitted (REST SDK limitations)
+
+These standard python-pptx members don't apply to a REST SDK:
+- `Shape.element`, `Shape.part` — XML element access (no local XML)
+- `TextFrame.part`, `Paragraph.part`, `Run.part` — package part access
+- `FillFormat.from_fill_parent()`, `ColorFormat.from_colorchoice_parent()` — internal constructors
+- `Font.fill` — font fill format (not supported)
+- `Font.language_id` — not yet implemented
+
+### If you need a deviation
+
+If there is a genuine technical reason why a deviation from python-pptx is necessary (e.g., the SDK is a REST client and cannot replicate XML-level behavior):
+
+1. **Stop and ask the user** before implementing
+2. Explain what the deviation is and why it's needed
+3. Get explicit confirmation that the deviation is acceptable
+4. Document the deviation in the table above
+
+**Do NOT silently add convenience methods, aliases, or "improved" APIs.** The value of this SDK is that it's a drop-in replacement — any divergence breaks that contract.
+
+## Development
+
+```bash
+# Install in editable mode
+pip install -e ".[dev]"
+
+# Run tests
+python -m pytest tests/ -x -q
+
+# Run specific test file
+python -m pytest tests/test_sdk_features.py -x -q
+```
+
+## Architecture
+
+This is a **REST API client** that mimics the python-pptx API. Instead of manipulating XML directly, method calls are translated to commands sent to the PPTX Studio API server. Key differences from python-pptx internals:
+
+- No `_element`, `_sp`, `_spTree` XML attributes — these don't exist
+- Operations are batched via `with prs.batch():` context manager
+- State is synchronized via the PPTX Studio collaboration layer (Yjs)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-pptx
-Version: 0.1.51
+Version: 0.1.54
 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/docs/API_PARITY_EXCEPTIONS.md

@@ -0,0 +1,110 @@
+# athena-python-pptx API Parity Exceptions
+
+This document lists all intentional deviations from the standard [python-pptx](https://python-pptx.readthedocs.io/) API in the athena-python-pptx SDK.
+
+The SDK's goal is 1:1 API parity with python-pptx. These exceptions exist because the SDK is a REST client (no local XML), or because LLM agents need ergonomic aliases for common patterns.
+
+---
+
+## REST SDK Limitations (python-pptx members that don't apply)
+
+These standard python-pptx members are omitted because a REST SDK has no access to the underlying XML or package structure:
+
+| Member | Reason |
+|--------|--------|
+| `Shape.element`, `Shape.part` | XML element access (no local XML) |
+| `TextFrame.part`, `Paragraph.part`, `Run.part` | Package part access |
+| `FillFormat.from_fill_parent()` | Internal constructor |
+| `ColorFormat.from_colorchoice_parent()` | Internal constructor |
+| `Font.fill` | Font fill format (not supported) |
+| `Font.language_id` | Not yet implemented |
+
+---
+
+## Agent-Friendly Additions (not in python-pptx)
+
+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.
+
+### `TableCell` — RGB tuple aliases
+
+| Property | Type | Maps to | Why |
+|----------|------|---------|-----|
+| `cell.font_bold` | `bool` | `cell.bold` | Agents write `cell.font_bold = True` instead of `cell.bold = True` |
+| `cell.font_color_rgb` | `tuple(R,G,B)` | `cell.font_color_hex` | Agents write `cell.font_color_rgb = (255, 255, 255)` instead of `cell.font_color_hex = "FFFFFF"` |
+| `cell.fill_color_rgb` | `tuple(R,G,B)` | `cell.fill` (hex) | Agents write `cell.fill_color_rgb = (31, 57, 100)` instead of `cell.fill = "1F3964"` |
+
+**Example of the agent pattern these support:**
+
+```python
+# LLM agents commonly generate this pattern:
+cell = tbl.cell(0, 0)
+cell.text = "Header"
+cell.font_size_pt = 14
+cell.font_bold = True
+cell.font_color_rgb = (255, 255, 255)
+cell.fill_color_rgb = (31, 57, 100)
+```
+
+### `GraphicFrame` — Table passthrough methods
+
+In python-pptx, `add_table()` returns a `GraphicFrame` and the table is accessed via `.table`. However, agents frequently call `.cell()`, `.rows`, `.cols` directly on the return value. These passthroughs prevent `AttributeError`:
+
+| Member | Delegates to |
+|--------|-------------|
+| `graphic_frame.cell(row, col)` | `graphic_frame.table.cell(row, col)` |
+| `graphic_frame.rows` | `graphic_frame.table.rows` |
+| `graphic_frame.cols` | `graphic_frame.table.cols` |
+
+**Example:**
+
+```python
+# Both patterns work:
+tbl = slide.shapes.add_table(rows=3, cols=3, ...)
+
+# Pattern 1: python-pptx canonical
+tbl.table.cell(0, 0).text = "Header"
+
+# Pattern 2: agent shortcut (also works)
+tbl.cell(0, 0).text = "Header"
+```
+
+---
+
+## Structural Deviations (python-pptx behavior differs)
+
+### `Table.first_row` / `Table.last_row` — Boolean look flags, not cell lists
+
+In python-pptx, `Table.first_row` and `Table.last_row` are boolean properties controlling table style look flags (whether the first/last row gets special styling).
+
+In a prior version of this SDK, these were cell-list properties returning `list[TableCell]`. They have been changed to match python-pptx (boolean). The old cell-list accessors are available as methods:
+
+| Old (removed) | New (python-pptx parity) | Cell-list replacement |
+|---------------|-------------------------|----------------------|
+| `table.first_row` → `list[TableCell]` | `table.first_row` → `bool` | `table.get_first_row_cells()` |
+| `table.last_row` → `list[TableCell]` | `table.last_row` → `bool` | `table.get_last_row_cells()` |
+| `table.first_column` → `list[TableCell]` | (not a python-pptx property) | `table.get_first_column_cells()` |
+| `table.last_column` → `list[TableCell]` | (not a python-pptx property) | `table.get_last_column_cells()` |
+
+### `Shapes.add_table()` — Returns `GraphicFrame`, not `Table`
+
+Changed to match python-pptx semantics. `add_table()` returns a `GraphicFrame`. Access the `Table` via `.table`. The passthrough methods above ensure backward compatibility for code that calls `.cell()` directly.
+
+### `_Row` / `_Column` with height/width setters
+
+python-pptx's `_Row.height` and `_Column.width` are read/write EMU properties. This SDK matches that API, but setting them also emits SDK commands (`SetRowHeight`, `SetColWidth`) to the server.
+
+### `Table.rows` / `Table.columns` — Return `_RowCollection` / `_ColumnCollection`
+
+In python-pptx, `Table.rows` returns a `_RowCollection` of `_Row` objects (each with `.height`). This SDK matches that. In a prior version, `Table.rows` returned a flat collection of cell lists.
+
+---
+
+## Non-Standard Convenience Methods (candidates for future cleanup)
+
+These exist on `TextFrame`, `Paragraph`, `Run`, `TableCell`, and `Table` but are NOT in python-pptx:
+
+- `to_dict()`, `word_count`, `capitalize()`, `upper()`, `lower()`, `title()`, `strip()`, `is_empty`
+- `Table.to_csv()`, `Table.to_list()`, `Table.to_dict_list()`, `Table.all_text`, `Table.contains_text()`, `Table.find_cells()`
+- `TableCell.address` (A1 notation), `TableCell.copy_from()`, `TableCell.clear()`
+
+These are convenience methods for agents and don't conflict with python-pptx API (python-pptx doesn't have them, so there's no behavioral difference).

{athena_python_pptx-0.1.51 → athena_python_pptx-0.1.54}/pptx/__init__.py

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

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

@@ -108,6 +108,9 @@ class Client:
         }
         if self.api_key:
             headers["Authorization"] = f"Bearer {self.api_key}"
+        custom_attr = os.environ.get("ATHENA_PPTX_CUSTOM_ATTRIBUTIONS")
+        if custom_attr:
+            headers["X-Custom-Attributions"] = custom_attr
         return headers
 
     def _handle_response(self, response: requests.Response) -> Any:
@@ -128,13 +131,17 @@ class Client:
                 # Extract message from top-level or nested error object
                 msg = data.get("message")
                 error_obj = data.get("error")
+                details = data.get("details")
                 if not msg and isinstance(error_obj, dict):
                     msg = error_obj.get("message")
-                    details = error_obj.get("details")
-                    if details:
-                        msg = f"{msg}: {details}"
+                    if not details:
+                        details = error_obj.get("details")
                 elif not msg and isinstance(error_obj, str):
                     msg = error_obj
+
+                detail_message = self._format_error_details(details)
+                if detail_message:
+                    msg = f"{msg or 'Request failed'}: {detail_message}"
                 raise RemoteError(
                     message=msg or f"API error: {response.status_code}",
                     status_code=response.status_code,
@@ -152,6 +159,42 @@ class Client:
 
         return response.json()
 
+    def _format_error_details(self, details: Any) -> Optional[str]:
+        """Convert structured API validation errors into actionable text."""
+        if not details:
+            return None
+
+        if isinstance(details, list):
+            rendered: list[str] = []
+            for item in details:
+                if not isinstance(item, dict):
+                    rendered.append(str(item))
+                    continue
+
+                path = ".".join(str(part) for part in item.get("path", []))
+                message = item.get("message") or "Invalid value"
+                received = item.get("received")
+
+                if path.endswith("shapeType") and isinstance(received, str):
+                    suggestion = self._suggest_shape_alias(received)
+                    if suggestion and suggestion != received:
+                        message = f"{message} (did you mean '{suggestion}'?)"
+
+                rendered.append(f"{path}: {message}" if path else message)
+
+            return "; ".join(rendered)
+
+        return str(details)
+
+    def _suggest_shape_alias(self, value: str) -> Optional[str]:
+        """Suggest the canonical backend shape name for common aliases."""
+        from .enum.shapes import mso_shape_to_string
+
+        try:
+            return mso_shape_to_string(value)
+        except Exception:
+            return None
+
     def _request(
         self,
         method: str,
@@ -465,7 +508,9 @@ class Client:
                     type=placeholder_data.get("type", "obj"),
                     idx=placeholder_data.get("idx", 0),
                     sz=placeholder_data.get("sz"),
+                    orient=placeholder_data.get("orient"),
                     has_custom_prompt=placeholder_data.get("hasCustomPrompt"),
+                    local_transform_override=placeholder_data.get("localTransformOverride"),
                 )
 
             elements[elem_id] = ElementSnapshot(

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

@@ -464,6 +464,9 @@ class SetTableCell(Command):
     col: int
     text: Optional[str] = None
     fill_color_hex: Optional[str] = None
+    font_size_centipoints: Optional[int] = None
+    bold: Optional[bool] = None
+    font_color_hex: Optional[str] = None
 
     @property
     def command_type(self) -> str:
@@ -507,6 +510,167 @@ class SetTableRowCount(Command):
             raise ValidationError("row_count must be at most 100", "row_count")
 
 
+@dataclass
+class MergeCells(Command):
+    """
+    Merge a rectangular region of cells in a table.
+
+    Args:
+        shape_id: ID of the table shape
+        start_row: Top-left row (0-based)
+        start_col: Top-left column (0-based)
+        end_row: Bottom-right row (0-based, inclusive)
+        end_col: Bottom-right column (0-based, inclusive)
+    """
+
+    shape_id: ShapeId
+    start_row: int
+    start_col: int
+    end_row: int
+    end_col: int
+
+    @property
+    def command_type(self) -> str:
+        return "MergeCells"
+
+    def validate(self) -> None:
+        if not self.shape_id:
+            raise ValidationError("shape_id is required", "shape_id")
+        if self.end_row < self.start_row or self.end_col < self.start_col:
+            raise ValidationError("end must be >= start", "end_row")
+
+
+@dataclass
+class SplitCell(Command):
+    """
+    Unmerge a previously merged cell region.
+
+    Args:
+        shape_id: ID of the table shape
+        row: Row of the merge-origin cell (0-based)
+        col: Column of the merge-origin cell (0-based)
+    """
+
+    shape_id: ShapeId
+    row: int
+    col: int
+
+    @property
+    def command_type(self) -> str:
+        return "SplitCell"
+
+    def validate(self) -> None:
+        if not self.shape_id:
+            raise ValidationError("shape_id is required", "shape_id")
+
+
+@dataclass
+class SetCellMargins(Command):
+    """
+    Set margins on a table cell.
+
+    Emits a SetCellTcPr command with margin values nested in tcPrPatch,
+    matching the backend's SetCellTcPrIntentSchema.
+
+    Args:
+        shape_id: ID of the table shape
+        row: Row index (0-based)
+        col: Column index (0-based)
+        mar_l_emu: Left margin in EMU (None to reset to default)
+        mar_r_emu: Right margin in EMU (None to reset to default)
+        mar_t_emu: Top margin in EMU (None to reset to default)
+        mar_b_emu: Bottom margin in EMU (None to reset to default)
+    """
+
+    shape_id: ShapeId
+    row: int
+    col: int
+    mar_l_emu: Optional[int] = None
+    mar_r_emu: Optional[int] = None
+    mar_t_emu: Optional[int] = None
+    mar_b_emu: Optional[int] = None
+
+    @property
+    def command_type(self) -> str:
+        return "SetCellTcPr"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize with tcPrPatch nesting expected by SetCellTcPrIntentSchema.
+
+        Always includes all margin keys — None values are serialized as null
+        so the backend can distinguish "reset to default" from "not specified".
+        """
+        tc_pr_patch: dict[str, Any] = {
+            "marL": self.mar_l_emu,
+            "marR": self.mar_r_emu,
+            "marT": self.mar_t_emu,
+            "marB": self.mar_b_emu,
+        }
+        return {
+            "type": self.command_type,
+            "shapeId": self.shape_id,
+            "row": self.row,
+            "col": self.col,
+            "tcPrPatch": tc_pr_patch,
+        }
+
+    def validate(self) -> None:
+        if not self.shape_id:
+            raise ValidationError("shape_id is required", "shape_id")
+
+
+@dataclass
+class SetColWidth(Command):
+    """
+    Set the width of a table column.
+
+    Args:
+        shape_id: ID of the table shape
+        col_index: Column index (0-based)
+        width_emu: Width in EMU
+    """
+
+    shape_id: ShapeId
+    col_index: int
+    width_emu: int
+
+    @property
+    def command_type(self) -> str:
+        return "SetColWidth"
+
+    def validate(self) -> None:
+        if not self.shape_id:
+            raise ValidationError("shape_id is required", "shape_id")
+        if self.width_emu < 0:
+            raise ValidationError("width_emu must be non-negative", "width_emu")
+
+
+@dataclass
+class SetRowHeight(Command):
+    """
+    Set the height of a table row.
+
+    Args:
+        shape_id: ID of the table shape
+        row_index: Row index (0-based)
+        height_emu: Height in EMU (0 = auto-fit)
+    """
+
+    shape_id: ShapeId
+    row_index: int
+    height_emu: int
+
+    @property
+    def command_type(self) -> str:
+        return "SetRowHeight"
+
+    def validate(self) -> None:
+        if not self.shape_id:
+            raise ValidationError("shape_id is required", "shape_id")
+        if self.height_emu < 0:
+            raise ValidationError("height_emu must be non-negative", "height_emu")
+
+
 @dataclass
 class SetSlideBackground(Command):
     """
@@ -1168,6 +1332,45 @@ class FitText(Command):
             )
 
 
+@dataclass
+class SubstitutePlaceholder(Command):
+    """
+    Substitute a placeholder shape with a picture, table, or chart.
+
+    Preserves the placeholder's semantic linkage (p:ph element in OOXML),
+    enabling correct layout reset and round-trip fidelity with PowerPoint.
+
+    Args:
+        shape_id: ID of the placeholder shape to substitute
+        kind: Kind of content ('picture', 'table', or 'chart')
+        image_base64: Base64-encoded image data (required for picture)
+        image_format: Image format ('png', 'jpeg', etc.) (required for picture)
+        rows: Number of rows (required for table)
+        cols: Number of columns (required for table)
+    """
+
+    shape_id: ShapeId
+    kind: str  # 'picture' | 'table' | 'chart'
+    image_base64: Optional[str] = None
+    image_format: Optional[str] = None
+    rows: Optional[int] = None
+    cols: Optional[int] = None
+
+    @property
+    def command_type(self) -> str:
+        return "SubstitutePlaceholder"
+
+    def validate(self) -> None:
+        if not self.shape_id:
+            raise ValidationError("shape_id is required", "shape_id")
+        if self.kind not in ('picture', 'table', 'chart'):
+            raise ValidationError("kind must be 'picture', 'table', or 'chart'", "kind")
+        if self.kind == 'picture' and (not self.image_base64 or not self.image_format):
+            raise ValidationError("image_base64 and image_format required for picture", "image_base64")
+        if self.kind == 'table' and (not self.rows or not self.cols):
+            raise ValidationError("rows and cols required for table", "rows")
+
+
 # Type alias for any command
 AnyCommand = Union[
     AddTextBox,
@@ -1207,4 +1410,5 @@ AnyCommand = Union[
     UngroupShapes,
     SetShapeAdjustments,
     FitText,
+    SubstitutePlaceholder,
 ]