athena-python-pptx 0.10.0__tar.gz → 0.14.0__tar.gz

athena_python_pptx-0.10.0/CLAUDE.md → athena_python_pptx-0.14.0/AGENTS.md

@@ -59,6 +59,11 @@ A small number of REST-SDK-specific departures are documented in
 - **`_BaseSeriesData.index`** raises `NotImplementedError` (raising
   rather than silently returning 0).
 - **`Package.open()`** raises `UnsupportedFeatureError`.
+- **Axis-title text frames** are one paragraph with one font: runs join
+  into one title string in the first run's font, with a one-time
+  `UserWarning` when that drops styling.
+- **Table-cell text frames** are one paragraph with one run (bold, italic,
+  size, name, color); `font.underline` raises.
 
 ### Intentionally omitted (REST SDK limitations)
 

{athena_python_pptx-0.10.0 → athena_python_pptx-0.14.0}/CHANGELOG.md

@@ -2,6 +2,383 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.14.0 — waterfall charts render and export as waterfalls
+
+Requires a studio that authors `AddChart2016` waterfalls and accepts the
+`SetWaterfallSubtotals` chart patch (older servers reject the batch).
+
+- `add_chart(XL_CHART_TYPE.WATERFALL, ...)` now makes a real waterfall instead
+  of a clustered column chart: one series of deltas, bars floating on the
+  running total, data labels on. More than one series raises
+  `ValidationError`.
+- New Athena extension `chart.plots[0].subtotals = [0, 5]` (also
+  `set_subtotals([...])`, a `WaterfallPlot`) marks the bars drawn from zero as
+  totals; a total left `None` shows the running total.
+- `chart.chart_type` reads back `XL_CHART_TYPE.WATERFALL`.
+- `chart.plots` on a reopened deck picks the plot class from the snapshot's
+  plot type, so `chart.plots[0]` is a `WaterfallPlot` (or `BarPlot`,
+  `LinePlot`, ...) instead of the bare base plot.
+- `chart.replace_data()` keeps the plot's other settings (subtotals, gap
+  width, data labels) in the local mirror, as the server does; subtotal
+  indices past the new points are dropped on both sides.
+- The exported deck carries a stacked-column waterfall (invisible base
+  series), so it opens in any PowerPoint version and stays editable; the studio
+  preview matches it (centred labels, no connector lines).
+
+## 0.14.0 — chart series line and no-fill formatting reach the deck
+
+Requires a studio with the `SetSeriesLine` / `SetSeriesFillVisible` /
+`SetPointFillVisible` chart patch ops (older servers reject the batch).
+
+- `series.format.line.color.rgb`, `.width`, `.dash_style` and
+  `.fill.background()` / `.fill.solid()` now emit `SetSeriesLine`: the plotted
+  line of a line / XY / radar series, the outline of a bar / area / pie /
+  bubble series. Previously these were local-state-only and a line chart kept
+  its palette colours. `dash_style` accepts `MSO_LINE_DASH_STYLE` members,
+  snake_case line tokens and `<a:prstDash>` presets, and reads back the enum
+  member (or the preset string for `dot` / `sysDashDot` / `sysDashDotDot`,
+  which have none); `None` clears width / dash.
+- `series.format.fill.background()` emits `SetSeriesFillVisible` (the invisible
+  base series of a stacked-column waterfall now stays invisible); `solid()`
+  on a hidden fill, or assigning `fore_color`, shows it again.
+  `series.points[i].format.fill.background()` emits `SetPointFillVisible`; the
+  hidden state is kept on the series, so `solid()` through a new `format`
+  object (or after a refresh) shows the point again.
+- Chart format writes that still have no patch op (axis line / fill, axis-title
+  and gridline fills, per-point line, marker hollow fill / line width / dash,
+  line `theme_color`, data-label borders) keep their local value and emit a
+  one-time `UserWarning`: `"<property> is not supported by the Athena studio
+  renderer and was ignored"`. They never raise. Data-label border setters no
+  longer send fields the server silently dropped.
+- Gridline `dash_style` accepts `MSO_LINE_DASH_STYLE` members (previously only
+  preset strings).
+
+## 0.14.0 — axis-title paragraphs and runs, per-cell font family
+
+Two python-pptx idioms crashed agent scripts partway through a deck
+(staging session thread_3de488f7), after earlier batches had committed:
+
+- `axis.axis_title.text_frame.paragraphs[0].runs` raised `AttributeError`
+  (`AxisTitleTextFrame` exposed only `.text`). It is now a python-pptx
+  `TextFrame`: `paragraphs` holds one paragraph whose `text`, `runs`,
+  `font` and `add_run()` work, and each run's `text` / `font`. Text goes to
+  the title text and fonts to the `SetAxisTitle` font fields (size, bold,
+  `color.rgb`, name). The patch model is one string and one font, so several
+  runs join into one title string drawn in the first run's font over the
+  paragraph font; a `UserWarning` is emitted once per axis title when that
+  drops a run's styling or when a font property the patch can't carry
+  (italic, underline, strike, theme color, …) is set. An existing title's
+  text is now read from the deck snapshot.
+- `cell.text_frame.paragraphs[0].runs[0].font.name = "Calibri"` raised
+  `UnsupportedFeatureError`. `SetTableCell` now carries `font_family` (wire
+  `fontFamily`) and `italic`; `font.name` / `font.italic` set them, the
+  studio draws them and the export writes `<a:latin typeface>` / `i="1"` on
+  the cell's runs, for SDK-authored and uploaded tables alike.
+  `paragraphs[0].font` is the cell's run font. Assigning `None` cannot clear
+  a value the session wrote (no inherit marker on the wire) and warns.
+  `font.underline` still raises.
+
+Needs a PPTX Studio server with `SetTableCell.fontFamily` / `italic`
+(older servers drop the fields without error).
+
+## 0.14.0 — `add_run()` on an empty paragraph returns `runs[0]`
+
+Fixes the empty run agent-built decks stored ahead of the real text in
+almost every text box (staging `asset_e41e33eb`: 224 of 226), and the
+doubled, default-styled titles and labels that later `runs[0].text = ...`
+edits produced by writing that empty run.
+
+- The first `paragraph.add_run()` on a paragraph whose only run is the SDK's
+  untouched empty seed returns that run as `runs[0]` instead of appending
+  after it, matching python-pptx. This covers new text boxes and autoshapes,
+  blank lines from `text_frame.text = ...`, and paragraphs emptied by
+  `paragraph.text = ""`. Repeated `add_run()` calls still create distinct
+  runs, and a seed run the caller wrote directly is kept.
+- After a text reset the returned run is bare, as in python-pptx: the SDK
+  sends `SetRunText` with the new `resetFormatting` flag so the look the
+  server's `SetText` kept on that empty run is dropped. The same command
+  writes run 0 into snapshot paragraphs stored with no runs (ingested empty
+  placeholders), so a style set before the text resolves.
+- Snapshot-loaded paragraphs keep their stored run indices, so decks written
+  before this fix keep their stored empty runs. `text_frame.clear()` +
+  `add_run()` is unchanged.
+- Release after the pptx-studio server with `SetRunText.resetFormatting` is
+  deployed. Older servers ignore the flag, and the run returned after a text
+  reset then keeps the replaced text's look.
+- Documented in `docs/API_PARITY_EXCEPTIONS.md`.
+
+## 0.14.0 — `validate()` judges text by its ink and flags table rows only when they grow
+
+Cuts the false layout warnings an agent had to reason about and dismiss
+(staging session `thread_3de488f7`: collisions for value labels on bubbles,
+captions inside wide title boxes and table cells in rows sized for two
+lines). Same signatures.
+
+- **Text is compared by its ink, not its frame.** Each text frame is laid out
+  on the glyph-width estimate — greedy word wrap at the inner width minus the
+  paragraph indent (the first-line indent on the first line; a bullet moves
+  the text at least 1.5em in and an unindented outline level 0.375in, as in
+  the studio renderer), per-paragraph size and line spacing — and every line is
+  placed by its paragraph's alignment and the frame's vertical anchor
+  (autoshapes centre by default, text boxes anchor at the top). Lines are
+  widened 10% within their frame so an under-estimate cannot hide a real
+  collision; a placeholder's alignment or anchor inherited from its layout
+  widens the ink to every place the text could be. Text whose ink sits
+  entirely on a shape (a label on a card or bubble, a caption on a picture)
+  counts as containment unless that shape is drawn over it with an opaque
+  fill; frames that overlap while their texts do not are not reported; and
+  text that runs over the edge of a visible shape (fill or outline — plain
+  text boxes show no edge) or partly under a later opaque shape gets its own
+  message. Hidden text is judged by the share of the *text* under the cover,
+  and a cover that carries text of its own still hides what is beneath it.
+  Overflowing text now spills out of its frame the way PowerPoint draws it,
+  so a paragraph running onto the box below is reported even though the two
+  frames never touch; a studio "fits" verdict pulls that ink back inside.
+- **Table cells warn only when the row grows**: wrapped lines x line height
+  plus the cell's top/bottom margins taller than the row (every row a vertical
+  merge spans) — the case where PowerPoint grows the row, measured at the
+  weight and family the snapshot resolved (table-style headers are bold). A single word wider
+  than its column (a number that will break mid-word) keeps a warning of its
+  own. Both are confirmed with `POST /measure-text-fit` like text overflow,
+  within the same 12-call budget.
+- **Readable overflow message**: `needs ~2 lines at 20pt but only ~1 fits
+  (~0.67in of text in a 0.40in-tall box)`, `needs ~1 line at 32pt but not
+  even one line fits (…)`, paragraph spacing called out when it alone tips
+  the box over, `12–40pt` for mixed sizes, and correct plurals.
+- **Measurement sends the real inner box.** `/measure-text-fit` subtracts
+  PowerPoint's default insets from the box it gets; `validate()` sent the box
+  with the frame margins already removed, so the studio measured a box 0.2in
+  narrower and 0.1in shorter than the text's and over-confirmed overflow. The
+  box now goes out grown by those insets.
+
+## 0.13.1 — in-batch `add_slide()` carries layout placeholders, proxies survive `refresh()`
+
+Fixes the `'NoneType' object has no attribute 'text'` failure agents hit
+with the textbook idiom `slide = prs.slides.add_slide(layout);
+slide.shapes.title.text = ...` inside `with prs.batch():`, and the
+follow-on where `prs.refresh()` left the held `slide` orphaned.
+
+- A slide added inside a batch now projects its layout's placeholders
+  locally, from the snapshot's `themeHierarchy.layouts[].placeholders`
+  (new server projection), under the same `__inherited__:<slide id>:<layout
+  element id>` ids the server materializes on `AddSlide`. `shapes.title` /
+  `placeholders` resolve immediately with no flush or refresh, and writes to
+  them are sent in the same request as the `AddSlide`, so batch atomicity is
+  preserved. Decks whose snapshot lacks layout placeholder data keep the
+  previous behaviour (`title` is `None` until the slide is committed).
+- `CommandBuffer.flush()` records `client_id -> server slide id` for every
+  `AddSlide` / `CopySlideFromDeck` it sends, from the response's
+  `created.slideIds` (same order). `Slides._update_from_snapshot()` uses
+  only those authoritative aliases to re-key the *existing* `Slide` object
+  (and its projected placeholder shape ids) to the server id instead of
+  dropping it and appending a fresh one. Pending proxies without an alias
+  are never paired positionally with unseen snapshot slides, which may
+  belong to other collaborators.
+- No public API change; `slide.delete()` remains intentionally absent
+  (python-pptx parity) — use `prs.slides.delete(slide)`.
+
+## 0.13.0 — `pptx.kit` composition kit
+
+- New Athena-only module `pptx.kit` (`from pptx.kit import Kit, Palette,
+  Fonts, Region`; also re-exported from `pptx`). `Kit(prs)` composes slides
+  from regions derived from the slide size: `header` (small-caps kicker,
+  action title auto-fit to a two-line band, footer rule + page number +
+  `kit.footer_text`), `footer`, `takeaway` (full-width bar one gap above the
+  footer band), `content_region`, `columns`, `grid`, `kpi_row` / `kpi_card`
+  (surface card, accent stripe, big auto-fit value, auto-fit label), `card`,
+  `text` and `bullets`.
+- Text asked to fit is sized to its box by the studio's `/measure-text-fit`
+  layouter (same client pattern as `TextFitter.best_fit_font_size`, result
+  floored and cached per kit, one failed probe latches the fallback) or, when
+  the studio is unreachable, by a conservative greedy wrap on the
+  `_estimate_text_width_emu` glyph table at 1.2 line height. It never grows
+  past the requested size; when nothing fits even at the minimum size the kit
+  uses the minimum and emits a `RuntimeWarning` naming the text; `fit=False`
+  keeps the size as given.
+- Regions are clamped to the slide and the footer band is reserved, so
+  nothing lands outside the slide or under the footer; a region with nothing
+  left raises instead of silently placing nothing. `content_region` keeps the
+  takeaway band free by default so a bar added after the body cannot hide it,
+  and the `y` / `h` overrides of `columns` / `grid` / `kpi_row` are clamped to
+  the content region. Per-slide state is keyed by the stable `slide.slide_id`.
+- Pure python-pptx public API underneath (`add_shape` / `add_textbox` /
+  `fill` / `line` / `text_frame` / `font`), emitted through the
+  presentation's command buffer — build each slide inside `with prs.batch():`
+  for one round-trip. Reaches agents with the next `athena-python-pptx` bump.
+  Documented in `docs/API_PARITY_EXCEPTIONS.md`; demo in
+  `examples/kit_demo.py`.
+
+## 0.13.0 — validate() finds overflow and hidden text, drops containment noise
+
+Reworks `Slide.validate()` around the defects that actually ship in agent
+decks (verified 2026-09-14 against two 8-slide agent builds: 167 and 127
+warnings, ~75% of them a background card behind its own label). Same
+signature; an empty list is once again reachable by a designed slide.
+
+- **Containment overlaps are no longer reported** unless both shapes carry
+  text (text on text is always reported). Partial overlaps are reported
+  only when at least one shape carries text; hairline overlaps thinner
+  than a text-frame inset (0.05in) and overlaps between two text-less
+  shapes are ignored. Tables count as text-bearing.
+- **New: text overflow for non-table shapes** — per-paragraph font-metric
+  estimate (`_estimate_text_width_emu`, run size → paragraph default →
+  shape default → 18pt; word wrap on → `ceil(width / inner_width)` lines,
+  off → horizontal check; `lines × font × 1.2 × line_spacing` + spacing vs
+  box height minus margins). Frames set to auto-fit are skipped. When the
+  presentation has a studio client each hit whose paragraphs share one
+  font size and weight is confirmed with one `MeasureTextFit` round-trip
+  pinned at that size (`fits: true` drops it; capped at 12 per call; every
+  network error falls back to the heuristic verdict); mixed-font frames keep
+  the heuristic verdict since the server measures at a single font.
+- **New: hidden text (occlusion)** — a text shape at least half covered by
+  a later (higher z-order) shape with a solid, non-transparent fill and no
+  text: `"text in 'X' is covered by 'Y'"`. Unknown fills (none, gradient,
+  pattern, pictures) count as not opaque; any transparency on the proxy or
+  a snapshot `fillTransparency` disables the rule for that shape.
+- Warnings are deduplicated, ordered overflow → occlusion → text-on-text →
+  other (off-slide, one-text partial overlaps, empty placeholders), capped
+  at 15 per slide with a trailing `"… and N more (M containment overlaps
+  ignored)"` line. Rotated shapes near 90°/270° use their swapped visual
+  bbox in the pairwise rules.
+- `bring_to_front()` / `send_to_back()` / `bring_forward()` /
+  `send_backward()` now mirror the move on the local `slide.shapes` order
+  (previously only the server saw it), so `validate()` reads the intended
+  stack without a refresh.
+- New module-level `pptx.validate_all_touched() -> dict[int, list[str]]`
+  (Athena extension) for the executor postamble: `CommandBuffer` records
+  the slide indexes / slide ids / shape ids of every command the server
+  applied (`CommandBuffer.take_touched()` returns and clears them);
+  `validate_all_touched()` resolves them to slides on every live
+  `Presentation`, validates only those, and returns the slides with
+  warnings. Recorded indexes are shifted for slide insertions, deletions
+  and reorders applied later in the run; destination-bearing commands
+  (`CloneShape`, `CopySlideFromDeck`, `ReplaceText`) record their
+  destination; `SetPresentationSize` and a deck-wide `ReplaceText` validate
+  every slide. Commands that cannot change a layout (notes, names,
+  citations, deck metadata) never mark a slide; never raises for
+  validation reasons.
+
+## 0.12.0 — snapshot hydration, ReplaceChartData emission, level dirty-flag, discard_all
+
+SDK halves of the issue #30178 Cluster D server work (#30204 / #30211 /
+#30212 / #30213).
+
+**⚠️ Server ordering:** `Chart.replace_data` now emits a single
+`ReplaceChartData` patch, which servers without #30211 reject (400) — the
+`presentation-exec` snapshot bump to 0.12.0 must wait for the pptx-studio
+deploy that ships the op.
+
+- `Shape.shadow` hydrates from the snapshot's `shadow` bag: a partial edit
+  like `shadow.blur_radius = Pt(6)` re-emits the ingested shadow's
+  `visible=True` / type / distance / direction / color / transparency
+  instead of the un-hydrated defaults (`visible=False` used to DELETE the
+  ingested shadow server-side). Hydrated shadows read back
+  `inherit == False`.
+- `Shape.click_action` hydrates from the snapshot's `clickAction` bag —
+  same deletion-bug class (`click_action.tooltip = ...` used to emit
+  `action_type='none'` and delete the ingested link).
+- `Presentation.core_properties` hydrates from the snapshot's
+  `coreProperties` (server #30204): setting one property no longer wipes
+  the deck's other metadata to `None`. `refresh()` re-hydrates.
+- `Chart.replace_data` emits ONE `ReplaceChartData` patch carrying the
+  full categories + series matrix (python-pptx semantics: shrink drops
+  trailing points, grow adds them, extra series are removed) instead of
+  per-index `UpdateSeries*` / `UpdateCategoryLabel` patches that couldn't
+  change the data's shape. The local `chartSpec` mirror still updates,
+  preserving server series ids by index. A zero-series `chart_data`
+  raises `ValidationError` before touching the local mirror (the op
+  requires at least one series; silently returning would desync local
+  reads from the server).
+- `run.hyperlink.target_slide = n` no longer rides with `address=''` (the
+  clear convention) — exactly one of address / targetSlideIndex is sent,
+  aligning with server #30212. The SetText re-emit carries
+  `hyperlinkTargetSlideIndex`, and snapshot rich content hydrates it back.
+  `SetRunHyperlinkTarget.validate()` rejects setting both.
+- `paragraph.level` is sent only when the paragraph is indented or the
+  caller explicitly assigned it (explicit `level = 0` still reaches the
+  wire); an untouched level-0 paragraph omits the field so unrelated style
+  edits don't stomp the server-side outline level (belt-and-suspenders
+  with the server-side lvl=0 canonicalization in #30213).
+- New module-level `pptx.discard_all()` (mirrors athena-python-docx):
+  drops all buffered, un-flushed commands across open decks without
+  posting and returns the dropped count. The agora executor postamble
+  calls it when user code raised, so failed scripts discard their
+  half-buffered tail instead of posting it.
+
+## 0.11.0 — silent no-op & data-loss fixes (deep-dive remediation)
+
+Eliminates a cluster of silent no-ops, read-after-write desyncs, and
+buffer-poisoning bugs found in the 2026-08 presentation-asset deep dive.
+All fixes preserve python-pptx API parity (behavior, not surface, changes).
+
+- `paragraph.level = 0` now reaches the wire (was dropped by the None-drop),
+  so resetting an indented paragraph works.
+- `font.subscript = False` / `font.superscript = False` now send `baseline: 0`
+  (the server's clear signal) instead of omitting the field, so they actually
+  un-sub/superscript existing text.
+- A bare `shape.fill.solid()` now emits, matching `gradient()`/`patterned()`.
+- Chart `has_legend` / `has_title` / `chart_title` now update the local
+  snapshot on write, so reads after a write return the new value.
+- `rows.insert()` / `columns.insert()` now shift the cached row-height /
+  column-width lists, fixing corrupted height/width reads after an insert.
+- `GroupShape.shapes` now resolves child shapes via `childIds` (was hardcoded
+  to `[]`).
+- `PicturePlaceholder.insert_picture` converts WebP/SVG/AVIF to PNG (was
+  mislabeling them `png`) and honors its `width`/`height` params.
+- `batch()` discards the buffer when its body raises (was committing the
+  partial prefix).
+- A server-rejected command in a batch is dropped (not re-queued), ending the
+  permanent buffer-poison loop; the rest of the rolled-back chunk is restored.
+- Command chunks carry a stable `txn.id` across retries so an ambiguous-timeout
+  resend dedups server-side instead of double-applying.
+- `flush_all(strict=True)` raises `FlushAllError` on a per-buffer flush failure
+  (the sandbox executor opts in) instead of silently swallowing it.
+- `Presentation` no longer pins its buffer/client/session via the atexit hook
+  (weakref closure); `close()`/`__del__` release the HTTP session.
+- Export 404s fail fast for a deck this client already read (deleted deck),
+  instead of burning the ~85s post-upload retry budget.
+- `XyChartData` / `BubbleChartData` `add_series` raise on malformed inline
+  points instead of silently dropping them.
+- `mso_shape_to_string` raises on an unmapped autoshape id instead of silently
+  authoring a rectangle.
+- `AddMovie` emits `posterBase64` (the key the server reads) and always sends a
+  poster (a 1x1 placeholder when none is supplied), so `add_movie`/`add_video`
+  no longer fail the whole batch.
+
+## 0.10.1 — unnamed-shape parity, browser UA on image fetches, honest SVG errors
+
+Fixes the three `execute_presentation_code` failures observed in the
+2026-08-12 production deck-build session (thread_d7eb9dd6).
+
+- `Shape.name` now always returns a `str` (python-pptx parity —
+  `cNvPr@name` is a schema-required attribute upstream). Elements
+  persisted before names were stored (e.g. pictures added by pre-0.10
+  SDKs) read back as `""` instead of `None`, so idioms like
+  `'Picture' in shape.name` no longer raise `TypeError`.
+- `add_picture(url)` fetches now send browser-equivalent
+  `User-Agent`/`Accept` headers. Image hosts and proxies behind bot
+  rules (e.g. `wsrv.nl`, Cloudflare-fronted CDNs) 403 the default
+  `python-requests/x.y` UA while serving the identical URL to a browser
+  UA. The Accept header advertises only formats the deck pipeline
+  handles (PNG/JPEG native, WebP via Pillow) so format-negotiating CDNs
+  don't switch the body to AVIF or SVG.
+- AVIF is now detected explicitly (any `avif`/`avis` brand in the
+  ISO-BMFF `ftyp` box — major or compatible, so `mif1`-major HEIF
+  containers are covered) instead of falling through the sniffer as
+  `png` — it converts via Pillow where the build supports AVIF, and
+  otherwise raises the actionable convert-or-fail error rather than
+  shipping undecodable bytes that render as a silent broken-image
+  placeholder.
+- `Shapes.by_name("")` / `get_by_name("")` no longer match unnamed
+  legacy shapes — `""` is the no-name sentinel, not an addressable
+  name.
+- The SVG `add_picture` error no longer recommends `pip install svglib`
+  (rasterization also needs the `rlPyCairo` backend and the native cairo
+  library, so that advice cannot work in a stock sandbox). WebP and SVG
+  now get separate, accurate remediation hints. Pairs with the
+  presentation-exec v59 snapshot, which bundles `svglib` + `rlPyCairo`
+  so SVG→PNG conversion works in-sandbox.
+
 ## 0.9.0 — eager validation, table overflow diagnostics, and text caps
 
 Publishes the SDK changes already deployed with PPTX Studio after 0.8.1.

athena_python_pptx-0.14.0/CLAUDE.md

@@ -0,0 +1,5 @@
+@AGENTS.md
+
+<!-- AGENTS.md next to this file is the single source of truth for agent
+     instructions. Claude Code does not read AGENTS.md natively, so this file
+     imports it. Add Claude-Code-only rules below this line. -->

{athena_python_pptx-0.10.0 → athena_python_pptx-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: athena-python-pptx
-Version: 0.10.0
+Version: 0.14.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