athena-python-pptx 0.4.1__tar.gz → 0.4.2__tar.gz

{athena_python_pptx-0.4.1 → athena_python_pptx-0.4.2}/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.4.2
+
+**Paragraph-level font fidelity — `paragraph.font` now matches stock
+python-pptx `defRPr` semantics (fidelity-pipeline findings batch).**
+
+- **`paragraph.font` is a real paragraph-level font.** Previously it
+  returned the first run's font ("approximate by targeting the first
+  run"), which (a) produced exports with explicit `<a:rPr>` on every run
+  where stock python-pptx writes `<a:pPr><a:defRPr/>` (the fidelity
+  pipeline's sdk-projection leg counted 229 structural diffs on the
+  25-slide diagnostic deck) and (b) mis-styled multi-run paragraphs (only
+  run 0 changed, where stock applies the default to ALL runs). Writes now
+  emit `SetParagraphStyle` with a `defaultRunStyle` payload; the studio
+  stores it as the paragraph's authored defaults and exports `defRPr`
+  exactly like stock.
+- **`run.font.color.brightness` now round-trips.** Previously stored
+  locally and silently dropped; now emitted with the theme color and
+  serialized as `lumMod`/`lumOff` modifiers on `<a:schemeClr>` using
+  python-pptx's mapping.
+- Studio-side (same batch): theme color references (`schemeColor`) now
+  survive on SDK-created textbox runs, and new paragraphs added via
+  `add_paragraph()`/multi-line `tf.text` no longer inherit the previous
+  paragraph's authored level/spacing/alignment (server-side paragraph
+  template bleed).
+
 ## 0.3.1
 
 **Chart title runs, slide insertion, and shape-delete local state — Insight

{athena_python_pptx-0.4.1 → athena_python_pptx-0.4.2}/CLAUDE.md

@@ -45,8 +45,9 @@ A small number of REST-SDK-specific departures are documented in
 [`docs/API_PARITY_EXCEPTIONS.md`](docs/API_PARITY_EXCEPTIONS.md):
 
 - **`Presentation(filename)` not supported** — REST SDK uses
-  `Presentation.upload(path)` or `Presentation(deck_id=…)` instead;
-  there's no local OPC package to open.
+  `Presentation.upload(path)` or `Presentation(asset_id=…)` instead
+  (`deck_id=` is the accepted legacy alias); there's no local OPC
+  package to open.
 - **`NotesSlide.shapes` / `.placeholders` / `.notes_placeholder`** not yet exposed —
   use `slide.notes_slide.notes_text_frame` for notes text.
 - **`XyChartData.add_series(name, values)`** signature drift vs upstream's

{athena_python_pptx-0.4.1 → athena_python_pptx-0.4.2}/DEV-GUIDE.md

@@ -23,9 +23,9 @@ Create `scratch.py` in the `python-sdk/` directory:
 ```python
 from pptx import Presentation
 
-# Upload a test file or use an existing deck ID
+# Upload a test file or use an existing asset id
 prs = Presentation.upload("path/to/test.pptx", name="test")
-print(f"Deck: {prs.deck_id}, Slides: {prs.slide_count}")
+print(f"Presentation: {prs.asset_id}, Slides: {prs.slide_count}")
 
 slide = prs.slides[0]
 for shape in slide.shapes:
@@ -100,5 +100,5 @@ The SDK is a **remote proxy** over the PPTX Studio API:
 | Method | Example |
 |--------|---------|
 | Env vars | `ATHENA_PPTX_BASE_URL=http://localhost:4000` |
-| Explicit | `Presentation(deck_id, base_url="http://localhost:4000")` |
+| Explicit | `Presentation(asset_id="asset_...", base_url="http://localhost:4000")` (`deck_id=` is the legacy alias) |
 | API key (optional) | `ATHENA_PPTX_API_KEY=your-key` |

{athena_python_pptx-0.4.1 → athena_python_pptx-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-pptx
-Version: 0.4.1
+Version: 0.4.2
 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
@@ -202,7 +202,7 @@ export ATHENA_PPTX_API_KEY=your-api-key  # Optional
 Or pass them explicitly:
 
 ```python
-prs = Presentation(deck_id="deck_123", base_url="...", api_key="...")
+prs = Presentation(asset_id="asset_3a9328bc-9c1c-4498-be8f-bda3883276f5", base_url="...", api_key="...")
 ```
 
 ## Quick Start
@@ -246,24 +246,27 @@ slide.shapes[0].text_frame.text = "Updated Title"
 prs.save("modified.pptx")
 ```
 
-### Connect to an Existing Deck
+### Connect to an Existing Presentation
 
 ```python
 from pptx import Presentation
 
-# Connect to a deck by ID
-prs = Presentation(deck_id="deck_abc123")
+# Connect to a presentation by its Athena asset id
+prs = Presentation(asset_id="asset_3a9328bc-9c1c-4498-be8f-bda3883276f5")
 
 # Work with slides
 for slide in prs.slides:
     print(f"Slide {slide.slide_index}: {len(slide.shapes)} shapes")
 ```
 
-> **Important:** When working with an existing deck, you **MUST** include the `deck_id` parameter:
+`deck_id=` is accepted as a legacy alias for `asset_id=` (it is the same
+identifier string); prefer `asset_id=` in new code.
+
+> **Important:** When working with an existing presentation, you **MUST** include the `asset_id` parameter:
 > ```python
-> prs = Presentation(deck_id="d822b6e3-0a73-4214-9e71-8f28a3f7c9d9")
+> prs = Presentation(asset_id="asset_d822b6e3-0a73-4214-9e71-8f28a3f7c9d9")
 > ```
-> Without `deck_id`, the SDK cannot connect to PPTX Studio and will fail.
+> Without `asset_id`, the SDK cannot connect to PPTX Studio and will fail.
 
 ---
 
@@ -271,7 +274,7 @@ for slide in prs.slides:
 
 ### Presentation
 
-The main entry point for working with a deck.
+The main entry point for working with a presentation.
 
 #### Class Methods
 
@@ -286,14 +289,14 @@ prs = Presentation.open("path/to/file.pptx")  # Alias for upload()
 # Connect from a full URL
 prs = Presentation.from_url("https://api.example.com/decks/deck_123")
 
-# Connect to an existing deck by ID
-prs = Presentation(deck_id="deck_123")
+# Connect to an existing presentation by asset id
+prs = Presentation(asset_id="asset_3a9328bc-9c1c-4498-be8f-bda3883276f5")
 ```
 
 #### Properties
 
 ```python
-prs.deck_id         # str: Deck identifier
+prs.asset_id        # str: Athena asset id (prs.deck_id is the legacy alias)
 prs.slides          # Slides: Collection of slides
 prs.slide_width     # Emu: Width of slides
 prs.slide_height    # Emu: Height of slides
@@ -889,7 +892,7 @@ print(info['authToken'])
 
 See [`docs/API_PARITY_EXCEPTIONS.md`](docs/API_PARITY_EXCEPTIONS.md) for the full list. Highlights:
 
-- **`Presentation(filename)` not supported** — use `Presentation.upload(path)` or `Presentation(deck_id=…)` instead.
+- **`Presentation(filename)` not supported** — use `Presentation.upload(path)` or `Presentation(asset_id=…)` instead (`deck_id=` is the legacy alias).
 - **`NotesSlide.shapes` / `.placeholders` / `.notes_placeholder`** not yet exposed — use `slide.notes_slide.notes_text_frame` for text.
 - **`XyChartData.add_series(name, values)`** signature drift vs upstream's `add_series(name, number_format=None)`.
 - **`TextFitter.best_fit_font_size()`** returns `max_size` unchanged (auto-fit is server-side).

{athena_python_pptx-0.4.1 → athena_python_pptx-0.4.2}/README.md

@@ -162,7 +162,7 @@ export ATHENA_PPTX_API_KEY=your-api-key  # Optional
 Or pass them explicitly:
 
 ```python
-prs = Presentation(deck_id="deck_123", base_url="...", api_key="...")
+prs = Presentation(asset_id="asset_3a9328bc-9c1c-4498-be8f-bda3883276f5", base_url="...", api_key="...")
 ```
 
 ## Quick Start
@@ -206,24 +206,27 @@ slide.shapes[0].text_frame.text = "Updated Title"
 prs.save("modified.pptx")
 ```
 
-### Connect to an Existing Deck
+### Connect to an Existing Presentation
 
 ```python
 from pptx import Presentation
 
-# Connect to a deck by ID
-prs = Presentation(deck_id="deck_abc123")
+# Connect to a presentation by its Athena asset id
+prs = Presentation(asset_id="asset_3a9328bc-9c1c-4498-be8f-bda3883276f5")
 
 # Work with slides
 for slide in prs.slides:
     print(f"Slide {slide.slide_index}: {len(slide.shapes)} shapes")
 ```
 
-> **Important:** When working with an existing deck, you **MUST** include the `deck_id` parameter:
+`deck_id=` is accepted as a legacy alias for `asset_id=` (it is the same
+identifier string); prefer `asset_id=` in new code.
+
+> **Important:** When working with an existing presentation, you **MUST** include the `asset_id` parameter:
 > ```python
-> prs = Presentation(deck_id="d822b6e3-0a73-4214-9e71-8f28a3f7c9d9")
+> prs = Presentation(asset_id="asset_d822b6e3-0a73-4214-9e71-8f28a3f7c9d9")
 > ```
-> Without `deck_id`, the SDK cannot connect to PPTX Studio and will fail.
+> Without `asset_id`, the SDK cannot connect to PPTX Studio and will fail.
 
 ---
 
@@ -231,7 +234,7 @@ for slide in prs.slides:
 
 ### Presentation
 
-The main entry point for working with a deck.
+The main entry point for working with a presentation.
 
 #### Class Methods
 
@@ -246,14 +249,14 @@ prs = Presentation.open("path/to/file.pptx")  # Alias for upload()
 # Connect from a full URL
 prs = Presentation.from_url("https://api.example.com/decks/deck_123")
 
-# Connect to an existing deck by ID
-prs = Presentation(deck_id="deck_123")
+# Connect to an existing presentation by asset id
+prs = Presentation(asset_id="asset_3a9328bc-9c1c-4498-be8f-bda3883276f5")
 ```
 
 #### Properties
 
 ```python
-prs.deck_id         # str: Deck identifier
+prs.asset_id        # str: Athena asset id (prs.deck_id is the legacy alias)
 prs.slides          # Slides: Collection of slides
 prs.slide_width     # Emu: Width of slides
 prs.slide_height    # Emu: Height of slides
@@ -849,7 +852,7 @@ print(info['authToken'])
 
 See [`docs/API_PARITY_EXCEPTIONS.md`](docs/API_PARITY_EXCEPTIONS.md) for the full list. Highlights:
 
-- **`Presentation(filename)` not supported** — use `Presentation.upload(path)` or `Presentation(deck_id=…)` instead.
+- **`Presentation(filename)` not supported** — use `Presentation.upload(path)` or `Presentation(asset_id=…)` instead (`deck_id=` is the legacy alias).
 - **`NotesSlide.shapes` / `.placeholders` / `.notes_placeholder`** not yet exposed — use `slide.notes_slide.notes_text_frame` for text.
 - **`XyChartData.add_series(name, values)`** signature drift vs upstream's `add_series(name, number_format=None)`.
 - **`TextFitter.best_fit_font_size()`** returns `max_size` unchanged (auto-fit is server-side).

{athena_python_pptx-0.4.1 → athena_python_pptx-0.4.2}/docs/API_PARITY_EXCEPTIONS.md

@@ -746,18 +746,35 @@ Athena-only. Equivalent to calling `prs.set_slide_size(Emu(14630400),
 Emu(8229600))` immediately after creation. For non-standard sizes call
 `prs.set_slide_size(width, height)` after `create()`.
 
-### `Presentation.asset_id` — alias for `deck_id`
+### `Presentation(asset_id=...)` / `Presentation.asset_id` — preferred spelling; `deck_id` is the legacy alias
 
 The deck id and the Athena asset id are the same string
-(`asset_<uuid>`); the property exists because Olympus URLs, GraphQL
-schemas, and most agent-facing copy refer to "asset id". Both names
-return `self._deck_id`:
+(`asset_<uuid>`); `asset_id` is the preferred name because Olympus
+URLs, GraphQL schemas, and most agent-facing copy refer to "asset id".
+Upstream `python-pptx` opens a local OPC package via
+`Presentation(pptx_path)` — the REST SDK has no local package, so the
+constructor reattaches to a server-side asset by id instead. Both the
+constructor keyword and the read property exist in both spellings:
 
 ```python
-prs.deck_id   # "asset_3a93..."
-prs.asset_id  # same value
+prs = Presentation(asset_id="asset_3a93...")  # preferred
+prs = Presentation(deck_id="asset_3a93...")   # legacy alias — same behaviour
+
+prs.asset_id  # "asset_3a93..." — preferred
+prs.deck_id   # same value — legacy alias
 ```
 
+Rules (mirrors the `name`/`title` reconciliation on
+`Presentation.create()`):
+
+- `asset_id` and `deck_id` are interchangeable; internally both bind the
+  same identifier (`self._deck_id`).
+- Passing **both** is allowed only when the values match; differing
+  values raise `ValueError`.
+- Passing **neither** raises `TypeError` (previously `deck_id` was the
+  required first positional parameter; positional
+  `Presentation("asset_...")` still works unchanged).
+
 ### `Presentation.close()` — alias for `flush()`
 
 Stock python-pptx has no flush/close concept (it writes packages

{athena_python_pptx-0.4.1 → athena_python_pptx-0.4.2}/pptx/__init__.py

@@ -19,8 +19,9 @@ for real-time collaboration. Use exactly the same code you would with python-ppt
     # Or upload an existing file
     prs = Presentation.upload("my_presentation.pptx")
 
-    # Or connect to an existing deck
-    prs = Presentation(deck_id="deck_123")
+    # Or connect to an existing presentation asset
+    # (deck_id= is accepted as a legacy alias for asset_id=)
+    prs = Presentation(asset_id="asset_3a9328bc-9c1c-4498-be8f-bda3883276f5")
 
     # Work with slides and shapes (same API as python-pptx)
     slide = prs.slides[0]
@@ -132,7 +133,7 @@ def flush_all() -> None:
     _active_buffers[:] = alive
 
 
-__version__ = "0.4.1"
+__version__ = "0.4.2"
 
 __all__ = [
     # Main entry point

{athena_python_pptx-0.4.1 → athena_python_pptx-0.4.2}/pptx/commands.py

@@ -294,6 +294,10 @@ class SetParagraphStyle(Command):
     space_after_emu: Optional[int] = None
     margin_left_emu: Optional[int] = None
     indent_emu: Optional[int] = None
+    # Authored paragraph-level run defaults (python-pptx ``paragraph.font``).
+    # Keys are already wire-format camelCase (the Font style payload);
+    # the studio exports them as ``<a:pPr><a:defRPr …/></a:pPr>``.
+    default_run_style: Optional[dict] = None
 
     @property
     def command_type(self) -> str:

{athena_python_pptx-0.4.1 → athena_python_pptx-0.4.2}/pptx/presentation.py

@@ -179,7 +179,7 @@ class Presentation:
         from pptx.units import Inches
 
         prs = Presentation(
-            deck_id="deck_123",
+            asset_id="asset_3a9328bc-9c1c-4498-be8f-bda3883276f5",
             base_url="https://api.pptx-studio.com",
             api_key="sk_live_..."
         )
@@ -192,41 +192,73 @@ class Presentation:
 
     def __init__(
         self,
-        deck_id: DeckId,
+        deck_id: Optional[DeckId] = None,
         base_url: Optional[str] = None,
         api_key: Optional[str] = None,
         auto_refresh: bool = True,
+        *,
+        asset_id: Optional[DeckId] = None,
     ):
         """
         Initialize a Presentation proxy.
 
         Args:
-            deck_id: ID of the deck. MUST be ``asset_<uuid>`` for Athena
-                     assets or ``deck_<id>`` for legacy standalone decks.
-                     Anything else (e.g. a deck TITLE) raises ``ValueError``
-                     before any HTTP request. To mint a new asset, call
-                     ``Presentation.create(name=...)`` and reuse the
-                     returned ``prs.deck_id`` for subsequent opens.
+            deck_id: Legacy alias for ``asset_id`` — the same identifier
+                     string. Prefer ``asset_id``. Passing both is allowed
+                     only when they match; differing values raise
+                     ``ValueError``.
             base_url: Base URL of the API. If not provided, uses ATHENA_PPTX_BASE_URL
                      environment variable.
             api_key: Optional API key for authentication. If not provided, uses
                     ATHENA_PPTX_API_KEY environment variable.
             auto_refresh: Whether to automatically fetch snapshot on init
-        """
-        if not deck_id or not _DECK_ID_PATTERN.match(deck_id):
+            asset_id: ID of the presentation asset. MUST be ``asset_<uuid>``
+                     for Athena assets or ``deck_<id>`` for legacy standalone
+                     decks. Anything else (e.g. a presentation TITLE) raises
+                     ``ValueError`` before any HTTP request. To mint a new
+                     asset, call ``Presentation.create(name=...)`` and reuse
+                     the returned ``prs.asset_id`` for subsequent opens.
+        """
+        if deck_id is not None and asset_id is not None and deck_id != asset_id:
             raise ValueError(
-                f"Presentation(deck_id={deck_id!r}) is not a valid deck id. "
+                "Presentation(asset_id=..., deck_id=...) — asset_id and "
+                "deck_id must match when both are provided (they are the "
+                "same identifier; deck_id is the legacy alias). Pass only "
+                "asset_id."
+            )
+        resolved_id = asset_id if asset_id is not None else deck_id
+        if resolved_id is None:
+            raise TypeError(
+                "Presentation() missing required argument 'asset_id' "
+                "(or its legacy alias 'deck_id')."
+            )
+        id_param = "deck_id" if asset_id is None else "asset_id"
+        if not resolved_id or not _DECK_ID_PATTERN.match(resolved_id):
+            if id_param == "asset_id":
+                raise ValueError(
+                    f"Presentation(asset_id={resolved_id!r}) is not a valid "
+                    f"asset id. Asset ids look like 'asset_<uuid>' "
+                    f"(e.g., 'asset_3a9328bc-9c1c-4498-be8f-bda3883276f5'); "
+                    f"legacy standalone decks use 'deck_<id>'. To open an "
+                    f"existing presentation, pass its id — NOT its title. To "
+                    f"create a new presentation titled {resolved_id!r}, call "
+                    f"Presentation.create(name={resolved_id!r}) and reuse "
+                    f"`prs.asset_id` on subsequent calls in the same "
+                    f"conversation."
+                )
+            raise ValueError(
+                f"Presentation(deck_id={resolved_id!r}) is not a valid deck id. "
                 f"Deck ids look like 'asset_<uuid>' "
                 f"(e.g., 'asset_3a9328bc-9c1c-4498-be8f-bda3883276f5'); "
                 f"legacy standalone decks use 'deck_<id>'. To open an "
                 f"existing deck, pass its id — NOT its title. To create a "
-                f"new deck titled {deck_id!r}, call "
-                f"Presentation.create(name={deck_id!r}) and reuse "
+                f"new deck titled {resolved_id!r}, call "
+                f"Presentation.create(name={resolved_id!r}) and reuse "
                 f"`prs.deck_id` on subsequent calls in the same conversation."
             )
-        self._deck_id = deck_id
+        self._deck_id = resolved_id
         self._client = Client(base_url=base_url, api_key=api_key)
-        self._buffer = CommandBuffer(self._client, deck_id)
+        self._buffer = CommandBuffer(self._client, resolved_id)
         self._snapshot: Optional[DeckSnapshot] = None
         self._slides: Optional[Slides] = None
         self._closed = False
@@ -265,7 +297,7 @@ class Presentation:
         if auto_refresh:
             from pptx import _ptc
 
-            call_id = _ptc.emit_begin("OpenPresentation", {"assetId": deck_id})
+            call_id = _ptc.emit_begin("OpenPresentation", {"assetId": resolved_id})
             try:
                 self.refresh()
             except AuthenticationError as exc:
@@ -276,10 +308,10 @@ class Presentation:
                     is_error=True,
                 )
                 raise PermissionError(
-                    f"Presentation(deck_id={deck_id!r}) — access denied. "
+                    f"Presentation({id_param}={resolved_id!r}) — access denied. "
                     f"The current user doesn't have permission to open this "
-                    f"deck, or the id is invalid. Verify the id is correct "
-                    f"and reachable from the current workspace."
+                    f"presentation, or the id is invalid. Verify the id is "
+                    f"correct and reachable from the current workspace."
                 ) from exc
             except RemoteError as exc:
                 _ptc.emit_end(
@@ -290,16 +322,18 @@ class Presentation:
                 )
                 if exc.status_code == 404:
                     raise ValueError(
-                        f"Presentation(deck_id={deck_id!r}) — deck not found. "
-                        f"To create a new deck, call "
-                        f"Presentation.create(name=...) and reuse `prs.deck_id` "
-                        f"for subsequent opens in the same conversation."
+                        f"Presentation({id_param}={resolved_id!r}) — "
+                        f"presentation not found. To create a new "
+                        f"presentation, call Presentation.create(name=...) "
+                        f"and reuse `prs.asset_id` for subsequent opens in "
+                        f"the same conversation."
                     ) from exc
                 if exc.status_code in (401, 403):
                     raise PermissionError(
-                        f"Presentation(deck_id={deck_id!r}) — access denied "
-                        f"(HTTP {exc.status_code}). Verify the deck id and "
-                        f"that the current user has permission to open it."
+                        f"Presentation({id_param}={resolved_id!r}) — access "
+                        f"denied (HTTP {exc.status_code}). Verify the asset "
+                        f"id and that the current user has permission to "
+                        f"open it."
                     ) from exc
                 raise
             except Exception as exc:
@@ -313,7 +347,7 @@ class Presentation:
             _ptc.emit_end(
                 call_id=call_id,
                 tool_name="OpenPresentation",
-                result={"ok": True, "assetId": deck_id},
+                result={"ok": True, "assetId": resolved_id},
                 is_error=False,
             )
 
@@ -708,13 +742,14 @@ class Presentation:
         description="Presentation.asset_id — Athena asset id alias for deck_id.",
     )
     def asset_id(self) -> DeckId:
-        """Alias for :attr:`deck_id`.
-
-        Athena hosts each presentation as an ``asset_<uuid>`` asset; many
-        callers think in "asset id" terms (matching the URL pattern in
-        Olympus and the GraphQL schema) rather than the historical
-        ``deck_id`` name. Both properties return the same string.
-        Athena-only ergonomic addition — not in upstream python-pptx.
+        """Athena asset id of the presentation — preferred spelling.
+
+        Athena hosts each presentation as an ``asset_<uuid>`` asset; this
+        matches the URL pattern in Olympus, the GraphQL schema, and
+        agent-facing vocabulary. :attr:`deck_id` is the legacy alias and
+        returns the same string, as does the ``deck_id=`` constructor
+        keyword. Athena-only ergonomic addition — not in upstream
+        python-pptx.
         """
         return self._deck_id