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

{athena_python_pptx-0.5.0 → athena_python_pptx-0.6.0}/CLAUDE.md

@@ -69,6 +69,15 @@ local XML / OPC parts:
 
 `Font.language_id` IS now implemented (returns `MSO_LANGUAGE_ID` enum, accepts enum or int LCID) — added in v0.1.68.
 
+### Slide-index conventions
+
+Slide indexing has TWO bases — never conflate them:
+
+- **0-based** — this SDK (python-pptx parity): `prs.slides[0]`, `slide.slide_index`, and every `slide_index=` parameter are 0-based.
+- **1-based** — the Athena citation/anchor system: `SlideAnchor.slideIndex` / `ShapeAnchor.slideIndex` (in `pptx/_references.py`), the citation methods, and anything displayed as "Slide N" are the 1-based display position.
+
+The PPTX Studio server applier converts at the SDK→anchor boundary (`+1`). `slideId` (== the SDK's `slide.slide_id`) is the stable, base-agnostic identity — prefer it when available.
+
 ### If you need a deviation
 
 If there is a genuine technical reason why a deviation from python-pptx is necessary (e.g., the SDK is a REST client and cannot replicate XML-level behavior):

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-pptx
-Version: 0.5.0
+Version: 0.6.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.5.0 → athena_python_pptx-0.6.0}/docs/API_PARITY_EXCEPTIONS.md

@@ -1368,8 +1368,8 @@ A citation record is:
 ```jsonc
 {
   "id": "citation_<uuid12>",
-  "destinationAnchor": { "type": "slide", "slideId": "...", "slideIndex": 0 },
-  // or { "type": "shape", "slideId": "...", "slideIndex": 0, "shapeIds": ["..."] }
+  "destinationAnchor": { "type": "slide", "slideId": "...", "slideIndex": 1 },
+  // or { "type": "shape", "slideId": "...", "slideIndex": 1, "shapeIds": ["..."] }
   "citation_string": "<source Spaces URL>",
   "displayValue": "Q4 Sales",        // optional
   "active": true,
@@ -1399,17 +1399,31 @@ cid = slide.add_citation(
 )
 ```
 
-### `Shape.cite(source, *, anchor=None, display_value=None) -> str`
+### `Shape.add_citation(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.
+created citation id. (Mirrors `Slide.add_citation` / `Cell.add_citation` — the
+citation verb is `add_citation` on every citable object.)
 
 ```python
 shape = slide.shapes.add_textbox(Inches(1), Inches(1), Inches(4), Inches(1))
-cid = shape.cite(AssetReference(id="asset_doc_xyz"))
+cid = shape.add_citation(AssetReference(id="asset_doc_xyz"))
 ```
 
+**Slide-index base shift (citations).** The SDK/command wire `slide_index`
+(`prs.slides[i]`, `slide.slide_index`) is **0-based** — python-pptx array
+parity. But the `destinationAnchor.slideIndex` the server writes into the
+citation record is **1-based** — the "Slide N" display position per the
+athena-references contract. The server applies the `+1` at the SDK→anchor
+boundary, so the stored anchor's `slideIndex` is always one greater than the
+SDK index of the cited slide.
+
+> ⚠️ If the **cited source** is itself a slide/shape (you pass a
+> `SlideAnchor` / `ShapeAnchor` as `anchor=`), that anchor's `slide_index` is
+> the **1-based** display position per the athena-references contract — do
+> **not** pass the SDK's 0-based `slide.slide_index` into it (add 1).
+
 ### `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

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

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

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

@@ -788,7 +788,11 @@ class AddSlideCitation(Command):
         ``docs/API_PARITY_EXCEPTIONS.md`` for the deviation rationale.
 
     Args:
-        slide_index: Zero-based index of the cited slide.
+        slide_index: Zero-based index of the cited slide. This stays 0-based on
+            the wire (python-pptx array parity); the studio server applier
+            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_anchor: Optional ``Anchor`` JSON within the source (e.g. a
@@ -834,7 +838,11 @@ class AddShapeCitation(Command):
         ``docs/API_PARITY_EXCEPTIONS.md`` for the deviation rationale.
 
     Args:
-        slide_index: Zero-based index of the slide the shapes live on.
+        slide_index: Zero-based index of the slide the shapes live on. This
+            stays 0-based on the wire (python-pptx array parity); the studio
+            server applier 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.
         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.

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

@@ -5954,7 +5954,7 @@ class Shape:
             if isinstance(by_id, dict):
                 by_id.pop(self._shape_id, None)
 
-    def cite(
+    def add_citation(
         self,
         source: "AssetReference",
         *,

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

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