athena-python-pptx 0.2.0__tar.gz → 0.3.1__tar.gz

{athena_python_pptx-0.2.0 → athena_python_pptx-0.3.1}/API_PARITY_REPORT.md

@@ -110,13 +110,36 @@ via Tranches R–W:
 | `*.element`, `*.part`, `*.ln`, `*.get_or_add_ln` | XML element / OPC package / direct DML XML access — REST SDK has no local XML or packages |
 | `FillFormat.from_fill_parent()` | Internal XML constructor |
 | `ColorFormat.from_colorchoice_parent()` | Internal XML constructor |
-| `Font.fill` | Font fill format (uncommon) |
-| `SlideLayout.background`, `SlideMaster.background` | Not yet exposed at layout / master level |
-| `SlideLayout.iter_cloneable_placeholders`, `SlideLayout.used_by_slides` | Placeholder cloning is server-side |
-| `SlideShapes.add_movie`, `add_ole_object`, `build_freeform` | Not implemented (uncommon) |
-| `Slide.follow_master_background` | XML-level inheritance flag — REST SDK abstracts this |
 | `Picture.image.blob` | Image bytes live in the studio's asset store — not materialized into Python |
 
+## Closed Parity Gaps (added 2026-05-18)
+
+The following members are now implemented at the SDK surface — every method is callable and emits the appropriate command (server-side handlers for the new commands ship as a follow-up where noted):
+
+| Member | Implementation |
+|--------|----------------|
+| `Font.fill` | Returns ``_FontFillFormat`` proxy; ``fore_color`` delegates to ``Font.color`` |
+| `Image.dpi` | Derived from PIL when blob loaded, ``(72, 72)`` fallback |
+| `Slide.follow_master_background` | Getter + setter; emits ``SetSlideBackground`` with ``follow_master`` |
+| `SlideLayout.background`, `SlideMaster.background` | Returns ``_LayoutBackground`` proxy (read/write local; server-side patch op pending) |
+| `SlideLayout.iter_cloneable_placeholders` | Derived from placeholders, skipping latent types |
+| `SlideLayout.used_by_slides` | Derived from ``prs.slides`` |
+| `SlideLayouts.index(layout)` | List operation |
+| `SlideLayouts.remove(layout)` | Emits ``RemoveLayout`` *(server handler pending)* |
+| `Shapes.clone_placeholder` | Emits ``ClonePlaceholder`` *(server handler pending)* |
+| `Shapes.clone_layout_placeholders` | Loops ``iter_cloneable_placeholders`` + ``clone_placeholder`` |
+| `Shapes.ph_basename` / ``NotesSlideShapes.ph_basename`` | Pure mapping, notes-slide override |
+| `Shapes.turbo_add_enabled` | Local property (REST SDK has no XML batch path) |
+| `NotesSlide.shapes` / ``.placeholders`` / ``.notes_placeholder`` / ``.name`` / ``.background`` / ``.clone_master_placeholders`` | Empty collections + helpers; notes inheritance is automatic in REST |
+| `GraphicFrame.chart_part` | Returns a real ``ChartPart`` with ``.chart`` |
+| `GraphicFrame.ole_format` | Returns ``_OleFormat`` exposing ``prog_id`` / ``show_as_icon`` |
+| `Table.notify_height_changed/width_changed` | Recomputes total + emits ``SetTransform`` |
+| `FillFormat.gradient()` | Emits ``SetGradientFill`` immediately (previously only setters emitted) |
+| `FillFormat.patterned()` + ``pattern`` setter | Emits ``SetPatternFill`` *(server handler pending)* |
+| `FreeformBuilder.convert_to_shape()` | Emits ``AddFreeformShape`` *(server handler pending)* |
+
+The 4 new client commands (``RemoveLayout``, ``ClonePlaceholder``, ``SetPatternFill``, ``AddFreeformShape``) ship in the same release; their pptx-studio handlers are tracked as a server-side follow-up.
+
 ## SDK Additions (Documented Deviations)
 
 See `docs/API_PARITY_EXCEPTIONS.md` for the full list. Highlights:

{athena_python_pptx-0.2.0 → athena_python_pptx-0.3.1}/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.3.1
+
+**Chart title runs, slide insertion, and shape-delete local state — Insight
+Partners session feedback batch.**
+
+Investigated [thread_7b324723-…](https://app.athenaintel.com/dashboard/spaces/?session_id=thread_7b324723-a478-4e99-ac8f-6e7a69766292)
+where an agent built a 15-slide LP pitch deck and tripped over three
+SDK rough edges. Each is addressed below.
+
+- **`chart.chart_title.text_frame.paragraphs[0].runs[0].font` now works.**
+  The `_ChartTitleTextFrame` previously exposed only `text`; iterating
+  `paragraphs` raised `AttributeError`, and the agent fell back to
+  unstyled titles. The text frame now carries paragraph and run
+  proxies; per-run font writes coalesce into a single
+  `SetChartTitleRich` patch on the next flush. The simple
+  `text_frame.text = "..."` path still uses the cheaper `SetChartTitle`
+  patch — no wire-size regression on the no-formatting case.
+
+- **`prs.slides.insert(idx, layout)` added.** Previously, placing a new
+  slide between two existing slides required `add_slide()` followed by
+  `clone(target_index=...)` to shuffle the list — a workaround that
+  cloned 11 shapes onto the new slide and then couldn't fully clear
+  them. `insert()` emits a single `AddSlide(index=...)` and refreshes
+  the local collection.
+
+- **`shape.delete()` updates the local `slide.shapes` view immediately.**
+  The buffered delete left `len(slide.shapes)` stale, so the
+  "Before: 33, After: 33" symptom appeared even when the delete was
+  going through correctly server-side. `delete()` now removes the
+  shape from the parent `Shapes` collection in addition to queueing
+  the `DeleteShape` command. Layout-inherited shapes
+  (`source == "layout"`) no-op rather than queue a guaranteed-to-fail
+  delete.
+
+- **Toolkit prompt updated** to surface the working chart APIs —
+  `series.format.fill.solid()` + `series.format.fill.fore_color.rgb`,
+  `chart.legend.position`, doughnut/pie chart enums — and the new
+  `slide.clear_shapes()` / `prs.slides.insert()` helpers. The
+  Insight Partners agent assumed series styling was unsupported and
+  skipped per-series brand colors entirely.
+
 ## 0.1.76
 
 **Table cell paragraph alignment now round-trips to OOXML (baseline-parity Gap A2).**

{athena_python_pptx-0.2.0 → athena_python_pptx-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-pptx
-Version: 0.2.0
+Version: 0.3.1
 Summary: Drop-in replacement for python-pptx that connects to PPTX Studio for real-time collaboration
 Project-URL: Homepage, https://github.com/pptx-studio/python-sdk
 Project-URL: Documentation, https://docs.pptx-studio.com/sdk/python

{athena_python_pptx-0.2.0 → athena_python_pptx-0.3.1}/docs/API_PARITY_EXCEPTIONS.md

@@ -17,7 +17,6 @@ These standard python-pptx members are omitted because a REST SDK has no access
 | `FillFormat.from_fill_parent()` | Internal constructor |
 | `ColorFormat.from_colorchoice_parent()` | Internal constructor |
 | `Font.fill` | Font fill format (uncommon) |
-| `Font.language_id` | Implemented in v0.1.68 (returns `MSO_LANGUAGE_ID` enum, accepts enum or int LCID) |
 
 ---
 
@@ -216,6 +215,35 @@ python-pptx's `_Row.height` and `_Column.width` are read/write EMU properties. T
 
 In python-pptx, `Table.rows` returns a `_RowCollection` of `_Row` objects (each with `.height`). This SDK matches that. In a prior version, `Table.rows` returned a flat collection of cell lists.
 
+### `TextFrame.clear()` — also resets bullet on paragraph 0
+
+In upstream python-pptx, `text_frame.clear()` removes every paragraph except the first, and on that first paragraph it removes every child element **except** `<a:pPr>`. Any bullet definition the author wrote into `<a:pPr>` survives the clear, and an inherited bullet from the master / layout's `<a:lstStyle>` is left to be re-resolved by PowerPoint at render time.
+
+This SDK additionally emits a `SetParagraphStyle(paragraph_index=0, bullet='none')` after the empty `SetText`, explicitly overriding the bullet on the cleared paragraph.
+
+The deviation exists because pptx-studio **pre-bakes** master/layout list-style inheritance into `richContent.paragraphs[i].bullet` at ingest time (and at slide materialization), then preserves that baked field through every subsequent `applySetText` via `preserveParagraphProps`. Without the explicit override, the python-pptx idiom
+
+```python
+tf.clear()
+p = tf.paragraphs[0]
+run = p.add_run()
+run.text = "Title"
+```
+
+renders the title with a stray "•" whenever the placeholder lives on a layout whose master defines a level-1 `<a:buChar/>` (the common case for `<p:bodyStyle>` and any content placeholder). The explicit `bullet='none'` clears the baked inheritance so the literal "no pPr was authored" intent reaches the renderer.
+
+To re-enable a bullet after `clear()`, set it back explicitly:
+
+```python
+tf.clear()
+p = tf.paragraphs[0]
+p.bullet = True             # restores 'disc' default
+run = p.add_run()
+run.text = "Bullet item"
+```
+
+Only `bullet` is overridden — `alignment`, `level`, `line_spacing`, `space_before`, `space_after`, `margin_left`, `indent`, and `bullet_color` are left alone (they continue to follow upstream `<a:pPr>`-preservation semantics, since baked-inheritance surprises are far less common on those fields).
+
 ---
 
 ## Non-Standard Convenience Methods (candidates for future cleanup)
@@ -271,6 +299,35 @@ if warnings:
         print(w)
 ```
 
+### `add_picture(image_file=...)` accepts `http(s)://` URLs
+
+python-pptx upstream treats a `str` `image_file` strictly as a local
+filesystem path. athena-python-pptx **additionally** treats strings
+starting with `http://` or `https://` as URLs and fetches their bytes
+with `requests` before falling through to the standard AddPicture
+pipeline (base64-encode → server-side SHA256 dedup → S3 upload).
+
+This is the canonical handoff for "spreadsheet range → image asset →
+slide": athena-openpyxl's `Worksheet.export_range_as_image_asset` returns
+an `ImageAssetRef` whose `.url` is exactly the Olympus-proxied
+`/asset/asset_<uuid>.png` form this branch accepts.
+
+Athena asset URLs (any hostname under `athenaintel.com` /
+`athenaintelligence.ai`) are fetched with the sandbox's
+`ATHENA_PPTX_API_KEY` injected as a Bearer token so Olympus's catch-all
+asset proxy can run the workspace ABAC permission check against the
+calling user. Non-Athena URLs are fetched without auth — they're assumed
+to be world-readable, like any plain image link.
+
+**Portable code that needs to run against stock python-pptx should
+download the URL externally and pass `bytes` or a file-like.**
+
+```python
+# Inside a Daytona pptx sandbox:
+img = ws.export_range_as_image_asset("A1:F20", name="Q4 Revenue")
+slide.shapes.add_picture(img.url, Inches(1), Inches(1), width=Inches(6))
+```
+
 ### `name=` kwarg on `add_textbox()` / `add_shape()` / `add_picture()`
 
 Optional keyword for setting a stable shape name at creation. python-pptx
@@ -400,7 +457,11 @@ that closed six more setters end-to-end (see the new table below):
   setters.
 - 3-D chart authoring (`XL_CHART_TYPE.THREE_D_*` raises
   `UnsupportedFeatureError`).
-- Combo / Stock / Radar variants for `add_chart()` (also raise).
+- Combo / Stock variants for `add_chart()` (also raise). Radar
+  (`XL_CHART_TYPE.RADAR` / `RADAR_FILLED` / `RADAR_MARKERS`) now authors
+  end-to-end — all three variants map to OOXML `<c:radarChart>` with
+  `<c:radarStyle val="standard"/>`; the marker / filled distinction
+  is collapsed to "standard" today (follow-up work to extend ChartSpec).
 - Trendlines and error bars on series.
 
 ### Chart Patches Added in the Styling Residuals PR (6 new operations)
@@ -769,6 +830,67 @@ The default `fit=None` preserves stock python-pptx behaviour. The only
 other accepted value is `"contain"`; passing anything else raises
 `ValueError` to fail loudly rather than silently no-op.
 
+## `Shapes.add_athena_anchor()` — Athena-only cross-asset screenshot insert
+
+Athena extension with no python-pptx analogue. Renders an Athena
+`Anchor` (a structured reference to a region of another asset — sheet
+cells, sheet ranges, etc.) to a PNG and inserts it as a regular
+`Picture` shape on the current slide. The result is a one-shot raster
+snapshot, **not** a live-linked binding — use `add_linked_table()` /
+`add_linked_ole_object()` for refreshable bindings.
+
+```python
+from pptx._references import AssetReference, SheetRangeAnchor
+
+slide.shapes.add_athena_anchor(
+    AssetReference(id="asset_20880ea3-95fb-4577-9a2e-ad11b7773939"),
+    SheetRangeAnchor(sheet_id=1, range="A1:F20"),
+    Inches(1), Inches(1),
+    width=Inches(8),
+)
+```
+
+Signature:
+
+```python
+add_athena_anchor(
+    source: AssetReference,
+    anchor: Anchor,
+    left: Length,
+    top: Length,
+    width: Length | None = None,
+    height: Length | None = None,
+    *,
+    name: str | None = None,
+    fit: str | None = None,  # "contain" — same semantics as add_picture
+) -> Shape
+```
+
+Supported anchor types today:
+
+| Anchor type        | Behaviour                                                |
+|--------------------|----------------------------------------------------------|
+| `SheetCellAnchor`  | Renders the single cell as a 1×1 range PNG.              |
+| `SheetRangeAnchor` | Renders the A1 range via xlsx-studio's screenshot.png.   |
+| `SheetTableAnchor` | Raises `NotImplementedError` (resolve to A1 + retry).    |
+| `SlideAnchor`      | Raises `NotImplementedError` (no slide-snapshot route).  |
+| anything else      | Raises `NotImplementedError`.                            |
+
+Sheet anchors route through `GET {ATHENA_XLSX_BASE_URL}/workbooks/:id/screenshot.png`
+with the sandbox's `ATHENA_XLSX_API_KEY` forwarded as a Bearer token —
+xlsx-studio's ownership middleware checks that the calling workspace
+can read the source workbook. Render scale is fixed at 3 (matches
+xlsx-studio's `range-as-asset` default — slide inserts sit at 6–9″
+widths where scale=2 leaves text soft). When `ATHENA_XLSX_BASE_URL` /
+`ATHENA_XLSX_API_KEY` aren't set (e.g. running outside a Daytona
+presentation_exec sandbox), the call raises `ValueError` rather than
+producing a broken picture.
+
+For finer control (custom scale, `include_headers`, off-snapshot
+post-processing), fetch the PNG bytes directly via athena-openpyxl's
+`Worksheet.export_range_sync()` and call `add_picture(bytes, …)`
+yourself.
+
 ---
 
 ## `Shapes.add_linked_table()` — Athena studio-linking extension (added in Phase 3)
@@ -825,3 +947,375 @@ the same table element on the Y.Doc.
 
 **`freshness_mode='office_live_link'` is reserved for Phase 5** and
 currently raises ``ValueError`` locally.
+
+---
+
+## Athena extensions for most-requested upstream features (v0.1.81)
+
+These surfaces are **additions** to python-pptx, not deviations — every
+upstream class, method, property, and parameter remains 1:1 with
+python-pptx 1.0.2. Each item below closes (or fundamentally improves)
+a long-standing upstream feature gap. Issue numbers reference
+`scanny/python-pptx`. Every entry is marked at runtime with
+`@athena_extension(issue=…, since="0.1.81")` so the registry walker
+picks them up; the legacy `@athena_only` markers continue to work for
+back-compat.
+
+This wave intentionally **excludes animations / Morph transitions**
+(python-pptx#1106 / #942) — they need export-worker and Y.Doc-schema
+work in addition to SDK surface and are tracked separately.
+
+### Shape-level additions
+
+- **`Shape.duplicate(target_slide=None, offset_x=None, offset_y=None)`**
+  (closes python-pptx#533, #620, 10-comment thread requesting a public
+  duplicate API). Alias for the existing `Shape.clone()` — both verbs
+  resolve identically. The clone preserves every server-resolved
+  property (transform, color, text, type) and accepts the same
+  `target_slide` / offset args as `clone()`.
+
+- **`LineFormat.head_end_type` / `tail_end_type` / `head_end_length` /
+  `tail_end_length` / `head_end_width` / `tail_end_width`** (closes
+  python-pptx#1033). Connector / line arrow heads. Accept either
+  the upstream `MSO_ARROWHEAD` / `MSO_ARROWHEAD_LENGTH` /
+  `MSO_ARROWHEAD_WIDTH` enums or the OOXML short strings
+  (`"triangle"` / `"stealth"` / `"diamond"` / `"oval"` / `"arrow"` /
+  `"none"`, `"sm"` / `"med"` / `"lg"`). Each setter emits a
+  `SetConnectorArrows` wire op carrying all six attrs at once.
+
+  ```python
+  from pptx.enum.dml import MSO_ARROWHEAD
+  conn = slide.shapes.add_connector(MSO_CONNECTOR.STRAIGHT,
+                                    Inches(1), Inches(1),
+                                    Inches(5), Inches(3))
+  conn.line.tail_end_type = MSO_ARROWHEAD.TRIANGLE
+  conn.line.tail_end_length = "med"
+  conn.line.tail_end_width = "lg"
+  ```
+
+- **`Shapes.add_picture(svg_bytes_or_path, …)`** now natively
+  supports SVG (closes python-pptx#1112). The picture's content-type
+  is detected from the magic bytes (`<?xml … <svg`), the native
+  size is parsed from the `<svg width=/height=>` attributes (or the
+  `viewBox`), and the wire payload carries `image_format="svg"` so
+  the server stores the SVG as a first-class picture asset (PowerPoint
+  2016+ supports SVG natively).
+
+- **`Shapes.add_connector(...)` int-coerces float endpoints**
+  (closes python-pptx#1058 — "Generating corrupted PPT when using
+  connectors"). Calls like `connector(top=shape.top + shape.height / 2)`
+  produce floats that legacy code wrote into `<a:off x="...">`
+  attributes that Google Slides and modern PowerPoint refuse to open.
+  We now route every endpoint through `int(round(float(...)))` so the
+  wire payload is integer EMU regardless of input type
+  (`float` / `numpy.float64` / `Decimal`).
+
+### Text-frame and run additions
+
+- **`Hyperlink.target_slide`** (closes python-pptx#1077). Run-level
+  internal slide jumps. Assign a `Slide` proxy or a zero-based int;
+  the SDK emits a `SetRunHyperlinkTarget` command with the
+  `targetSlideIndex` payload, and the server writes
+  `<a:hlinkClick action="ppaction://hlinksldjump">` with the matching
+  slide-jump relationship. Mutually exclusive with `address` (an
+  external URL); setting one nulls the other.
+
+  ```python
+  run.hyperlink.target_slide = prs.slides[3]
+  # or
+  run.hyperlink.target_slide = 3
+  ```
+
+- **`Run.font.color.rgb` overrides the theme hyperlink color**
+  (closes python-pptx#940 — "Set/change font color when working with
+  Hyperlinks is impossible", 11-comment thread). The Hyperlink
+  emitter now reads the run's explicit color and ships an
+  `overrideColorHex` field on `SetRunHyperlinkTarget` so the server
+  writes the matching `<a:rPr><a:solidFill>` over the run instead of
+  letting the theme `hlink` color win.
+
+- **`TextFrame.replace_text(pattern, replacement, *, regex=False,
+  match_case=False, whole_word=False, max_replacements=None)`**
+  (closes python-pptx#684, #1037, #884). Find-and-replace that
+  preserves run-level formatting (fonts / colors / sizes / bold /
+  italic) by splitting runs across the match boundary on the server.
+  Returns the count of substitutions performed.
+
+- **`TextFitter.best_fit_font_size(text, extents, max_size, font_file)`**
+  no longer returns `max_size` unconditionally (closes
+  python-pptx#715, #936, #970, #1026). When a base URL is configured
+  (`ATHENA_PPTX_BASE_URL`), the classmethod issues a `MeasureTextFit`
+  query to the studio's text-measurement endpoint and returns the
+  largest size that fits. The upstream signature is preserved exactly
+  (additional knobs read from `ATHENA_PPTX_TEXTFITTER_*` env vars).
+  Falls back to `max_size` with a `RuntimeWarning` if no client is
+  reachable so offline tests keep working.
+
+### Table additions
+
+- **`_RowCollection.add(*, height=None, copy_format_from=None)`** and
+  **`_RowCollection.insert(index, *, height=None, copy_format_from=None)`**
+  (closes python-pptx#895, #1016, 17-comment thread). Restores the
+  `rows.add()` method removed in upstream 1.0.0 and adds an indexed
+  `insert()` companion. `copy_format_from=<row_index>` inherits the
+  source row's height + every cell's formatting.
+
+- **`_ColumnCollection.add(*, width=None, copy_format_from=None)`** and
+  **`_ColumnCollection.insert(index, ...)`** — column-axis mirror.
+  `Table.add_column()` / `Table.remove_column()` / `Table.delete_column()`
+  / `Table.delete_row()` are convenience wrappers on top.
+
+  ```python
+  table.rows.add(copy_format_from=0)
+  table.columns.insert(2, width=Inches(1.5))
+  table.delete_row(-1)
+  table.delete_column(0)
+  ```
+
+### Chart additions
+
+- **`DataLabel.show_value` / `show_series_name` / `show_category_name` /
+  `show_percentage` / `number_format` / `text` / `font` / `position`**
+  (closes python-pptx#1068, #1024, #1025). Per-point data-label
+  overrides. Reach via `series.points[i].data_label.show_value = True`;
+  each setter emits a `SetPointDataLabelStyle` wire op so the
+  server can apply the override on top of the series default.
+
+- **`_ChartTitle.left` / `top` / `width` / `height`** (closes
+  python-pptx#1030 — "How to set manually chart_title position?").
+  Fractional layout (0.0 – 1.0 of the plot area) for the manual
+  title placement. Each setter emits `SetChartTitlePosition` which
+  the server materialises as `<c:layout><c:manualLayout xMode="edge"
+  yMode="edge" …>`. Setting any axis to `None` clears the override and
+  falls back to PowerPoint's auto-placement.
+
+- **Office 2016+ chart types**: `XL_CHART_TYPE.TREEMAP` (117),
+  `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.
+
+### Slide- and presentation-level additions
+
+- **`Presentation.create(widescreen=True)` is now the default**
+  (closes python-pptx#1066, 9-comment thread). The blank-template
+  factory creates 16:9 widescreen decks at 14630400 × 8229600 EMU
+  (PowerPoint's "Widescreen (16:9)" preset). Pass `widescreen=False`
+  to fall back to the legacy 4:3 default.
+
+- **`Presentation.open(deck_id, base_url=None, api_key=None)`**
+  (closes python-pptx#1018 — "open a PPT in append mode"). Named
+  factory that mirrors the iterate-and-edit verb the upstream thread
+  filed under. Internally identical to `Presentation(deck_id=…)`
+  but reads naturally next to `Presentation.create` / `.upload`.
+
+- **`Presentation.copy_slide_from(source, source_slide_index, *,
+  destination_index=-1)`** (closes python-pptx#1036, #696, #934,
+  three threads totalling 20+ comments asking for cross-deck slide
+  copy). Emits `CopySlideFromDeck`; the server runs the deep copy
+  with full relationship + media-de-duplication handling. Accepts
+  either a live `Presentation` instance (its pending edits are
+  flushed first) or a raw deck id string.
+
+- **`Slides.remove_slide(slide_or_index)`** (closes python-pptx#956).
+  Alias for the existing `Slides.delete()`. Both verbs accept a
+  `Slide` proxy or an integer index.
+
+- **`SlideMaster.shapes.add_shape / add_picture / add_textbox /
+  add_table`** and **`SlideLayout.shapes.add_*`** (closes
+  python-pptx#575 — "Add shapes to Slide Master" — and #1044 —
+  "Add textbox to layout"). Mutation surface on master / layout
+  shape collections. Reads remain empty (REST snapshot doesn't
+  materialise master / layout shapes as first-class read targets),
+  but writes round-trip through `AddShapeOnMaster` so the addition
+  is inherited by every slide using the master / layout.
+
+  ```python
+  master = prs.slide_masters[0]
+  master.shapes.add_picture("logo.png",
+                            Inches(0.25), Inches(0.25),
+                            width=Inches(1))
+  ```
+
+### Audit notes
+
+- **python-pptx#1085 / #925 / #899 (group-shape coords)** — verified
+  not applicable to this SDK. The REST snapshot carries
+  server-resolved absolute coordinates for every shape, including
+  group children that surface as flat slide-level siblings, so the
+  group-relative coord bug the upstream issues describe can't occur
+  here.
+
+When upstream python-pptx eventually lands native versions of any of
+these surfaces, the SDK should swap to the upstream signature in
+place — this section is the canonical reference for what each Athena
+extension wires up.
+
+---
+
+## Tier B — next-wave upstream features (v0.1.82)
+
+Second wave from the open-issue spectrum. Same contract as v0.1.81:
+upstream surface preserved, additions tagged with
+`@athena_extension(issue=…, since="0.1.82")`. New wire commands in
+`pptx.commands`: `SetShapeHidden`, `SetPointInvertIfNegative`,
+`SetSeriesErrorBars`, `SetConnectorEndpoint`, `AddMovie`,
+`SetChartHyperlink`, `ApplyForeignLayout`, `HideChartSeries`.
+
+### Shape and connector additions
+
+- **`Shape.hidden`** (closes python-pptx#971). Boolean read/write
+  toggle that emits `SetShapeHidden` so the `<p:cNvPr hidden="1">`
+  flag round-trips. Hidden shapes are excluded from render + Selection
+  Pane but stay in the OOXML tree.
+
+- **`Connector.begin_connect` / `end_connect`** now emit
+  `SetConnectorEndpoint` (closes python-pptx#946, #1017). The
+  pre-0.1.82 local-state-only stubs were exposed only so `isinstance`-
+  style code didn't `AttributeError`; the new wire op makes the
+  binding survive the round-trip and tracks the bound shape if it
+  moves.
+
+- **`Connector.set_elbow_adjustment(fraction, endpoint="begin")`**
+  (closes python-pptx#1017 specifically). Adjusts the midpoint of an
+  elbow connector; `fraction` is the position along the major axis
+  (`0.0` first endpoint, `1.0` second). No-op on STRAIGHT / CURVE
+  connectors.
+
+### Chart additions
+
+- **`Point.invert_if_negative`** (closes python-pptx#776). Per-data-
+  point override that emits `SetPointInvertIfNegative`.
+  Series-level `invert_if_negative` is overridden the moment any
+  point in the series has its own `<c:spPr>`, so per-point control
+  is the only reliable color-inversion path once explicit colors
+  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.
+
+- **`Chart.set_hyperlink(url=..., target_slide_index=..., tooltip=...)`**
+  (closes python-pptx#962). Routes chart-level click-actions through
+  `SetChartHyperlink` since the canonical `SetClickAction`
+  path doesn't carry chart-shape relationships.
+
+- **`Chart.hide_series(*series_ids)`** (closes python-pptx#1043).
+  Hides series from the rendered plot without dropping them from the
+  underlying chart-data workbook — callers can run the same data
+  through multiple chart templates that surface different subsets.
+
+- **Office 2016+ `pareto` chart type round-trips** —
+  `AddChart2016.validate()` now includes `"pareto"` in the valid
+  set, fixing a pre-merge ratchet that rejected the documented
+  enum value. (Already in Tier A spec, closed in PR #20711 follow-up.)
+
+### Slide and presentation additions
+
+- **`Slide.apply_foreign_layout(master_index, layout_index)`**
+  (closes python-pptx#1109, #1028). Apply a layout from a different
+  master to an existing slide via `ApplyForeignLayout`. The
+  server runs the relationship + theme inheritance fix-up so the
+  slide renders against any master's layout without a deep-copy
+  workaround.
+
+- **`Slides.remove_slide()` alias for `delete()`** (already in Tier
+  A, restated here because the upstream issue #956 spelled it both
+  ways — both verbs accept a `Slide` or an integer index).
+
+### Text additions
+
+- **`Font.resolve() -> dict`** (closes python-pptx#1063, #765, #883).
+  Returns the *rendered* font properties (name / size_pt / bold /
+  italic / underline / strike / color_hex / language_id) walking
+  paragraph → shape → master → theme inheritance. Closes three
+  threads asking for "what font does this run actually use?" since
+  the bare `font.name` / `.size` surfaces only return the
+  explicitly-set values, not the resolved chain.
+
+- **`Paragraph.auto_number_prefix`** (closes python-pptx#939).
+  Returns the rendered numbering prefix (`"1."`, `"A)"`, `"i."`) for
+  numbered bullets. Upstream's `paragraph.text` strips the prefix
+  because it's stored as `<a:buAutoNum>` metadata, not text;
+  callers feeding screen-readers / Markdown exporters previously
+  had to manually count siblings.
+
+### Picture additions
+
+- **`Picture.transparency`** (closes python-pptx#1020). Fractional
+  alpha (0.0 opaque .. 1.0 fully transparent) read from the OOXML
+  `<a:blipFill><a:blip><a:alphaModFix amt="…">` stored on the
+  picture-fill. Read-only — write goes through the existing
+  picture-fill set-transparency path.
+
+- **`Picture.freeform_geometry`** (closes python-pptx#1020). Returns
+  the freeform clip-path points for pictures whose `<p:spPr>`
+  carries a `<a:custGeom>` (e.g. wave-clipped photos). `None` when
+  the picture uses the default rectangular clip.
+
+### Movie / video additions
+
+- **`Shapes.add_movie(...)` and `Shapes.add_video(...)` alias**
+  (closes python-pptx#811 start time, #1034 online video URL, #954
+  corrupted-file workflow, #974 safe deletion). New first-class
+  author path for video shapes via :class:`AddMovie`. Upstream's
+  `Movie` class is read-only; users have to deepcopy the OOXML to
+  add new movies, which routinely produces corrupt files for
+  non-OOXML animations (#954). The signature mirrors python-pptx's
+  positional surface (`movie_file, left, top, width, height,
+  poster_frame_image, mime_type`) plus keyword-only Athena extras:
+  `url=` (online video URL — closes #1034), `start_time=` /
+  `end_time=` (in seconds — closes #811), `autoplay`,
+  `show_controls`, `loop`, `name`.
+
+### Read-only / shape-collection additions
+
+- **`Shapes.by_name(name)` and `Shapes.get_by_name(name, default=None)`**
+  (closes python-pptx#532, 5-year-old request for a
+  Selection-Pane-equivalent listing). `by_name` raises `KeyError`
+  with the list of available names on a miss; `get_by_name` returns
+  the supplied default. Mirrors the shape `SlideLayouts.by_name` /
+  `get_by_name` pair already exposed for layouts.
+
+### Image / mime fixes
+
+- **`Image.content_type` correctly identifies EMF files**
+  (closes python-pptx#1042). Pre-0.1.82 the legacy fallback used
+  the WMF magic bytes for any `.emf`, returning `image/x-wmf` /
+  `.wmf`. The sniffer now checks the EMR_HEADER signature first
+  and falls back to the filename suffix; EMF files round-trip with
+  the correct `image/x-emf` / `.emf`.
+
+### Audit notes
+
+- **python-pptx#1099 (slide notes missing after slide 20)** —
+  verified not applicable here. Notes are pre-parsed server-side
+  and surfaced via the snapshot; the upstream XML-parser bug
+  doesn't live in our SDK.
+
+- **python-pptx#1051 (Keynote speaker-notes interop)** — same
+  rationale: notes-master bootstrap runs in the ingest worker and
+  is unaffected by the SDK surface.
+
+- **python-pptx#1038 (`MSO_LANGUAGE_ID has no XML mapping for
+  'en-CN'`)** — not applicable. The upstream error originates in
+  python-pptx's XML-tag → enum lookup; the SDK consumes integer
+  LCIDs from the server snapshot so the lookup never runs.
+
+- **python-pptx#1035 (add_chart return type annotation)** —
+  already correct in the SDK. `add_chart(...) -> "GraphicFrame"`
+  (chart accessed via `.chart` on the frame).
+
+- **python-pptx#1127 (PERCENT_40 typo)** — already correct in the
+  SDK. The upstream issue was a missing leading "P"; our enum has
+  the proper spelling `PERCENT_40 = 6`.
+
+Total Tier B closures: 16 implemented, 6 audited (already
+applicable or N/A by REST architecture).

{athena_python_pptx-0.2.0 → athena_python_pptx-0.3.1}/pptx/__init__.py

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