athena-python-pptx 0.18.0__tar.gz → 0.19.0__tar.gz

{athena_python_pptx-0.18.0 → athena_python_pptx-0.19.0}/AGENTS.md

@@ -23,7 +23,17 @@ Before adding or modifying any API surface:
 3. Confirm the method/property/parameter exists with the same name and signature
 4. If it doesn't exist in python-pptx, **do not add it** without explicit user approval
 
-### Current status (v0.1.74)
+### Current status
+
+[`API_PARITY_REPORT.md`](API_PARITY_REPORT.md) is generated
+(`scripts/generate_parity_report.py`; `tests/test_parity_report_generated.py`
+fails CI when it is stale): it joins the usage census of agent code
+(`docs/sdk_usage_census.json`, built by `scripts/pull_agent_traces.py` and
+`scripts/sdk_usage_census.py`) with the surface audit and python-pptx's
+surface, and ranks the gaps by usage, used and broken first.
+[`PARITY_QUESTIONS.md`](PARITY_QUESTIONS.md) holds the open questions in that
+order. After an SDK change that moves a member, regenerate both; refresh the
+census (a new trace window) with the steps in `scripts/sdk_usage_census.py`.
 
 **Full public-class parity reached** against python-pptx 1.0.2 across
 three dimensions:
@@ -59,11 +69,27 @@ 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.
+- **Axis-title text frames** have one font: their paragraphs and line
+  breaks are python-pptx's, but runs join into one title string in the
+  first run's font, with a one-time `UserWarning` when that drops styling,
+  and there is no `add_paragraph()`.
+- **Chart and axis titles in lines** are written and read as python-pptx's
+  (a paragraph per `\n`, a line break per `\v`); a run's own text with
+  either character becomes a break in the deck (`docs/API_PARITY_EXCEPTIONS.md`).
+- **Table-cell text frames** hold python-pptx's paragraphs and runs (sent as
+  `SetTableCell.paragraphs` once a cell holds more than one run); an empty
+  cell's paragraph still lists one empty run, a one-run cell's `paragraph.font`
+  is its run's font, and every underline style reads back as `True`
+  (`docs/API_PARITY_EXCEPTIONS.md`).
+
+### Approved Athena extensions
+
+Members python-pptx lacks that were added with explicit approval, each
+documented in [`docs/API_PARITY_EXCEPTIONS.md`](docs/API_PARITY_EXCEPTIONS.md)
+and listed in `tests/test_python_pptx_api_parity.py`'s allowlist:
+`Shapes.add_linked_ole_object()`, `Shapes.add_linked_table()` and
+`Shapes.add_linked_chart()` (approved 2026-10-20), the studio-linking
+methods that bind an element to an Athena source.
 
 ### Intentionally omitted (REST SDK limitations)
 
@@ -73,7 +99,9 @@ local XML / OPC parts:
   shape's element, for python-pptx's shape-tree recipes; see Architecture.)
 - `TextFrame.part`, `Paragraph.part`, `Run.part` — package part access.
 - `FillFormat.from_fill_parent()`, `ColorFormat.from_colorchoice_parent()` — internal XML constructors.
-- `Font.fill` — Font fill format (uncommon; use `font.color` for text color).
+
+`Font.fill` exists: `solid()` and `fore_color` drive `font.color`; gradient,
+pattern and no-fill text raise `UnsupportedFeatureError`.
 
 `Font.language_id` IS now implemented (returns `MSO_LANGUAGE_ID` enum, accepts enum or int LCID) — added in v0.1.68.
 

athena_python_pptx-0.19.0/API_PARITY_REPORT.md

@@ -0,0 +1,220 @@
+# API parity report: athena-python-pptx and python-pptx 1.0.2
+
+<!-- Generated by scripts/generate_parity_report.py; do not edit by hand. tests/test_parity_report_generated.py fails CI when it is stale. -->
+
+Which python-pptx members agent code calls, what the SDK does with each, and the gaps
+ranked by that usage: used and broken first. Three inputs are joined per member:
+
+1. **What agents call** — `docs/sdk_usage_census.json`, built by `scripts/sdk_usage_census.py`
+   from the Python agents sent to Athena's code tools in production traces: static analysis
+   (the code is parsed, never run) types each expression against the SDK's classes and records
+   the member it reaches.
+2. **What the SDK does** — the surface audit (`tests/_surface_audit.py`) probes every public
+   setter and method on a mocked deck: it sends a command, warns once, raises, or sends nothing;
+   `pptx/_unsupported.py` lists members the SDK refuses.
+3. **What python-pptx has** — python-pptx 1.0.2's public members (the parity tests'
+   reference).
+
+Counts are customer **workspaces | sessions | tool calls** in the window; Athena staff traffic is
+counted apart and excluded. A count from fewer than three workspaces reads `<3`.
+
+## Census
+
+- Source: LangSmith agora-production traces; the 60 days from 2026-08-16 to 2026-10-14 (55 of them with SDK code).
+- Customers: 6335 tool calls with SDK code, 290 sessions, 10 workspaces; computer_asset_exec <3; eval 109; execute <3; execute_presentation_code 5992; run_python_code 121; write_file 26.
+- Athena staff: 1335 tool calls, 101 sessions, 5 workspaces. Left out of both: the calls with neither a signed-in user nor a workspace (no workspace is behind them, so their count is withheld).
+- Members used by customers: 743. How the analysis typed them: downcast 17,  heuristic 7,  static 660,  unknown 59 (`unknown`: no SDK class defines the member).
+
+## Used and broken, ranked by usage
+
+Members customers' agents called whose call the SDK does not carry out as python-pptx does today.
+Ranked by customer workspaces, then sessions.
+
+| # | python-pptx member | SDK class | op | Workspaces | Sessions | Tool calls | What the SDK does |
+|---|---|---|---|---|---|---|---|
+| 1 | `Shapes._spTree` | `Shapes` | get | <3 | <3 | <3 | raises: in 4 of 8 probed contexts; athena-python-pptx mirrors a slide's own shape tree, slide.shapes._spTree; a notes slide's, layout's or master's is not mirrored. |
+| 2 | `Chart._chartSpace` | `Chart` | get | <3 | <3 | <3 | raises: python-pptx XML internal: Use the Chart API: chart.plots, chart.series, chart.replace_data(chart_data), chart.has_title / chart.chart_title, chart.value_axis, chart.category_axis. |
+| 3 | `Slide._element` | `Slide` | get | <3 | <3 | <3 | raises: python-pptx XML internal: Use the object's own properties and methods. |
+| 4 | `Subshape.part` | `Paragraph` | get | <3 | <3 | <3 | raises: athena-python-pptx edits a deck that lives on the PPTX Studio server, so there are no OPC package parts or relationships to reach. |
+| 5 | `_ChartSeries._element` | `_ChartSeries` | get | <3 | <3 | <3 | raises: python-pptx XML internal: Use the object's own properties and methods. |
+| 6 | `ColorFormat.brightness` | `_FillColorFormat` | set | <3 | <3 | <3 | raises: Shape fills carry no brightness in the Athena studio (SetShapeStyle has no lumMod / lumOff). |
+
+## Known structural gaps, measured
+
+The gaps the fidelity plan names (`../docs/plans/2026-10-14-powerpoint-fidelity-program.md` §5.3),
+with the members that reach each. A gap no customer reached in the window is not prioritized.
+
+| Gap | Members | Workspaces | Sessions | What the SDK does |
+|---|---|---|---|---|
+| A table cell holds several paragraphs and runs | `_TableCellParagraph.add_run`, `_TableCellTextFrame.add_paragraph` | 3 | 23 | Closed: add_run() / add_paragraph() add a run / paragraph, each run keeps its own font, and the cell's text body is sent run by run (SetTableCell.paragraphs) |
+| Table-cell paragraph spacing and level | `_TableCellParagraph.line_spacing`, `_TableCellParagraph.space_before`, `_TableCellParagraph.space_after`, `_TableCellParagraph.level` | <3 | <3 | Closed: sent with the cell's paragraphs (SetTableCell.paragraphs) |
+| Table-cell word wrap and auto-size | `_TableCellTextFrame.word_wrap`, `_TableCellTextFrame.auto_size` | 3 | 19 | word_wrap = True, the value every measured use sets, is how a cell lays out its text and is accepted; False, None and auto_size warn once and keep the value locally |
+| Table-cell colours are sRGB only; no table-cell hyperlink writes (no customer use) | `_TableCellFontColorFormat.theme_color`, `_TableCellFillColorFormat.theme_color`, `_TableCellHyperlink.address` | 0 | 0 | raise UnsupportedFeatureError |
+| 3-D, stock and surface charts (no customer use) | `XL_CHART_TYPE.THREE_D_*`, `XL_CHART_TYPE.STOCK_*`, `XL_CHART_TYPE.SURFACE*` | 0 | 0 | add_chart() raises UnsupportedFeatureError |
+| Gradient and pattern text (Font.fill) (no customer use) | `_FontFillFormat.gradient`, `_FontFillFormat.patterned` | 0 | 0 | raise UnsupportedFeatureError |
+| Notes-slide shapes and placeholders (no customer use) | `NotesSlide.shapes`, `NotesSlide.placeholders`, `NotesSlide.notes_placeholder` | 0 | 0 | empty collections; notes text works through notes_slide.notes_text_frame |
+| Layout and master backgrounds are read-only (no customer use) | `_LayoutBackgroundFill.solid`, `_LayoutBackgroundColor.rgb` | 0 | 0 | raise UnsupportedFeatureError |
+
+Workspaces and sessions are the largest count of any one member of the gap (a lower bound on the
+gap's reach).
+
+## Members agents call that python-pptx does not have
+
+Not parity gaps: python-pptx raises `AttributeError` for these too. They show where agents guess
+at an API, which the skill text and error messages can steer.
+
+| Member | op | Workspaces | Sessions | Tool calls |
+|---|---|---|---|---|
+| `Slides.move` | call | <3 | <3 | <3 |
+| `_TableCellTextFrame.replace_text` | call | <3 | <3 | <3 |
+| `Client.timeout` | get | <3 | <3 | <3 |
+| `DeckSnapshot.get` | call | <3 | <3 | <3 |
+| `Shapes.remove` | call | <3 | <3 | <3 |
+| `ActionSetting.tooltip` | set | <3 | <3 | <3 |
+| `CategoryAxis.major_unit` | set | <3 | <3 | <3 |
+| `DataLabel._dLbl` | get | <3 | <3 | <3 |
+| `DataLabel.number_format_is_linked` | set | <3 | <3 | <3 |
+| `LineFormat._get_or_add_ln` | call | <3 | <3 | <3 |
+| `Picture.insert_picture` | get | <3 | <3 | <3 |
+| `Presentation._buffer` | get | <3 | <3 | <3 |
+| `Presentation.move_slide` | call | <3 | <3 | <3 |
+| `Region.split` | call | <3 | <3 | <3 |
+| `Run._parent` | get | <3 | <3 | <3 |
+| `Shape._placeholder` | get | <3 | <3 | <3 |
+| `Shape._properties` | get | <3 | <3 | <3 |
+| `Shape._shape_id` | get | <3 | <3 | <3 |
+| `Shape.id` | get | <3 | <3 | <3 |
+| `Shape.margin_bottom` | set | <3 | <3 | <3 |
+| `Shape.margin_left` | set | <3 | <3 | <3 |
+| `Shape.margin_right` | set | <3 | <3 | <3 |
+| `Shape.margin_top` | set | <3 | <3 | <3 |
+| `Shape.vertical_anchor` | set | <3 | <3 | <3 |
+| `Shapes.clear_shapes` | call | <3 | <3 | <3 |
+| … 17 more | | | | |
+
+Agent code also reached names neither the SDK nor python-pptx has (attributes it hung on SDK
+objects, made-up enum members) on `Client`, `MSO_SHAPE`, `Paragraph`, `Shape`, `SlideLayout`, `Slides`, `_ChartSeries`. The census
+records them only as `?`: a name the code invents may say anything.
+
+## Most-used members (top 60)
+
+| # | python-pptx member | SDK class | op | Workspaces | Sessions | Tool calls | Status |
+|---|---|---|---|---|---|---|---|
+| 1 | `Slide.shapes` | `Slide` | get | 10 | 256 | 4644 | works |
+| 2 | `Presentation.slides` | `Presentation` | get | 10 | 255 | 5245 | works |
+| 3 | `Presentation()` | `Presentation` | new | 10 | 244 | 4960 | works |
+| 4 | `Presentation.slide_layouts` | `Presentation` | get | 10 | 185 | 881 | works |
+| 5 | `Shape.text_frame` | `Shape` | get | 9 | 247 | 3053 | works |
+| 6 | `TextFrame.paragraphs` | `TextFrame` | get | 9 | 227 | 2220 | works |
+| 7 | `Pt()` | `Pt` | new | 9 | 224 | 2237 | works |
+| 8 | `Font.color` | `Font` | get | 9 | 216 | 1733 | works |
+| 9 | `_Run.font` | `Run` | get | 9 | 215 | 1954 | works |
+| 10 | `Font.size` | `Font` | set | 9 | 213 | 1897 | works |
+| 11 | `ColorFormat.rgb` | `_FontColorFormat` | set | 9 | 213 | 1636 | works |
+| 12 | `Inches()` | `Inches` | new | 9 | 212 | 2179 | works |
+| 13 | `Font.bold` | `Font` | set | 9 | 211 | 1594 | works |
+| 14 | `RGBColor()` | `RGBColor` | new | 9 | 210 | 2071 | works |
+| 15 | `TextFrame.word_wrap` | `TextFrame` | set | 9 | 205 | 1427 | works |
+| 16 | `_BaseGroupShapes.add_textbox` | `Shapes` | call | 9 | 201 | 1263 | works |
+| 17 | `_Paragraph.alignment` | `Paragraph` | set | 9 | 179 | 1057 | works |
+| 18 | `TextFrame.add_paragraph` | `TextFrame` | call | 9 | 179 | 940 | works |
+| 19 | `_BaseSlide.name` | `SlideLayout` | get | 9 | 172 | 464 | works |
+| 20 | `_Run.text` | `Run` | set | 9 | 169 | 1047 | works |
+| 21 | `BaseShape.shape_type` | `Shape` | get | 9 | 168 | 433 | works |
+| 22 | `Presentation.batch` | `Presentation` | call | 9 | 159 | 2190 | works (Athena extension) |
+| 23 | `TextFrame.margin_left` | `TextFrame` | set | 9 | 153 | 800 | works |
+| 24 | `_Paragraph.add_run` | `Paragraph` | call | 9 | 151 | 805 | works |
+| 25 | `TextFrame.margin_right` | `TextFrame` | set | 9 | 149 | 709 | works |
+| 26 | `Presentation.slide_width` | `Presentation` | get | 9 | 148 | 401 | works |
+| 27 | `TextFrame.margin_top` | `TextFrame` | set | 9 | 147 | 691 | works |
+| 28 | `Presentation.slide_height` | `Presentation` | get | 9 | 142 | 316 | works |
+| 29 | `Font.name` | `Font` | set | 9 | 132 | 816 | works |
+| 30 | `TextFrame.margin_bottom` | `TextFrame` | set | 9 | 131 | 607 | works |
+| 31 | `FillFormat.fore_color` | `FillFormat` | get | 8 | 201 | 1373 | works |
+| 32 | `Shape.fill` | `Shape` | get | 8 | 200 | 1263 | works |
+| 33 | `FillFormat.solid` | `FillFormat` | call | 8 | 199 | 1302 | works |
+| 34 | `ColorFormat.rgb` | `_FillColorFormat` | set | 8 | 199 | 1301 | works |
+| 35 | `Shape.line` | `Shape` | get | 8 | 194 | 1228 | works |
+| 36 | `_BaseGroupShapes.add_shape` | `Shapes` | call | 8 | 189 | 1160 | works |
+| 37 | `BaseShape.name` | `Shape` | get | 8 | 186 | 1454 | works |
+| 38 | `FillFormat.background` | `LineFillFormat` | call | 8 | 181 | 1031 | works |
+| 39 | `LineFormat.fill` | `LineFormat` | get | 8 | 181 | 1033 | works |
+| 40 | `PP_PARAGRAPH_ALIGNMENT.CENTER` | `PP_PARAGRAPH_ALIGNMENT` | enum | 8 | 162 | 856 | works |
+| 41 | `LineFormat.color` | `LineFormat` | get | 8 | 157 | 822 | works |
+| 42 | `ColorFormat.rgb` | `_LineColorFormat` | set | 8 | 155 | 809 | works |
+| 43 | `LineFormat.width` | `LineFormat` | set | 8 | 150 | 752 | works |
+| 44 | `Font.italic` | `Font` | set | 8 | 138 | 808 | works |
+| 45 | `Slides.add_slide` | `Slides` | call | 8 | 134 | 718 | works |
+| 46 | `_Paragraph.space_after` | `Paragraph` | set | 8 | 115 | 448 | works |
+| 47 | `PP_PARAGRAPH_ALIGNMENT.RIGHT` | `PP_PARAGRAPH_ALIGNMENT` | enum | 8 | 114 | 493 | works |
+| 48 | `Slide.validate` | `Slide` | call | 8 | 114 | 999 | works (Athena extension) |
+| 49 | `Presentation.flush` | `Presentation` | call | 8 | 106 | 1176 | works (Athena extension) |
+| 50 | `Presentation.slide_size_inches` | `Presentation` | get | 8 | 75 | 151 | works (Athena extension) |
+| 51 | `_Paragraph.runs` | `Paragraph` | get | 7 | 176 | 1601 | works |
+| 52 | `MSO_VERTICAL_ANCHOR.MIDDLE` | `MSO_ANCHOR` | enum | 7 | 170 | 971 | works |
+| 53 | `TextFrame.vertical_anchor` | `TextFrame` | set | 7 | 164 | 868 | works |
+| 54 | `MSO_AUTO_SHAPE_TYPE.RECTANGLE` | `MSO_SHAPE` | enum | 7 | 136 | 704 | works |
+| 55 | `PP_PARAGRAPH_ALIGNMENT.LEFT` | `PP_PARAGRAPH_ALIGNMENT` | enum | 7 | 122 | 490 | works |
+| 56 | `BaseShape.top` | `Shape` | set | 7 | 118 | 408 | works |
+| 57 | `Table.cell` | `Table` | call | 7 | 112 | 738 | works |
+| 58 | `_Cell.text_frame` | `TableCell` | get | 7 | 109 | 650 | works |
+| 59 | `Table.columns` | `Table` | get | 7 | 108 | 509 | works |
+| 60 | `TextFrame.paragraphs` | `_TableCellTextFrame` | get | 7 | 108 | 636 | works |
+
+## Errors in customers' tool results
+
+API-name-only signals from the tool results: the exception class, a missing attribute of an SDK
+class, the feature tag of the SDK's unsupported errors. **Now** checks the SDK as it is today.
+
+| Signal | Workspaces | Tool calls | Now |
+|---|---|---|---|
+| `UnsupportedFeatureError` | 8 | 70 |  |
+| `UnsupportedFeatureError:[Shape._element]` | 6 | 28 | fixed (the member exists now) |
+| `UnsupportedFeatureError:[cell font.name]` | 6 | 34 | no longer raised |
+| `ValueError` | 6 | 66 |  |
+| `AttributeError` | 5 | 83 |  |
+| `RemoteError` | 5 | 47 |  |
+| `TypeError` | 5 | 35 |  |
+| `BatchPartialError` | 4 | 13 |  |
+| `ConnectionError` | 4 | 39 |  |
+| `FlushAllError` | 4 | 19 |  |
+| `MaxRetryError` | 4 | 39 |  |
+| `NameError` | 4 | 21 |  |
+| `ReadTimeoutError` | 4 | 39 |  |
+| `TimeoutError` | 4 | 39 |  |
+| `AttributeError:Slides._sldIdLst` | 3 | 10 | fixed (the member exists now) |
+| `FileNotFoundError` | 3 | 4 |  |
+| `ImportError` | 3 | 16 |  |
+| `IndexError` | 3 | 9 |  |
+| `KeyError` | 3 | 5 |  |
+| `ModuleNotFoundError` | 3 | 6 |  |
+| `UnsupportedFeatureError:[cell font.italic]` | 3 | 7 | no longer raised |
+| `AttributeError:AxisTitleTextFrame.paragraphs` | <3 | <3 | fixed (the member exists now) |
+| `AttributeError:BackgroundFill.type` | <3 | <3 | fixed (the member exists now) |
+| `AttributeError:Run._r` | <3 | <3 | fixed (the member exists now) |
+| `AttributeError:Shapes._spTree` | <3 | <3 | fixed (the member exists now) |
+
+## Class-level parity with python-pptx 1.0.2
+
+- 150 python-pptx classes are compared member by member (`tests/test_python_pptx_api_parity.py`); their public members missing from the SDK: 432 allowlisted (XML elements, OPC parts, chart-workbook builders, listed in `docs/API_PARITY_EXCEPTIONS.md`), 0 unexpected.
+- Writes the SDK refuses or ignores, member by member: the generated `unsupported-writes` table in
+  `docs/API_PARITY_EXCEPTIONS.md`.
+
+## Method and privacy
+
+- `scripts/pull_agent_traces.py` reads the code-tool runs of the production LangSmith project
+  (read-only) into a local directory; `scripts/sdk_usage_census.py extract` turns each run's code
+  into events and `aggregate` counts them. Raw traces and event files never leave the operator's
+  machine.
+- An event is a class, member and parameter name, an enum member name, or `True` / `False` / `None`
+  assigned to a property: no literal, no string, no name the agent's code defines. Workspace and
+  session ids are hashed with a per-run salt and dropped after counting.
+- Population: a call is Athena staff when its signed-in user is staff, or when it ran without a
+  signed-in user (an automation) in a workspace where staff made most signed-in calls.
+- Typing: each expression is typed from the SDK's annotations (and, where a member has none, from
+  the classes its `return` statements build). A member only a subclass defines is credited to that
+  subclass (`downcast`); a name the code never assigns is typed by agents' naming convention
+  (`prs`, `slide`, `tf`, `cell`: the executor keeps globals between calls) (`heuristic`).
+- Limits: code that reaches the SDK through objects the analysis cannot type (dict lookups, helper
+  classes) is not counted, so counts are lower bounds; customer VPC environments keep their own
+  traces and are not in this census.

{athena_python_pptx-0.18.0 → athena_python_pptx-0.19.0}/CHANGELOG.md

@@ -2,6 +2,198 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.19.0 — `Shapes.add_linked_chart()`: a chart whose data is a source range
+
+- `slide.shapes.add_linked_chart(chart_type, source, anchor, left=, top=,
+  width=, height=, series_in='columns', freshness_mode='athena_refreshable',
+  version_policy=None, title=None, name=None)` sends `AddLinkedChart`. The
+  studio reads the range and writes the chart's categories and series from
+  it, and the chart refreshes from the range as a linked table does.
+- An Athena studio-linking extension with no python-pptx counterpart, beside
+  `add_linked_table()` and `add_linked_ole_object()`, added with explicit
+  approval (2026-10-20). See `docs/API_PARITY_EXCEPTIONS.md`.
+- Column, bar, line, area, pie and doughnut chart types; a scatter, bubble,
+  radar or Office 2016 type raises `UnsupportedFeatureError`.
+- Needs a studio with `AddLinkedChart` in its command schema (pptx-studio
+  since the linked-chart refresh work, #45113).
+
+## 0.19.0 — a text write keeps what someone typed after the SDK read the box
+
+- A write of a box's text (`text_frame.text`, `paragraph.text`,
+  `text_frame.clear()`, `add_paragraph()`, a hyperlink change, …) sends
+  `SetText` with `baseText`: the frame's text as the SDK read it from the
+  snapshot, or last wrote it (python-pptx's `text_frame.text`, a line break
+  as `\v`). A run's (`run.text`, `run.upper()`, …) sends `SetRunText` with the
+  run's. When the box holds other text, someone changed it between the read
+  and the write (an executor run sends its writes when the script ends), and
+  the studio merges three ways: the SDK's change goes onto the box's current
+  text, so their typing is kept, and a word they deleted stays deleted. Where
+  both changed the same words, both versions are kept, theirs first (#44914,
+  PR 8).
+- No public API changes, and python-pptx code reads and writes as before:
+  `text_frame.text` reads what the SDK wrote until the deck is read again.
+- After `text_frame.replace_text()` (the studio replaces in the text it finds)
+  the frame's next write sends no base, until the frame is read again or
+  written whole.
+- Needs a studio that merges (pptx-studio with `baseText` in its command
+  schema). An older studio drops the field, as it drops any key it does not
+  declare, and writes the text over the box as before.
+
+## 0.19.0 — chart and axis titles in lines read and write as python-pptx's
+
+- `chart.chart_title.text_frame` and `axis.axis_title.text_frame` hold
+  python-pptx's paragraphs and line breaks. `text_frame.text = "a\nb\vc"` is a
+  paragraph per `\n`-separated line and a line break for each `\v`, and the
+  saved deck gets them so (it got one run whose text held the line feeds);
+  `paragraph.text = "a\nb"` makes both line breaks. `text_frame.text` reads
+  `\n` between paragraphs and `\v` for a line break, `paragraphs` one per
+  line (an axis title had one), and a paragraph's `runs` leave its line breaks
+  out. An uploaded deck's titles read the same way, where a line break
+  (`a:br`) read as `\n`.
+- A chart title's runs styled across its lines (`paragraphs[i].runs[j].font`,
+  a paragraph from `add_paragraph()`) reach the deck in their fonts, each in
+  its paragraph: `SetChartTitleRich` carries each paragraph break as a run of
+  `"\n"` and each line break as a run of `"\v"`. They were sent as one
+  paragraph, the paragraphs run together.
+- Departures (a run's own text with a line feed, the font kept on replaced
+  text, trimmed chart titles, fields read as runs):
+  `docs/API_PARITY_EXCEPTIONS.md`, "Chart and axis titles in lines".
+- Needs a studio that writes titles in lines; an older one writes each
+  paragraph break as a line feed inside a run, and a line break as a vertical
+  tab the deck's XML cannot hold.
+
+## 0.19.0 — a chart point's own line reads and writes as python-pptx's
+
+- `series.points[i].format.line` is the point's own line
+  (`c:dPt/c:spPr/a:ln`): the outline of its bar, slice or bubble, or on a
+  line or XY series the segment ending at it. `color.rgb`, `width`,
+  `dash_style`, `fill.background()` and `fill.solid()` emit a `SetPointLine`
+  chart patch for that point (the series' line is left alone), which the deck
+  gets as python-pptx writes it; they warned that they were ignored and sent
+  nothing. Reads return the point's own line as the uploaded file has it (an
+  uploaded slice's white separator reads `MSO_FILL.SOLID`, `FFFFFF`, its
+  width; a point repeating its series' line reads that copy), and `width`
+  reads `0` for a point without one, as python-pptx's does. `color.theme_color` still warns. Departures:
+  `docs/API_PARITY_EXCEPTIONS.md`.
+- Needs a studio with the `SetPointLine` op; an older one rejects the batch
+  that carries it.
+
+## 0.19.0 — converting an uploaded file keeps its id
+
+- Opening an uploaded `.pptx`/`.potx` that was never converted says to convert
+  it with `convert_powerpoint_to_athena_presentation` and then open the same id:
+  the upload itself becomes the presentation. It said the conversion creates a
+  NEW presentation with its own id, which Athena's conversion no longer does.
+
+## 0.19.0 — a chart's date axis reads as python-pptx's `DateAxis`
+
+- `chart.category_axis` on an uploaded chart whose category axis is a
+  `c:dateAx` (and that has no `c:catAx`) is a `DateAxis`, as in python-pptx
+  1.0.2, its `category_type` `XL_CATEGORY_TYPE.TIME_SCALE`. It was a
+  `CategoryAxis` that read nothing of the axis (the studio did not read date
+  axes): its number format, its link to the source, its title, gridlines,
+  reversal and visibility now read back as the deck has them. Its edits reach
+  the date axis, as before.
+- `CategoryAxis.category_type` reads `XL_CATEGORY_TYPE.CATEGORY_SCALE`, as
+  python-pptx's does; it read `None`. After the SDK's own setter it reads the
+  type written.
+- Needs a studio that reads date axes (`AxisSpec.dateAxis`); with an older one
+  `category_axis` stays a `CategoryAxis`.
+
+## 0.19.0 — table cells hold paragraphs and runs
+
+- A table cell's text frame holds python-pptx's paragraphs and runs.
+  `cell.text_frame.add_paragraph()` and `paragraph.add_run()` add a paragraph or
+  a run, where they handed back the cell's single paragraph or run with a
+  warning: a "**Label:** value" cell built from two runs kept only the last
+  run's text, in its formatting, and a cell built paragraph by paragraph kept
+  only its last line. These were the most-used gaps in customers' agent code
+  (`API_PARITY_REPORT.md`). Each run has its own `font` (`bold`, `italic`,
+  `size`, `name`, `color.rgb`, and now `underline`, which raised), each
+  paragraph its own `alignment`, `level`, `line_spacing`, `space_before` and
+  `space_after` (which warned and were dropped) and `font` (its run defaults,
+  `a:defRPr`), and `text_frame.clear()` / `paragraph.clear()` keep the
+  paragraph's properties, as in python-pptx. Assigning `None` removes a run's
+  or paragraph's own value, and a run added with no text stays an empty run. A
+  cell holding more than one run is sent whole (`SetTableCell.paragraphs`, with
+  its text beside it for a studio that predates the field). On an uploaded
+  table a kept run keeps its own run properties, a kept paragraph its own
+  paragraph properties and end mark, and the export writes only what the edit
+  changed; an uploaded cell's runs read their own family, italic and underline.
+  Needs a studio with `SetTableCell.paragraphs`; an older one applies the
+  cell's text alone.
+- `cell.text_frame.word_wrap = True` no longer warns: a table cell's text wraps
+  at the cell width in PowerPoint and the studio, which is what `True` asks for.
+- `run.text = …` on a table cell holding one run keeps the run, as python-pptx's
+  does: only its text changes, and the font, size, colour, bold, italic and link
+  it had in the uploaded deck (or that this session wrote) stay, with its
+  paragraph's alignment. It retyped the cell (`cell.text`), which dropped every
+  property read from the deck: a template's styled cell came out plain. The
+  stored run is kept (`SetTableCell.paragraphs`, `keep`) and only its text is
+  sent; a studio that predates the field applies the text beside it, which
+  keeps the run's style. An uploaded cell's empty run (a template's run
+  formatted for text to come) is a run too: given text (or an underline) it
+  keeps its properties and link, and `paragraph.add_run()` adds a run after it,
+  as python-pptx's does, where the text went in a new, plain run (or in that
+  run). On a table the SDK built, the font written on an empty cell's run in an
+  earlier session goes with the text it is given, as this session's does.
+- On a table the SDK built, a run's bold or colour written before a family, an
+  alignment or italic reads back after a refresh: it read `None`, while the
+  studio drew it and the downloaded deck had it.
+- With a studio from this release, `font.bold = False` (`italic`, `underline`)
+  on a table the SDK built reaches the downloaded deck as `b="0"` (`i="0"`,
+  `u="none"`), as python-pptx writes it: PowerPoint drew a header run turned off
+  in the table style's bold, where the studio drew it regular. The fix is in the
+  studio's export, so it applies to every SDK version once the studio deploys;
+  an uploaded table already wrote them.
+  `tests/test_table_cell_formatting_parity.py` compares both with stock
+  python-pptx in session, after a refresh and in the exported XML.
+- `shape.shadow.inherit = False` on a shape without a shadow of its own gives
+  it python-pptx's empty effect list (`<a:effectLst/>` in the downloaded
+  deck), so it casts no shadow, the one its theme effect style casts included,
+  and `inherit` reads `False` after the deck is reopened. It changed nothing
+  before: PowerPoint kept showing the style's shadow (an Office 2007 theme's
+  second effect style, which `add_shape()` names), and a reopened deck read
+  `True`. `inherit = True` removes the shape's own shadow and that list, and
+  `shadow.visible = False` on a shape with a shadow of its own keeps its
+  effect list, emptied, as deleting the `<a:outerShdw>` would (the export
+  dropped the list, and PowerPoint drew the style's shadow in its place). An
+  uploaded shape with an effect list of its own, an empty `<a:effectLst/>`
+  included, reads `inherit == False` as in python-pptx (it read `True`), and
+  `inherit = True` removes that list, every effect in it, from the downloaded
+  deck. A shadow the shape takes from its style is not reported as its own:
+  `inherit` stays `True` and `visible` `False`. Needs a studio with
+  `SetShapeShadow.inherit`; an older one ignores the field.
+- `line.dash_style` on an uploaded line reads its `<a:prstDash>` as python-pptx
+  1.0.2 does: `sysDash` is `SQUARE_DOT`, `sysDot` `ROUND_DOT`, `lgDashDotDot`
+  `DASH_DOT_DOT` and an explicit `solid` `SOLID`, where the studio's import read
+  `sysDash` as `DASH`, `sysDashDot` as `DASH_DOT` and `lgDashDotDot` as no dash
+  at all (on a connector, `LONG_DASH_DOT`), and a shape's explicit `solid` as
+  `None`. The presets python-pptx has no member for (`dot`, `sysDashDot`,
+  `sysDashDotDot`) raise its `ValueError`, as python-pptx does. A dash set in
+  the session reads back as the preset the studio writes for it. Needs a
+  studio that sends `strokeDashPreset`; with an older one, and for decks
+  imported before it, `dash_style` reads as before.
+- `font.fill.type` reads a run's own fill as python-pptx does:
+  `MSO_FILL.GRADIENT` for gradient text (`<a:gradFill>`), `MSO_FILL.BACKGROUND`
+  for hollow text (`<a:noFill/>`), `MSO_FILL.SOLID` for a colour of its own and
+  `None` when the run inherits its fill. It read `None` unless `fill.solid()`
+  had been called in the session, and then the string `"solid"`. Setting
+  `font.color` on gradient or hollow text makes it solid, as in python-pptx.
+  The glyph outline (`<a:ln>`, which python-pptx has no API for) and a
+  gradient are carried unchanged when the SDK resends a run. Needs a studio
+  that stores `textFill`; with an older one, and for decks imported before it
+  until they are imported again, `fill.type` reads as before.
+- `font.fill.background()` makes the text of a run or a paragraph's font
+  transparent (`<a:noFill/>`), as python-pptx does: hollow glyphs, drawn by
+  their outline alone (an uploaded run's `<a:ln>`) and invisible without one.
+  It raised. A colour set afterwards fills the text again, within one batch
+  too. Table and chart text still raise. `font.fill.solid()` on hollow or
+  gradient text removes that fill, and the text takes the colour it inherits
+  until a colour is set (python-pptx writes a colourless `<a:solidFill/>`); it
+  only recorded the fill type. Needs a studio that stores `textFill`; an older
+  one ignores the writes.
+
 ## 0.18.0 — chart.chart_area / chart.plot_area format and add_chart(name=)
 
 - `chart.chart_area.format` and `chart.plot_area.format` now round-trip fill

athena_python_pptx-0.19.0/PARITY_QUESTIONS.md

@@ -0,0 +1,112 @@
+# athena-python-pptx ↔ python-pptx — open parity questions
+
+The open gaps and design questions between this SDK and python-pptx 1.0.2, in the order to work
+them: by how much customers' agent code uses each. Sister documents:
+
+- [`API_PARITY_REPORT.md`](API_PARITY_REPORT.md) — generated: the usage census joined with the
+  surface audit, with every used member's status.
+- [`docs/API_PARITY_EXCEPTIONS.md`](docs/API_PARITY_EXCEPTIONS.md) — the deviations this SDK makes on
+  purpose, and the generated tables of the members it refuses or ignores.
+
+Usage comes from `docs/sdk_usage_census.json` (`scripts/sdk_usage_census.py`): the customer
+workspaces and sessions whose agent code reached a member in the census window. A gap no customer
+reached stays listed, unscheduled, until a later census moves it.
+
+## Used and broken today
+
+<!-- BEGIN GENERATED: ranked-gaps (scripts/generate_parity_report.py; do not edit by hand) -->
+Census: the 60 days from 2026-08-16 to 2026-10-14; counts are customer workspaces | sessions (`<3`: fewer than three workspaces). Full table: `API_PARITY_REPORT.md`.
+
+| # | Member | SDK class | Workspaces | Sessions | What the SDK does |
+|---|---|---|---|---|---|
+| 1 | `Shapes._spTree` | `Shapes` | <3 | <3 | raises: in 4 of 8 probed contexts; athena-python-pptx mirrors a slide's own shape tree, slide.shapes._spTree; a notes slide's, layout's or master's is not mirrored. |
+| 2 | `Chart._chartSpace` | `Chart` | <3 | <3 | raises: python-pptx XML internal: Use the Chart API: chart.plots, chart.series, chart.replace_data(chart_data), chart.has_title / chart.chart_title, chart.value_axis, chart.category_axis. |
+| 3 | `Slide._element` | `Slide` | <3 | <3 | raises: python-pptx XML internal: Use the object's own properties and methods. |
+| 4 | `Subshape.part` | `Paragraph` | <3 | <3 | raises: athena-python-pptx edits a deck that lives on the PPTX Studio server, so there are no OPC package parts or relationships to reach. |
+| 5 | `_ChartSeries._element` | `_ChartSeries` | <3 | <3 | raises: python-pptx XML internal: Use the object's own properties and methods. |
+| 6 | `ColorFormat.brightness` | `_FillColorFormat` | <3 | <3 | raises: Shape fills carry no brightness in the Athena studio (SetShapeStyle has no lumMod / lumOff). |
+<!-- END GENERATED: ranked-gaps -->
+
+## Open, in usage order
+
+### python-pptx XML internals agents reach
+
+In the table above, each from fewer than three workspaces: `chart._chartSpace`, `slide._element`,
+`series._element`, `paragraph.part`, and `shapes._spTree` where it is not a slide's own (a notes
+slide's, layout's or master's shapes; the census cannot tell which the agents read). Each raises
+`UnsupportedAttributeError` naming the supported API. The text, table and shape-tree mirrors (0.17)
+cover the recipes customers used most.
+
+**Question:** mirror a chart's or a slide's XML only when a census shows a recipe at three or
+more workspaces.
+
+### Shape fill brightness
+
+In the table above, from fewer than three workspaces: `shape.fill.fore_color.brightness = …` raises; the
+studio's fill model has no `lumMod` / `lumOff`.
+
+### Members agents invent
+
+Not parity gaps (python-pptx raises too), listed in the report's "Members agents call that
+python-pptx does not have": a misspelt `MSO_SHAPE.ISOCELES_TRIANGLE`, `prs.slides.move(…)` /
+`prs.move_slide(…)`, `shapes.remove(…)`, `category_axis.major_unit`, and agents setting the SDK's
+private HTTP client timeouts (`Client.timeout`, and attributes of their own on `Client`), which
+matches the read timeouts in the error signals.
+
+**Question:** which of these deserve a teaching `AttributeError` (as `GUESSED_MEMBERS` gives the
+slide-move guesses) or a line in the skill text.
+
+## Open, with no customer use in the window (unscheduled)
+
+- **3-D, stock and surface charts** — `add_chart()` raises `UnsupportedFeatureError`. The deck
+  census found no stock chart in any customer deck either.
+- **Gradient and pattern text** (`Font.fill.gradient()` / `.patterned()`) — raise.
+- **Notes-slide shapes and placeholders** (`NotesSlide.shapes`, `.placeholders`,
+  `.notes_placeholder`) — empty collections; `notes_slide.notes_text_frame` carries notes text.
+  `prs.notes_master` raises.
+- **Layout and master backgrounds** — read-only; `fill.solid()` and colour writes raise.
+- **Table-cell theme colours and hyperlinks** — `font.color.theme_color`,
+  `fill.fore_color.theme_color` and `run.hyperlink.address` on a cell raise; a cell's link is
+  cell-wide (`SetTableCell.hyperlinkUrl`), so every run of a cell reads it.
+- **Table-cell `word_wrap = False` / `None` and `auto_size`** — warn once and keep the value
+  locally. `word_wrap = True` is accepted (see Resolved).
+- **`MSO_LANGUAGE_ID.MIXED`** — exists for parity; nothing returns it (runs are addressed one at a
+  time).
+- **`Area3DPlot`** behaves as `AreaPlot`.
+- **`XyChartData.add_series(name, values)`** — signature drift from python-pptx's
+  `add_series(name, number_format=None)` (documented in `docs/API_PARITY_EXCEPTIONS.md`).
+
+## Resolved since the 2026-05 report
+
+- **Table cells hold python-pptx's paragraphs and runs** — the census's most-used gap
+  (`_TableCellParagraph.add_run` 3 workspaces / 23 sessions, `_TableCellTextFrame.add_paragraph`
+  3 / 10). `add_run()` and `add_paragraph()` add a run or paragraph, each run keeps its own font
+  (`underline` included), a paragraph carries its own alignment, level, line spacing and space
+  before / after, and `clear()` keeps the first paragraph's properties, as in python-pptx. The SDK
+  sends the cell's whole text body (`SetTableCell.paragraphs`); an uploaded cell's runs keep their
+  own XML and take only what an edit wrote. `tests/test_table_cell_runs_parity.py` compares the
+  reads with stock python-pptx in session, after a refresh and in the exported deck.
+- **`cell.text_frame.word_wrap = True`** (3 workspaces / 19 sessions) is accepted without a
+  warning: PowerPoint and the studio wrap a cell's text at the cell width, which is what `True`
+  asks for. It reads back in the session; after a refresh it reads `None` (python-pptx reads the
+  `wrap="square"` it wrote).
+- **Chart patch ops** — axis scale, gridlines, tick-label and legend fonts, legend position, chart
+  font and style, data labels, markers, series and point fills, trendlines and error bars all
+  round-trip through chart patches. What the studio still ignores is the warn-once list in
+  `docs/API_PARITY_EXCEPTIONS.md` (`unsupported-writes`).
+- **`Legend.include_in_layout`** — `False`, the value customers' agents assign, is what the studio
+  draws; only `True` (legend over the plot) warns.
+- **`Picture.image`** returns python-pptx's `Image` with the picture's bytes (0.18.0).
+- **`GroupShape.shapes`** lists the group's member shapes.
+- **Detached chart fonts** (`chart.font`, `legend.font`, `tick_labels.font`) send their changes.
+- **XML recipes** — `prs.slides._sldIdLst`, `shape._element` / `_spTree`, `text_frame._txBody`,
+  `paragraph._p`, `run._r`, `table._tbl`, `cell._tc` are real mirrors (0.17.0); the census's error
+  signals show customers hitting the old refusals (`Shapes._spTree`, `Slides._sldIdLst`,
+  `Run._r`) before that release.
+- **Table-cell font name and italic** — supported; the `UnsupportedFeatureError` customers hit for
+  `[cell font.name]` / `[cell font.italic]` earlier in the window no longer exists.
+- **`Connector.begin_connect(None)`** raises instead of recording an empty endpoint.
+- **Private-class naming** — python-pptx's public names (`AxisTitle`, `TickLabels`, `Legend`, …) are
+  the SDK's (Tranche B); `_Paragraph`, `_Run`, `_Cell` import from their python-pptx paths.
+- **`Font.language_id`** (with `MSO_LANGUAGE_ID.NONE` removing the language) and the language-tag
+  mapping, **`shape.click_action`** returning `ActionSetting`, and **core properties** — done.

{athena_python_pptx-0.18.0 → athena_python_pptx-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-pptx
-Version: 0.18.0
+Version: 0.19.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
@@ -869,6 +869,15 @@ print(info['wsUrl'])
 print(info['authToken'])
 ```
 
+People can edit a deck while your code runs, and your writes reach it when
+the batch is sent (in Athena's executor, when the script ends). A write of a
+box's text (`text_frame.text`, `paragraph.text`, `run.text`, …) names the text
+it replaces as the SDK read it, so the studio keeps what someone typed into
+the box after that read: your change goes onto the box's current text. Where
+you both changed the same words, both versions stay, theirs first. Nothing
+changes in the code you write; `text_frame.text` reads what you wrote until
+the deck is read again (`prs.refresh()`).
+
 ---
 
 ## Supported Features

{athena_python_pptx-0.18.0 → athena_python_pptx-0.19.0}/README.md

@@ -828,6 +828,15 @@ print(info['wsUrl'])
 print(info['authToken'])
 ```
 
+People can edit a deck while your code runs, and your writes reach it when
+the batch is sent (in Athena's executor, when the script ends). A write of a
+box's text (`text_frame.text`, `paragraph.text`, `run.text`, …) names the text
+it replaces as the SDK read it, so the studio keeps what someone typed into
+the box after that read: your change goes onto the box's current text. Where
+you both changed the same words, both versions stay, theirs first. Nothing
+changes in the code you write; `text_frame.text` reads what you wrote until
+the deck is read again (`prs.refresh()`).
+
 ---
 
 ## Supported Features