athena-python-pptx 0.14.1__tar.gz → 0.14.3__tar.gz

{athena_python_pptx-0.14.1 → athena_python_pptx-0.14.3}/.gitignore

@@ -28,8 +28,17 @@ wheels/
 venv/
 ENV/
 
+# uv's lockfile for local `uv run` / `uv sync`. CI installs with pip
+# (test-pptx-studio-sdk.yml) and the SDK ships as a library whose consumers
+# resolve their own dependencies, so a committed lock would be read by
+# nothing and go stale with every version bump.
+uv.lock
+
 # Testing
 .pytest_cache/
+# Per-checkout test caches, e.g. the stock python-pptx parity reference
+# (tests/_stock_python_pptx.py).
+.cache/
 .coverage
 htmlcov/
 .tox/

{athena_python_pptx-0.14.1 → athena_python_pptx-0.14.3}/AGENTS.md

@@ -99,16 +99,22 @@ If there is a genuine technical reason why a deviation from python-pptx is neces
 ## Development
 
 ```bash
-# Install in editable mode
-pip install -e ".[dev]"
+# Full suite, the way CI selects it — uv installs the `dev` dependency group
+# into the SDK's own .venv, so this never runs another interpreter's pytest
+uv run pytest tests/ -q --ignore=tests/test_visual_comparison.py
 
-# Run tests
-python -m pytest tests/ -x -q
+# Specific test file
+uv run pytest tests/test_sdk_features.py -x -q
 
-# Run specific test file
-python -m pytest tests/test_sdk_features.py -x -q
+# pip alternative (what CI does)
+pip install -e ../../python-sdk/athena-references -e ".[dev]" && python -m pytest tests/ -x -q
 ```
 
+Stock python-pptx for the parity tests is installed on first use into this
+checkout's git-ignored `.cache/` (per pinned version × interpreter × platform;
+`tests/_stock_python_pptx.py`) — never into a shared `/tmp` directory. A failed
+install fails the parity tests rather than skipping them.
+
 ## Architecture
 
 This is a **REST API client** that mimics the python-pptx API. Instead of manipulating XML directly, method calls are translated to commands sent to the PPTX Studio API server. Key differences from python-pptx internals:

{athena_python_pptx-0.14.1 → athena_python_pptx-0.14.3}/API_PARITY_REPORT.md

@@ -159,6 +159,8 @@ See `docs/API_PARITY_EXCEPTIONS.md` for the full list. Highlights:
 ## How to Run
 
 ```bash
-pip install python-pptx --target /tmp/pptx-standard
-python -m pytest tests/test_python_pptx_api_parity.py -v -s
+uv run pytest tests/test_python_pptx_api_parity.py -v -s
 ```
+
+The stock python-pptx reference is installed on first use into this
+checkout's git-ignored `.cache/` (`tests/_stock_python_pptx.py`).

{athena_python_pptx-0.14.1 → athena_python_pptx-0.14.3}/CHANGELOG.md

@@ -2,6 +2,160 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.14.3 — waterfall `connector_lines`
+
+- New Athena extension `chart.plots[0].connector_lines = False` on a
+  `WaterfallPlot` hides the lines joining each bar to the next (Excel's
+  "Show connector lines"; `True` by default). Emits a
+  `SetWaterfallConnectorLines` chart patch; an SDK-authored waterfall then
+  exports one category per bar with its `gap_width`, and an uploaded Office
+  2016 waterfall writes `connectorLines` into its own part. Reads back from
+  either.
+- Studio-side (no SDK change, any SDK version): SDK-authored bar / column
+  series export `<c:invertIfNegative val="0"/>` by default, so negative bars
+  keep the series colour instead of rendering white in PowerPoint; an explicit
+  `series.invert_if_negative = True` still wins. `chart.replace_data()` on an
+  uploaded bar chart rebuilds its series the same way.
+
+## 0.14.2 — `chart.value_axis` / `chart.category_axis` edit the axis python-pptx returns
+
+Axis edits (`axis_title`, `visible`, `minimum_scale` / `maximum_scale` /
+`major_unit` / `minor_unit` / `reverse_order`, gridlines and their line,
+`tick_labels`, tick marks, `crosses` / `crosses_at`, `category_type`) now
+change the axis python-pptx 1.0.2's `chart.category_axis` /
+`chart.value_axis` return:
+
+- On an XY chart (scatter, bubble) `value_axis` is the Y axis and
+  `category_axis` the X axis. Previously a `value_axis` edit changed the X
+  axis of an uploaded XY chart and was dropped on one made with `add_chart`,
+  and a `category_axis` edit was dropped on both.
+- On an XY chart `category_axis` is a `ValueAxis`, as in python-pptx, so
+  `chart.category_axis.major_unit` / `crosses` / `crosses_at` reach the X
+  axis (a `CategoryAxis` has no such properties, so those writes did
+  nothing).
+- **Behaviour change:** on a chart with two value axes (a combo with a
+  secondary axis) `value_axis` is the secondary axis, as in python-pptx;
+  previously it was the primary one. Scripts that styled the primary axis
+  through `value_axis` on such a chart now style the secondary axis.
+- `axis_title.text_frame.text` reads the title back from the same axis.
+- `chart.replace_data()` keeps the chart's axes (and a combo's other plots)
+  in the local mirror, as the server does, so later axis edits still address
+  the right axis and axis titles still read back.
+- Each axis patch now carries `axisRef` — the kind of axis and its position,
+  e.g. `{"role": "value", "index": 1}` — next to `axisId`. Works with any
+  studio: one that predates `axisRef` drops the field and resolves `axisId`,
+  which the SDK now picks per chart (`val-axis-y` for an XY chart's Y axis
+  or a secondary value axis, `val-axis-x` for an XY chart's X axis) so it
+  names the same axis.
+
+## 0.14.2 — inside Athena's executor a failed script leaves the deck untouched
+
+Agent scripts crashed partway (an `AttributeError` on a chart adapter, an
+`UnsupportedFeatureError` from a setter) after earlier edits had already been
+sent by the 2 s idle auto-flush, by `add_slide()` flushing to hand back the
+server's slide, or by `with prs.batch():` exits; the executor's
+`pptx.discard_all()` could only drop what was still buffered, so decks were
+left half-edited.
+
+- With `ATHENA_PPTX_EXECUTOR_MODE=1` (set by agora's `execute_presentation_code`
+  for every run, alongside `ATHENA_PPTX_BASE_URL`) the SDK never sends on its
+  own: no idle auto-flush, no `atexit` flush, `with prs.batch():` keeps its
+  commands buffered on exit, and `add_slide()` / `Slides.insert()` /
+  `Slides.delete()` / `delete_slides()` / `group_shapes()` return local
+  proxies as they do inside a batch. Writes reach the deck at the run's final
+  `pptx.flush_all(strict=True)` — or are dropped by `pptx.discard_all()` when
+  the script raised.
+- Sync points still commit what is buffered so far: `flush()`, `save()`,
+  `save_to_bytes()`, `refresh()`, `close()`, `render_slide()` /
+  `slide.render()`, a clean `with Presentation(...)` exit, `slide.clone()`,
+  `copy_slide_from()`, `slide.slide_layout = ...`, `apply_foreign_layout()`.
+- `with Presentation(...) as prs:` discards the writes buffered inside the
+  block when the block raises (executor only; writes buffered before it stay
+  for the run's final flush); a `Presentation` the script drops keeps its
+  buffered writes for the run's final drain instead of flushing them at
+  garbage collection. A `CommandBuffer(auto_batch=False)` buffers too while
+  commits are deferred.
+- A final flush larger than the per-request budget (24 MiB) is still sent as
+  several requests; when a later one fails, `FlushAllError` now says how many
+  commands earlier requests applied (`applied_before_failure` on the
+  exception). Commands in a later request that name a slide an earlier request
+  created by its `sld_…` client id (`clear_shapes()`, freeforms,
+  `clone_placeholder()`, and edits of the new slide's layout placeholders,
+  addressed as `__inherited__:<slide id>:…` until a refresh) now carry the
+  server id, which the server needs outside the creating request — in every
+  mode, also after a `flush()` / `render()` that did not refresh.
+- Outside the executor (plain scripts, notebooks, Computer assets) behaviour
+  is unchanged. `CommandBuffer(defer_commits=...)` overrides the environment.
+- Release note: needs the agora change that sets the variable (older agora
+  keeps today's eager flushing; older SDKs ignore the variable), so either
+  deploy order is safe.
+
+## 0.14.2 — `replace_data()` drops a chart's old category hierarchy
+
+- `chart.replace_data()` on a chart with multi-level categories (an imported
+  Office 2016 waterfall, for one) no longer leaves the old hierarchy in the
+  local mirror. The new categories are flat, and the server drops the old
+  hierarchy the same way, so `chart.plots[0].categories` reads back the
+  categories you passed.
+
+## 0.14.2 — no silent no-ops: an unsupported call fails or warns at its own line
+
+Scripts could build on a write that never reached the deck: a setter kept the
+value on the local proxy and sent nothing, or a convenience method died with a
+bare `AttributeError` from inside the SDK. `tests/test_no_silent_noops.py` now
+probes every public setter and method of every deck-bound adapter (mocked
+client) and fails CI on any that neither sends a command, warns, nor raises.
+
+- python-pptx members this SDK has no equivalent for (XML `element`, OPC
+  `part`, `parent`, the chart-workbook builders, … on 109 classes) raise the
+  new `pptx.UnsupportedAttributeError`, naming the member and what to use
+  instead. It is both an `UnsupportedFeatureError` and an `AttributeError`, so
+  `hasattr()` and `getattr(obj, name, default)` behave as before.
+- These writes now raise at the call instead of being dropped:
+  `UnsupportedFeatureError` for a non-zero `brightness` on a shape fill or line
+  colour or on a table-cell colour, `theme_color` on a table-cell fill or font
+  colour, `font.color.brightness` without a theme colour, `font.fill.background()`
+  (python-pptx's transparent text), `fill.solid()` / `fore_color.rgb` on a layout,
+  master or notes-page background (the notes-page background used to restyle the
+  *slide*), and `ChartWorkbook.update_from_xlsx_blob()`;
+  `UnsupportedAttributeError` for `shape.text = …` on a shape with no text frame;
+  `TypeError`, as in python-pptx, for `fill.pattern` outside a patterned fill and
+  `fill.gradient_angle` / `gradient_stops` outside a gradient fill.
+- These now warn once per presentation (the value is kept locally): chart-font
+  properties the target's font patch cannot carry (for example
+  `chart.font.italic`, `legend.font.underline`, `data_label.font.name`, title
+  `language_id`), chart-title paragraph `alignment` and `word_wrap`,
+  `Legend.horz_offset` other than 0, `Legend.include_in_layout = True`,
+  `DataLabels.show_legend_key = True`, `TickLabels.offset` other than 100, a
+  `number_format_is_linked` that contradicts `number_format`,
+  `notes_slide.name`, and `add_paragraph()` / `add_run()` on a table cell that
+  already has text (a cell holds one paragraph with one run, so writing the
+  returned one replaces the text).
+- These now reach the deck: `axis.has_title = False` removes the axis title
+  (`= True` alone still sends nothing — the studio exports no empty axis title —
+  and the title is sent with its text); clearing a chart title's text frame
+  sends the empty title; `data_label.text_frame.text = …`;
+  `paragraph.add_line_break()`; `text_frame.clear_formatting()` (hyperlinks are
+  kept; runs styled only by a font reference or a stored style field are reset
+  too); `run.copy_format_from()` (a styled destination is reset first, so none
+  of its own formatting survives); `text_frame.apply_style_to_all()` (unknown
+  keys raise `ValueError`); `shape.fill_solid()` and `shape.line_fill_none()`;
+  `shape.line.color = RGBColor(…)`.
+- `run = paragraph.add_run(); run.font.bold = True` — a font or hyperlink write
+  before the run's text — sent a style for a run the server did not have yet,
+  so the whole batch failed at flush; the run is now created first.
+- `prs.get_all_colors()`, `text_frame.get_styled_runs()` and
+  `get_formatting_summary()` no longer raise `AttributeError`.
+- `Legend.include_in_layout` reads `False` by default: the studio never draws
+  the legend over the plot.
+- The tables in `docs/API_PARITY_EXCEPTIONS.md` of unsupported members, of writes
+  that warn or raise, and of Athena extensions are generated by
+  `scripts/generate_parity_tables.py`; CI fails when they are stale.
+
+Release note: scripts that made one of these calls may now stop with
+`UnsupportedFeatureError` / `UnsupportedAttributeError`, or print a
+`UserWarning`, where they used to continue on a write that never landed.
+
 ## 0.14.1 — no shutdown error from `Presentation.__del__`
 
 - A `Presentation` still alive when the script's interpreter exits no longer

{athena_python_pptx-0.14.1 → athena_python_pptx-0.14.3}/DEV-GUIDE.md

@@ -44,19 +44,27 @@ python scratch.py
 ### Run tests
 
 ```bash
-# All tests
-pytest tests/ -v
+# All tests, the way CI selects them (uv installs the `dev` dependency group
+# into the SDK's own .venv; a bare `pytest` may belong to another interpreter)
+uv run pytest tests/ -q --ignore=tests/test_visual_comparison.py
 
 # Single file
-pytest tests/test_text.py -v
+uv run pytest tests/test_text.py -v
 
 # Single test
-pytest tests/test_text.py::TestTextFrame::test_set_text -v
+uv run pytest tests/test_text.py::TestTextFrame::test_set_text -v
 
 # Integration tests (needs running API)
-ATHENA_PPTX_BASE_URL=http://localhost:4000 pytest tests/test_smoke_integration.py -v
+ATHENA_PPTX_BASE_URL=http://localhost:4000 uv run pytest tests/test_smoke_integration.py -v
 ```
 
+The parity tests compare against stock python-pptx, which the first run
+installs into this checkout's git-ignored `.cache/stock-python-pptx/<key>/`
+(pinned version × interpreter × platform; see `tests/_stock_python_pptx.py`).
+Each checkout has its own copy, concurrent runs install it once, and a failed
+install fails those tests instead of skipping them. `uv.lock` is git-ignored:
+CI installs with pip, so a committed lock would be read by nothing.
+
 ### Interactive REPL
 
 ```bash

{athena_python_pptx-0.14.1 → athena_python_pptx-0.14.3}/PKG-INFO

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