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

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

@@ -2,6 +2,127 @@
 
 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
+shared between the foreground `add`/`flush`/`clear` path and the 2.0s
+auto-flush daemon thread, with only the timer guarded — so a flush that
+snapshotted-then-reset the buffer could drop a command a concurrent `add`
+appended in between (silent slide/shape loss), and a timer flush racing a
+foreground flush could POST the same commands twice (duplication). In
+long-lived Daytona executor processes this silently dropped or duplicated
+slides/shapes with no error. A dedicated `_commands_lock` now guards every
+read/append/reassign of `_commands` (drain atomically under the lock; POST
+outside it). No public API change. (#24278)
+
+## 0.7.0
+
+**python-pptx behavioral-parity sweep — read-path return types, enum
+values, and chart-data builder objects now match python-pptx 1.0.2.**
+
+Surface parity (every public class/method/signature) was already 100%, but a
+deep-dive against python-pptx 1.0.2 found *behavioral* divergences where
+getters returned raw strings/`None` instead of enum members or typed
+defaults, two enums had wrong integer values, and the chart-data builders
+weren't python-pptx-shaped. All fixes are pure-local (no wire/server change);
+`to_series_payload()` output is byte-identical to before.
+
+**Enum value corrections (silent drop-in breakers):**
+
+- **`MSO_THEME_COLOR.TEXT_2` / `BACKGROUND_2` were swapped** — now `15` /
+  `16` to match upstream (the `<a:schemeClr>` read/write maps were updated in
+  lockstep so OOXML output is unchanged). `MSO_THEME_COLOR_INDEX` inherits.
+- **`MSO_TEXT_UNDERLINE_TYPE` had 6 wrong values, 9 missing members, and a
+  bogus `DASHED_LINE`** — rewritten to upstream's exact 19 members/values;
+  added the `MSO_UNDERLINE` alias (`from pptx.enum.text import MSO_UNDERLINE`).
+- **`PP_MEDIA_TYPE`**: `MOVIE` corrected `2`→`3`, added `OTHER = 1`, and the
+  enum is now importable from its canonical `pptx.enum.shapes` location.
+- Added `MSO_SHAPE_TYPE.MIXED = -2` and the `MSO` alias; added the
+  upstream-typo `MSO_PATTERN.ERCENT_40` member.
+
+**Read-path return-type parity (getters now return enums / typed defaults):**
+
+- `FillFormat.type` → `MSO_FILL_TYPE` (was a raw string); `background()` now
+  reports `MSO_FILL_TYPE.BACKGROUND`. `gradient_angle`/`gradient_stops`/
+  `pattern` raise `TypeError` on a wrong-type fill (parity).
+- `LineFormat.dash_style` → `MSO_LINE_DASH_STYLE` (or `None` when unstyled,
+  instead of defaulting to `"solid"`); `LineFormat.width` defaults to
+  `Emu(0)` for an unstyled line (a color-/dash-only edit no longer injects a
+  synthetic 1pt width).
+- `Chart.chart_type` → `XL_CHART_TYPE` member (was a raw server string);
+  `add_chart` now persists `grouping` so stacked/clustered variants read back
+  exactly.
+- `TableCell.vertical_anchor` → `MSO_VERTICAL_ANCHOR`; `TableCell.margin_*`
+  default to the OOXML defaults (`91440`/`45720` EMU) instead of `None`.
+- `Shape.rotation` is normalized to `[0, 360)` and float-coerced.
+- `_Column.width` / `_Row.height` are populated for `add_table(...)` tables
+  (even division, last column/row absorbs the remainder).
+- `RGBColor` is now a real `tuple` subclass (`RGBColor(255,0,0) == (255,0,0)`,
+  `isinstance(c, tuple)`).
+- `ColorFormat.theme_color` returns `MSO_THEME_COLOR.NOT_THEME_COLOR` for an
+  sRGB color (raises `TypeError` when no color is present) instead of `None`.
+- `TextFrame.auto_size` / `vertical_anchor` return their enums; `margin_*`
+  default to the python-pptx `Length` defaults; `Paragraph.line_spacing =
+  None` clears the override without crashing; `Font.language_id` returns
+  `MSO_LANGUAGE_ID.NONE` on an unset run.
+- `SlideLayouts.get_by_name` is exact/case-sensitive (the fuzzy match moved to
+  the Athena-only `by_name`); `Slide.has_notes_slide` flips `True` once
+  `notes_slide` is accessed.
+- `Video.ext` returns the bare extension (`'mp4'`, `'vid'` fallback) and
+  `Video.filename` synthesizes `'movie.{ext}'`.
+
+**`pptx.util` truncation parity:** unit constructors (`Emu`/`Pt`/`Inches`/…)
+truncate toward zero like upstream (`int(Pt(1.9999)) == 25398`) instead of
+rounding; `Length.centipoints` is integer floor-division.
+
+**Chart-data builder objects (`pptx.chart.data`) are now python-pptx-shaped:**
+
+- `CategoryChartData.add_series(name, values)` returns a real
+  `CategorySeriesData` with `.values`, `.add_data_point()`, and `.index`;
+  `XyChartData`/`BubbleChartData.add_series` return `XySeriesData`/
+  `BubbleSeriesData` whose `add_data_point(...)` returns the data point and
+  expose `.x_values` / `.y_values` / `.bubble_sizes`.
+- `CategoryChartData.add_category(label)` and a `Categories`/`Category`
+  sequence with `are_dates` / `are_numeric` / `number_format`; category label
+  types (dates, numbers) are preserved through `cd.categories[i].label`.
+- The three chart-data containers implement the `Sequence` protocol
+  (`for s in chart_data` / `chart_data[0]`).
+
 ## 0.4.2
 
 **Paragraph-level font fidelity — `paragraph.font` now matches stock

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

@@ -52,8 +52,10 @@ A small number of REST-SDK-specific departures are documented in
   use `slide.notes_slide.notes_text_frame` for notes text.
 - **`XyChartData.add_series(name, values)`** signature drift vs upstream's
   `add_series(name, number_format=None)` — caller passes inline tuples.
-- **`TextFitter.best_fit_font_size()`** returns `max_size` unchanged
-  (auto-fit is server-side); emits `RuntimeWarning`.
+- **`TextFitter.best_fit_font_size()`** is server-measured: with a base
+  URL configured it queries `POST /measure-text-fit` and returns the
+  largest fitting size; only falls back to `max_size` (+ `RuntimeWarning`)
+  when no studio client is reachable.
 - **`_BaseSeriesData.index`** raises `NotImplementedError` (raising
   rather than silently returning 0).
 - **`Package.open()`** raises `UnsupportedFeatureError`.

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

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

@@ -45,48 +45,51 @@ text = slide.notes_slide.notes_text_frame.text
 A future server-side notes-master patch op will plumb the full shape
 tree through. Tracked in `PARITY_QUESTIONS.md`.
 
-### `XyChartData.add_series()` — different signature
+### `XyChartData.add_series()` — both the upstream and inline patterns work (v0.7.0)
 
-Upstream signature: `add_series(name, number_format=None)` — caller adds
-data points via the returned series object.
-
-**Our signature:** `add_series(name, values)` — caller passes the
-(x, y) tuples up front.
-
-**Migration:**
+As of v0.7.0 `add_series` returns a real `XySeriesData` (resp.
+`BubbleSeriesData`), so the **upstream pattern works**:
 
 ```python
-# python-pptx pattern (NOT supported by athena-python-pptx):
+# python-pptx pattern (now supported):
 series = data.add_series("Series 1")
-series.add_data_point(1.0, 2.0)
+series.add_data_point(1.0, 2.0)          # returns the XyDataPoint
 series.add_data_point(3.0, 4.0)
+series.x_values  # [1.0, 3.0]; series.y_values -> [2.0, 4.0]
 
-# athena-python-pptx pattern (use this):
+# athena-python-pptx inline shorthand (still supported):
 data.add_series("Series 1", [(1.0, 2.0), (3.0, 4.0)])
 ```
 
-Same applies to `BubbleChartData.add_series`. Fixing this is a larger
-refactor (the SDK's chart-authoring path expects values inline);
-tracked in `PARITY_QUESTIONS.md`.
+`add_series` additionally accepts an optional `number_format=` for
+signature parity. The same applies to `BubbleChartData.add_series`
+(inline triples are `(x, y, size)`).
 
-### `TextFitter.best_fit_font_size()` — returns `max_size` unchanged
+### `TextFitter.best_fit_font_size()` — server-measured (needs a base URL)
 
-Upstream binary-searches font sizes locally to fit text within bounds.
-Our stub always returns `max_size` and emits a `RuntimeWarning`.
-Auto-fit happens server-side at render time. **Don't rely on this for
-local layout decisions**; use the auto-fit text frame property instead:
+Upstream binary-searches font sizes against locally-installed font
+metrics, which a REST SDK can't read. When a base URL is configured
+(`ATHENA_PPTX_BASE_URL` or an explicit `client`) the classmethod issues
+a `MeasureTextFit` query to the studio's `POST /measure-text-fit`
+endpoint and returns the largest integer size that fits — measured
+against the studio's bundled fonts via the same layouter the renderer
+uses (see the extension entry below). It falls back to `max_size` with a
+`RuntimeWarning` **only** when no studio client is reachable (offline /
+import-time tests). For full-deck layout, prefer letting the text frame
+auto-fit at render time:
 
 ```python
 from pptx.enum.text import MSO_AUTO_SIZE
 text_frame.auto_size = MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE
 ```
 
-### `_BaseSeriesData.index` — raises `NotImplementedError`
+### `_BaseSeriesData.index` — resolves against the parent chart-data (v0.7.0)
 
-Upstream's `CategorySeriesData.index` returns the series's offset
-within its parent chart-data. Our stub raises rather than silently
-returning `0` (which would corrupt any OOXML `<c:idx>` builder that
-trusts the value). If you need the series index, track it externally.
+As of v0.7.0, a series created via `chart_data.add_series(...)` carries a
+back-reference to its parent, so `series.index` returns the series's
+offset within the chart-data exactly like upstream. A *detached* series
+constructed standalone (no parent) still raises `NotImplementedError`
+rather than lying about the offset.
 
 ### `Package.open(pkg_file)` — raises `UnsupportedFeatureError`
 
@@ -137,6 +140,24 @@ prs.save()              # flush only (Athena-only)
 prs.save("out.pptx")    # flush + export + write to local file (parity)
 ```
 
+### Oversized flushes are split into multiple atomic sub-transactions
+
+The SDK serializes every buffered command into one JSON body and POSTs it
+to `/decks/:id/commands`. pptx-studio's apps/api (Fastify) caps that body
+at 32 MiB, and `AddPicture` / `SubstitutePlaceholder(picture)` carry inline
+base64 image bytes (~4/3 expansion), so a few large images can blow past
+the ceiling. For batches that exceed the limit, `CommandBuffer.flush`
+splits them into multiple atomic sub-transactions (still validating the
+whole batch up front, so an invalid command aborts before anything is
+applied). The all-or-nothing guarantee then holds *per sub-transaction*
+rather than end-to-end — a server-side failure mid-sequence can leave
+earlier chunks committed. The split threshold is tunable via
+`ATHENA_PPTX_MAX_REQUEST_BYTES`; batches within the limit ship as one
+atomic request, unchanged. A single command larger than the budget (one
+very large inline image) cannot be split — it is sent alone and may still
+be rejected with a teaching `IMAGE_TOO_LARGE` error, but it no longer
+takes the rest of the queued edits down with it.
+
 ---
 
 ## Agent-Friendly Additions (not in python-pptx)
@@ -215,34 +236,23 @@ python-pptx's `_Row.height` and `_Column.width` are read/write EMU properties. T
 
 In python-pptx, `Table.rows` returns a `_RowCollection` of `_Row` objects (each with `.height`). This SDK matches that. In a prior version, `Table.rows` returned a flat collection of cell lists.
 
-### `TextFrame.clear()` — also resets bullet on paragraph 0
-
-In upstream python-pptx, `text_frame.clear()` removes every paragraph except the first, and on that first paragraph it removes every child element **except** `<a:pPr>`. Any bullet definition the author wrote into `<a:pPr>` survives the clear, and an inherited bullet from the master / layout's `<a:lstStyle>` is left to be re-resolved by PowerPoint at render time.
-
-This SDK additionally emits a `SetParagraphStyle(paragraph_index=0, bullet='none')` after the empty `SetText`, explicitly overriding the bullet on the cleared paragraph.
-
-The deviation exists because pptx-studio **pre-bakes** master/layout list-style inheritance into `richContent.paragraphs[i].bullet` at ingest time (and at slide materialization), then preserves that baked field through every subsequent `applySetText` via `preserveParagraphProps`. Without the explicit override, the python-pptx idiom
-
-```python
-tf.clear()
-p = tf.paragraphs[0]
-run = p.add_run()
-run.text = "Title"
-```
-
-renders the title with a stray "•" whenever the placeholder lives on a layout whose master defines a level-1 `<a:buChar/>` (the common case for `<p:bodyStyle>` and any content placeholder). The explicit `bullet='none'` clears the baked inheritance so the literal "no pPr was authored" intent reaches the renderer.
+### `TextFrame.clear()` — bullet inheritance (now matches upstream)
 
-To re-enable a bullet after `clear()`, set it back explicitly:
+`text_frame.clear()` matches upstream python-pptx: it removes the runs but
+preserves the cleared paragraph's inherited list style. A content/body
+placeholder therefore keeps its master `<p:bodyStyle>` bullet, and a title
+keeps its `<p:titleStyle>` `<a:buNone/>` (no bullet), exactly as PowerPoint
+re-resolves them at render time.
 
-```python
-tf.clear()
-p = tf.paragraphs[0]
-p.bullet = True             # restores 'disc' default
-run = p.add_run()
-run.text = "Bullet item"
-```
-
-Only `bullet` is overridden — `alignment`, `level`, `line_spacing`, `space_before`, `space_after`, `margin_left`, `indent`, and `bullet_color` are left alone (they continue to follow upstream `<a:pPr>`-preservation semantics, since baked-inheritance surprises are far less common on those fields).
+> **Historical note:** earlier versions emitted a
+> `SetParagraphStyle(paragraph_index=0, bullet='none')` after the empty
+> `SetText` to mask a *stray title bullet*. The real cause was incorrect
+> per-type bullet baking — empty layout/master prompt paragraphs were baked
+> with `bullet:'none'` instead of their master `<p:txStyles>` value, and a
+> blanket override then stripped bullets from **content** placeholders too
+> (where bullets are expected). That baking is now correct per placeholder
+> type (`titleStyle` → no bullet, `bodyStyle` → its `<a:buChar/>`), so the
+> override was removed and `clear()` is faithful to upstream.
 
 ---
 
@@ -328,6 +338,37 @@ img = ws.export_range_as_image_asset("A1:F20", name="Q4 Revenue")
 slide.shapes.add_picture(img.url, Inches(1), Inches(1), width=Inches(6))
 ```
 
+### `Picture.image_url` — owner-scoped media URL for cross-deck image copy
+
+python-pptx upstream exposes `Picture.image` returning an `Image` with
+`.blob` bytes. The REST SDK can't materialize bytes locally, so `.image`
+stays `None` (see the omissions list above). **Additionally**, when a
+picture is loaded from a server snapshot it now carries `image_url`: a
+stable `{base_url}/media?key=<assetId>` URL that streams the picture's
+bytes. It returns `None` for pictures with no backing media asset (an
+SDK-added picture not yet flushed/refreshed, a placeholder with no image,
+or exotic sources like OLE/movie posters that lack a top-level asset id).
+
+The URL is owner/EDIT-scoped (the `/media` route runs the same deck-access
+check as every other deck op), and `add_picture` auto-attaches the
+sandbox bearer for Athena hosts — so it composes directly into the
+canonical "copy every image from deck A into deck B" recipe:
+
+```python
+src = Presentation(asset_id="asset_source")
+dst = Presentation(asset_id="asset_dest")
+for i, slide in enumerate(src.slides):
+    for pic in slide.shapes.get_images():
+        if pic.image_url:
+            dst.slides[i].shapes.add_picture(
+                pic.image_url, pic.left, pic.top, pic.width, pic.height
+            )
+dst.save()
+```
+
+**Portable code that needs to run against stock python-pptx cannot rely
+on `image_url`** — it is an Athena-only accessor.
+
 ### `name=` kwarg on `add_textbox()` / `add_shape()` / `add_picture()`
 
 Optional keyword for setting a stable shape name at creation. python-pptx

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

@@ -133,7 +133,7 @@ def flush_all() -> None:
     _active_buffers[:] = alive
 
 
-__version__ = "0.6.0"
+__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"
+    )