athena-python-pptx 0.1.62__tar.gz → 0.1.63__tar.gz

{athena_python_pptx-0.1.62 → athena_python_pptx-0.1.63}/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.1.63
+
+Theme-hierarchy parity round (originally targeted 0.1.62, but PyPI's 0.1.62
+was claimed by an unrelated upload on 2026-05-06 — bumped to 0.1.63 to keep
+the SDK and PyPI sequence in step). — closes the remaining python-pptx surface gaps
+on `Presentation`, `SlideMaster`, `SlideLayout`, `Slides`, and `SlideShapes`
+that the parity test was allow-listing as KNOWN_MISSING.
+
+- **`Presentation.slide_master`** — shorthand for `slide_masters[0]`. Matches
+  python-pptx where most single-master decks reach for the canonical master
+  via this attribute. Raises `IndexError` if the snapshot has no masters.
+- **`SlideMaster.shapes`** / **`SlideMaster.placeholders`** — return empty
+  read-only collections instead of raising `AttributeError`. The REST snapshot
+  doesn't materialize master-level shapes as first-class elements (they are
+  projected onto each slide during ingestion), but code that probes these
+  collections for parity now gets a sensible empty result.
+- **`SlideLayout.shapes`** — same treatment as the master-level collection.
+- **`SlideLayout.slide_master`** — backreference to the parent
+  `SlideMaster`. `_build_slide_masters` now threads the master onto each
+  child layout when constructing the theme hierarchy, and the backreference
+  is `None` only on the legacy hardcoded fallback layouts (used when no
+  snapshot is available).
+- **`Slides.get(slide_id, default=None)`** — matches python-pptx's
+  dict-style lookup. Same backing store as `Slides.get_by_id`, with the
+  added optional default-return semantics.
+- **`SlideShapes.add_group_shape(shapes=())`** — alias that materializes any
+  iterable to a list and forwards to `group_shapes(...)`. Consistent with
+  python-pptx's signature; the SDK still requires at least 2 shapes per
+  group (one `GroupShapes` command per call).
+- **Parity test cleanup** — `tests/test_python_pptx_api_parity.py` no longer
+  allow-lists the items above under `KNOWN_MISSING`. Type mismatches for the
+  new `@property` accessors are documented in `KNOWN_TYPE_MISMATCHES`
+  (functionally identical to python-pptx's `lazyproperty`).
+
 ## 0.1.61
 
 Parity round: structural module shims + python-pptx-aligned signatures.

{athena_python_pptx-0.1.62 → athena_python_pptx-0.1.63}/PKG-INFO

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

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

{athena_python_pptx-0.1.62 → athena_python_pptx-0.1.63}/pptx/presentation.py

@@ -513,6 +513,16 @@ class Presentation:
         from .slides import _build_slide_masters
         return _build_slide_masters(self)
 
+    @property
+    def slide_master(self):
+        """The first :class:`SlideMaster` (python-pptx parity).
+
+        Stock python-pptx exposes ``Presentation.slide_master`` as a shortcut
+        for ``slide_masters[0]``. Raises ``IndexError`` if the deck has no
+        masters in its snapshot.
+        """
+        return self.slide_masters[0]
+
     def reorder_slides(self, new_order: list[int]) -> None:
         """
         Reorder slides in the presentation.

{athena_python_pptx-0.1.62 → athena_python_pptx-0.1.63}/pptx/shapes.py

@@ -3915,6 +3915,17 @@ class Shapes:
     # Phase 5: Grouping
     # -------------------------------------------------------------------------
 
+    def add_group_shape(self, shapes=()) -> Shape:
+        """Return a group shape containing ``shapes`` (python-pptx parity).
+
+        Stock python-pptx accepts any iterable of shapes, including an empty
+        one (in which case the group is created and shapes can be added to
+        its child tree later). The REST SDK requires at least two shapes
+        because group creation is a single ``GroupShapes`` command — passing
+        fewer than two raises ``ValueError`` to match :meth:`group_shapes`.
+        """
+        return self.group_shapes(list(shapes))
+
     def group_shapes(self, shapes: list[Shape]) -> Shape:
         """
         Group multiple shapes together into a single group shape.
@@ -4652,11 +4663,19 @@ class _TableCellParagraph:
     the existing per-cell style (``_bold/_font_size_pt/_font_color_hex``).
     Fine for the common header-row formatting use case; richer cells
     will need a real ``<a:txBody>`` model on the server side.
+
+    For API parity with python-pptx, ``add_run()`` and ``clear()`` are
+    supported but operate on the single underlying run — multiple
+    ``add_run()`` calls return the *same* ``_TableCellRun`` object, and
+    only the last text/style assignment wins. ``alignment`` is accepted
+    for compatibility but doesn't yet round-trip to OOXML (no per-cell
+    paragraph-alignment command on the applier).
     """
 
     def __init__(self, cell: "TableCell"):
         self._cell = cell
         self._runs = [_TableCellRun(cell)]
+        self._alignment: Optional[Any] = None
 
     @property
     def runs(self) -> list[_TableCellRun]:
@@ -4670,6 +4689,29 @@ class _TableCellParagraph:
     def text(self, value: str) -> None:
         self._cell.text = value
 
+    @property
+    def alignment(self) -> Optional[Any]:
+        return self._alignment
+
+    @alignment.setter
+    def alignment(self, value: Any) -> None:
+        # Accepted for python-pptx parity; not yet round-tripped to OOXML.
+        self._alignment = value
+
+    def add_run(self) -> _TableCellRun:
+        """Return the single underlying run.
+
+        python-pptx semantics create a new ``_Run`` per call. The cell
+        text-frame shim only supports one run per cell, so every call
+        returns the same ``_TableCellRun`` — text / font assignments on
+        the returned run apply to the cell's existing style fields.
+        """
+        return self._runs[0]
+
+    def clear(self) -> None:
+        """Reset the cell text to empty (compatibility with python-pptx)."""
+        self._cell.text = ""
+
 
 class _TableCellTextFrame:
     """``TextFrame`` adapter for a table cell.
@@ -4677,6 +4719,10 @@ class _TableCellTextFrame:
     Real python-pptx returns a full TextFrame here; we expose a single
     paragraph with a single run so the common ``cell.text_frame.
     paragraphs[0].runs[0].font.bold = True`` recipe works.
+
+    ``add_paragraph()`` returns the same single underlying paragraph for
+    API parity, since the cell shim only supports one paragraph.
+    ``clear()`` empties the cell text.
     """
 
     def __init__(self, cell: "TableCell"):
@@ -4695,6 +4741,14 @@ class _TableCellTextFrame:
     def text(self, value: str) -> None:
         self._cell.text = value
 
+    def add_paragraph(self) -> _TableCellParagraph:
+        """Return the single underlying paragraph (cell shim is single-paragraph)."""
+        return self._paragraphs[0]
+
+    def clear(self) -> None:
+        """Reset the cell text to empty."""
+        self._cell.text = ""
+
 
 class TableCell:
     """

{athena_python_pptx-0.1.62 → athena_python_pptx-0.1.63}/pptx/slides.py

@@ -1179,6 +1179,18 @@ class Slides:
         """Get slide by ID."""
         return self._slides_by_id.get(slide_id)
 
+    def get(
+        self,
+        slide_id: SlideId,
+        default: Optional[Slide] = None,
+    ) -> Optional[Slide]:
+        """Return the slide identified by ``slide_id`` (python-pptx parity).
+
+        Returns ``default`` when no slide matches. Mirrors stock python-pptx's
+        ``Slides.get(slide_id, default=None)``.
+        """
+        return self._slides_by_id.get(slide_id, default)
+
     # -------------------------------------------------------------------------
     # Convenience properties and methods
     # -------------------------------------------------------------------------
@@ -1784,6 +1796,39 @@ class Slides:
         return f"<Slides count={len(self._slides)}>"
 
 
+class _ReadOnlyShapeCollection:
+    """Empty read-only shape collection for layout/master proxies.
+
+    python-pptx exposes ``slide_layout.shapes`` and ``slide_master.shapes`` as
+    iterable shape collections. The REST snapshot doesn't materialize layout-
+    or master-level shapes as first-class entities, so we surface a
+    consistently-typed empty collection rather than raising ``AttributeError``.
+    Callers that need slide-level shapes should use ``slide.shapes`` instead.
+    """
+
+    def __len__(self) -> int:
+        return 0
+
+    def __iter__(self):
+        return iter(())
+
+    def __getitem__(self, key):
+        raise IndexError("layout/master shapes are not materialized in the REST snapshot")
+
+
+class _ReadOnlyPlaceholderCollection:
+    """Empty read-only placeholder collection for layout/master proxies."""
+
+    def __len__(self) -> int:
+        return 0
+
+    def __iter__(self):
+        return iter(())
+
+    def __getitem__(self, key):
+        raise KeyError(f"No placeholder with idx={key}")
+
+
 class SlideLayout:
     """
     Slide layout template.
@@ -1824,6 +1869,7 @@ class SlideLayout:
         slide: Optional["Slide"] = None,
         presentation: Optional["Presentation"] = None,
         path: Optional[str] = None,
+        slide_master: Optional["SlideMaster"] = None,
     ):
         self._index = index
         self._name = name
@@ -1836,6 +1882,7 @@ class SlideLayout:
         # `<p:sldLayoutIdLst>` and generally does NOT match the file-name
         # numbering the server otherwise falls back to.
         self._path = path
+        self._slide_master_ref: Optional["SlideMaster"] = slide_master
 
     @property
     def index(self) -> int:
@@ -1898,6 +1945,28 @@ class SlideLayout:
 
         return SlidePlaceholders({})
 
+    @property
+    def shapes(self) -> "_ReadOnlyShapeCollection":
+        """Layout-level shapes (python-pptx parity).
+
+        The REST snapshot does not materialize layout shapes as first-class
+        elements (they are merged into each slide's inherited content during
+        ingestion), so this returns an empty read-only collection. Callers
+        that need to introspect what a layout contributes should iterate
+        ``slide.shapes`` on a slide using the layout instead.
+        """
+        return _ReadOnlyShapeCollection()
+
+    @property
+    def slide_master(self) -> Optional["SlideMaster"]:
+        """The :class:`SlideMaster` this layout belongs to.
+
+        Returns ``None`` if the layout was constructed without a master
+        reference (e.g., from the legacy hardcoded fallback set used when no
+        snapshot is available).
+        """
+        return self._slide_master_ref
+
 
 class SlideLayouts:
     """Collection of slide layouts.
@@ -2028,10 +2097,12 @@ class _MasterSlideLayouts:
 class SlideMaster:
     """A single slide master in the presentation (read-only proxy).
 
-    Provides python-pptx-compatible access to ``name`` and ``slide_layouts``.
-    Shape and placeholder collections on the master itself are not yet
-    materialized via the REST snapshot, so ``shapes`` / ``placeholders`` are
-    intentionally not implemented here.
+    Provides python-pptx-compatible access to ``name``, ``slide_layouts``,
+    ``shapes``, and ``placeholders``. Master-level shapes and placeholders
+    are not materialized as first-class elements in the REST snapshot
+    (they are projected onto each slide during ingestion), so ``shapes``
+    and ``placeholders`` return empty read-only collections rather than
+    raising ``AttributeError``.
     """
 
     def __init__(
@@ -2053,6 +2124,16 @@ class SlideMaster:
     def slide_layouts(self) -> _MasterSlideLayouts:
         return self._slide_layouts
 
+    @property
+    def shapes(self) -> _ReadOnlyShapeCollection:
+        """Master-level shapes (python-pptx parity, empty in REST snapshot)."""
+        return _ReadOnlyShapeCollection()
+
+    @property
+    def placeholders(self) -> _ReadOnlyPlaceholderCollection:
+        """Master-level placeholders (python-pptx parity, empty in REST snapshot)."""
+        return _ReadOnlyPlaceholderCollection()
+
     def __repr__(self) -> str:
         return f"<SlideMaster name='{self._name}' layouts={len(self._slide_layouts)}>"
 
@@ -2112,14 +2193,17 @@ def _build_slide_masters(presentation: "Presentation") -> SlideMasters:
                     index=global_index,
                     name=layout_meta.name,
                     presentation=presentation,
+                    path=layout_meta.path,
                 )
             )
             global_index += 1
-        masters.append(
-            SlideMaster(
-                path=master_data.path,
-                name=master_data.name,
-                layouts=master_layouts,
-            )
+        master = SlideMaster(
+            path=master_data.path,
+            name=master_data.name,
+            layouts=master_layouts,
         )
+        # Backreference layout → master so SlideLayout.slide_master works.
+        for layout in master_layouts:
+            layout._slide_master_ref = master
+        masters.append(master)
     return SlideMasters(masters)

{athena_python_pptx-0.1.62 → athena_python_pptx-0.1.63}/pyproject.toml

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