athena-python-pptx 0.7.1__tar.gz → 0.8.1__tar.gz

{athena_python_pptx-0.7.1 → athena_python_pptx-0.8.1}/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.8.0 — Surgical run text + faithful style hydration
+
+Closes the "agent edited deck text and the styling vanished" class of bugs
+(font size/weight/color jumping to the renderer's 18pt default after a text
+rewrite).
+
+**`run.text = …` is now surgical.** The setter (and the run text helpers
+`upper/lower/capitalize/title/strip/clear/replace`) emits the new
+`SetRunText` command — the server updates just that run's text, leaving its
+style, hyperlink, sibling runs, and paragraph properties untouched — instead
+of re-serializing the entire text frame from local state. Setting text on a
+freshly `add_run()`-appended run appends server-side inheriting the previous
+run's style (continue-typing semantics). Requires a pptx-studio deployment
+that knows `SetRunText`; set `ATHENA_PPTX_LEGACY_RUN_TEXT=1` to restore the
+old whole-frame re-emit against older servers.
+
+**Snapshot hydration is now faithful.** `Run` hydration previously mapped
+only 8 style keys (bold/italic/underline/fontSizePt/fontFamily/fontRef/
+colorHex/spacingPt) — any full-frame re-emit (`paragraph.text`,
+`add_paragraph()`, pre-0.8 `run.text`) silently stripped everything else
+from every run in the shape. Now:
+
+- `schemeColor`/`brightness` hydrate into the color API —
+  `run.font.color.theme_color` / `.brightness` return the ingested values.
+- `strike`/`strikethrough`, `subscript`/`superscript`/`baseline`, and
+  `languageId` hydrate into their typed fields.
+- Everything else the server sends (`cap`, `highlightColorHex`,
+  `highlightSchemeColor`, future keys) is carried verbatim in
+  `Font._extra_style` and reproduced by re-serialization.
+
+Pairs with the server-side `applySetText` preservation upgrade (same PR):
+unchanged lines keep their exact runs, rewritten lines keep the replaced
+line's explicit style, and new lines continue the surrounding style instead
+of collapsing to the 18pt default.
+
 ## 0.7.1 — CommandBuffer thread-safety
 
 Fixes a data-loss/duplication race in `CommandBuffer`. `self._commands` was

{athena_python_pptx-0.7.1 → athena_python_pptx-0.8.1}/PKG-INFO

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

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

athena_python_pptx-0.8.1/pptx/_citations.py

@@ -0,0 +1,54 @@
+"""Helpers for SDK-native Athena citations."""
+
+from __future__ import annotations
+
+from urllib.parse import parse_qs, urlparse
+
+_ATHENA_SPACES_HOST_SUFFIXES: tuple[str, ...] = (
+    "athenaintel.com",
+    "athenaintelligence.ai",
+)
+
+
+def _is_athena_spaces_host(hostname: str | None) -> bool:
+    host = (hostname or "").lower()
+    return any(
+        host == suffix or host.endswith(f".{suffix}")
+        for suffix in _ATHENA_SPACES_HOST_SUFFIXES
+    )
+
+
+def normalize_citation_string(citation_string: str) -> str:
+    value = citation_string.strip()
+    if not value:
+        raise ValueError("citation_string must not be empty")
+
+    parsed = urlparse(value)
+    if parsed.scheme in ("http", "https") and parsed.netloc:
+        if parsed.path.rstrip("/") == "/dashboard/spaces":
+            if not _is_athena_spaces_host(parsed.hostname):
+                raise ValueError(
+                    "absolute Athena Spaces citation URLs must use an Athena host"
+                )
+            asset_ids = parse_qs(parsed.query).get("asset_ids")
+            if not asset_ids or not asset_ids[0]:
+                raise ValueError("Athena Spaces citation URLs must include asset_ids")
+        return value
+
+    if not parsed.scheme and value.startswith("/"):
+        relative = urlparse(value)
+        if relative.netloc:
+            raise ValueError(
+                "protocol-relative Athena Spaces citation URLs are not allowed; "
+                "use an absolute Athena host"
+            )
+        if relative.path.rstrip("/") == "/dashboard/spaces":
+            asset_ids = parse_qs(relative.query).get("asset_ids")
+            if asset_ids and asset_ids[0]:
+                return value
+            raise ValueError("Athena Spaces citation URLs must include asset_ids")
+
+    raise ValueError(
+        "citation_string must be a serialized citation URL, such as "
+        "'/dashboard/spaces/?asset_ids=...' or an 'https://...' URL"
+    )

{athena_python_pptx-0.7.1 → athena_python_pptx-0.8.1}/pptx/client.py

@@ -129,9 +129,13 @@ class Client:
         duplicate slides/shapes/cells). This mirrors docx-studio's
         ``_build_retry_session`` policy:
 
-        - **Status-only retries** (``connect``/``read``/``other`` disabled).
-          A transport drop *after* the server processed the batch must never
-          trigger an automatic resend.
+        - **Connect retries** (``connect=2``) are enabled because a TCP
+          connection failure means no data ever reached the server — zero
+          risk of double-applying commands. Critical during Kubernetes
+          rolling deployments where old pods stop accepting connections.
+        - **Read retries** remain disabled (``read=0``): a transport drop
+          *after* the server processed the batch must never trigger an
+          automatic resend.
         - **Retry only on transient statuses raised before any commit**
           (429/502/503/504). ``500`` is intentionally removed — a 500 from
           ``/commands`` can mean the batch was applied and then
@@ -140,16 +144,14 @@ class Client:
           concurrent agents don't thunder-herd a recovering pod.
 
         Idempotent reads (GET/HEAD) and DELETE remain in ``allowed_methods``
-        so they still retry on those transient statuses; disabling
-        connect/read retries only costs a resend on a mid-flight socket drop,
-        which is the safe trade.
+        so they still retry on those transient statuses.
         """
         session = requests.Session()
 
         retry_kwargs: dict[str, Any] = {
             "total": None,
             "status": 3,
-            "connect": 0,
+            "connect": 2,
             "read": 0,
             "other": 0,
             "backoff_factor": 0.5,

{athena_python_pptx-0.7.1 → athena_python_pptx-0.8.1}/pptx/commands.py

@@ -15,6 +15,7 @@ __athena_extension_since__: str = "0.1.0"
 
 from dataclasses import dataclass, field, asdict
 from typing import Any, Optional, Union
+from ._citations import normalize_citation_string
 from .errors import ValidationError
 from .typing import ShapeId, SlideId, TextRunPath, TextStyle
 
@@ -193,6 +194,38 @@ class SetRunStyle(Command):
             raise ValidationError("path must contain 'p' and 'r'", "path")
 
 
+@dataclass
+class SetRunText(Command):
+    """
+    Surgically set the text of a single run.
+
+    Unlike ``SetText`` (which replaces the whole text frame), this leaves the
+    run's style, hyperlink, sibling runs, and paragraph properties untouched
+    server-side. When ``path.r`` equals the paragraph's current run count the
+    server appends a run inheriting the previous run's style, matching the
+    ``add_run()`` + ``run.text = ...`` flow.
+
+    Args:
+        shape_id: ID of the shape containing the text
+        path: Path to the text run (paragraph index, run index)
+        text: New text content for the run
+    """
+
+    shape_id: ShapeId
+    path: TextRunPath
+    text: str
+
+    @property
+    def command_type(self) -> str:
+        return "SetRunText"
+
+    def validate(self) -> None:
+        if not self.shape_id:
+            raise ValidationError("shape_id is required", "shape_id")
+        if "p" not in self.path or "r" not in self.path:
+            raise ValidationError("path must contain 'p' and 'r'", "path")
+
+
 @dataclass
 class AddSlide(Command):
     """
@@ -772,6 +805,45 @@ class AddLinkedTable(Command):
             )
 
 
+def _validate_citation_string(citation_string: str) -> None:
+    try:
+        normalize_citation_string(citation_string)
+    except ValueError as exc:
+        raise ValidationError(str(exc), "citation_string") from exc
+
+
+def _validate_citation_source(
+    *,
+    source_ref: Optional[dict],
+    source_anchor: Optional[dict],
+    citation_string: Optional[str],
+) -> None:
+    if source_ref is None and citation_string is None:
+        raise ValidationError(
+            "source_ref or citation_string is required",
+            "source_ref",
+        )
+    if source_ref is not None and citation_string is not None:
+        raise ValidationError(
+            "source_ref and citation_string are mutually exclusive",
+            "citation_string",
+        )
+    if source_ref is None and source_anchor is not None:
+        raise ValidationError(
+            "source_anchor requires source_ref; encode the anchor in citation_string instead",
+            "source_anchor",
+        )
+    if source_ref is not None and (
+        not isinstance(source_ref, dict) or not source_ref.get("id")
+    ):
+        raise ValidationError(
+            "source_ref must be an AssetReference dict with an 'id' field",
+            "source_ref",
+        )
+    if citation_string is not None:
+        _validate_citation_string(citation_string)
+
+
 @dataclass
 class AddSlideCitation(Command):
     """Attach an Athena source citation to a whole slide.
@@ -793,19 +865,20 @@ class AddSlideCitation(Command):
             resolves the stable ``slideId`` from it and stores the resulting
             ``destinationAnchor.slideIndex`` as 1-based (display "Slide N") — do
             not read this wire value as a 1-based position.
-        source_ref: Source ``AssetReference`` JSON (``referenced='asset'`` +
-            ``id``); the asset the slide is sourced from.
+        source_ref: Optional source ``AssetReference`` JSON
+            (``referenced='asset'`` + ``id``); the asset the slide is sourced
+            from. Omit when passing a fully serialized ``citation_string``.
         source_anchor: Optional ``Anchor`` JSON within the source (e.g. a
             spreadsheet range); omit to cite the whole asset.
         display_value: Optional human-readable badge label.
-        citation_string: Optional pre-serialized source Spaces URL; the
-            server derives it from ``source_ref`` + ``source_anchor`` when
-            unset.
+        citation_string: Optional pre-serialized source Spaces URL. Prefer
+            this for sources/anchors the SDK does not model directly, such as
+            video/audio time ranges or external URLs.
         client_id: Client-provided ID (optional).
     """
 
     slide_index: int
-    source_ref: dict
+    source_ref: Optional[dict] = None
     source_anchor: Optional[dict] = None
     display_value: Optional[str] = None
     citation_string: Optional[str] = None
@@ -818,11 +891,11 @@ class AddSlideCitation(Command):
     def validate(self) -> None:
         if self.slide_index < 0:
             raise ValidationError("slide_index must be non-negative", "slide_index")
-        if not isinstance(self.source_ref, dict) or not self.source_ref.get("id"):
-            raise ValidationError(
-                "source_ref must be an AssetReference dict with an 'id' field",
-                "source_ref",
-            )
+        _validate_citation_source(
+            source_ref=self.source_ref,
+            source_anchor=self.source_anchor,
+            citation_string=self.citation_string,
+        )
 
 
 @dataclass
@@ -844,16 +917,19 @@ class AddShapeCitation(Command):
             the resulting ``destinationAnchor.slideIndex`` as 1-based (display
             "Slide N") — do not read this wire value as a 1-based position.
         shape_ids: Non-empty list of shape ids on that slide to cite.
-        source_ref: Source ``AssetReference`` JSON.
+        source_ref: Optional source ``AssetReference`` JSON. Omit when passing
+            a fully serialized ``citation_string``.
         source_anchor: Optional ``Anchor`` JSON within the source.
         display_value: Optional human-readable badge label.
-        citation_string: Optional pre-serialized source Spaces URL.
+        citation_string: Optional pre-serialized source Spaces URL. Prefer
+            this for sources/anchors the SDK does not model directly, such as
+            video/audio time ranges or external URLs.
         client_id: Client-provided ID (optional).
     """
 
     slide_index: int
     shape_ids: list[str]
-    source_ref: dict
+    source_ref: Optional[dict] = None
     source_anchor: Optional[dict] = None
     display_value: Optional[str] = None
     citation_string: Optional[str] = None
@@ -868,11 +944,11 @@ class AddShapeCitation(Command):
             raise ValidationError("slide_index must be non-negative", "slide_index")
         if not self.shape_ids:
             raise ValidationError("shape_ids must be non-empty", "shape_ids")
-        if not isinstance(self.source_ref, dict) or not self.source_ref.get("id"):
-            raise ValidationError(
-                "source_ref must be an AssetReference dict with an 'id' field",
-                "source_ref",
-            )
+        _validate_citation_source(
+            source_ref=self.source_ref,
+            source_anchor=self.source_anchor,
+            citation_string=self.citation_string,
+        )
 
 
 @dataclass
@@ -940,8 +1016,8 @@ class AddTable(Command):
             raise ValidationError("slide_index must be non-negative", "slide_index")
         if self.rows < 1 or self.rows > 100:
             raise ValidationError("rows must be between 1 and 100", "rows")
-        if self.cols < 1 or self.cols > 26:
-            raise ValidationError("cols must be between 1 and 26", "cols")
+        if self.cols < 1 or self.cols > 35:
+            raise ValidationError("cols must be between 1 and 35", "cols")
         if self.w_emu < 0:
             raise ValidationError(f"width must be >= 0 EMU (got {self.w_emu})", "w_emu")
         if self.h_emu < 0:
@@ -3226,6 +3302,7 @@ AnyCommand = Union[
     SetText,
     SetTransform,
     SetRunStyle,
+    SetRunText,
     AddSlide,
     DeleteSlide,
     DeleteShape,

{athena_python_pptx-0.7.1 → athena_python_pptx-0.8.1}/pptx/shapes/__init__.py

@@ -14,6 +14,7 @@ from urllib.parse import quote, urlparse
 
 import requests
 
+from .._citations import normalize_citation_string
 from ..commands import (
     AddTextBox, DeleteShape, SetTransform, AddShape as AddShapeCmd,
     SetShapeStyle, AddPicture as AddPictureCmd, AddOleObject as AddOleObjectCmd,
@@ -90,25 +91,49 @@ def _is_athena_url(url: str) -> bool:
 
 def _build_citation_wire(
     *,
-    source: "AssetReference",
+    source: "AssetReference | str | None",
     anchor: Optional["Anchor"],
-) -> tuple[dict, Optional[dict], None]:
+    citation_string: Optional[str] = None,
+) -> tuple[Optional[dict], Optional[dict], Optional[str]]:
     """Build the ``(source_ref, source_anchor, citation_string)`` wire triple
     for a citation command (Athena extension).
 
-    Type-checks ``source`` and duck-types the optional ``anchor`` exactly as
-    ``add_linked_ole_object`` does, then serializes both to their canonical
-    wire dicts. ``citation_string`` is left ``None`` so the studio server
-    derives the Spaces URL from ``source_ref`` + ``source_anchor`` — keeping a
-    single canonical serializer (matching agora's output) rather than a second
-    SDK-side one.
+    ``source`` can be a typed ``AssetReference`` for SDK-modeled assets or a
+    serialized citation URL for arbitrary sources/anchors. When a string source
+    is used, the anchor must already be encoded into that URL.
     """
     from .._references import AssetReference
 
-    if not isinstance(source, AssetReference):
+    if isinstance(source, str):
+        if (
+            citation_string is not None
+            and normalize_citation_string(citation_string)
+            != normalize_citation_string(source)
+        ):
+            raise ValueError("Pass citation_string either positionally or by keyword, not both")
+        citation_string = source
+        source_ref = None
+    elif source is None:
+        source_ref = None
+    elif isinstance(source, AssetReference):
+        if citation_string is not None:
+            raise ValueError("Pass either an AssetReference source or citation_string, not both")
+        source_ref = source.to_dict()
+    else:
         raise TypeError(
-            f"source must be an AssetReference; got {type(source).__name__}",
+            "source must be an AssetReference, citation string, or None; got "
+            f"{type(source).__name__}",
         )
+    normalized_citation_string = (
+        normalize_citation_string(citation_string)
+        if citation_string is not None
+        else None
+    )
+    if source_ref is None and normalized_citation_string is None:
+        raise ValueError("source or citation_string is required")
+    if source_ref is None and anchor is not None:
+        raise ValueError("anchor requires an AssetReference source; encode the anchor in citation_string instead")
+
     source_anchor: Optional[dict] = None
     if anchor is not None:
         if not hasattr(anchor, "to_dict"):
@@ -118,7 +143,7 @@ def _build_citation_wire(
                 f"{type(anchor).__name__}",
             )
         source_anchor = anchor.to_dict()
-    return source.to_dict(), source_anchor, None
+    return source_ref, source_anchor, normalized_citation_string
 
 
 def _add_citation_command(buffer: Optional["CommandBuffer"], cmd: Any) -> str:
@@ -6118,10 +6143,11 @@ class Shape:
 
     def add_citation(
         self,
-        source: "AssetReference",
+        source: "AssetReference | str | None" = None,
         *,
         anchor: Optional["Anchor"] = None,
         display_value: Optional[str] = None,
+        citation_string: Optional[str] = None,
     ) -> str:
         """Attach an Athena source citation to this shape.
 
@@ -6133,18 +6159,24 @@ class Shape:
         user-authored link.
 
         Args:
-            source: Source ``AssetReference`` from ``pptx._references`` — the
-                asset this shape is sourced from.
+            source: Source ``AssetReference`` from ``pptx._references`` or a
+                serialized citation URL such as
+                ``"/dashboard/spaces/?asset_ids=..."``.
             anchor: Optional ``Anchor`` within the source (e.g.
                 ``SheetRangeAnchor``); omit to cite the whole asset.
             display_value: Optional human-readable badge label.
+            citation_string: Optional serialized citation URL. Prefer this for
+                sources/anchors the SDK does not model directly, such as
+                video/audio time ranges or external URLs.
 
         Returns:
             The created citation id (``citation_<...>``).
 
         Raises:
-            TypeError: if ``source`` is not an ``AssetReference`` or ``anchor``
-                isn't an Anchor dataclass.
+            TypeError: if ``source`` is not an ``AssetReference``/string/None
+                or ``anchor`` isn't an Anchor dataclass.
+            ValueError: if neither ``source`` nor ``citation_string`` is
+                provided, or a string citation is malformed.
 
         Note (Athena extension):
             This method is NOT part of python-pptx. See
@@ -6155,6 +6187,7 @@ class Shape:
         source_ref, source_anchor, citation_string = _build_citation_wire(
             source=source,
             anchor=anchor,
+            citation_string=citation_string,
         )
         cmd = AddShapeCitationCmd(
             slide_index=self._slide.slide_index,

{athena_python_pptx-0.7.1 → athena_python_pptx-0.8.1}/pptx/slides.py

@@ -1066,6 +1066,14 @@ class Slide:
     def clear_shapes(self) -> int:
         """Delete every slide-local shape on this slide.
 
+        .. warning::
+            This permanently deletes user-drawn slide content — rectangles,
+            annotations, images, and anything else collaborators added that
+            is not part of a template. Do not use it to "reset" a slide
+            before editing: edit shapes in place instead (set placeholder
+            text, add the shapes you need). Only call ``clear_shapes`` when
+            the user explicitly asked for the slide to be cleared.
+
         Athena extension — python-pptx has no equivalent. Targets only
         slide-local shapes (the ones ``slide.shapes`` iterates). Inherited
         layout / master placeholders are left untouched because they
@@ -1073,13 +1081,10 @@ class Slide:
         server's ``DeleteShape`` handler raises for inherited ids, which
         would derail the whole batch.
 
-        Useful when iterating on a slide design and you want a blank
-        canvas to rebuild from — the previous workaround was a manual
-        ``for shape in slide.shapes: shape.delete()`` loop, which could
-        leave shapes layered on top of each other if any single delete
-        failed silently. ``clear_shapes`` queues every delete in one
-        batched ``post_commands`` call so partial failures surface
-        immediately as a :class:`RemoteError`.
+        Compared with a manual ``for shape in slide.shapes: shape.delete()``
+        loop, ``clear_shapes`` queues every delete in one batched
+        ``post_commands`` call, so partial failures surface immediately as a
+        :class:`RemoteError` instead of silently leaving some shapes behind.
 
         If shapes were created earlier in the session, ``clear_shapes``
         refreshes from the server snapshot first so every targeted
@@ -1087,16 +1092,12 @@ class Slide:
         client id. Buffered ``add_*`` calls keep their local ``shp_<uuid>``
         id until a refresh reconciles them; deleting by that client id makes
         the server raise ``Shape not found`` and roll back the whole atomic
-        batch (including any rebuild queued in the same session). The
+        batch (including any other commands queued in the same session). The
         refresh is skipped inside an open ``with prs.batch()`` so it doesn't
         flush a partial user batch.
 
         Returns:
             The number of shapes queued for deletion.
-
-        Example:
-            slide.clear_shapes()
-            slide.shapes.add_textbox(Inches(1), Inches(1), Inches(8), Inches(2))
         """
         from .commands import DeleteShape
 
@@ -1209,10 +1210,11 @@ class Slide:
     )
     def add_citation(
         self,
-        source: "AssetReference",
+        source: "AssetReference | str | None" = None,
         *,
         anchor: Optional["Anchor"] = None,
         display_value: Optional[str] = None,
+        citation_string: Optional[str] = None,
     ) -> str:
         """Attach an Athena source citation to this whole slide.
 
@@ -1224,11 +1226,15 @@ class Slide:
         user-authored link.
 
         Args:
-            source: Source ``AssetReference`` from ``pptx._references`` — the
-                asset this slide is sourced from.
+            source: Source ``AssetReference`` from ``pptx._references`` or a
+                serialized citation URL such as
+                ``"/dashboard/spaces/?asset_ids=..."``.
             anchor: Optional ``Anchor`` within the source (e.g.
                 ``SheetRangeAnchor``); omit to cite the whole asset.
             display_value: Optional human-readable badge label.
+            citation_string: Optional serialized citation URL. Prefer this for
+                sources/anchors the SDK does not model directly, such as
+                video/audio time ranges or external URLs.
 
         Returns:
             The created citation id (``citation_<...>``).
@@ -1243,6 +1249,7 @@ class Slide:
         source_ref, source_anchor, citation_string = _build_citation_wire(
             source=source,
             anchor=anchor,
+            citation_string=citation_string,
         )
         cmd = AddSlideCitation(
             slide_index=self._slide_index,

{athena_python_pptx-0.7.1 → athena_python_pptx-0.8.1}/pptx/text/__init__.py

@@ -5,14 +5,16 @@ Provides python-pptx-compatible TextFrame, Paragraph, and Run abstractions.
 """
 
 from __future__ import annotations
+
+import os
 from typing import TYPE_CHECKING, Any, Iterator, Optional, Union
 
 from ..commands import (
-    SetText, SetRunStyle, SetParagraphStyle, SetTextFrameProperties, FitText,
+    SetText, SetRunStyle, SetRunText, SetParagraphStyle, SetTextFrameProperties, FitText,
     # Tier A — most-requested upstream features (this wave)
     SetRunHyperlinkTarget, MeasureTextFit, ReplaceText,
 )
-from ..dml.color import RGBColor, ColorFormat, theme_color_to_scheme_name
+from ..dml.color import RGBColor, ColorFormat, scheme_name_to_theme_color, theme_color_to_scheme_name
 from ..errors import UnsupportedFeatureError
 from ..typing import ShapeId, TextStyle, TextFramePropertiesSnapshot
 from .._athena_extension import athena_extension
@@ -33,6 +35,34 @@ class PP_ALIGN:
     THAI_DISTRIBUTE = 'justify'
 
 
+# Wire style keys the SDK hydrates into typed Font state. Anything else the
+# server sends (``cap``, ``highlightColorHex``, ``highlightSchemeColor``,
+# future keys) is carried verbatim in ``Font._extra_style`` so full-frame
+# re-emits (run.text / paragraph.text / add_paragraph) don't silently strip
+# properties the SDK doesn't model.
+_TYPED_WIRE_STYLE_KEYS = frozenset({
+    "bold", "italic", "underline", "fontSizePt", "fontFamily", "fontRef",
+    "colorHex", "spacingPt", "strike", "strikethrough", "baseline",
+    "subscript", "superscript", "languageId", "schemeColor", "brightness",
+})
+
+
+def _baseline_from_wire(style: dict) -> Optional[int]:
+    """Derive the rPr ``baseline`` value from whichever wire spelling is present.
+
+    The studio normalizes the SDK's ``baseline`` into ``subscript`` /
+    ``superscript`` booleans on write, so snapshots can carry either form.
+    """
+    baseline = style.get("baseline")
+    if baseline is not None:
+        return int(baseline)
+    if style.get("subscript"):
+        return -25000  # python-pptx's default subscript baseline
+    if style.get("superscript"):
+        return 30000  # python-pptx's default superscript baseline
+    return None
+
+
 class _FontColorFormat(ColorFormat):
     """
     ColorFormat subclass that notifies the Font when color changes.
@@ -224,6 +254,11 @@ class Font:
         self._language_id: Optional[int] = (
             int(language_id) if language_id is not None else None
         )
+        # Wire style properties hydrated from the server that the SDK doesn't
+        # model as typed fields (``cap``, highlights, …). Carried verbatim so
+        # ``_build_style_dict`` reproduces them on full-frame re-emits instead
+        # of stripping them from the deck.
+        self._extra_style: dict[str, Any] = {}
         # Initialize color format with callback
         rgb = RGBColor.from_string(color_hex) if color_hex else None
         self._color_format = _FontColorFormat(self, rgb=rgb)
@@ -441,9 +476,36 @@ class Font:
         self._theme_brightness = brightness if brightness != 0 else None
         self._emit_style_change()
 
+    def _hydrate_theme_color(
+        self, scheme_name: Optional[str], brightness: Optional[float]
+    ) -> None:
+        """Seed theme-color state from a snapshot style without emitting.
+
+        Keeps the read path faithful (``font.color.theme_color`` /
+        ``color.brightness`` return the ingested values) and keeps full-frame
+        re-emits from stripping a theme-colored run down to the renderer
+        default.
+        """
+        if scheme_name is None:
+            return
+        self._theme_color_name = scheme_name
+        if brightness:
+            self._theme_brightness = brightness
+        theme_color = scheme_name_to_theme_color(scheme_name)
+        if theme_color is not None:
+            self._color_format._theme_color = theme_color
+            if brightness:
+                self._color_format._brightness = brightness
+
     def _build_style_dict(self) -> dict:
-        """Return a dict of non-None style properties for serialization."""
-        style: dict = {}
+        """Return a dict of non-None style properties for serialization.
+
+        Starts from ``_extra_style`` — hydrated wire properties the SDK
+        doesn't model — then overlays the typed fields, so a full-frame
+        re-emit reproduces the run's stored style rather than a lossy
+        subset of it.
+        """
+        style: dict = dict(self._extra_style)
         if self._color_hex is not None:
             style["colorHex"] = self._color_hex
         if self._theme_color_name is not None:
@@ -875,17 +937,38 @@ class Run:
         self._paragraph = paragraph
         self._index = index
         self._text = text
+        style_dict: dict[str, Any] = dict(style) if style else {}
+        strike = style_dict.get("strike")
+        if strike is None:
+            # The studio stores the normalized ``strikethrough`` spelling.
+            # Re-serialization emits the wire spelling ``strike``; the studio's
+            # ``normalizeRunStyleWireFields`` maps it back to ``strikethrough``
+            # at write time, so the stored spelling stays stable across
+            # hydrate → re-emit round-trips.
+            strike = style_dict.get("strikethrough")
         self._font = Font(
             self,
-            bold=style.get("bold") if style else None,
-            italic=style.get("italic") if style else None,
-            underline=style.get("underline") if style else None,
-            size=int(style.get("fontSizePt", 0) * 12700) if style and style.get("fontSizePt") else None,
-            name=style.get("fontFamily") if style else None,
-            font_ref=style.get("fontRef") if style else None,
-            color_hex=style.get("colorHex") if style else None,
-            spacing_pt=style.get("spacingPt") if style else None,
+            bold=style_dict.get("bold"),
+            italic=style_dict.get("italic"),
+            underline=style_dict.get("underline"),
+            size=int(style_dict.get("fontSizePt", 0) * 12700) if style_dict.get("fontSizePt") else None,
+            name=style_dict.get("fontFamily"),
+            font_ref=style_dict.get("fontRef"),
+            color_hex=style_dict.get("colorHex"),
+            spacing_pt=style_dict.get("spacingPt"),
+            strike=strike,
+            baseline=_baseline_from_wire(style_dict),
+            language_id=style_dict.get("languageId"),
+        )
+        self._font._hydrate_theme_color(
+            style_dict.get("schemeColor"), style_dict.get("brightness")
         )
+        # Everything the SDK doesn't model as a typed field survives verbatim
+        # so re-serialization is faithful to the stored run style.
+        self._font._extra_style = {
+            key: value for key, value in style_dict.items()
+            if key not in _TYPED_WIRE_STYLE_KEYS
+        }
         self._hyperlink = Hyperlink(self, address=hyperlink_address, tooltip=hyperlink_tooltip)
 
     @property
@@ -895,12 +978,43 @@ class Run:
 
     @text.setter
     def text(self, value: str) -> None:
-        """Set text content. Note: This currently sets all text in the shape."""
-        # For Phase 1, we only support setting full text content
-        # Individual run edits would require more complex tracking
+        """Set text content surgically — only this run's text changes.
+
+        Emits a ``SetRunText`` command so the run's style, hyperlink, sibling
+        runs, and paragraph properties stay untouched in the deck, instead of
+        re-serializing the whole text frame from (potentially partially
+        hydrated) local state.
+        """
         self._text = value
-        self._paragraph._text_frame._set_full_text(
-            self._paragraph._text_frame._get_full_text()
+        self._emit_run_text()
+
+    def _emit_run_text(self) -> None:
+        """Emit a surgical ``SetRunText`` for this run.
+
+        Falls back to the legacy whole-frame re-emit when the run can't be
+        located in its text frame's current structure (detached proxy) or
+        when ``ATHENA_PPTX_LEGACY_RUN_TEXT`` is set (escape hatch for talking
+        to a studio that predates the SetRunText command).
+        """
+        text_frame = self._paragraph._text_frame
+        if text_frame._buffer is None:
+            return
+        if os.environ.get("ATHENA_PPTX_LEGACY_RUN_TEXT"):
+            text_frame._set_full_text(text_frame._get_full_text())
+            return
+        try:
+            paragraph_index = text_frame._paragraphs.index(self._paragraph)
+            run_index = self._paragraph._runs.index(self)
+        except ValueError:
+            text_frame._set_full_text(text_frame._get_full_text())
+            return
+        text_frame._preview_text = text_frame._get_full_text()
+        text_frame._buffer.add(
+            SetRunText(
+                shape_id=text_frame._shape_id,
+                path={"p": paragraph_index, "r": run_index},
+                text=self._text,
+            )
         )
 
     @property
@@ -978,44 +1092,32 @@ class Run:
     def upper(self) -> None:
         """Convert run text to uppercase."""
         self._text = self._text.upper()
-        self._paragraph._text_frame._set_full_text(
-            self._paragraph._text_frame._get_full_text()
-        )
+        self._emit_run_text()
 
     def lower(self) -> None:
         """Convert run text to lowercase."""
         self._text = self._text.lower()
-        self._paragraph._text_frame._set_full_text(
-            self._paragraph._text_frame._get_full_text()
-        )
+        self._emit_run_text()
 
     def capitalize(self) -> None:
         """Capitalize first letter of run text."""
         self._text = self._text.capitalize()
-        self._paragraph._text_frame._set_full_text(
-            self._paragraph._text_frame._get_full_text()
-        )
+        self._emit_run_text()
 
     def title(self) -> None:
         """Convert run text to title case."""
         self._text = self._text.title()
-        self._paragraph._text_frame._set_full_text(
-            self._paragraph._text_frame._get_full_text()
-        )
+        self._emit_run_text()
 
     def strip(self) -> None:
         """Remove leading and trailing whitespace from run text."""
         self._text = self._text.strip()
-        self._paragraph._text_frame._set_full_text(
-            self._paragraph._text_frame._get_full_text()
-        )
+        self._emit_run_text()
 
     def clear(self) -> None:
         """Clear the run's text content."""
         self._text = ""
-        self._paragraph._text_frame._set_full_text(
-            self._paragraph._text_frame._get_full_text()
-        )
+        self._emit_run_text()
 
     def __len__(self) -> int:
         """Return length of text (allows len(run))."""
@@ -1059,9 +1161,7 @@ class Run:
         count = self._text.count(old)
         if count > 0:
             self._text = self._text.replace(old, new)
-            self._paragraph._text_frame._set_full_text(
-                self._paragraph._text_frame._get_full_text()
-            )
+            self._emit_run_text()
         return count
 
     def startswith(self, prefix: str) -> bool:

{athena_python_pptx-0.7.1 → athena_python_pptx-0.8.1}/pptx/typing.py

@@ -107,6 +107,7 @@ CommandType = Literal[
     "SetText",
     "SetTransform",
     "SetRunStyle",
+    "SetRunText",
     "AddSlide",
     "DeleteSlide",
     "DeleteShape",

{athena_python_pptx-0.7.1 → athena_python_pptx-0.8.1}/pyproject.toml

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