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

{athena_python_pptx-0.13.0 → 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.13.0 → athena_python_pptx-0.14.0}/CHANGELOG.md

@@ -2,7 +2,182 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
-## Unreleased — `pptx.kit` composition kit
+## 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
@@ -33,7 +208,7 @@ All notable changes to `athena-python-pptx` are documented in this file.
   Documented in `docs/API_PARITY_EXCEPTIONS.md`; demo in
   `examples/kit_demo.py`.
 
-## Unreleased — validate() finds overflow and hidden text, drops containment noise
+## 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

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

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

{athena_python_pptx-0.13.0 → athena_python_pptx-0.14.0}/docs/API_PARITY_EXCEPTIONS.md

@@ -98,6 +98,63 @@ adapter. The REST SDK has no OPC; use `Presentation.upload(path)`
 instead, which uploads the file to the studio backend and returns
 a `Presentation` adapter.
 
+### Axis titles are one paragraph with one font
+
+`axis.axis_title.text_frame` is a python-pptx `TextFrame`: `text`,
+`paragraphs`, and each paragraph's `text` / `runs` / `font` / `add_run()`
+and each run's `text` / `font` work. The `SetAxisTitle` patch carries one
+title string and one font (size, bold, `color.rgb`, name), so:
+
+- `paragraphs` always holds one paragraph; `add_paragraph()` is absent.
+- Several runs join into one title string drawn in the first run's font,
+  layered over `paragraphs[0].font` (which is `axis_title.font`). When a
+  later run's own styling differs, the SDK emits one `UserWarning` per axis
+  title instead of dropping it silently.
+- `italic`, `underline`, `strike`, `color.theme_color`, `cap`, sub/superscript
+  and character spacing are not carried; setting them on the title font emits
+  one `UserWarning` per axis title.
+- Replacing the text (`text_frame.text = …`, `paragraph.text = …`) keeps the
+  title's font. python-pptx starts an unformatted run, but `SetAxisTitle`
+  cannot clear a font field; assign the font fields to change them.
+- An existing title's text is read from the deck snapshot, for SDK-authored and
+  uploaded charts (its font is not).
+
+```python
+tf = chart.value_axis.axis_title.text_frame
+tf.text = "Revenue ($M)"
+run = tf.paragraphs[0].runs[0]
+run.font.size = Pt(10)
+run.font.bold = True
+```
+
+`chart.chart_title.text_frame` is not limited this way — its runs keep their
+own fonts through `SetChartTitleRich`.
+
+### Table cells are one paragraph with one run
+
+python-pptx cells hold any number of paragraphs and runs. The SDK's cell
+`text_frame` is a single paragraph with a single run whose font is the cell's
+font — `paragraphs[0].font` and `paragraphs[0].runs[0].font` are the same
+object, and `add_run()` / `add_paragraph()` return the existing run /
+paragraph.
+
+- Supported run styling: `bold`, `italic`, `size`, `name` (font family) and
+  `color.rgb`, sent on `SetTableCell`; the server writes them to every run of
+  the cell and the export emits them as `a:rPr` attributes / `<a:latin>`.
+- `font.underline` raises `UnsupportedFeatureError`.
+- `font.name` / `font.italic` read back what this session wrote; a cell's
+  own font in an uploaded deck reads as `None`.
+- Assigning `None` to `font.name` / `font.italic` cannot clear a value this
+  session wrote (the wire format has no inherit marker): the cell keeps it and
+  the SDK emits a `UserWarning`. Assign `False` to turn italic off.
+
+```python
+cell.text = "Revenue"
+run = cell.text_frame.paragraphs[0].runs[0]
+run.font.name = "Georgia"
+run.font.italic = True
+```
+
 ### `Presentation(pptx=...)` constructor kwarg — exposed via `Presentation.create(pptx=...)`
 
 Upstream's `Presentation(pptx=None)` accepts a file path / stream
@@ -271,6 +328,46 @@ explicit `run.hyperlink.address = None` with no slide target still sends
 `hyperlinkTargetSlideIndex` on the run, and snapshot rich content with
 that key hydrates back into `run.hyperlink`.
 
+### A run-less paragraph shows one empty run; `add_run()` returns it as `runs[0]` (Unreleased)
+
+In python-pptx a new text box's or autoshape's paragraph has no runs, and so
+does one emptied by `text_frame.text = ""` (or a blank line of
+`text_frame.text = "a\n\nb"`) or by `paragraph.text = ""`; `add_run()` then
+creates `runs[0]`. This SDK seeds such a paragraph with one empty run so
+code that writes `paragraph.runs[0]` directly keeps working. That seed is the
+remaining departure: `len(paragraph.runs)` is 1, not 0, until a run is added.
+
+The first `add_run()` on a paragraph whose only run is that untouched seed
+now returns the seed as `runs[0]`, so the stored element holds the runs
+python-pptx would write and a later `runs[0].text = ...` replaces the text.
+Earlier versions appended the new run at index 1 behind a stored empty run;
+a later `runs[0].text` edit then wrote the empty run and doubled the text.
+
+- The seed is returned once. A second `add_run()` appends a new run.
+- A seed the caller already wrote (`runs[0].text`, `runs[0].font.*`,
+  `runs[0].hyperlink.*`) is a real run; `add_run()` appends after it.
+- Snapshot-loaded paragraphs keep their stored runs and indices, so decks
+  written before this change keep their stored leading empty runs. A lone
+  stored empty run with no formatting (how the server stores an empty line)
+  is returned like the seed; a lone empty run that carries formatting is
+  kept and `add_run()` appends after it, as python-pptx does. The stored
+  form cannot tell an empty line from an empty run a caller added on
+  purpose, so after a reload such a run is reused as well. Export writes no
+  empty-text runs, so stock python-pptx reading the exported file also sees
+  that paragraph with no runs.
+- After a text reset the returned run is bare, as in python-pptx. The
+  server's `SetText` keeps the replaced text's look on the empty run it
+  writes, so `add_run()` first sends `SetRunText` with `resetFormatting` to
+  make that run bare. A pptx-studio server older than the field ignores it,
+  and the run then keeps the replaced text's look. A paragraph stored with no
+  runs (an ingested empty `<a:p/>`) gets its run 0 written the same way, so a
+  style set before the text has a run to land on.
+- `text_frame.clear()` is unchanged: it already leaves no local runs, and
+  its `add_run()` writes into the run the cleared paragraph keeps on the
+  server, which retains the cleared text's look under the `SetText`
+  style-retention contract for clear-and-rebuild. python-pptx returns a bare
+  run there.
+
 ---
 
 ## Agent-Friendly Additions (not in python-pptx)
@@ -429,45 +526,71 @@ slide.shapes.add_textbox(Inches(1), Inches(1), Inches(8), Inches(2))
 
 Report the layout defects a reader would notice, without rendering. An
 empty list means the slide is clean — and a designed slide (cards behind
-their labels, icons inside tiles) reaches it. Warnings come back in this
-order, at most 15 per slide, then a count line
-`"… and N more (M containment overlaps ignored)"`:
-
-1. **Text overflow** — `"text in 'X' likely overflows its box (needs ~N
-   lines of ~M at Spt; …)"` for non-table text whose estimated height
-   (per-paragraph font-metric width → wrapped lines → lines × font × 1.2 +
-   spacing) exceeds the box minus its text-frame margins. Word-wrap-off
-   frames are checked horizontally; auto-fit frames are skipped. When the
-   presentation has a studio client, each hit whose paragraphs share one
-   font size and weight is confirmed with one `POST /measure-text-fit`
-   pinned at that size (`fits: true` drops the warning, at most 12
-   round-trips per call, network errors keep the heuristic verdict); a
-   mixed-font frame (60pt heading over 12pt body) keeps the heuristic
-   verdict because the server lays the frame out at a single font. Table
-   cells whose single-line text is wider than the column are reported here
-   too.
-2. **Hidden text** — `"text in 'X' is covered by 'Y'"`: a text shape at
-   least half covered by a *later* (higher z-order) shape with a solid fill,
-   no transparency and no text. A solid fill the snapshot reports without
+their labels, value labels on bubbles, icons inside tiles) reaches it.
+Warnings come back in this order, at most 15 per slide, then a count line
+`"… and N more (M containment overlaps ignored)"`.
+
+Text is judged by its **ink** — the boxes its laid-out lines occupy — not by
+its frame. Each frame's text is word-wrapped (greedy, at spaces) on the
+glyph-width estimate 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 outline level without a margin 0.375in, as the studio renders),
+with per-paragraph size and line spacing; every line is placed by its paragraph's
+alignment and the frame's vertical anchor (autoshapes centre their text by
+default, text boxes anchor at the top) and widened 10% within its frame so an
+under-estimate cannot hide a collision. A placeholder's alignment or anchor
+inherited from its layout is unknown to the proxy, so its ink covers every
+place the text could be. Text that overflows spills out of its frame the way
+PowerPoint draws it (a studio "fits" verdict pulls it back inside).
+
+1. **Text overflow** — `"text in 'X' likely overflows its box: needs ~2
+   lines at 20pt but only ~1 fits (~0.67in of text in a 0.40in-tall box) —
+   …"` for non-table text whose laid-out height (lines × font × 1.2 × line
+   spacing + paragraph spacing) exceeds the box minus its text-frame
+   margins (`"… but not even one line fits"` when a single line is too
+   tall). Word-wrap-off frames are checked horizontally; auto-fit frames are
+   skipped. When the presentation has a studio client, each hit whose
+   paragraphs share one font size and weight is confirmed with one
+   `POST /measure-text-fit` pinned at that size (`fits: true` drops the
+   warning, at most 12 round-trips per call, network errors keep the
+   heuristic verdict); a mixed-font frame (60pt heading over 12pt body)
+   keeps the heuristic verdict because the server lays the frame out at a
+   single font. The endpoint subtracts PowerPoint's default insets from the
+   box it gets, so the inner box goes out grown by exactly those insets.
+   Table cells are reported here too, when their wrapped text (lines × line
+   height + the cell's top/bottom margins) is taller than the row — every
+   row a vertical merge spans — which is when PowerPoint grows the row, or
+   when one word is wider than the column and PowerPoint breaks it mid-word.
+   Both are confirmed by the same endpoint within the same budget.
+2. **Hidden text** — `"text in 'X' is covered by 'Y' (N% of its text …)"`:
+   text whose ink is at least half covered by a *later* (higher z-order)
+   shape with a solid fill and no transparency — whether or not that shape
+   carries text of its own. A solid fill the snapshot reports without
    transparency data is taken as opaque (PowerPoint's default); any
    transparency set on the proxy or carried as `fillTransparency` disables
-   the rule for that shape. `send_to_back()` / `bring_to_front()` now mirror
-   the move on `slide.shapes` order so the rule sees the intended stack
-   without a refresh.
-3. **Text on text** — two text-bearing shapes (tables count) whose bboxes
-   overlap or nest.
-4. **Other** — off-slide shapes; partial overlaps where exactly one shape
-   carries text (a title running under a card); empty slide-level
+   the rule for that shape. `send_to_back()` / `bring_to_front()` mirror the
+   move on `slide.shapes` order so the rule sees the intended stack without
+   a refresh.
+3. **Text on text** — `"text in 'X' and text in 'Y' overlap by ~0.40x0.20in
+   — the two texts collide"`: two texts (tables count, by their frame) whose
+   inks overlap.
+4. **Other** — off-slide shapes; text that runs over the edge of a visible
+   shape (`"… runs over the edge of 'Y' …"`) or sits partly under a later
+   opaque one (`"… is partly hidden by 'Y' …"`); empty slide-level
    placeholders.
 
-Not reported: one shape fully inside another unless both carry text,
-overlaps between two text-less shapes, and hairline overlaps thinner than
-a text-frame inset (0.05in). Rotated shapes near 90°/270° use their swapped
-visual bbox.
+Not reported: text whose ink sits entirely on a shape (a label on a card or
+bubble, a caption on a picture) unless that shape is drawn over it with an
+opaque fill; a shape sitting in the empty part of a text box;
+frames that overlap while their texts do not; text crossing the edge of a
+plain text box that paints neither fill nor outline; overlaps between two
+text-less shapes; and hairline overlaps thinner than a text-frame inset
+(0.05in). Rotated shapes near 90°/270° use their swapped visual bbox, and
+their ink turns with them.
 
-The overflow estimate uses average glyph widths, so offline it can be off
-by a line either way; render the slide before rebuilding a layout around a
-single warning.
+The estimate uses average glyph widths, so offline it can be off by a line
+either way; render the slide before rebuilding a layout around a single
+warning.
 
 ```python
 warnings = slide.validate()
@@ -730,7 +853,7 @@ charts:
 | `series.marker.style / size / format.fill.fore_color.rgb / format.line.color.rgb` | `SetMarkerStyle` |
 | `axis.major_gridlines.format.line.* / minor_gridlines.format.line.*` | `SetGridlineFormat` |
 | `axis.major_tick_mark / minor_tick_mark / tick_label_position` | `SetAxisTickMarks` |
-| `axis.axis_title.text_frame.text + axis_title.font.*` | `SetAxisTitle` |
+| `axis.axis_title.text_frame.text` / `.paragraphs[0]` (+ `.runs`) and their `font.*` | `SetAxisTitle` (one string, one font — see "Axis titles are one paragraph with one font") |
 | `chart.legend.position` | `SetLegendPosition` |
 | `chart.legend.font.*` | `SetLegendFont` |
 
@@ -794,6 +917,118 @@ picture.line.dash_style = "solid"
 
 ---
 
+## Chart Series Line + Fill Visibility; Ignored Chart Format Writes (unreleased)
+
+`series.format.line` and `series.format.fill.background()` used to be
+local-state-only: the calls succeeded, read back, and never reached the deck
+(a line chart kept its palette colours; the hidden base series of a
+stacked-column waterfall drew as solid bars). They now emit chart patches that
+both the SDK-authored path (`author.ts`) and the ingested path (`patcher.ts`)
+honour, and the studio renderer draws them:
+
+| Property | Patch op | Emitted OOXML |
+|---|---|---|
+| `series.format.line.color.rgb = RGBColor(...)` | `SetSeriesLine` (`lineColorHex`) | `c:ser/c:spPr/a:ln/a:solidFill` |
+| `series.format.line.width = Pt(2)` | `SetSeriesLine` (`lineWidthEmu`) | `<a:ln w="25400">` |
+| `series.format.line.dash_style = MSO_LINE_DASH_STYLE.DASH` | `SetSeriesLine` (`dashStyle`) | `<a:prstDash val="dash"/>` |
+| `series.format.line.fill.background()` / `.fill.solid()` | `SetSeriesLine` (`noLine`) | `<a:ln><a:noFill/></a:ln>` / removed |
+| `series.format.fill.background()` / `.fill.solid()` on a hidden fill | `SetSeriesFillVisible` | `c:ser/c:spPr/<a:noFill/>` / removed |
+| `series.points[i].format.fill.background()` / `.fill.solid()` | `SetPointFillVisible` | `<c:dPt><c:spPr><a:noFill/>` / removed |
+
+python-pptx semantics: on a line / XY / radar series the line is the plotted
+line; on a bar / area / pie / bubble series it is the outline. Assigning `None` to
+`width` or `dash_style` clears the override; assigning a line colour (or
+`fill.fore_color.rgb`) makes a hidden line or fill visible again.
+`dash_style` accepts `MSO_LINE_DASH_STYLE` members, the SDK's snake_case line
+tokens (`"round_dot"`, `"long_dash"`, …) and the `<a:prstDash>` presets
+(`"sysDot"`, `"lgDash"`, …). Gridline `dash_style` now accepts the same forms.
+Reading `series.format.line.dash_style` returns the `MSO_LINE_DASH_STYLE`
+member, or the preset string for the presets that have none (`"dot"`,
+`"sysDashDot"`, `"sysDashDotDot"`; python-pptx cannot read those at all).
+A point's hidden fill is kept on the series, so a later
+`series.points[i].format.fill.solid()`, through a new `format` object or
+after a refresh, shows it again.
+
+**Ignored writes warn instead of vanishing.** Chart format properties that
+still have no patch op keep their value locally (read-after-write works) and
+emit a `UserWarning` — `"<property> is not supported by the Athena studio
+renderer and was ignored"` — once per property per presentation session.
+They never raise, so existing scripts keep running:
+
+| Property | Why it is ignored |
+|---|---|
+| `axis.format.line.*` / `axis.format.fill.*` | no axis line / fill op (hide the axis with `axis.visible = False`) |
+| `axis_title.format.line.*` / `.fill.*` | no axis-title shape op |
+| `axis.major_gridlines.format.fill.*` / `.format.line.fill.*` / `.line.color.theme_color` | gridlines carry only colour / width / dash (hide them with `axis.has_major_gridlines = False`) |
+| `series.points[i].format.line.*` | no per-point outline op |
+| `series.format.line.color.theme_color` | `SetSeriesLine` carries an sRGB colour only |
+| `series.marker.format.fill.background()` / `.fill.fore_color.theme_color` | `SetMarkerStyle` has no hollow or theme fill |
+| `series.marker.format.line.width` / `.dash_style` / `.fill.*` / `.color.theme_color` | `SetMarkerStyle` carries the marker line colour only |
+| `DataLabels.border_color_hex` / `border_width` / `border_dash_style` | the data-label ops carry no border (these were previously sent and silently dropped by the server) |
+
+Other python-pptx chart setters that stay local-only without a warning
+(they are layout or label flags, not format): `Legend.horz_offset` /
+`include_in_layout`, `DataLabels.show_legend_key` / `number_format_is_linked`,
+and field-level `Trendline` edits.
+
+---
+
+## Waterfall Charts (unreleased)
+
+python-pptx has no waterfall chart. `slide.shapes.add_chart(XL_CHART_TYPE.WATERFALL,
+...)` previously produced a plain clustered column chart with no way to mark
+totals; it now authors a waterfall the studio renders and exports.
+
+```python
+cd = CategoryChartData()
+cd.categories = ["FY24", "Price", "Volume", "FX", "FY25"]
+cd.add_series("EBIT", (120, 18, -9, -4, None))   # one series of deltas
+chart = slide.shapes.add_chart(XL_CHART_TYPE.WATERFALL, x, y, cx, cy, cd).chart
+chart.plots[0].subtotals = [0, 4]                # Athena extension
+```
+
+| Surface | Kind | Wire |
+|---|---|---|
+| `chart.plots[0]` on a waterfall | `WaterfallPlot` (a `BarPlot`: `gap_width`, `data_labels`, `has_data_labels` work) | — |
+| `WaterfallPlot.subtotals` (get / set) | Athena extension | `SetWaterfallSubtotals` chart patch |
+| `WaterfallPlot.set_subtotals(indices)` | Athena extension (same as the setter) | `SetWaterfallSubtotals` |
+| `chart.chart_type` | reads back `XL_CHART_TYPE.WATERFALL` | — |
+
+Semantics follow Excel's "Set as total": a subtotal point is drawn from zero
+to its own value and resets the running total; a subtotal left `None` shows
+the running total. Every other point floats from the running total by its
+delta; a `None` delta is a gap. Setting `subtotals` replaces the list (`[]`
+clears it); an index outside the series raises `IndexError`. Exactly one
+series is accepted — more raise `ValidationError` before anything is sent.
+Data labels start on (deltas on floating bars, totals on totals);
+`plots[0].data_labels.show_value = False` turns them off.
+Increase / decrease / total bars take theme accent 1 / 2 / 3; a series fill
+colour paints every bar and `series.points[i].format.fill` overrides one bar.
+`series.format.fill.background()` hides every bar's fill except the bars
+with their own point colour. `chart.replace_data(...)` keeps the totals by
+position and drops any past the new points. A reopened deck's
+`chart.plots[0]` is a `WaterfallPlot` with its `subtotals`.
+
+**Export — a stacked-column waterfall, not a chartEx part.** There is no
+Office-2016 chartEx (`cx:`) author, and a chartEx part only renders in
+PowerPoint 2016+. The exported chart is the classic stacked-column
+construction: an invisible base series (`<a:noFill/>`, left out of the
+legend) plus Increase / Decrease / Total series, with bars that cross zero
+split into above- and below-zero parts because PowerPoint stacks positive and
+negative values separately. It renders in every PowerPoint version, Keynote,
+Google Slides and LibreOffice, stays editable through Edit Data, and a
+re-imported deck renders as the same waterfall. What that construction cannot
+carry, the studio does not draw either, so the preview matches the deck: no
+connector lines, labels centred in the bars (a stacked chart has no
+outside-end position), and no label on a floating bar that crosses zero.
+PowerPoint shows it as a stacked column chart rather than its native waterfall
+type.
+
+Not yet covered: waterfalls ingested from uploaded decks (Office-2016 chartEx
+parts) still arrive without series data and render as a placeholder.
+
+---
+
 ## Table Cell Borders (added in v0.1.78+)
 
 python-pptx exposes table-cell border styling only through raw OOXML
@@ -1346,11 +1581,11 @@ work in addition to SDK surface and are tracked separately.
   `SUNBURST` (118), `HISTOGRAM` (119), `PARETO` (120),
   `BOX_WHISKER` (121), `WATERFALL` (122), `FUNNEL` (123). Closes
   python-pptx#583 ("New Chart Types in Office 2016"), #944
-  (Treemap / Scatter), #651 (Waterfall), #1047 (Box plot). These
-  use the cx-namespace OOXML schema instead of the legacy c-schema;
-  `slide.shapes.add_chart(...)` dispatches through a separate
-  `AddChart2016` wire op so the server can author the cx-flavoured
-  chart-part XML.
+  (Treemap / Scatter), #651 (Waterfall), #1047 (Box plot).
+  `slide.shapes.add_chart(...)` dispatches them through a separate
+  `AddChart2016` wire op. `WATERFALL` authors a real waterfall (see
+  "Waterfall Charts" below); the others are still authored as the
+  nearest legacy chart family until a cx-namespace author exists.
 
 ### Slide- and presentation-level additions
 
@@ -1449,11 +1684,10 @@ upstream surface preserved, additions tagged with
   are set.
 
 - **`DataLabels.border_color_hex / border_width / border_dash_style`**
-  (closes python-pptx#716, 17-comment thread). Adds outline styling
-  to plot- and series-level data labels via the existing
-  `SetDataLabelStyle` / `SetSeriesDataLabelStyle` patch envelopes.
-  Both writes and reads work consistently with the rest of the
-  `DataLabels` surface.
+  (closes python-pptx#716 at the API level, 17-comment thread). The
+  data-label patch ops carry no border fields, so the values read back
+  locally and each setter warns once that it was ignored (see "Chart Series
+  Line + Fill Visibility; Ignored Chart Format Writes").
 
 - **`Chart.set_hyperlink(url=..., target_slide_index=..., tooltip=...)`**
   (closes python-pptx#962). Routes chart-level click-actions through

{athena_python_pptx-0.13.0 → athena_python_pptx-0.14.0}/pptx/__init__.py

@@ -205,7 +205,8 @@ def validate_all_touched() -> dict[int, list[str]]:
       ``ReplaceText`` validate every slide.
     * Validation uses the local proxies (no snapshot refresh) plus, when the
       presentation has a studio client, at most 12 text-measurement
-      round-trips per slide to confirm suspected text overflow.
+      round-trips per slide to confirm suspected text overflow and table
+      row growth.
     * When several decks are open, indexes of the LAST deck whose slide
       carried warnings win on collision; the executor runs one deck per
       script in practice.
@@ -264,7 +265,7 @@ def validate_all_touched() -> dict[int, list[str]]:
     return results
 
 
-__version__ = "0.13.0"
+__version__ = "0.14.0"
 
 __all__ = [
     # Main entry point