athena-python-pptx 0.4.3__tar.gz → 0.5.0__tar.gz

{athena_python_pptx-0.4.3 → athena_python_pptx-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-pptx
-Version: 0.4.3
+Version: 0.5.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
@@ -21,6 +21,7 @@ Classifier: Topic :: Office/Business :: Office Suites
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
+Requires-Dist: athena-references>=0.1.0
 Requires-Dist: requests>=2.28.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.0; extra == 'dev'

{athena_python_pptx-0.4.3 → athena_python_pptx-0.5.0}/docs/API_PARITY_EXCEPTIONS.md

@@ -1347,3 +1347,91 @@ upstream surface preserved, additions tagged with
 
 Total Tier B closures: 16 implemented, 6 audited (already
 applicable or N/A by REST architecture).
+
+---
+
+## Athena Source Citations — SDK-native (added post-v0.4.3)
+
+These methods are **additions** to python-pptx, not deviations — python-pptx
+has no concept of Athena asset references or citations. The user has approved
+SDK-native citations. They let an agent attach an Athena source citation to a
+slide or shape; the studio server applies the citation into the deck's
+`citations` Y.Array as a unified record that is byte-compatible with agora's
+`build_deck_source_citation`
+(`agora/agora/web/api/asset/utils/presentations/citation_operations.py`) and the
+Olympus `Citation` type (`olympus/src/store/citation.types.ts`). So the deck's
+existing badge + sidebar rendering surfaces agent-authored citations identically
+to user-authored ones.
+
+A citation record is:
+
+```jsonc
+{
+  "id": "citation_<uuid12>",
+  "destinationAnchor": { "type": "slide", "slideId": "...", "slideIndex": 0 },
+  // or { "type": "shape", "slideId": "...", "slideIndex": 0, "shapeIds": ["..."] }
+  "citation_string": "<source Spaces URL>",
+  "displayValue": "Q4 Sales",        // optional
+  "active": true,
+  "created_at": "2026-…T…Z",
+  "created_by": "Athena"
+}
+```
+
+`citation_string` is the serialized source `AssetReference` (whole asset, or
+asset + sub-anchor) in Spaces-URL form. The SDK leaves it to the server to
+derive (from `source_ref` + `source_anchor`) so a single canonical serializer
+produces it.
+
+### `Slide.add_citation(source, *, anchor=None, display_value=None) -> str`
+
+Attach a citation to a whole slide. Emits `AddSlideCitation`; the server
+resolves `slideId` from `slideIndex` and writes a `slide` destination anchor.
+Returns the created citation id.
+
+```python
+from pptx._references import AssetReference, SheetRangeAnchor
+
+cid = slide.add_citation(
+    AssetReference(id="asset_xlsx_abc123"),
+    anchor=SheetRangeAnchor(sheet_id=0, range="A1:F20"),  # optional
+    display_value="Q4 Sales · A1:F20",                    # optional
+)
+```
+
+### `Shape.cite(source, *, anchor=None, display_value=None) -> str`
+
+Shape-scoped citation — emits `AddShapeCitation` carrying this shape's id, so
+the server writes a `shape` destination anchor with `shapeIds`. Returns the
+created citation id.
+
+```python
+shape = slide.shapes.add_textbox(Inches(1), Inches(1), Inches(4), Inches(1))
+cid = shape.cite(AssetReference(id="asset_doc_xyz"))
+```
+
+### `Slide.remove_citation(citation_id, *, soft=True)` / `Presentation.remove_citation(citation_id, *, soft=True)`
+
+Remove a citation from the deck by id. Citations are deck-scoped, so both
+spellings emit the same `RemoveCitation` command — `Slide.remove_citation` is a
+convenience when an agent already holds a slide. `soft` (default) flips
+`active` to `False` in place (reversible, readers skip inactive citations);
+`soft=False` splices the record out of the array.
+
+```python
+prs.remove_citation(cid)            # soft delete (default)
+slide.remove_citation(cid, soft=False)  # hard splice
+```
+
+### `pptx._references` re-homed on the shared `athena-references` package
+
+`pptx._references` now re-exports the anchor + version-policy dataclasses from
+the shared `athena-references` package (the single Python source of truth, kept
+in lockstep with `packages/references` and `agora/agora/utils/asset_references`).
+The `to_dict()` wire output of the four anchors the module historically exported
+(`SheetCellAnchor` / `SheetRangeAnchor` / `SheetTableAnchor` / `SlideAnchor`),
+plus `VersionPolicyLatest` / `VersionPolicyPinned`, is byte-identical to the
+prior in-module definitions. `AssetReference` remains a thin in-module wrapper
+that additionally accepts a plain `dict` `meta` (the historical SDK shape) and
+serializes it verbatim, preserving byte-identical `to_dict()` output for
+existing callers.

{athena_python_pptx-0.4.3 → athena_python_pptx-0.5.0}/pptx/__init__.py

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

athena_python_pptx-0.5.0/pptx/_references.py

@@ -0,0 +1,73 @@
+"""Thin Python mirror of the @athenaintel/references TypeScript package.
+
+Used by the linked-OLE / linked-table / citation SDK methods (Athena
+extensions beyond the python-pptx surface). Mirrors only what the SDK needs to
+construct ``AssetReference`` + ``Anchor`` payloads — full reference
+serialization (URI / URL / Spaces format) is server-side.
+
+The anchor + version-policy dataclasses are re-exported from the shared
+``athena-references`` package (the single Python source of truth, kept in
+lockstep with ``packages/references`` and ``agora/agora/utils/asset_references``).
+``AssetReference`` is a thin back-compat wrapper that additionally accepts a
+plain ``dict`` ``meta`` (the historical SDK shape) and serializes it verbatim,
+preserving byte-identical ``to_dict()`` output for existing SDK callers.
+
+Note (Athena extension):
+    This module is NOT part of python-pptx — it exists to construct
+    Athena-asset references for the SDK's linked-object / citation methods.
+"""
+
+from __future__ import annotations
+
+__athena_extension_module__: bool = True
+__athena_extension_description__: str = (
+    "Cross-studio asset reference types (Athena studio-linking, no upstream)."
+)
+__athena_extension_since__: str = "0.1.71"
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from athena_references import (
+    Anchor,
+    SheetCellAnchor,
+    SheetRangeAnchor,
+    SheetTableAnchor,
+    SlideAnchor,
+    VersionPolicy,
+    VersionPolicyLatest,
+    VersionPolicyPinned,
+)
+
+
+@dataclass
+class AssetReference:
+    """Athena asset reference. ``id`` is the asset UUID.
+
+    Re-homes the canonical anchor types onto the shared ``athena-references``
+    package while preserving the historical SDK contract that ``meta`` may be a
+    plain ``dict`` (serialized verbatim) in addition to ``None``.
+    """
+
+    id: str
+    meta: Optional[dict[str, Any]] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the canonical wire shape."""
+        out: dict[str, Any] = {"referenced": "asset", "id": self.id}
+        if self.meta is not None:
+            out["meta"] = dict(self.meta)
+        return out
+
+
+__all__ = [
+    "AssetReference",
+    "SheetCellAnchor",
+    "SheetRangeAnchor",
+    "SheetTableAnchor",
+    "SlideAnchor",
+    "Anchor",
+    "VersionPolicyLatest",
+    "VersionPolicyPinned",
+    "VersionPolicy",
+]

{athena_python_pptx-0.4.3 → athena_python_pptx-0.5.0}/pptx/commands.py

@@ -772,6 +772,131 @@ class AddLinkedTable(Command):
             )
 
 
+@dataclass
+class AddSlideCitation(Command):
+    """Attach an Athena source citation to a whole slide.
+
+    Records that a deck slide is sourced from another Athena asset. The
+    studio server appends a unified citation record to the deck's
+    ``citations`` Y.Array, byte-compatible with agora's
+    ``build_deck_source_citation`` and the Olympus ``Citation`` type, so the
+    deck's existing badge + sidebar rendering surfaces agent-authored links
+    identically to user-authored ones.
+
+    Note (Athena extension):
+        This command is NOT part of python-pptx. See
+        ``docs/API_PARITY_EXCEPTIONS.md`` for the deviation rationale.
+
+    Args:
+        slide_index: Zero-based index of the cited slide.
+        source_ref: Source ``AssetReference`` JSON (``referenced='asset'`` +
+            ``id``); the asset the slide is sourced from.
+        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.
+        client_id: Client-provided ID (optional).
+    """
+
+    slide_index: int
+    source_ref: dict
+    source_anchor: Optional[dict] = None
+    display_value: Optional[str] = None
+    citation_string: Optional[str] = None
+    client_id: Optional[str] = None
+
+    @property
+    def command_type(self) -> str:
+        return "AddSlideCitation"
+
+    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",
+            )
+
+
+@dataclass
+class AddShapeCitation(Command):
+    """Attach an Athena source citation to one or more shapes on a slide.
+
+    Shape-scoped analogue of :class:`AddSlideCitation`. The deck citation's
+    ``destinationAnchor`` is a ``shape`` anchor carrying ``shapeIds`` so the
+    canvas can draw per-shape highlight overlays.
+
+    Note (Athena extension):
+        This command is NOT part of python-pptx. See
+        ``docs/API_PARITY_EXCEPTIONS.md`` for the deviation rationale.
+
+    Args:
+        slide_index: Zero-based index of the slide the shapes live on.
+        shape_ids: Non-empty list of shape ids on that slide to cite.
+        source_ref: Source ``AssetReference`` JSON.
+        source_anchor: Optional ``Anchor`` JSON within the source.
+        display_value: Optional human-readable badge label.
+        citation_string: Optional pre-serialized source Spaces URL.
+        client_id: Client-provided ID (optional).
+    """
+
+    slide_index: int
+    shape_ids: list[str]
+    source_ref: dict
+    source_anchor: Optional[dict] = None
+    display_value: Optional[str] = None
+    citation_string: Optional[str] = None
+    client_id: Optional[str] = None
+
+    @property
+    def command_type(self) -> str:
+        return "AddShapeCitation"
+
+    def validate(self) -> None:
+        if self.slide_index < 0:
+            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",
+            )
+
+
+@dataclass
+class RemoveCitation(Command):
+    """Remove a citation from a deck's ``citations`` Y.Array by id.
+
+    ``soft`` (default) flips the record's ``active`` flag to ``False`` in
+    place (readers skip inactive citations; Keryx rollback can restore it);
+    ``soft=False`` splices the record out of the array.
+
+    Note (Athena extension):
+        This command is NOT part of python-pptx. See
+        ``docs/API_PARITY_EXCEPTIONS.md`` for the deviation rationale.
+
+    Args:
+        citation_id: Id of the citation record to remove.
+        soft: Soft-delete (flip ``active``) when ``True`` (default); hard
+            splice when ``False``.
+    """
+
+    citation_id: str
+    soft: bool = True
+
+    @property
+    def command_type(self) -> str:
+        return "RemoveCitation"
+
+    def validate(self) -> None:
+        if not self.citation_id:
+            raise ValidationError("citation_id is required", "citation_id")
+
+
 @dataclass
 class AddTable(Command):
     """
@@ -3098,6 +3223,9 @@ AnyCommand = Union[
     AddOleObject,
     AddLinkedOleObject,
     AddLinkedTable,
+    AddSlideCitation,
+    AddShapeCitation,
+    RemoveCitation,
     AddTable,
     SetTableCell,
     SetTableRowCount,

{athena_python_pptx-0.4.3 → athena_python_pptx-0.5.0}/pptx/presentation.py

@@ -871,6 +871,28 @@ class Presentation:
             for i, slide in enumerate(self._slides._slides):
                 slide._slide_index = i
 
+    @athena_extension(
+        description=(
+            "Presentation.remove_citation — remove an Athena source citation "
+            "from the deck by id. Not in python-pptx."
+        ),
+    )
+    def remove_citation(self, citation_id: str, *, soft: bool = True) -> None:
+        """Remove an Athena source citation from the deck by id.
+
+        Citations are deck-scoped records in the deck's ``citations`` Y.Array.
+        ``soft`` (default) flips the record's ``active`` flag to ``False`` in
+        place (readers skip inactive citations; Keryx rollback can restore it);
+        ``soft=False`` splices the record out of the array.
+
+        Note (Athena extension):
+            This method is NOT part of python-pptx. See
+            ``docs/API_PARITY_EXCEPTIONS.md`` for the deviation rationale.
+        """
+        from .commands import RemoveCitation
+
+        self._buffer.add(RemoveCitation(citation_id=citation_id, soft=soft))
+
     @athena_extension(
         issue=1036,
         since="0.1.81",

{athena_python_pptx-0.4.3 → athena_python_pptx-0.5.0}/pptx/shapes/__init__.py

@@ -88,6 +88,61 @@ def _is_athena_url(url: str) -> bool:
     return any(host == suffix or host.endswith("." + suffix) for suffix in _ATHENA_URL_SUFFIXES)
 
 
+def _build_citation_wire(
+    *,
+    source: "AssetReference",
+    anchor: Optional["Anchor"],
+) -> tuple[dict, Optional[dict], None]:
+    """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.
+    """
+    from .._references import AssetReference
+
+    if not isinstance(source, AssetReference):
+        raise TypeError(
+            f"source must be an AssetReference; got {type(source).__name__}",
+        )
+    source_anchor: Optional[dict] = None
+    if anchor is not None:
+        if not hasattr(anchor, "to_dict"):
+            raise TypeError(
+                "anchor must be an Anchor dataclass (SheetRangeAnchor, "
+                "SlideAnchor, etc.) — got "
+                f"{type(anchor).__name__}",
+            )
+        source_anchor = anchor.to_dict()
+    return source.to_dict(), source_anchor, None
+
+
+def _add_citation_command(buffer: Optional["CommandBuffer"], cmd: Any) -> str:
+    """Enqueue a citation command and return the created citation id.
+
+    Reads the id back from the command response
+    (``created.citationIds[0]`` / ``created.citationId``) when the buffer
+    flushes synchronously; falls back to the command's ``client_id`` (or empty
+    string) when the response doesn't carry one (e.g. queued in a batch).
+    """
+    if buffer is None:
+        return getattr(cmd, "client_id", "") or ""
+    response = buffer.add(cmd)
+    if response and response.get("created"):
+        created = response["created"]
+        citation_ids = created.get("citationIds")
+        if citation_ids:
+            return citation_ids[0]
+        citation_id = created.get("citationId")
+        if citation_id:
+            return citation_id
+    return getattr(cmd, "client_id", "") or ""
+
+
 # Default render scale for xlsx-range screenshots embedded in slides.
 # scale=3 matches xlsx-studio's ``range-as-asset`` default — slide inserts
 # sit at 6–9″ widths, where scale=2 leaves text visibly soft.
@@ -5899,6 +5954,56 @@ class Shape:
             if isinstance(by_id, dict):
                 by_id.pop(self._shape_id, None)
 
+    def cite(
+        self,
+        source: "AssetReference",
+        *,
+        anchor: Optional["Anchor"] = None,
+        display_value: Optional[str] = None,
+    ) -> str:
+        """Attach an Athena source citation to this shape.
+
+        Records that this shape is sourced from another Athena asset. The
+        studio server appends a unified citation record to the deck's
+        ``citations`` array (byte-compatible with agora's
+        ``build_deck_source_citation`` and the Olympus ``Citation`` type), so
+        the deck's badge + sidebar rendering surfaces it identically to a
+        user-authored link.
+
+        Args:
+            source: Source ``AssetReference`` from ``pptx._references`` — the
+                asset this shape is sourced from.
+            anchor: Optional ``Anchor`` within the source (e.g.
+                ``SheetRangeAnchor``); omit to cite the whole asset.
+            display_value: Optional human-readable badge label.
+
+        Returns:
+            The created citation id (``citation_<...>``).
+
+        Raises:
+            TypeError: if ``source`` is not an ``AssetReference`` or ``anchor``
+                isn't an Anchor dataclass.
+
+        Note (Athena extension):
+            This method is NOT part of python-pptx. See
+            ``docs/API_PARITY_EXCEPTIONS.md`` for the deviation rationale.
+        """
+        from ..commands import AddShapeCitation as AddShapeCitationCmd
+
+        source_ref, source_anchor, citation_string = _build_citation_wire(
+            source=source,
+            anchor=anchor,
+        )
+        cmd = AddShapeCitationCmd(
+            slide_index=self._slide.slide_index,
+            shape_ids=[self._shape_id],
+            source_ref=source_ref,
+            source_anchor=source_anchor,
+            display_value=display_value,
+            citation_string=citation_string,
+        )
+        return _add_citation_command(self._buffer, cmd)
+
     # -------------------------------------------------------------------------
     # Fill and line styling
     # -------------------------------------------------------------------------

{athena_python_pptx-0.4.3 → athena_python_pptx-0.5.0}/pptx/slides.py

@@ -21,6 +21,7 @@ from .typing import DeckSnapshot, ElementSnapshot, SlideId, SlideSnapshot
 if TYPE_CHECKING:
     from .batching import CommandBuffer
     from .presentation import Presentation
+    from ._references import AssetReference, Anchor
 
 
 def _parse_layout_index(layout_path: Optional[str]) -> Optional[int]:
@@ -1167,6 +1168,84 @@ class Slide:
                     )
         return warnings
 
+    @athena_only(
+        description=(
+            "Slide.add_citation — attach an Athena source citation to a whole "
+            "slide. Not in python-pptx."
+        ),
+    )
+    def add_citation(
+        self,
+        source: "AssetReference",
+        *,
+        anchor: Optional["Anchor"] = None,
+        display_value: Optional[str] = None,
+    ) -> str:
+        """Attach an Athena source citation to this whole slide.
+
+        Records that this slide is sourced from another Athena asset. The
+        studio server appends a unified citation record to the deck's
+        ``citations`` array (byte-compatible with agora's
+        ``build_deck_source_citation`` and the Olympus ``Citation`` type), so
+        the deck's badge + sidebar rendering surfaces it identically to a
+        user-authored link.
+
+        Args:
+            source: Source ``AssetReference`` from ``pptx._references`` — the
+                asset this slide is sourced from.
+            anchor: Optional ``Anchor`` within the source (e.g.
+                ``SheetRangeAnchor``); omit to cite the whole asset.
+            display_value: Optional human-readable badge label.
+
+        Returns:
+            The created citation id (``citation_<...>``).
+
+        Note (Athena extension):
+            This method is NOT part of python-pptx. See
+            ``docs/API_PARITY_EXCEPTIONS.md`` for the deviation rationale.
+        """
+        from .commands import AddSlideCitation
+        from .shapes import _add_citation_command, _build_citation_wire
+
+        source_ref, source_anchor, citation_string = _build_citation_wire(
+            source=source,
+            anchor=anchor,
+        )
+        cmd = AddSlideCitation(
+            slide_index=self._slide_index,
+            source_ref=source_ref,
+            source_anchor=source_anchor,
+            display_value=display_value,
+            citation_string=citation_string,
+        )
+        return _add_citation_command(self._buffer, cmd)
+
+    @athena_only(
+        description=(
+            "Slide.remove_citation — remove a citation from the deck by id. "
+            "Not in python-pptx."
+        ),
+    )
+    def remove_citation(self, citation_id: str, *, soft: bool = True) -> None:
+        """Remove a citation from the deck's ``citations`` array by id.
+
+        ``soft`` (default) flips the record's ``active`` flag to ``False`` in
+        place (readers skip inactive citations; Keryx rollback can restore it);
+        ``soft=False`` splices the record out of the array.
+
+        Citations are deck-scoped, so this is identical to
+        :meth:`Presentation.remove_citation`; it's exposed on ``Slide`` for
+        convenience when an agent is already holding a slide.
+
+        Note (Athena extension):
+            This method is NOT part of python-pptx. See
+            ``docs/API_PARITY_EXCEPTIONS.md`` for the deviation rationale.
+        """
+        from .commands import RemoveCitation
+
+        if self._buffer is not None:
+            self._buffer.add(RemoveCitation(citation_id=citation_id, soft=soft))
+
     @property
     def name(self) -> Optional[str]:
         """

{athena_python_pptx-0.4.3 → athena_python_pptx-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-pptx"
-version = "0.4.3"
+version = "0.5.0"
 description = "Drop-in replacement for python-pptx that connects to PPTX Studio for real-time collaboration"
 readme = "README.md"
 license = "MIT"
@@ -36,6 +36,11 @@ classifiers = [
 ]
 dependencies = [
     "requests>=2.28.0",
+    # Canonical Python source of truth for AssetReference + the Anchor union,
+    # re-exported by pptx/_references.py. Deploy follow-up: Dockerfile.prod
+    # vendors this wheel via `pip download --no-deps athena-references` (the
+    # presentation-exec sandbox has no PyPI access at build time).
+    "athena-references>=0.1.0",
 ]
 
 [project.optional-dependencies]