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

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

@@ -2,6 +2,68 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.9.0 — eager validation, table overflow diagnostics, and text caps
+
+Publishes the SDK changes already deployed with PPTX Studio after 0.8.1.
+
+- Invalid buffered commands now raise at the originating SDK call instead of
+  waiting until `flush()`. Validation errors include command context such as
+  the slide index, shape ID, or name, making the offending edit actionable
+  without sacrificing the final send-time validation backstop.
+- `Slide.validate()` now warns when table-cell text is likely to wrap beyond
+  the available column width. The offline heuristic accounts for cell margins,
+  font size, merged-column spans, digits, and common punctuation.
+- `Font.cap` and the `TextCap` type expose PowerPoint's native `none`, `all`,
+  and `small` capitalization modes. The value hydrates from existing decks and
+  survives full-frame text re-emission.
+
+The public text-capitalization surface makes this a minor release.
+
+## 0.8.1 — version-string fix (re-cut of 0.8.0)
+
+Functionally identical to 0.8.0. The 0.8.0 wheel was auto-published from a
+tree where `pptx/__init__.py::__version__` was never bumped off `0.7.1`, so
+`import pptx; pptx.__version__` reported `0.7.1` even though the wheel
+contained the surgical-`SetRunText` + faithful-hydration code. PyPI versions
+are immutable, so 0.8.1 re-cuts the release with the corrected `__version__`
+string. No behavior change vs 0.8.0; use 0.8.1 (the `presentation-exec:v55`
+snapshot bundles it).
+
+## 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.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-pptx
-Version: 0.7.1
+Version: 0.9.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.7.1 → athena_python_pptx-0.9.0}/docs/API_PARITY_EXCEPTIONS.md

@@ -164,6 +164,19 @@ takes the rest of the queued edits down with it.
 
 These properties/methods were added because LLM agents (Claude, GPT, etc.) frequently generate code using these patterns. Without them, agent-generated table code fails at runtime.
 
+### `Font.cap` — PowerPoint-native capitalization mode
+
+The SDK exposes PowerPoint's OOXML run capitalization property as
+`run.font.cap`, accepting `"none"`, `"all"`, or `"small"`. Stock
+python-pptx 1.0.2 does not expose `a:rPr/@cap`, but the Athena SDK needs a
+typed surface so template-authored all-caps and small-caps text survives
+agent edits and full-frame text re-emission.
+
+```python
+run.font.cap = "all"
+assert run.font.cap == "all"
+```
+
 ### `TableCell` — RGB tuple aliases
 
 | Property | Type | Maps to | Why |

{athena_python_pptx-0.7.1 → athena_python_pptx-0.9.0}/pptx/__init__.py

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

athena_python_pptx-0.9.0/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.9.0}/pptx/batching.py

@@ -19,7 +19,7 @@ from threading import local
 from typing import TYPE_CHECKING, Any, Generator, Optional
 
 from . import _ptc
-from .commands import AnyCommand
+from .commands import AnyCommand, validate_command
 from .errors import BatchPartialError
 from .typing import CommandsResponse
 
@@ -234,12 +234,21 @@ class CommandBuffer:
 
         Returns:
             Response if sent immediately, None if buffered
+
+        Raises:
+            ValidationError: If the command's parameters are invalid. Raised
+                here — at the API call that created the command — rather than
+                at the eventual ``flush()``, so the traceback points at the
+                offending user line and the invalid command is never buffered
+                (a flush-time failure would discard the whole pending batch).
         """
         # Surface any error captured by the background auto-flush timer
         # before accepting more work — otherwise the user could continue
         # queueing commands on top of a partially-failed batch.
         self._raise_deferred_error()
 
+        validate_command(command)
+
         # PTC begin: emit only for commands in the allow-list. Other
         # commands still flow through the buffer (and through the batched
         # HTTP POST), they just don't produce a sub-tool-card. ``emit_end``
@@ -365,7 +374,7 @@ class CommandBuffer:
         if len(chunks) > 1:
             try:
                 for command in commands:
-                    command.validate()
+                    validate_command(command)
             except Exception:
                 with self._commands_lock:
                     self._commands = commands + self._commands

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

@@ -37,7 +37,7 @@ from .typing import (
     ExportStatus,
     RenderStatus,
 )
-from .commands import AnyCommand
+from .commands import AnyCommand, validate_command
 
 
 SDK_VERSION = "0.1.0"
@@ -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,
@@ -645,9 +647,11 @@ class Client:
         Returns:
             Response with applied status, created IDs, and optional snapshot
         """
-        # Validate all commands
+        # Validate all commands (backstop — CommandBuffer.add validates
+        # eagerly at the creating call site; this covers direct client use
+        # and commands mutated after they were buffered).
         for cmd in commands:
-            cmd.validate()
+            validate_command(cmd)
 
         payload = {
             "client": {"type": SDK_CLIENT_TYPE, "version": SDK_VERSION},

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

@@ -14,7 +14,8 @@ __athena_extension_description__: str = (
 __athena_extension_since__: str = "0.1.0"
 
 from dataclasses import dataclass, field, asdict
-from typing import Any, Optional, Union
+from typing import Any, ClassVar, Optional, Union
+from ._citations import normalize_citation_string
 from .errors import ValidationError
 from .typing import ShapeId, SlideId, TextRunPath, TextStyle
 
@@ -38,6 +39,26 @@ class Command:
         components = snake_str.split("_")
         return components[0] + "".join(x.title() for x in components[1:])
 
+    # Identifying fields surfaced in validation errors so a failure names the
+    # exact command instance ("AddShape(slide_index=4, name='Card 2')") rather
+    # than only the bad value.
+    _CONTEXT_FIELDS: ClassVar[tuple[str, ...]] = (
+        "slide_index",
+        "index",
+        "shape_id",
+        "name",
+    )
+
+    def context_label(self) -> str:
+        """Short human-readable identity for this command instance."""
+        parts: list[str] = []
+        for field_name in self._CONTEXT_FIELDS:
+            value = getattr(self, field_name, None)
+            if value is not None:
+                parts.append(f"{field_name}={value!r}")
+        label = type(self).__name__
+        return f"{label}({', '.join(parts)})" if parts else label
+
     def validate(self) -> None:
         """Validate command parameters. Raises ValidationError if invalid."""
         pass
@@ -48,6 +69,23 @@ class Command:
         raise NotImplementedError
 
 
+def validate_command(command: "Command") -> None:
+    """Validate ``command``, prefixing any ValidationError with its identity.
+
+    The bare per-command ``validate()`` messages name only the bad field/value
+    ("height must be >= 0 EMU"); when validation runs away from the creating
+    call site (batched flush, multi-command POST) that alone can't be traced
+    back to a shape or slide. Every SDK-internal validation path goes through
+    this wrapper so the error always carries the command context.
+    """
+    try:
+        command.validate()
+    except ValidationError as exc:
+        raise ValidationError(
+            f"{command.context_label()}: {exc.message}", exc.field
+        ) from None
+
+
 @dataclass
 class AddTextBox(Command):
     """
@@ -193,6 +231,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 +842,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 +902,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 +928,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 +954,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 +981,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 +1053,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 +3339,7 @@ AnyCommand = Union[
     SetText,
     SetTransform,
     SetRunStyle,
+    SetRunText,
     AddSlide,
     DeleteSlide,
     DeleteShape,

{athena_python_pptx-0.7.1 → athena_python_pptx-0.9.0}/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,