athena-python-pptx 0.16.1__tar.gz → 0.17.1__tar.gz

{athena_python_pptx-0.16.1 → athena_python_pptx-0.17.1}/AGENTS.md

@@ -69,7 +69,8 @@ A small number of REST-SDK-specific departures are documented in
 
 These standard python-pptx members are omitted because a REST SDK has no
 local XML / OPC parts:
-- `Shape.element`, `Shape.part` — XML element access.
+- `Shape.part` — package part access. (`Shape.element` is implemented: the
+  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).
@@ -119,7 +120,33 @@ install fails the parity tests rather than skipping them.
 
 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:
 
-- No `_element`, `_sp`, `_spTree` XML attributes — these don't exist
+- No local OOXML package. python-pptx's private XML attributes (`_tbl`,
+  `_tc`, `series._element`, ...) raise `UnsupportedAttributeError` naming the
+  supported API (`pptx/_unsupported.py`), except where common recipes map onto
+  commands. Those edits are held until complete
+  (`CommandBuffer.hold_pending_edit`):
+  - `prs.slides._sldIdLst` and `prs.part.drop_rel()` for slide delete and move
+    (`pptx/oxml/presentation.py`, tests in `tests/test_sldidlst_compat.py`);
+  - `shape._element` / `shape.element` (with `_sp`, `_pic`, `_graphicFrame`,
+    `_grpSp`) and `slide.shapes._spTree` for shape delete, z-order and
+    duplicate, sent as `DeleteShape`, `SetShapeZOrder` and `CloneShape`
+    (`pptx/oxml/shapes/`, tests in `tests/test_shape_element_compat.py`);
+  - a shape's text: `text_frame._txBody` / `_bodyPr`, `paragraph._p`,
+    `run._r` and `font._rPr` are real lxml elements of python-pptx's classes
+    (`pptx/oxml/text.py` on the ported `xmlchemy` / `simpletypes`), a mirror of
+    the deck that is diffed into the public API's commands when the change
+    resolves. `pptx/oxml/_mirror.py` holds the reusable lifecycle (hold,
+    resolve, in-place re-sync, late edits, the access hooks that resolve before
+    a public call), `pptx/oxml/_txbody.py` the text translation; tests in
+    `tests/test_text_xml_compat.py`. A change no command carries raises
+    naming the XML path; never drop one silently.
+  - a table: `table._tbl`, `cell._tc`, `row._tr` and `column._gridCol`
+    (`pptx/oxml/table.py`), the same kind of mirror (`pptx/oxml/_tbl.py`):
+    cell borders, margins, anchor and fill, row heights, column widths, the
+    look flags, and row / column removal. It captures rows by their
+    serialization and re-syncs only the cells an API write touched, so a
+    recipe that walks a large table cell by cell stays linear; tests in
+    `tests/test_table_xml_compat.py`.
 - Operations are batched via `with prs.batch():` context manager
 - State is synchronized via the PPTX Studio collaboration layer (Yjs)
 - **Programmatic Tool Calling (PTC):** every `CommandBuffer.add` and

{athena_python_pptx-0.16.1 → athena_python_pptx-0.17.1}/API_PARITY_REPORT.md

@@ -91,7 +91,7 @@ via Tranches R–W:
 | SlideLayout | PASS (+`index`) |
 | SlideMaster | PASS |
 | SlideShapes | PASS (+SDK REST helpers; `add_connector` accepts optional `begin_shape`/`end_shape`) |
-| Table | PASS (+SDK REST helpers + inherited `Shape.element` proxy) |
+| Table | PASS (+SDK REST helpers + inherited `Shape.element`, its frame's `p:graphicFrame` element) |
 | `_Cell` | PASS (+SDK REST helpers) |
 | PlaceholderFormat | PASS (+convenience type-check booleans + custom-prompt/transform fields) |
 | Chart | PASS (`category_axis` / `value_axis` / `legend` / `font` / `chart_style` added in v0.1.68; replaces `UnsupportedFeatureError` stubs) |

{athena_python_pptx-0.16.1 → athena_python_pptx-0.17.1}/CHANGELOG.md

@@ -2,6 +2,167 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.17.1
+
+- `Table.table_style` returns the table's style GUID, the text of
+  `table._tbl`'s `a:tableStyleId`, which python-pptx code reads: an uploaded
+  table's from the deck, or the one `add_table()` / `add_linked_table()` gave a
+  table the SDK added; None for a table without one. It returned None for every
+  table (it read a snapshot field the studio never sends). It stays read-only:
+  the studio has no command that changes an existing table's style.
+- `shape._element.txBody` (and `shape._sp.txBody`) of an autoshape, text box
+  or placeholder is its text frame's `_txBody`, the same lxml element
+  (`sp.txBody is shape.text_frame._txBody`, as in python-pptx), and
+  `sp.get_or_add_txBody()` returns it; it raised `UnsupportedAttributeError`.
+  Edits through it are held and sent as the text's commands, as edits through
+  `text_frame._txBody` are, so python-pptx's "for every shape, rewrite each
+  `a:t` of `shape._element.txBody`" recipe works. As in python-pptx it is None
+  for a picture's, graphic frame's, connector's or group's element, and for a
+  shape without a text frame.
+- A table cell's cleared edge (`cell.border_left.no_border()`, or
+  `SetCellBorders` with `None`) reads in `cell._tc` as an `a:lnX` holding
+  `a:noFill` on every table, as the studio now stores and exports it (an
+  uploaded table's read as no `a:lnX`, which in PowerPoint is the table
+  style's line). A width or dash written after `no_border()` keeps the edge
+  without a line, as it does an `a:noFill` an XML recipe wrote, and an RGB
+  color draws it again (it sent a width-only edge). Removing a cell's `a:lnX`
+  through `cell._tc` raises
+  `UnsupportedAttributeError`: in python-pptx that hands the edge back to the
+  table style, which no studio command does (it cleared the edge before). For
+  no line, keep the `a:lnX` and give it an `a:noFill`, or call `no_border()`.
+
+## 0.17.0
+
+- python-pptx's slide delete and move recipes work. They edit
+  `prs.slides._sldIdLst`, which raised `UnsupportedAttributeError`; it is now
+  python-pptx's `p:sldIdLst` (`pptx.oxml.presentation.CT_SlideIdList`):
+  - `xml_slides.remove(entry)` (or `del xml_slides[i]`) deletes the slide;
+  - re-inserting it (`insert`, `append`, `addnext`, `addprevious`) moves it
+    instead, and inserting a slide that is still in the list moves it, as
+    lxml does;
+  - `prs.part.drop_rel(entry.rId)` then `del` deletes the slide once;
+  - an entry's `id` is its slide's `slide_id`, as in python-pptx, so the
+    recipe that finds a slide's entry by comparing the two works.
+
+  Edits are held until the change is complete, then sent as deletes and one
+  reorder, so a move never deletes its slide first and "remove every slide,
+  then append them in a new order" is a single reorder. Anything that reads
+  slide positions sends an open change first (the next command, `prs.slides`,
+  a slide's index, a flush, a refresh, a `batch()` or `with prs:` block), so
+  later commands address slides by their new positions; a block that raises
+  drops the edits made inside it. The bulk-delete guard applies. Other lxml
+  members, and other OPC members of `prs.part`, raise naming the supported
+  API.
+- A slide proxy held from before its slide was deleted (`prs.slides.delete`
+  or the recipes above) raises `ConflictError` on an edit. It wrote to the
+  slide that had taken its position.
+- python-pptx's shape delete, z-order and duplicate recipes work.
+  `shape._element` and python-pptx's public `shape.element` (both raised or
+  answered with a delete-only proxy) are the shape's element, with python-pptx's
+  `_sp`, `_pic`, `_graphicFrame` and `_grpSp` aliases, and
+  `slide.shapes._spTree` is the slide's shape tree (`pptx.oxml.shapes`:
+  `CT_Shape`, `CT_Picture`, `CT_GraphicalObjectFrame`, `CT_Connector`,
+  `CT_GroupShape`). As in python-pptx, `group.shapes._spTree` is the group's
+  element and the tree holds `p:nvGrpSpPr` and `p:grpSpPr` first.
+  - `sp.getparent().remove(sp)` (or `spTree.remove(el)`, `del spTree[i]`)
+    deletes the shape or placeholder;
+  - putting it back (`insert`, `append`, `addnext`, `addprevious`), or
+    inserting a shape that is still in the tree, moves it, as lxml does, sent
+    as the fewest `SetShapeZOrder` steps that give exactly the new order:
+    `spTree.insert(2, el)` sends it to the back;
+  - inserting `copy.deepcopy(shape._element)` into any slide's tree clones the
+    shape there in place (`CloneShape` with no offset), and a copy never
+    inserted sends nothing.
+
+  Edits are held until the change is complete, as for `_sldIdLst`, so a move
+  never deletes its shape; the next command, a flush or refresh, and reading
+  `slide.shapes` send them (clones, then deletes, then z-order). An element's
+  tag, parent and siblings, and its `p:cNvPr` id and name, read as in
+  python-pptx. Other lxml members, property-level XML (`spPr`, `txBody`),
+  moving a shape to another slide or group, and copies changed after
+  `deepcopy()` raise naming the supported API.
+- A held XML-recipe change that completes sends its commands without forcing
+  the other held change, so a shape move made during a slide move no longer
+  turns the slide's removal into a delete, and a clone lands on the slide it
+  named.
+- A group member's `bring_to_front()` / `send_to_back()` / `bring_forward()` /
+  `send_backward()` and `delete()` update `group.shapes`, which kept the old
+  order and the deleted member until a refresh.
+- python-pptx's text XML recipes work: bullets on and off, numbered lists,
+  hanging indents, superscript, letter spacing, line spacing and autofit
+  through XML. `text_frame._txBody` / `_bodyPr`, `paragraph._p` / `_pPr` /
+  `_defRPr`, `run._r` / `_rPr` and `font._rPr` raised
+  `UnsupportedAttributeError`; they are now real lxml elements of
+  python-pptx's classes (`pptx.oxml.text`), one tree per text frame built from
+  the deck, with python-pptx's helpers (`get_or_add_pPr()`,
+  `insert_element_before()`, `pPr.lvl`, ...). What a recipe changes is sent
+  through the public API's setters:
+  - `a:pPr` as `SetParagraphStyle` (indents, level, alignment, spacing, bullet
+    color and the `•` / `◦` / `▪`, `a:buNone` and `arabicPeriod` bullets),
+    its `a:defRPr` as `paragraph.font`;
+  - `a:rPr` as `SetRunStyle` (bold, italic, underline, size, strike,
+    baseline, caps, spacing, language, color, highlight, typeface);
+  - `a:bodyPr` as `SetTextFrameProperties` (wrap, anchor, insets, autofit);
+  - run text, appended runs, breaks and paragraphs, and trailing removals
+    through the existing text commands.
+
+  The change is sent before the next command, explicit flush, refresh or API
+  call on that text (never by the idle timer), so a later API write wins and
+  reads see the edit; like `_sldIdLst`'s, a `prs.batch()` or `with prs:` block
+  that raises drops the changes made inside it. Requested again, the tree shows
+  the deck's state in place. Anything no command carries raises
+  `UnsupportedAttributeError` naming the XML path and the supported API, and
+  is dropped. `pptx.oxml.parse_xml` and `pptx.oxml.xmlchemy.OxmlElement` build
+  real elements instead of raising. `lxml` is now a dependency.
+- `str()` of a length (`Emu`, `Pt`, ...) and f-strings give the EMU integer, as
+  in python-pptx, so `pPr.set("marL", str(Emu(Pt(18))))` writes `"228600"`
+  (it wrote `"Emu(228600)"`); `repr()` is unchanged.
+- A run's color writes merged into one command drop an earlier brightness the
+  later write does not set, as the studio does when it applies them one by
+  one: `font.color.brightness = 0.4` then `font.color.brightness = 0` (or a
+  new `theme_color`) sent the 0.4.
+- python-pptx's table XML recipes work: cell borders, row heights, column
+  widths, the look flags, a cell's margins, anchor and fill through XML, and
+  the row and column delete recipes. `table._tbl`, `cell._tc`, `row._tr` and
+  `column._gridCol` raised `UnsupportedAttributeError`; they are now real lxml
+  elements of python-pptx's classes (`pptx.oxml.table`), one tree per table
+  built from the deck. What a recipe changes is sent through the public API's
+  setters:
+  - a cell's `a:lnL` / `a:lnR` / `a:lnT` / `a:lnB` as one `SetCellBorders`
+    (`w`, an RGB or no line, the dash), which `cell.border_*` then reads (a
+    later `width` or `dash_style` write keeps the no line or theme color);
+  - `marL` / `marR` / `marT` / `marB` as `SetCellMargins`, `anchor` as
+    `SetCellAnchor`, an RGB `a:solidFill` or `a:noFill` as `SetTableCell`;
+  - `a:tr/@h` as `SetRowHeight`, `a:gridCol/@w` as `SetColWidth`, the
+    `a:tblPr` flags as one `SetTableLook`;
+  - a removed `a:tr` as `DeleteTableRow`, a removed column (its `a:gridCol`
+    and its `a:tc` in every row) as `DeleteTableColumn`.
+
+  The studio cannot change an existing table's style, so an edit to
+  `a:tableStyleId` raises `UnsupportedAttributeError` naming what can change;
+  so do merges, a cell's text, rows or columns added through XML and the
+  other properties no command carries. A border's `cap` is ignored with a
+  warning. Walking the table (`table.cell(r, c)`, `row.cells`) does not send a
+  pending change, so a recipe that edits every cell sends its edits together.
+- `table.delete_row(i)` / `table.delete_column(i)` drop the row's height (the
+  column's width) locally, as the server does: the rows below kept reading
+  the height of the row after them.
+- A row or column proxy (`table.rows[i]`, `table.columns[i]`) kept across
+  rows or columns inserted or removed before it keeps meaning its own row or
+  column, as python-pptx's does: it read and wrote the one that took its
+  index. One whose row or column was removed raises `IndexError`.
+- A chart data label's `text_frame` has python-pptx's `paragraphs`: one
+  paragraph over the label's text whose runs and font are the label's, so
+  `point.data_label.text_frame.paragraphs[0].runs[0].font.bold = True` and
+  `paragraphs[0].text = ...` work. `paragraphs` raised `AttributeError`.
+- Table cell text frames have python-pptx's `vertical_anchor` and margins
+  (they write the cell's own), and `word_wrap` / `auto_size`; cell paragraphs
+  have `line_spacing`, `space_before`, `space_after` and `level`. A
+  one-paragraph cell cannot apply those last members, so a write warns once
+  per presentation and keeps the value for read-after-write, instead of
+  raising `AttributeError`, which production scripts hit. An uploaded cell's
+  paragraph reads its own level and spacing (`a:pPr`), as python-pptx does.
+
 ## 0.16.1 — `Presentation.upload()` and `create(pptx=...)` report the deck they create
 
 - `Presentation.upload()` emits the `CreatePresentation` tool-call event with

{athena_python_pptx-0.16.1 → athena_python_pptx-0.17.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-pptx
-Version: 0.16.1
+Version: 0.17.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
@@ -22,6 +22,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: athena-references>=0.1.0
+Requires-Dist: lxml>=4.9.0
 Requires-Dist: requests>=2.28.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.0; extra == 'dev'