athena-python-pptx 0.19.0__tar.gz → 0.20.0__tar.gz

{athena_python_pptx-0.19.0 → athena_python_pptx-0.20.0}/API_PARITY_REPORT.md

@@ -90,7 +90,7 @@ at an API, which the skill text and error messages can steer.
 | `Shape.margin_top` | set | <3 | <3 | <3 |
 | `Shape.vertical_anchor` | set | <3 | <3 | <3 |
 | `Shapes.clear_shapes` | call | <3 | <3 | <3 |
-| … 17 more | | | | |
+| … 15 more | | | | |
 
 Agent code also reached names neither the SDK nor python-pptx has (attributes it hung on SDK
 objects, made-up enum members) on `Client`, `MSO_SHAPE`, `Paragraph`, `Shape`, `SlideLayout`, `Slides`, `_ChartSeries`. The census

{athena_python_pptx-0.19.0 → athena_python_pptx-0.20.0}/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.20.0 — an older deck opens by its deck id
+
+- `Presentation(asset_id=...)` asks pptx-studio once, at open, for the id it
+  names the deck by (`GET /decks/by-asset/<asset id>/deck-id`, #46493). An older deck's
+  room, and every `/decks/...` route, name it by its deck id rather than its
+  asset id (#46319). Every snapshot, command, export and render then uses that
+  id, so code run against an older deck edits the deck instead of an empty
+  room.
+- `prs.asset_id` (and its `deck_id` alias) stays the id you passed, and tool
+  cards still name the asset.
+- Only a successful answer for this asset is used. Any other outcome keeps the
+  asset id, as every open did before, with one `pptx.client` log record: a
+  studio without the route, a refusal, an error or a timeout.
+- `copy_slide_from(source)` names an older source deck by its deck id too.
+- Needs a pptx-studio with `GET /decks/by-asset/:assetId/deck-id` (#46590) and agora's
+  lookup (#46588); against an older studio, nothing changes.
+
+## 0.20.0 — slides hide from the slide show, as PowerPoint's Hide Slide does
+
+- `slide.hidden = True` hides a slide from the slide show and keeps it in the
+  deck; the saved deck writes `<p:sld show="0">`. `slide.hidden = False` shows
+  it again. `slide.hidden` reads an uploaded slide's flag. Not in python-pptx:
+  `docs/API_PARITY_EXCEPTIONS.md`, "`Slide.hidden`".
+- Needs a studio with `SetSlideHidden`; an older one rejects the command.
+
 ## 0.19.0 — `Shapes.add_linked_chart()`: a chart whose data is a source range
 
 - `slide.shapes.add_linked_chart(chart_type, source, anchor, left=, top=,

{athena_python_pptx-0.19.0 → athena_python_pptx-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-pptx
-Version: 0.19.0
+Version: 0.20.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.19.0 → athena_python_pptx-0.20.0}/docs/API_PARITY_EXCEPTIONS.md

@@ -1415,6 +1415,18 @@ These edits apply to classic charts (authored or uploaded); Office 2016
 chartEx charts, such as waterfall and treemap, refuse them
 (`chartExEditsRefusal`).
 
+### `Slide.hidden` — PowerPoint's Hide Slide (Unreleased)
+
+python-pptx has no slide-level hidden flag. `slide.hidden = True` hides the
+slide from the slide show (`<p:sld show="0">` in the saved deck) and keeps it
+in the deck; `slide.hidden = False` shows it again. `slide.hidden` reads an
+uploaded slide's own flag, including the rare `<p:sldId show="0">` form. Sends
+`SetSlideHidden`; a studio that predates it rejects the command.
+
+```python
+prs.slides[2].hidden = True
+```
+
 ### `Font.cap` — PowerPoint-native capitalization mode
 
 The SDK exposes PowerPoint's OOXML run capitalization property as
@@ -2631,6 +2643,28 @@ per-element "Auto" option (off by default) re-read the range.
 `freshness_mode='office_live_link'` is not supported and raises `ValueError`
 locally.
 
+**From a semantic model:** pass the model's `AssetReference` and a
+`SemanticQueryAnchor` (from `athena_references`). The studio runs the query
+as the person the deck is written for, so the chart only shows numbers they
+may read: the first dimension (or the time dimension) is the categories and
+each measure a series. A refresh re-runs the query.
+
+```python
+from athena_references import SemanticQueryAnchor
+
+slide.shapes.add_linked_chart(
+    XL_CHART_TYPE.COLUMN_CLUSTERED,
+    AssetReference(id='asset_semantic_model_abc'),
+    SemanticQueryAnchor(query={
+        'measures': ['orders.revenue'],
+        'dimensions': ['orders.region'],
+        'limit': 20,
+    }),
+    left=Inches(1), top=Inches(1), width=Inches(6), height=Inches(4),
+)
+prs.flush()  # surfaces a refused query here, not at exit
+```
+
 ---
 
 ## Athena extensions for most-requested upstream features (v0.1.81)
@@ -3316,6 +3350,7 @@ python-pptx. Generated from `pptx._athena_extension.iter_athena_extensions()`.
 | `pptx.slides.Slide.apply_foreign_layout` | method | 0.1.82 |  | Slide.apply_foreign_layout — apply a layout from a different slide master. |
 | `pptx.slides.Slide.clear_shapes` | method | 0.1.78 |  | Delete every slide-local shape in one batched call |
 | `pptx.slides.Slide.clone` | method | 0.1.6 |  | Clone slide with all its content |
+| `pptx.slides.Slide.hidden` | property | Unreleased |  | Slide.hidden — PowerPoint's Hide Slide (p:sld@show). Not in python-pptx. |
 | `pptx.slides.Slide.remove_citation` | method | 0.1.0 |  | Slide.remove_citation — remove a citation from the deck by id. Not in python-pptx. |
 | `pptx.slides.Slide.render` | method | 0.1.5 |  | Render slide to PNG image |
 | `pptx.slides.Slide.validate` | method | 0.1.78 |  | Validate slide layout (text overflow, hidden text, collisions, off-slide shapes) |

{athena_python_pptx-0.19.0 → athena_python_pptx-0.20.0}/pptx/__init__.py

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

{athena_python_pptx-0.19.0 → athena_python_pptx-0.20.0}/pptx/batching.py

@@ -150,6 +150,7 @@ _NON_LAYOUT_COMMANDS: frozenset[str] = frozenset(
     {
         "SetSlideNotes",
         "SetSlideName",
+        "SetSlideHidden",
         "SetSlideBackground",
         "AddSlideCitation",
         "AddShapeCitation",
@@ -204,6 +205,7 @@ _LOCALLY_MIRRORED_COMMANDS: frozenset[str] = frozenset(
         "SetClickAction",
         "SetRunHyperlinkTarget",
         "SetSlideName",
+        "SetSlideHidden",
         "SetSlideNotes",
         "SetSlideBackground",
         "SetCoreProperties",
@@ -714,6 +716,8 @@ class CommandBuffer:
         auto_batch: bool = True,
         auto_flush_seconds: Optional[float] = 2.0,
         defer_commits: Optional[bool] = None,
+        *,
+        asset_id: Optional[str] = None,
     ):
         """
         Initialize the command buffer.
@@ -730,9 +734,13 @@ class CommandBuffer:
             defer_commits: Hold every buffered command until an explicit
                        flush (see the class docstring). ``None`` (default)
                        follows :func:`executor_mode_enabled`.
+            asset_id: The presentation's Athena asset id, which its tool
+                       cards name. Defaults to ``deck_id``; differs only for
+                       an older deck, whose pptx-studio id is its deck id.
         """
         self._client = client
         self._deck_id = deck_id
+        self._asset_id = asset_id or deck_id
         self._commands: list[AnyCommand] = []
         self._batch_depth = 0
         self._batch_start_index = 0
@@ -1141,7 +1149,7 @@ class CommandBuffer:
                 command._ptc_call_id = _ptc.emit_begin(  # type: ignore[attr-defined]
                     type(command).__name__,
                     command.to_dict(),
-                    asset_id=self._deck_id,
+                    asset_id=self._asset_id,
                 )
             except Exception:  # noqa: BLE001
                 pass

{athena_python_pptx-0.19.0 → athena_python_pptx-0.20.0}/pptx/client.py

@@ -14,6 +14,7 @@ import contextvars
 import hashlib
 import inspect
 import json as _json
+import logging
 import os
 import re
 import threading
@@ -39,6 +40,8 @@ from .errors import (
     RenderError,
     UploadError,
 )
+
+logger = logging.getLogger(__name__)
 from .typing import (
     CommandsResponse,
     DeckSnapshot,
@@ -1171,6 +1174,44 @@ class Client:
         attribution = os.environ.get("ATHENA_PPTX_CUSTOM_ATTRIBUTIONS") or ""
         return (self.base_url, deck_id, identity, attribution)
 
+    def resolve_deck_id(self, asset_id: str) -> str:
+        """The id pptx-studio names the deck of ``asset_id`` by, once per open.
+
+        An older deck's room, and every ``/decks/...`` route, name it by its
+        deck id, not its asset id (#46319, #46493). pptx-studio answers it at
+        ``GET /decks/by-asset/<asset id>/deck-id`` for a caller who may read the deck.
+        Only a successful answer for this asset is used; any failure (a studio
+        without the route, a refusal, an error, a timeout) keeps the asset id,
+        as every open did before, with one log line. The deck's own calls then
+        surface a real refusal as they always have, and an older deck named by
+        its asset id is refused loudly by pptx-studio rather than written to
+        the wrong room.
+        """
+        if not asset_id.startswith("asset_"):
+            return asset_id
+        path = f"/decks/by-asset/{asset_id}/deck-id"
+        try:
+            response = self._send("GET", path)
+            if response.status_code == 200:
+                data = response.json()
+                deck_id = data.get("deck_id") if isinstance(data, dict) else None
+                if (
+                    isinstance(deck_id, str)
+                    and deck_id
+                    and data.get("asset_id") == asset_id
+                ):
+                    return deck_id
+            reason = f"HTTP {response.status_code}"
+        except Exception as exc:  # noqa: BLE001 - never break an open over the lookup
+            reason = type(exc).__name__
+        logger.info(
+            "pptx: no deck id for %s from %s (%s); addressing it by its asset id",
+            asset_id,
+            path,
+            reason,
+        )
+        return asset_id
+
     def get_snapshot(self, deck_id: str) -> DeckSnapshot:
         """Get the current state snapshot of a deck.
 
@@ -1297,6 +1338,7 @@ class Client:
                     inherited_element_ids=slide_data.get("inheritedElementIds", []),
                     name=slide_data.get("name") if isinstance(slide_data.get("name"), str) else None,
                     background_image_asset_id=slide_data.get("backgroundImageAssetId"),
+                    hidden=slide_data.get("isHidden") is True,
                 )
             )
 

{athena_python_pptx-0.19.0 → athena_python_pptx-0.20.0}/pptx/commands.py

@@ -2371,6 +2371,30 @@ class SetSlideName(Command):
             raise ValidationError("name must be a string", "name")
 
 
+
+@dataclass
+class SetSlideHidden(Command):
+    """
+    Hide a slide from the slide show, or show it again (``p:sld@show``).
+
+    Args:
+        slide_index: Zero-based index of the slide
+        hidden: True hides the slide; False shows it again
+    """
+
+    slide_index: int
+    hidden: bool
+
+    @property
+    def command_type(self) -> str:
+        return "SetSlideHidden"
+
+    def validate(self) -> None:
+        if self.slide_index < 0:
+            raise ValidationError("slide_index must be non-negative", "slide_index")
+        if not isinstance(self.hidden, bool):
+            raise ValidationError("hidden must be a bool", "hidden")
+
 @dataclass
 class SetClickAction(Command):
     """
@@ -3818,6 +3842,7 @@ AnyCommand = Union[
     SetCoreProperties,
     SetShapeName,
     SetSlideName,
+    SetSlideHidden,
     SetClickAction,
     SetPresentationSize,
     # Phase 5

{athena_python_pptx-0.19.0 → athena_python_pptx-0.20.0}/pptx/presentation.py

@@ -287,6 +287,18 @@ def _release_opened_slides(prs: Any) -> None:
         slides._release_opened_slides()
 
 
+
+def _pptx_deck_id(client: Any, asset_id: str) -> str:
+    """The id pptx-studio names the deck of ``asset_id`` by (#46493).
+
+    Only an ``asset_`` id is looked up (a legacy ``deck_`` id is the studio's
+    own); anything but a non-empty answer keeps the id the caller passed.
+    """
+    if not asset_id.startswith("asset_"):
+        return asset_id
+    resolved = client.resolve_deck_id(asset_id)
+    return resolved if isinstance(resolved, str) and resolved else asset_id
+
 class Presentation:
     """
     Presentation proxy - the main entry point for working with a deck.
@@ -376,9 +388,14 @@ class Presentation:
                 f"Presentation.create(name={resolved_id!r}) and reuse "
                 f"`prs.deck_id` on subsequent calls in the same conversation."
             )
-        self._deck_id = resolved_id
+        # ``asset_id`` (and its ``deck_id`` alias) stays the id the caller
+        # passed. pptx-studio names an older deck by its deck id instead
+        # (#46319): every ``/decks/...`` call uses ``_deck_id``, resolved once
+        # here, and the asset id wherever no lookup answers it (#46493).
+        self._asset_id = resolved_id
         self._client = Client(base_url=base_url, api_key=api_key)
-        self._buffer = CommandBuffer(self._client, resolved_id)
+        self._deck_id = _pptx_deck_id(self._client, resolved_id)
+        self._buffer = CommandBuffer(self._client, self._deck_id, asset_id=resolved_id)
         self._buffer.set_discard_listener(self._on_commands_discarded)
         self._snapshot: Optional[DeckSnapshot] = None
         self._slides: Optional[Slides] = None
@@ -953,8 +970,8 @@ class Presentation:
         description="Presentation.deck_id — Athena asset id.",
     )
     def deck_id(self) -> DeckId:
-        """ID of the deck."""
-        return self._deck_id
+        """ID of the deck: its Athena asset id, as :attr:`asset_id`."""
+        return self._asset_id
 
     @property
     @athena_extension(
@@ -971,7 +988,7 @@ class Presentation:
         keyword. Athena-only ergonomic addition — not in upstream
         python-pptx.
         """
-        return self._deck_id
+        return self._asset_id
 
     def _on_commands_discarded(self, created_ids: set[str]) -> None:
         """Commands were dropped unsent (a failed run's ``discard_all``, a
@@ -1196,11 +1213,13 @@ class Presentation:
             prs_out.copy_slide_from(prs_in, source_slide_index=5)
             prs_out.save()
         """
+        # pptx-studio names the source by its own pptx-studio id: an older
+        # deck's deck id, not its asset id (#46493).
         if isinstance(source, str):
-            source_deck_id = source
+            source_deck_id = _pptx_deck_id(self._client, source)
         else:
             source.flush()  # land any pending edits in the source.
-            source_deck_id = source.deck_id
+            source_deck_id = source._deck_id
         if source_slide_index < 0:
             raise ValueError("source_slide_index must be >= 0")
         if destination_index < -1:
@@ -1834,7 +1853,7 @@ class Presentation:
             Dictionary with presentation metadata and content
         """
         return {
-            "deck_id": self._deck_id,
+            "deck_id": self._asset_id,
             "name": self.name,
             "slide_count": len(self.slides),
             "slide_width_emu": int(self.slide_width),
@@ -2233,4 +2252,4 @@ class Presentation:
 
     def __repr__(self) -> str:
         slide_count = len(self._slides) if self._slides else "?"
-        return f"<Presentation deck_id='{self._deck_id}' slides={slide_count}>"
+        return f"<Presentation deck_id='{self._asset_id}' slides={slide_count}>"

{athena_python_pptx-0.19.0 → athena_python_pptx-0.20.0}/pptx/slides.py

@@ -18,7 +18,7 @@ if TYPE_CHECKING:
     from .enum.dml import MSO_FILL_TYPE
     from .shapes import Shape
 
-from .commands import AddSlide, DeleteSlide, SetSlideBackground, SetSlideNotes, CloneSlide, SetSlideName, SetSlideLayout, MeasureTextFit
+from .commands import AddSlide, DeleteSlide, SetSlideBackground, SetSlideNotes, CloneSlide, SetSlideName, SetSlideHidden, SetSlideLayout, MeasureTextFit
 from .decorators import athena_only
 from .errors import ConflictError, UnsupportedFeatureError, ValidationError
 from .oxml.presentation import CT_SlideIdList
@@ -2354,6 +2354,7 @@ class Slide:
         layout_path: Optional[str] = None,
         name: Optional[str] = None,
         background_image_asset_id: Optional[str] = None,
+        hidden: bool = False,
     ):
         self._presentation = presentation
         self._slide_id = slide_id
@@ -2364,6 +2365,7 @@ class Slide:
         self._background_image_asset_id = background_image_asset_id
         self._notes = notes
         self._name = name or ""
+        self._hidden = hidden
 
         # Layout tracking
         self._layout_index = layout_index
@@ -3225,6 +3227,34 @@ class Slide:
             cmd = SetSlideName(slide_index=self._slide_index, name=self._name)
             self._buffer.add(cmd)
 
+    @property
+    @athena_only(
+        description="Slide.hidden — PowerPoint's Hide Slide (p:sld@show). Not in python-pptx.",
+        since="Unreleased",
+    )
+    def hidden(self) -> bool:
+        """True when the slide is hidden from the slide show (``p:sld@show="0"``).
+
+        A hidden slide stays in the deck; PowerPoint skips it when presenting.
+
+        Example:
+            slide.hidden = True
+
+        Note (Athena extension):
+            This property is NOT part of python-pptx. See
+            ``docs/API_PARITY_EXCEPTIONS.md`` for the deviation rationale.
+        """
+        return self._hidden
+
+    @hidden.setter
+    def hidden(self, value: bool) -> None:
+        """Hide the slide from the slide show, or show it again."""
+        if not isinstance(value, bool):
+            raise ValidationError("hidden must be a bool", "hidden")
+        self._hidden = value
+        if self._buffer:
+            self._buffer.add(SetSlideHidden(slide_index=self._slide_index, hidden=value))
+
     # -------------------------------------------------------------------------
     # Convenience properties and methods
     # -------------------------------------------------------------------------
@@ -3694,6 +3724,7 @@ class Slide:
             layout_path=slide_snapshot.layout_path,
             name=slide_snapshot.name,
             background_image_asset_id=slide_snapshot.background_image_asset_id,
+            hidden=slide_snapshot.hidden,
         )
 
     def _adopt_prepared_snapshot(self, *, prepared: Slide) -> None:
@@ -3716,6 +3747,7 @@ class Slide:
         self._background = None
         self._notes = prepared._notes
         self._name = prepared._name
+        self._hidden = prepared._hidden
         self._layout_index = prepared._layout_index
         self._layout_name = prepared._layout_name
         self._layout_path = prepared._layout_path

{athena_python_pptx-0.19.0 → athena_python_pptx-0.20.0}/pptx/typing.py

@@ -178,6 +178,8 @@ class SlideSnapshot:
     name: Optional[str] = None
     # The slide's own ``<p:bg>`` picture fill (python-pptx: not a shape).
     background_image_asset_id: Optional[str] = None
+    # PowerPoint's Hide Slide (``p:sld@show="0"``); False when the server predates it.
+    hidden: bool = False
 
 
 @dataclass

{athena_python_pptx-0.19.0 → athena_python_pptx-0.20.0}/pyproject.toml

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