athena-python-pptx 0.15.0__tar.gz → 0.16.0__tar.gz

{athena_python_pptx-0.15.0 → athena_python_pptx-0.16.0}/AGENTS.md

@@ -124,7 +124,7 @@ This is a **REST API client** that mimics the python-pptx API. Instead of manipu
 - State is synchronized via the PPTX Studio collaboration layer (Yjs)
 - **Programmatic Tool Calling (PTC):** every `CommandBuffer.add` and
   `flush` emits begin/end events to agora via `pptx/_ptc.py` when run
-  inside a Daytona sandbox with `ATHENA_PTC_URL` set. Each method call
+  inside an Athena sandbox with `ATHENA_PTC_URL` set. Each method call
   surfaces as a nested sub-tool-card under the parent
   `run_python_code` tool. See
   [`docs/PROGRAMMATIC_TOOL_CALLING_GUIDE.md`](../../docs/PROGRAMMATIC_TOOL_CALLING_GUIDE.md)

{athena_python_pptx-0.15.0 → athena_python_pptx-0.16.0}/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.16.0 — `Presentation.create()` makes 13.333" × 7.5" decks; `create(name=, title=)` titles the deck
+
+- **Behaviour change:** `Presentation.create()` makes a deck at PowerPoint's
+  Widescreen size, 16:9 at 13.333" × 7.5" (12192000 × 6858000 EMU) — the
+  size of the blank template, whose master and layouts are laid out for it.
+  It used to resize every blank deck to 16" × 9" (14630400 × 8229600 EMU),
+  which changed only the size field: layout placeholders sat off-centre, and
+  a deck laid out for 13.333" × 7.5" filled only the top-left 83% of each
+  slide's width and height, leaving a white band on the right and bottom. `widescreen=True` (the
+  default) now sends nothing unless the template has another size.
+  `widescreen=False` keeps the template's size, which is the same: it never
+  made a 4:3 deck, whatever the docstring said. Decks created earlier keep
+  their stored 16" × 9" size.
+- `Presentation.create(name=..., title=...)` with different values names the
+  asset `name` and sets the deck's core title (`prs.core_properties.title`)
+  to `title`, also with `pptx=`. It used to raise `ValueError`. `title=`
+  alone, or the same value for both, still just names the deck.
+
+## 0.16.0 — deleting most of an existing deck needs allow_bulk_delete=True
+
+- **Behaviour change:** a run that opens an existing deck of 4 or more slides
+  and deletes more than half of them — `slides.keep_only([0])`, a
+  `delete_slides()` of most indices, or `slides.delete()` calls adding up —
+  raises `ValueError` before anything is sent, unless the call passes
+  `allow_bulk_delete=True` (a new keyword on `delete()`, `delete_slides()`
+  and `keep_only()`). An agent asked to add one slide had re-run its whole
+  build (`keep_only([0])` then rebuild), and stopping it midway left a
+  21-slide deck half-built. Decks the run created with
+  `Presentation.create()` or `Presentation.upload()` are not guarded, so
+  trimming a fresh template still works.
+
 ## 0.15.0 — uploaded click actions read back; pictures carry python-pptx's descr; layout graphics refuse delete()
 
 - `shape.click_action` reads the click actions of an uploaded deck as

{athena_python_pptx-0.15.0 → athena_python_pptx-0.16.0}/DEV-GUIDE.md

@@ -3,15 +3,15 @@
 ## Quick Setup
 
 ```bash
-# Install in editable mode (changes take effect immediately, no reinstall)
-cd python-sdk
-pip install -e ".[dev]"
+# Editable install with the dev group, in the SDK's own .venv
+cd pptx-studio/python-sdk
+uv sync
 
 # Point at local API
 export ATHENA_PPTX_BASE_URL=http://localhost:4000
 
-# Start the API server (in another terminal)
-pnpm dev
+# Start the API server (in another terminal, from pptx-studio/)
+bun run dev
 ```
 
 ## Testing Changes
@@ -38,7 +38,7 @@ with prs.batch():
 ```
 
 ```bash
-python scratch.py
+uv run python scratch.py
 ```
 
 ### Run tests
@@ -68,8 +68,7 @@ CI installs with pip, so a committed lock would be read by nothing.
 ### Interactive REPL
 
 ```bash
-pip install ipython
-ATHENA_PPTX_BASE_URL=http://localhost:4000 ipython
+ATHENA_PPTX_BASE_URL=http://localhost:4000 uv run --with ipython ipython
 ```
 
 ### Debug HTTP calls

{athena_python_pptx-0.15.0 → athena_python_pptx-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-pptx
-Version: 0.15.0
+Version: 0.16.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.15.0 → athena_python_pptx-0.16.0}/docs/API_PARITY_EXCEPTIONS.md

@@ -1192,7 +1192,7 @@ to be world-readable, like any plain image link.
 download the URL externally and pass `bytes` or a file-like.**
 
 ```python
-# Inside a Daytona pptx sandbox:
+# Inside the presentation-exec sandbox:
 img = ws.export_range_as_image_asset("A1:F20", name="Q4 Revenue")
 slide.shapes.add_picture(img.url, Inches(1), Inches(1), width=Inches(6))
 ```
@@ -1788,29 +1788,37 @@ These additions don't change any python-pptx behaviour — they're new
 optional surface on top of the existing API. Portable code that needs to
 run against stock `python-pptx` should avoid them.
 
-### `Presentation.create(title=...)` — alias for `name=`
+### `Presentation.create(title=...)` — names the deck, or titles it next to `name=`
 
 Upstream `python-pptx` has no `Presentation.create()` factory at all;
-this whole method is an Athena addition. The `title=` keyword is a
+this whole method is an Athena addition. On its own, `title=` is a
 convenience alias for `name=` because callers often think of the deck
-label as a "title" rather than a "name". Passing both at once raises
-`ValueError` unless they agree:
+label as a "title" rather than a "name". Next to a different `name=`,
+the asset is named `name` and `title` becomes the deck's core title
+(`prs.core_properties.title`, the title PowerPoint shows in File > Info):
 
 ```python
 Presentation.create(name="Q4")              # canonical
 Presentation.create(title="Q4")             # alias — same result
-Presentation.create(name="Q4", title="Q4")  # OK, values match
-Presentation.create(name="Q4", title="Q3")  # ValueError
+Presentation.create(name="Q4", title="Q4")  # same result
+Presentation.create(name="q4-review", title="Q4 Review")
+# asset named "q4-review"; prs.core_properties.title == "Q4 Review"
 ```
 
 ### `Presentation.create(widescreen=True)`
 
-Optional kwarg on `Presentation.create()` that creates the deck at 16:9
-widescreen dimensions (14630400 × 8229600 EMU = 16" × 9") instead of
-the template's default size (typically 4:3 at 12192000 × 6858000 EMU).
-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()`.
+Optional kwarg on `Presentation.create()`, `True` by default: the deck
+gets PowerPoint's Widescreen size, 16:9 at 13.333" × 7.5" (12192000 ×
+6858000 EMU). The blank template new decks start from already has that
+size and its master and layouts are laid out for it, so nothing is sent
+unless the template has another size. Athena-only. `widescreen=False`
+keeps the template's own size, which today is the same 13.333" × 7.5":
+there is no 4:3 blank template, and resizing a blank deck to 4:3 would
+leave its master and layout placeholders laid out for 13.333". For any
+other size call `prs.set_slide_size(width, height)` after `create()`;
+the master and layouts keep their geometry. Read the size from
+`prs.slide_width` / `prs.slide_height` (or `prs.slide_size_inches`)
+rather than assuming it.
 
 ### `Presentation(asset_id=...)` / `Presentation.asset_id` — preferred spelling; `deck_id` is the legacy alias
 
@@ -1978,8 +1986,8 @@ xlsx-studio's ownership middleware checks that the calling workspace
 can read the source workbook. Render scale is fixed at 3 (matches
 xlsx-studio's `range-as-asset` default — slide inserts sit at 6–9″
 widths where scale=2 leaves text soft). When `ATHENA_XLSX_BASE_URL` /
-`ATHENA_XLSX_API_KEY` aren't set (e.g. running outside a Daytona
-presentation_exec sandbox), the call raises `ValueError` rather than
+`ATHENA_XLSX_API_KEY` aren't set (e.g. running outside the
+presentation-exec sandbox), the call raises `ValueError` rather than
 producing a broken picture.
 
 For finer control (custom scale, `include_headers`, off-snapshot
@@ -2205,11 +2213,12 @@ work in addition to SDK surface and are tracked separately.
 
 ### Slide- and presentation-level additions
 
-- **`Presentation.create(widescreen=True)` is now the default**
+- **`Presentation.create(widescreen=True)` is the default**
   (closes python-pptx#1066, 9-comment thread). The blank-template
-  factory creates 16:9 widescreen decks at 14630400 × 8229600 EMU
-  (PowerPoint's "Widescreen (16:9)" preset). Pass `widescreen=False`
-  to fall back to the legacy 4:3 default.
+  factory creates 16:9 decks at PowerPoint's Widescreen size,
+  13.333" × 7.5" (12192000 × 6858000 EMU) — the size of the blank
+  template itself. `widescreen=False` keeps the template's size, which is
+  the same; there is no 4:3 blank deck.
 
 - **`Presentation.open(deck_id, base_url=None, api_key=None)`**
   (closes python-pptx#1018 — "open a PPT in append mode"). Named
@@ -2624,7 +2633,7 @@ python-pptx. Generated from `pptx._athena_extension.iter_athena_extensions()`.
 <!-- BEGIN GENERATED: athena-extensions (scripts/generate_parity_tables.py; do not edit by hand) -->
 | Surface | Kind | Since | Upstream issue | What it is |
 |---|---|---|---|---|
-| `pptx._ptc` | module | 0.1.0 |  | Programmatic Tool Calling (Daytona sandbox event emission). |
+| `pptx._ptc` | module | 0.1.0 |  | Programmatic Tool Calling (sandbox event emission). |
 | `pptx._references` | module | 0.1.71 |  | Cross-studio asset reference types (Athena studio-linking, no upstream). |
 | `pptx.action.ActionSetting.action` | property | 0.15.0 |  | ActionSetting.action setter: relative slide jumps and end show (read-only in python-pptx). |
 | `pptx.action._ActionHyperlink.tooltip` | property | 0.15.0 |  | click_action.hyperlink.tooltip: hover text for a shape's click action. |

{athena_python_pptx-0.15.0 → athena_python_pptx-0.16.0}/docs/athena-api.md

@@ -109,17 +109,19 @@ new_slide = slide.clone(target_index=len(prs.slides))
 Delete multiple slides from the presentation by their indices.
 
 ```python
-def delete_slides(indices: list[int]) -> None
+def delete_slides(indices: list[int], *, allow_bulk_delete: bool = False) -> None
 ```
 
 **Parameters:**
 
 - **indices** (`list[int]`): List of zero-based slide indices to delete
+- **allow_bulk_delete** (`bool`): Allow deleting more than half of the slides an existing deck (4+ slides) had when this run opened it.
 
 **Raises:**
 
 - `ValueError`: If any index is out of range
 - `ValueError`: If duplicate indices are provided
+- `ValueError`: If the run would delete most of an existing deck's slides without `allow_bulk_delete=True`
 
 **Example:**
 
@@ -144,18 +146,20 @@ prs.slides.delete_slides([len(prs.slides) - 1, len(prs.slides) - 2])
 Keep only the slides at the specified indices, deleting all others.
 
 ```python
-def keep_only(indices: list[int]) -> None
+def keep_only(indices: list[int], *, allow_bulk_delete: bool = False) -> None
 ```
 
 **Parameters:**
 
 - **indices** (`list[int]`): List of zero-based slide indices to keep
+- **allow_bulk_delete** (`bool`): Allow deleting more than half of the slides an existing deck (4+ slides) had when this run opened it.
 
 **Raises:**
 
 - `ValueError`: If any index is out of range
 - `ValueError`: If duplicate indices are provided
 - `ValueError`: If indices list is empty
+- `ValueError`: If the run would delete most of an existing deck's slides without `allow_bulk_delete=True`
 
 **Example:**
 

{athena_python_pptx-0.15.0 → athena_python_pptx-0.16.0}/pptx/__init__.py

@@ -189,7 +189,7 @@ def _flush_failure_message(buffer: "CommandBuffer", exc: BaseException) -> str:
 def flush_all(*, strict: bool = False) -> None:
     """Flush all active presentation command buffers.
 
-    Called by the Daytona/Talos prelude after user code runs. By default a
+    Called by Athena's sandbox executor after user code runs. By default a
     per-buffer flush failure is written to stderr and swallowed (local-script
     back-compat); the sandbox executor calls ``flush_all(strict=True)`` so a
     server rejection of the final buffered edits surfaces as a real tool
@@ -327,7 +327,7 @@ def validate_all_touched() -> dict[int, list[str]]:
     return results
 
 
-__version__ = "0.15.0"
+__version__ = "0.16.0"
 
 __all__ = [
     # Main entry point

{athena_python_pptx-0.15.0 → athena_python_pptx-0.16.0}/pptx/_ptc.py

@@ -37,9 +37,7 @@ of stdlib code is cheaper than spinning up a 4th release pipeline.
 from __future__ import annotations
 
 __athena_extension_module__: bool = True
-__athena_extension_description__: str = (
-    "Programmatic Tool Calling (Daytona sandbox event emission)."
-)
+__athena_extension_description__: str = "Programmatic Tool Calling (sandbox event emission)."
 __athena_extension_since__: str = "0.1.0"
 
 import http.client

{athena_python_pptx-0.15.0 → athena_python_pptx-0.16.0}/pptx/batching.py

@@ -656,7 +656,8 @@ class CommandBuffer:
 
     An auto-flush timer (default 2.0s) automatically flushes pending commands
     after an idle period. This ensures commands are not silently lost in
-    persistent process environments (e.g. Daytona) where atexit never fires.
+    persistent process environments (e.g. long-lived sandbox executors) where
+    atexit never fires.
 
     Usage:
         # Default: commands are buffered

{athena_python_pptx-0.15.0 → athena_python_pptx-0.16.0}/pptx/presentation.py

@@ -33,6 +33,11 @@ from .units import Emu, Length, ensure_emu
 # asset and capture its id from ``prs.deck_id``.
 _DECK_ID_PATTERN = re.compile(r"^(asset_|deck_)[A-Za-z0-9_-]+$")
 
+# PowerPoint's "Widescreen" slide size (Design > Slide Size), 16:9 at
+# 13.333" x 7.5" — the size of the blank template new decks start from, whose
+# master and layouts are laid out for it.
+_WIDESCREEN_SLIDE_SIZE_EMU = (12192000, 6858000)
+
 
 # -------------------------------------------------------------------------
 # CoreProperties — python-pptx's ``prs.core_properties``
@@ -273,6 +278,14 @@ def _open_failure(*, target: str, exc: Exception) -> Exception:
     return exc
 
 
+def _release_opened_slides(prs: Any) -> None:
+    """A deck this run created or uploaded has no earlier slides to protect."""
+    prs._protect_slides_pending = False
+    slides = getattr(prs, "_slides", None)
+    if slides is not None:
+        slides._release_opened_slides()
+
+
 class Presentation:
     """
     Presentation proxy - the main entry point for working with a deck.
@@ -406,6 +419,10 @@ class Presentation:
             self._atexit_flush = _flush_on_exit
             atexit.register(_flush_on_exit)
 
+        # The first snapshot adopted (here or a later manual refresh())
+        # records the slides the bulk-delete guard protects.
+        self._protect_slides_pending = True
+
         # PTC: surface deck open as its own sub-tool-card so the
         # frontend can react (e.g., auto-open the asset tab). The
         # paired ``Presentation.create()`` path emits
@@ -683,9 +700,11 @@ class Presentation:
         """
         Create a new presentation.
 
-        By default this creates an empty 16:9 widescreen presentation
-        that's immediately ready to use; you can then add slides and
-        content.
+        By default this creates an empty presentation at PowerPoint's
+        Widescreen size (16:9, 13.333" x 7.5") that's immediately ready to
+        use; you can then add slides and content. Read the size from
+        ``prs.slide_width`` / ``prs.slide_height`` (or
+        ``prs.slide_size_inches``) rather than assuming it.
 
         When ``pptx`` is provided, the local ``.pptx`` / ``.potx`` file is
         uploaded as the seed instead of starting from a blank template.
@@ -706,22 +725,27 @@ class Presentation:
                 file. When provided, the file is uploaded and used as the
                 seed for the new presentation (mirrors python-pptx's
                 ``Presentation(pptx=...)`` constructor kwarg).
-            title: Optional alias for ``name`` — accepted for ergonomic parity
-                   with callers that think of the deck label as a "title".
-                   Passing both ``name`` and ``title`` is allowed only when
-                   they match; differing values raise ``ValueError``.
-            widescreen: Create the deck at 16:9 widescreen dimensions
-                        (14630400 × 8229600 EMU = 16" × 9"). Defaults to
-                        ``True`` since 0.1.81 — closes python-pptx#1066,
-                        a 9-comment thread asking for a 16:9 default
-                        because PowerPoint itself ships every new deck as
-                        16:9 and 4:3 is now a legacy aspect ratio.
-                        Pass ``widescreen=False`` to fall back to the
-                        template's default (4:3, 12192000 × 6858000 EMU).
-                        Ignored when ``pptx=`` is provided (the uploaded
-                        file defines its own slide size). Not in upstream
-                        python-pptx, which has no factory method here at
-                        all.
+            title: Optional deck title. On its own it names the deck, as an
+                   alias for ``name`` (callers often think of the deck label
+                   as a "title"). With a different ``name``, the deck is
+                   named ``name`` and ``title`` becomes its core title
+                   (``prs.core_properties.title``, the title PowerPoint
+                   shows in File > Info). The same value for both just
+                   names the deck.
+            widescreen: Give the deck PowerPoint's Widescreen size: 16:9,
+                        13.333" x 7.5" (12192000 x 6858000 EMU). The blank
+                        template already has that size, so nothing is sent
+                        unless the template has another one. Defaults to
+                        ``True``. ``widescreen=False`` keeps the template's
+                        own size, which today is the same 13.333" x 7.5":
+                        there is no 4:3 blank template, and a 4:3 resize
+                        would leave the master and layout placeholders laid
+                        out for 13.333". For another size call
+                        :meth:`set_slide_size` after ``create()``; the master
+                        and layouts keep their geometry. Ignored when
+                        ``pptx=`` is provided (the uploaded file defines its
+                        own slide size). Not in upstream python-pptx, which
+                        has no factory method here at all.
 
         Returns:
             Presentation instance for the new deck
@@ -741,25 +765,25 @@ class Presentation:
             )
             slide = prs.slides.add_slide()
 
-            # 16:9 widescreen deck
-            prs = Presentation.create(name="Quarterly review", widescreen=True)
+            # Asset named "q3-review", deck titled "Q3 Review"
+            prs = Presentation.create(name="q3-review", title="Q3 Review")
+            print(prs.slide_size_inches)  # (13.333..., 7.5)
         """
-        # Reconcile ``name`` and ``title``: ``title`` is an ergonomic alias
-        # for ``name``. If both are passed they must agree; otherwise the
-        # caller almost certainly has a bug (two different intents merged).
+        # ``title`` alone names the deck. Next to a different ``name`` it is
+        # the deck's core title, checked here so a title python-pptx would
+        # refuse fails before any deck exists.
+        core_title: str | None = None
         if title is not None and name is not None and title != name:
-            raise ValueError(
-                "Presentation.create(name=..., title=...) — name and title "
-                "must match when both are provided. Pass only one."
-            )
+            core_title = _core_text_value(title)
         effective_name = name if name is not None else title
 
         from pptx import _ptc
 
         if pptx is not None:
-            return cls.upload(
-                pptx, base_url=base_url, api_key=api_key, name=effective_name,
-            )
+            uploaded = cls.upload(pptx, base_url=base_url, api_key=api_key, name=effective_name)
+            if core_title is not None:
+                uploaded.core_properties.title = core_title
+            return uploaded
 
         # PTC: surface asset creation as its own top-level sub-tool-card.
         # Scoped tightly around ``create_empty_deck`` — the deck is
@@ -791,12 +815,16 @@ class Presentation:
         # The presentation's client takes over this connection.
         with _hand_session_to_next_client(client):
             prs = cls(deck_id=deck_id, base_url=base_url, api_key=api_key)
+        _release_opened_slides(prs)
 
-        # Apply widescreen sizing before slide cleanup so the size command
-        # is sent even if the template arrives with no default slides.
         if widescreen:
-            # 16:9 widescreen — matches PowerPoint's "Widescreen (16:9)" preset.
-            prs.set_slide_size(Emu(14630400), Emu(8229600))
+            width_emu, height_emu = _WIDESCREEN_SLIDE_SIZE_EMU
+            snapshot = prs._snapshot
+            if snapshot is None or (
+                int(snapshot.slide_width_emu),
+                int(snapshot.slide_height_emu),
+            ) != (width_emu, height_emu):
+                prs.set_slide_size(Emu(width_emu), Emu(height_emu))
 
         # Delete any default slides from the blank template
         # The blank template includes one slide that we need to remove
@@ -804,6 +832,9 @@ class Presentation:
         while len(prs.slides) > 0:
             prs.slides.delete(prs.slides[0])
 
+        if core_title is not None:
+            prs.core_properties.title = core_title
+
         return prs
 
     @classmethod
@@ -881,7 +912,9 @@ class Presentation:
                 # Upload without waiting
                 deck_id = client.upload_file_async(str(path), name=name)
 
-            return cls(deck_id=deck_id, base_url=base_url, api_key=api_key, auto_refresh=wait)
+            prs = cls(deck_id=deck_id, base_url=base_url, api_key=api_key, auto_refresh=wait)
+        _release_opened_slides(prs)
+        return prs
 
     @property
     @athena_extension(
@@ -1932,6 +1965,9 @@ class Presentation:
                 buffer=self._buffer,
                 snapshot=snapshot,
             )
+        if self.__dict__.get("_protect_slides_pending"):
+            self._protect_slides_pending = False
+            self._slides._protect_opened_slides()
 
         # A rejected shape graph leaves the previously published snapshot and
         # held slide proxies intact, including reconciliation aliases for retry.

{athena_python_pptx-0.15.0 → athena_python_pptx-0.16.0}/pptx/shapes/__init__.py

@@ -92,7 +92,7 @@ _ATHENA_URL_SUFFIXES: tuple[str, ...] = (
 )
 
 # Hard cap on bytes read for a URL-supplied image. Olympus's asset proxy
-# limits in practice, but ``add_picture`` runs inside a Daytona sandbox
+# limits in practice, but ``add_picture`` runs inside a sandbox
 # with finite memory, so we want a deterministic local stop regardless
 # of what the server claims.
 _MAX_URL_IMAGE_BYTES = 50 * 1024 * 1024
@@ -292,7 +292,7 @@ def _try_convert_to_png(data: bytes, image_format: str) -> Optional[bytes]:
     produces a broken-image placeholder on the slide.
 
     WebP → PNG: requires ``Pillow`` (transitively included via
-    ``matplotlib`` in the presentation_exec Daytona snapshot, so this
+    ``matplotlib`` in the presentation-exec image, so this
     just works in the standard agent runtime).
 
     AVIF → PNG: same Pillow path, but only on Pillow builds with AVIF

{athena_python_pptx-0.15.0 → athena_python_pptx-0.16.0}/pptx/slides.py

@@ -3696,6 +3696,11 @@ class Slide:
         return f"<Slide slide_id='{self._slide_id}' index={self.__dict__.get('_slide_index_value')}>"
 
 
+# An existing deck this size or larger refuses losing most of its slides in
+# one run unless the caller passes allow_bulk_delete=True.
+_BULK_DELETE_MIN_SLIDES = 4
+
+
 class Slides:
     """
     Collection of slides in a presentation.
@@ -3713,6 +3718,9 @@ class Slides:
         self._buffer = buffer
         self._slides: list[Slide] = []
         self._slides_by_id: dict[SlideId, Slide] = {}
+        # Slides the deck already had when this run opened it; the
+        # bulk-delete guard counts how many of them are no longer present.
+        self._opened_slide_ids: frozenset[SlideId] = frozenset()
 
         # Build slides from snapshot
         if snapshot:
@@ -4367,11 +4375,44 @@ class Slides:
             s._slide_index = i
         return slide
 
+    def _protect_opened_slides(self) -> None:
+        """Record the slides an existing deck had when this run opened it."""
+        self._opened_slide_ids = frozenset(s._slide_id for s in self._slides)
+
+    def _release_opened_slides(self) -> None:
+        """A deck this run created or uploaded has no prior slides to protect."""
+        self._opened_slide_ids = frozenset()
+
+    def _check_bulk_delete(self, slides: list[Slide], allow_bulk_delete: bool) -> None:
+        """Refuse a run deleting most of the slides an existing deck had.
+
+        Re-running a whole-deck build (``keep_only([0])`` then rebuild) to
+        change one slide wipes every slide the user did not ask to change,
+        and an interrupted rebuild leaves the deck half-built.
+        """
+        opened = self._opened_slide_ids
+        if allow_bulk_delete or len(opened) < _BULK_DELETE_MIN_SLIDES:
+            return
+        # Counted from the slides still present, so deletions a failed batch
+        # discarded stop counting once the deck is re-read.
+        remaining = {s._slide_id for s in self._slides} - {s._slide_id for s in slides}
+        deleted = opened - remaining
+        if len(deleted) * 2 <= len(opened):
+            return
+        raise ValueError(
+            f"Refusing to delete {len(deleted)} of the {len(opened)} slides this "
+            f"deck had when it was opened. To change, add or remove a few "
+            f"slides, edit only those: add_slide() then prs.reorder_slides(), "
+            f"edit the slide's shapes, or prs.slides.delete(slide). Do not "
+            f"delete the deck and rebuild it. If the user asked to remove these "
+            f"slides, pass allow_bulk_delete=True."
+        )
+
     def index(self, slide: Slide) -> int:
         """Get the index of a slide."""
         return self._slides.index(slide)
 
-    def delete(self, slide) -> None:
+    def delete(self, slide, *, allow_bulk_delete: bool = False) -> None:
         """
         Delete a slide from the presentation.
 
@@ -4385,15 +4426,20 @@ class Slides:
 
         Args:
             slide: The slide to delete, or an integer index.
+            allow_bulk_delete: Allow this delete to bring the run's deletions
+                past half of the slides an existing deck had when opened.
 
         Raises:
             ValueError: If slide is not in this collection
+            ValueError: If the run would delete most of an existing deck's
+                slides without ``allow_bulk_delete=True``
             IndexError: If integer index is out of range
         """
         if isinstance(slide, int):
             slide = self._slides[slide]
         if slide not in self._slides:
             raise ValueError("Slide not found in presentation")
+        self._check_bulk_delete([slide], allow_bulk_delete)
 
         slide_index = self._slides.index(slide)
 
@@ -4416,20 +4462,20 @@ class Slides:
         description="Slides.remove_slide — alias for delete() matching the python-pptx#956 verb.",
         since="0.1.81",
     )
-    def remove_slide(self, slide) -> None:
+    def remove_slide(self, slide, *, allow_bulk_delete: bool = False) -> None:
         """Remove a slide (alias for :py:meth:`delete`).
 
         Closes python-pptx#956 — both ``delete`` and ``remove_slide`` are
         spellings the upstream issue thread uses. Accepts a slide object
         or an integer index.
         """
-        self.delete(slide)
+        self.delete(slide, allow_bulk_delete=allow_bulk_delete)
 
     @athena_only(
         description="Delete multiple slides at once by index",
         since="0.1.2",
     )
-    def delete_slides(self, indices: list[int]) -> None:
+    def delete_slides(self, indices: list[int], *, allow_bulk_delete: bool = False) -> None:
         """
         Delete multiple slides from the presentation by their indices.
 
@@ -4439,10 +4485,14 @@ class Slides:
 
         Args:
             indices: List of zero-based slide indices to delete
+            allow_bulk_delete: Allow deleting more than half of the slides an
+                existing deck (4+ slides) had when this run opened it.
 
         Raises:
             ValueError: If any index is out of range
             ValueError: If duplicate indices are provided
+            ValueError: If the run would delete most of an existing deck's
+                slides without ``allow_bulk_delete=True``
 
         Example:
             # Delete slides at indices 1, 3, and 5
@@ -4462,6 +4512,8 @@ class Slides:
             if idx < 0 or idx >= len(self._slides):
                 raise ValueError(f"Slide index {idx} is out of range (0-{len(self._slides) - 1})")
 
+        self._check_bulk_delete([self._slides[idx] for idx in indices], allow_bulk_delete)
+
         # Sort indices in descending order to avoid index shifting
         sorted_indices = sorted(indices, reverse=True)
 
@@ -4500,7 +4552,7 @@ class Slides:
         description="Keep only specified slides, removing all others",
         since="0.1.2",
     )
-    def keep_only(self, indices: list[int]) -> None:
+    def keep_only(self, indices: list[int], *, allow_bulk_delete: bool = False) -> None:
         """
         Keep only the slides at the specified indices, deleting all others.
 
@@ -4509,11 +4561,15 @@ class Slides:
 
         Args:
             indices: List of zero-based slide indices to keep
+            allow_bulk_delete: Allow deleting more than half of the slides an
+                existing deck (4+ slides) had when this run opened it.
 
         Raises:
             ValueError: If any index is out of range
             ValueError: If duplicate indices are provided
             ValueError: If indices list is empty
+            ValueError: If the run would delete most of an existing deck's
+                slides without ``allow_bulk_delete=True``
 
         Example:
             # Keep only the first and last slides
@@ -4545,7 +4601,7 @@ class Slides:
 
         # Use delete_slides for the actual deletion
         if delete_indices:
-            self.delete_slides(delete_indices)
+            self.delete_slides(delete_indices, allow_bulk_delete=allow_bulk_delete)
 
     def _drop_unsent(self, created_ids: set[str]) -> None:
         """Forget slides and shapes whose creating command was dropped unsent.

{athena_python_pptx-0.15.0 → athena_python_pptx-0.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-pptx"
-version = "0.15.0"
+version = "0.16.0"
 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.15.0/PUBLISHING.md

@@ -1,177 +0,0 @@
-# Publishing the Python SDK to PyPI
-
-This guide covers how to bump, build, and publish the `athena-python-pptx` package to PyPI.
-
-## Quick Start
-
-```bash
-# Bump to version 0.1.26 and publish to PyPI
-./scripts/publish-python-sdk.sh 0.1.26
-```
-
-## Prerequisites
-
-The script will check for and install these if missing:
-
-- Python 3.10+
-- `build` module (`pip install build`)
-- `twine` (`pip install twine`)
-
-## PyPI Credentials
-
-You'll need PyPI credentials configured. Options:
-
-### Option 1: API Token (Recommended)
-
-1. Go to https://pypi.org/manage/account/token/
-2. Create a token scoped to the `athena-python-pptx` project
-3. Configure in `~/.pypirc`:
-
-```ini
-[pypi]
-username = __token__
-password = pypi-AgEIcHlwaS5vcmc...
-```
-
-### Option 2: Environment Variables
-
-```bash
-export TWINE_USERNAME=__token__
-export TWINE_PASSWORD=pypi-AgEIcHlwaS5vcmc...
-```
-
-### Option 3: Interactive
-
-The script will prompt for credentials if not configured.
-
-## Usage
-
-### Basic Usage
-
-```bash
-# Publish a new version
-./scripts/publish-python-sdk.sh 0.1.26
-```
-
-### Options
-
-| Flag | Description |
-|------|-------------|
-| `--dry-run` | Preview changes without executing |
-| `--test-pypi` | Upload to TestPyPI instead of PyPI |
-| `--skip-build` | Skip build step (use existing `dist/`) |
-| `-h, --help` | Show help message |
-
-### Examples
-
-```bash
-# Preview what would happen
-./scripts/publish-python-sdk.sh --dry-run 0.1.26
-
-# Test on TestPyPI first
-./scripts/publish-python-sdk.sh --test-pypi 0.1.26
-
-# Then publish to production PyPI
-./scripts/publish-python-sdk.sh 0.1.26
-
-# Re-upload without rebuilding
-./scripts/publish-python-sdk.sh --skip-build 0.1.26
-```
-
-## What the Script Does
-
-1. **Checks prerequisites** - Python, pip, build, twine
-2. **Validates version** - Ensures semver format (X.Y.Z)
-3. **Bumps version** in both files:
-   - `pyproject.toml` (line 7)
-   - `pptx/__init__.py` (line 98)
-4. **Builds package** - Creates wheel and sdist in `dist/`
-5. **Uploads to PyPI** - Uses twine to publish
-
-## Version Locations
-
-The version must be updated in two places (the script handles this):
-
-```
-python-sdk/
-├── pyproject.toml      # version = "X.Y.Z"
-└── pptx/
-    └── __init__.py     # __version__ = "X.Y.Z"
-```
-
-## Manual Process
-
-If you prefer to do it manually:
-
-```bash
-cd python-sdk
-
-# 1. Update version in pyproject.toml and pptx/__init__.py
-
-# 2. Clean and build
-rm -rf dist/ build/ *.egg-info
-python -m build
-
-# 3. Upload to TestPyPI (optional)
-twine upload --repository testpypi dist/*
-
-# 4. Upload to PyPI
-twine upload dist/*
-```
-
-## After Publishing
-
-1. **Commit the version bump:**
-   ```bash
-   git add python-sdk/pyproject.toml python-sdk/pptx/__init__.py
-   git commit -m "Bump python-sdk to 0.1.26"
-   ```
-
-2. **Create a git tag:**
-   ```bash
-   git tag python-sdk-v0.1.26
-   ```
-
-3. **Push:**
-   ```bash
-   git push && git push --tags
-   ```
-
-## Testing the Published Package
-
-### From TestPyPI
-
-```bash
-pip install -i https://test.pypi.org/simple/ athena-python-pptx==0.1.26
-```
-
-### From PyPI
-
-```bash
-pip install athena-python-pptx==0.1.26
-```
-
-### Verify Installation
-
-```python
-import pptx
-print(pptx.__version__)  # Should print: 0.1.26
-```
-
-## Troubleshooting
-
-### "File already exists" Error
-
-PyPI doesn't allow re-uploading the same version. Bump the version number.
-
-### Authentication Failed
-
-Check your `~/.pypirc` or environment variables. For tokens, username must be `__token__`.
-
-### Build Fails
-
-Ensure you're in the `python-sdk/` directory and have the build module installed:
-
-```bash
-pip install build
-```