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

{athena_python_pptx-0.16.1 → athena_python_pptx-0.17.0}/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.0}/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.0}/CHANGELOG.md

@@ -2,6 +2,138 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 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.0}/PKG-INFO

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

{athena_python_pptx-0.16.1 → athena_python_pptx-0.17.0}/docs/API_PARITY_EXCEPTIONS.md

@@ -45,10 +45,8 @@ parity test's known-missing list by `tests/test_no_silent_noops.py`).
 | `pptx.shapes.DateAxis` | `element` |
 | `pptx.shapes.DoughnutPlot` | `element` |
 | `pptx.shapes.FillFormat` | `from_fill_parent` |
-| `pptx.shapes.GroupShapes` | `element` |
 | `pptx.shapes.LayoutPlaceholder` | `get_or_add_ln`, `ln` |
 | `pptx.shapes.LayoutPlaceholders` | `element` |
-| `pptx.shapes.LayoutShapes` | `element` |
 | `pptx.shapes.Legend` | `element` |
 | `pptx.shapes.LinePlot` | `element` |
 | `pptx.shapes.LineSeries` | `element` |
@@ -56,12 +54,10 @@ parity test's known-missing list by `tests/test_no_silent_noops.py`).
 | `pptx.shapes.Marker` | `element` |
 | `pptx.shapes.MasterPlaceholder` | `get_or_add_ln`, `ln` |
 | `pptx.shapes.MasterPlaceholders` | `element` |
-| `pptx.shapes.MasterShapes` | `element` |
 | `pptx.shapes.Movie` | `get_or_add_ln`, `ln` |
 | `pptx.shapes.NotesMaster` | `element` |
 | `pptx.shapes.NotesSlidePlaceholder` | `get_or_add_ln`, `ln` |
 | `pptx.shapes.NotesSlidePlaceholders` | `element` |
-| `pptx.shapes.NotesSlideShapes` | `element` |
 | `pptx.shapes.Picture` | `get_or_add_ln`, `ln` |
 | `pptx.shapes.PicturePlaceholder` | `get_or_add_ln`, `ln` |
 | `pptx.shapes.PiePlot` | `element` |
@@ -72,7 +68,6 @@ parity test's known-missing list by `tests/test_no_silent_noops.py`).
 | `pptx.shapes.RadarPlot` | `element` |
 | `pptx.shapes.RadarSeries` | `element` |
 | `pptx.shapes.Shape` | `get_or_add_ln`, `ln` |
-| `pptx.shapes.Shapes` | `element` |
 | `pptx.shapes.SlidePlaceholder` | `get_or_add_ln`, `ln` |
 | `pptx.shapes.SlidePlaceholders` | `element` |
 | `pptx.shapes.TableCell` | `element` |
@@ -111,14 +106,13 @@ parity test's known-missing list by `tests/test_no_silent_noops.py`).
 | `pptx.parts.embeddedpackage.EmbeddedXlsxPart` | `factory`, `load`, `load_rels_from_xml`, `new`, `package`, `part_related_by`, `partname_template`, `relate_to`, `related_part`, `rels`, `target_ref` |
 | `pptx.parts.image.ImagePart` | `desc`, `ext`, `image`, `load`, `load_rels_from_xml`, `new`, `package`, `part_related_by`, `relate_to`, `related_part`, `rels`, `scale`, `sha1`, `target_ref` |
 | `pptx.parts.media.MediaPart` | `load`, `load_rels_from_xml`, `new`, `package`, `part_related_by`, `relate_to`, `related_part`, `rels`, `sha1`, `target_ref` |
-| `pptx.parts.presentation.PresentationPart` | `add_slide`, `core_properties`, `drop_rel`, `get_slide`, `load`, `load_rels_from_xml`, `notes_master`, `notes_master_part`, `package`, `part`, `part_related_by`, `presentation`, `relate_to`, `related_part`, `related_slide`, `related_slide_master`, `rels`, `rename_slide_parts`, `save`, `slide_id`, `target_ref` |
+| `pptx.parts.presentation.PresentationPart` | `add_slide`, `core_properties`, `get_slide`, `load`, `load_rels_from_xml`, `notes_master`, `notes_master_part`, `package`, `part`, `part_related_by`, `presentation`, `relate_to`, `related_part`, `related_slide`, `related_slide_master`, `rels`, `rename_slide_parts`, `save`, `slide_id`, `target_ref` |
 | `pptx.parts.slide.BaseSlidePart` | `drop_rel`, `get_image`, `get_or_add_image_part`, `load`, `load_rels_from_xml`, `name`, `package`, `part`, `part_related_by`, `relate_to`, `related_part`, `rels`, `target_ref` |
 | `pptx.parts.slide.NotesMasterPart` | `create_default`, `drop_rel`, `get_image`, `get_or_add_image_part`, `load`, `load_rels_from_xml`, `name`, `notes_master`, `package`, `part`, `part_related_by`, `relate_to`, `related_part`, `rels`, `target_ref` |
 | `pptx.parts.slide.NotesSlidePart` | `drop_rel`, `get_image`, `get_or_add_image_part`, `load`, `load_rels_from_xml`, `name`, `new`, `notes_master`, `notes_slide`, `package`, `part`, `part_related_by`, `relate_to`, `related_part`, `rels`, `target_ref` |
 | `pptx.parts.slide.SlideLayoutPart` | `drop_rel`, `get_image`, `get_or_add_image_part`, `load`, `load_rels_from_xml`, `name`, `package`, `part`, `part_related_by`, `relate_to`, `related_part`, `rels`, `slide_layout`, `slide_master`, `target_ref` |
 | `pptx.parts.slide.SlideMasterPart` | `drop_rel`, `get_image`, `get_or_add_image_part`, `load`, `load_rels_from_xml`, `name`, `package`, `part`, `part_related_by`, `relate_to`, `related_part`, `related_slide_layout`, `rels`, `slide_master`, `target_ref` |
 | `pptx.parts.slide.SlidePart` | `add_chart_part`, `add_embedded_ole_object_part`, `drop_rel`, `get_image`, `get_or_add_image_part`, `get_or_add_video_media_part`, `has_notes_slide`, `load`, `load_rels_from_xml`, `name`, `new`, `notes_slide`, `package`, `part`, `part_related_by`, `relate_to`, `related_part`, `rels`, `slide`, `slide_id`, `slide_layout`, `target_ref` |
-| `pptx.presentation.Presentation` | `part` |
 | `pptx.shapes.Area3DPlot` | `part` |
 | `pptx.shapes.AreaPlot` | `part` |
 | `pptx.shapes.AreaSeries` | `part` |
@@ -271,6 +265,9 @@ After changing any of these behaviours run
 <!-- BEGIN GENERATED: unsupported-writes (scripts/generate_parity_tables.py; do not edit by hand) -->
 | Call | SDK member | Behaviour | Why / what to do instead |
 |---|---|---|---|
+| `CT_GroupShape item assignment` | `CT_GroupShape.__setitem__` | raises `UnsupportedAttributeError` | replacing a child by assignment is not mirrored: remove() the old element and insert() the new one (spTree.insert(i, el) puts el before child i). |
+| `CT_NonVisualDrawingProps.id` | `CT_NonVisualDrawingProps.id` | raises `UnsupportedAttributeError` | the studio gives every shape its own id, a copy inserted with copy.deepcopy() included, so a recipe's id renumbering is not needed: drop the line. |
+| `CT_NonVisualDrawingProps.name` | `CT_NonVisualDrawingProps.name` | raises `UnsupportedAttributeError` | set the shape's name with shape.name = '...' (for a copy, on the shape it becomes once inserted: slide.shapes[-1].name after spTree.append(copy)). |
 | `Connector.text` | `Connector.text` | raises `UnsupportedAttributeError` | a Connector has no text frame (has_text_frame is False). Put the text in a text box or an autoshape instead. |
 | `Font.fill.gradient` | `_FontFillFormat.gradient` | raises `UnsupportedFeatureError` | Gradient text fills aren't yet wired through to the studio exporter. Use Font.color for a solid colour, or render the gradient text to an image and add_picture(...) instead. |
 | `Font.fill.patterned` | `_FontFillFormat.patterned` | raises `UnsupportedFeatureError` | Pattern text fills aren't yet wired through to the studio exporter. |
@@ -327,7 +324,13 @@ After changing any of these behaviours run
 | `slide_layout.background.fill.fore_color.rgb` | `_LayoutBackgroundColor.rgb` | raises `UnsupportedFeatureError` | Layout and master backgrounds are read-only in athena-python-pptx (no command writes them). Set slide.background.fill on each slide instead. |
 | `slide_layout.background.fill.solid` | `_LayoutBackgroundFill.solid` | raises `UnsupportedFeatureError` | Layout and master backgrounds are read-only in athena-python-pptx (no command writes them). Set slide.background.fill on each slide instead. |
 | `slide_master.background.fill.fore_color.rgb` | `_LayoutBackgroundColor.rgb` | raises `UnsupportedFeatureError` | Layout and master backgrounds are read-only in athena-python-pptx (no command writes them). Set slide.background.fill on each slide instead. |
+| `table cell paragraph.level` | `_TableCellParagraph.level` | warns once; value kept locally | a table cell has one top-level paragraph |
+| `table cell paragraph.line_spacing` | `_TableCellParagraph.line_spacing` | warns once; value kept locally | a table cell is one paragraph that follows the table style's spacing; set the row height (table.rows[i].height) or the cell margins instead |
+| `table cell paragraph.space_after` | `_TableCellParagraph.space_after` | warns once; value kept locally | a table cell is one paragraph that follows the table style's spacing; set the row height (table.rows[i].height) or the cell margins instead |
+| `table cell paragraph.space_before` | `_TableCellParagraph.space_before` | warns once; value kept locally | a table cell is one paragraph that follows the table style's spacing; set the row height (table.rows[i].height) or the cell margins instead |
 | `table cell run.hyperlink.address` | `_TableCellHyperlink.address` | raises `UnsupportedFeatureError` | Setting a hyperlink on table-cell text is not supported yet. Put the link on a text box run (run.hyperlink.address) or a shape (shape.click_action.hyperlink.address) instead. |
+| `table cell text_frame.auto_size` | `_TableCellTextFrame.auto_size` | warns once; value kept locally | a table row grows to fit its text |
+| `table cell text_frame.word_wrap` | `_TableCellTextFrame.word_wrap` | warns once; value kept locally | table cell text wraps at the cell's width |
 | `tick_labels.offset` | `TickLabels.offset` | warns once; value kept locally | no command carries it |
 <!-- END GENERATED: unsupported-writes -->
 ---
@@ -337,6 +340,340 @@ After changing any of these behaviours run
 These are documented intentional differences in behavior where the
 SDK doesn't yet match python-pptx's API one-for-one.
 
+### `prs.slides._sldIdLst` and `prs.part.drop_rel()` — the slide delete and move recipes (v0.17.0)
+
+python-pptx has no public slide delete or move, so the recipes everyone copies
+edit the slide-list element. They work here, line for line:
+
+```python
+xml_slides = prs.slides._sldIdLst
+slides = list(xml_slides)
+xml_slides.remove(slides[i])           # delete slide i
+xml_slides.insert(j, slides[i])        # ...or, re-inserted, move it to j
+
+rId = prs.slides._sldIdLst[i].rId      # delete, the other common spelling
+prs.part.drop_rel(rId)
+del prs.slides._sldIdLst[i]
+
+id_dict = {sldId.id: [i, sldId.rId] for i, sldId in enumerate(prs.slides._sldIdLst)}
+prs.part.drop_rel(id_dict[slide.slide_id][1])   # ...and keyed by slide id
+del prs.slides._sldIdLst[id_dict[slide.slide_id][0]]
+```
+
+`prs.slides._sldIdLst` is python-pptx's `p:sldIdLst`
+(`pptx.oxml.presentation.CT_SlideIdList`). Each entry is a `CT_SlideId`
+with an `id` and an `rId`.
+
+- **`id`** is the slide's `slide_id`, as in python-pptx, so recipes that
+  match the two find the slide. python-pptx's is an int (`p:sldId/@id`, from
+  256); this SDK's slide ids are the studio's strings, so `id` is that string.
+- **`rId`** is never reused within the presentation, even after a delete or
+  a refresh, so an `rId` read earlier still names the same slide.
+- **List edits order slides as lxml does:** `insert(i, entry)` puts the entry
+  before the slide now at `i` (counting the entry itself when it is still in
+  the list), or last when `i` is past the end, so on A B C D `insert(3, A)`
+  gives B C A D.
+- **What differs from lxml:** the edits are not applied one line at a time.
+  - They collect in one pending change, and nothing reaches the studio until
+    the change is complete.
+  - It commits when no slide is detached, or before anything else reads slide
+    positions: the next command, a read of `prs.slides` or of a slide's index,
+    an explicit flush, a refresh, or the start of a `batch()` or `with prs:`
+    block. It sends the deletes first, then one `ReorderSlides`, so a command
+    built after the edit addresses slides by their new positions.
+  - The idle auto-flush timer never commits a change, because it could fire
+    between a `remove()` and its `insert()`.
+  - Because reading `prs.slides` commits it, inserting a removed entry after
+    other deck access raises: that slide is already deleted.
+  - A `batch()` or `with prs:` block that raises drops the edits made inside
+    it, and keeps those made before it.
+- **Deletes** go through `Slides.delete`, so the bulk-delete guard applies. A
+  proxy of a deleted slide (`slide = prs.slides[i]` held from before) refuses
+  further edits with `ConflictError` instead of writing to the slide that took
+  its position.
+- **Supported operations:** `len`, iteration, indexing, `index`, `remove`,
+  `del`, `insert`, `append`, `extend`, `getparent`, plus the entries' `id`,
+  `rId`, `get`, `addnext` and `addprevious`.
+- **Refused operations:** anything else lxml offers (`xpath`, `set`, a new or
+  copied `p:sldId`) raises `UnsupportedAttributeError`. To add a slide use
+  `prs.slides.add_slide(layout)`; to copy one, `slide.clone(target_index)`.
+- **`prs.part`:** its only working member is `drop_rel(rId)`. Other OPC members
+  raise.
+
+### `shape._element` and `slide.shapes._spTree` — the shape delete, z-order and duplicate recipes (v0.17.0)
+
+python-pptx has no public shape delete, z-order or shape copy, so the recipes
+everyone copies edit the shape tree. They work here, line for line:
+
+```python
+sp = shape._element                      # delete a shape or a placeholder
+sp.getparent().remove(sp)
+shape.element.getparent().remove(shape.element)
+
+spTree = slide.shapes._spTree
+spTree.remove(el); spTree.insert(2, el)   # send it to the back
+spTree.append(el)                         # bring it to the front
+slide.shapes[0]._element.addprevious(el)  # put it below another shape
+
+new_el = copy.deepcopy(shape._element)   # duplicate it, on any slide
+other_slide.shapes._spTree.insert_element_before(new_el, "p:extLst")
+```
+
+- **The elements** come from `pptx.oxml.shapes`, as in python-pptx:
+  - `shape._element` and `shape.element` (python-pptx's `BaseShape.element`)
+    are a `CT_Shape` (`p:sp`: autoshape, text box, freeform, placeholder; also
+    `shape._sp`), a `CT_Picture` (`_pic`), a `CT_GraphicalObjectFrame` (table,
+    chart, OLE object; `_graphicFrame`), a `CT_Connector` or a `CT_GroupShape`
+    (`_grpSp`). A connector has no `_cxnSp` and a picture no `_sp`, as in
+    python-pptx.
+  - `slide.shapes._spTree` (also `_element`, `_grpSp`, `element`) is the
+    slide's `p:spTree`: `p:nvGrpSpPr`, `p:grpSpPr`, then one element per shape,
+    back to front, so index 2 is the back. A group's tree is its own element:
+    `group.shapes._spTree is group._element`.
+- **What it sends** (the public API's commands):
+  - removing an element deletes its shape (`Shape.delete`, `DeleteShape`)
+    unless it is put back first, which moves it;
+  - moves are `SetShapeZOrder` steps (`to_back`, `to_front`, `forward`,
+    `backward`) composed so the order is exactly the one the XML says,
+    including `spTree.insert(i, el)` of a shape still in the tree, which lxml
+    treats as "move it before the child at `i`";
+  - inserting a `copy.deepcopy()` (or `copy.copy()`) of an element clones its
+    shape (`Shape.clone`, `CloneShape` with no offset) where python-pptx's copy
+    lands: in place, or for a group member at its group coordinates (one
+    `SetTransform`), then z-order steps if it is not on top. A copy that is
+    never inserted sends nothing.
+- **What differs from lxml:** as for `_sldIdLst`, the edits collect in one
+  pending change per presentation.
+  - It commits when no shape is left detached, or before the next command,
+    an explicit flush, `prs.refresh()`, the start of an outermost
+    `prs.batch()` or `with prs:` block, or a read of `slide.shapes` or
+    `slide.placeholders`. Reading `slide.shapes._spTree` does not commit, so
+    `slide.shapes._spTree.remove(el); slide.shapes._spTree.insert(2, el)` is
+    one move.
+  - It sends the clones first, then the deletes, then the z-order steps, so a
+    copy of a shape the same change deletes is cloned before the delete. A
+    held `_sldIdLst` change stays held while it sends, and edits on a slide
+    such a change deleted first go with the slide.
+  - The idle auto-flush timer never commits a change, and a batch or executor
+    block whose body raises drops the edits it held.
+  - Because reads commit, inserting a removed element after reading the
+    shapes raises: that shape is already deleted.
+  - A copy is cloned from its shape as the studio has it when inserted, so a
+    copy whose original changed after `deepcopy()` raises instead of
+    differing from python-pptx's copy.
+- **Supported operations:** an element's `tag`, `getparent`, `getnext`,
+  `getprevious`, `addnext`, `addprevious`, `copy.deepcopy`, `shape_id`,
+  `shape_name`, `has_ph_elm`, and its read-only `p:cNvPr` (`sp.nvSpPr.cNvPr`,
+  any shape's `sp._nvXxPr.cNvPr`): `get`, `attrib`, `keys`, `values`, `items`,
+  `id`, `name`, for the id, name and hidden flag. A tree's `len`, iteration,
+  indexing, `index`, `remove`, `del`, `insert`, `append`, `extend`,
+  `insert_element_before`, `first_child_found_in`, `iterchildren`,
+  `getchildren`, `iter_shape_elms`, `iter_ph_elms`, `nvGrpSpPr` and
+  `grpSpPr`.
+- **Ids:** `p:cNvPr/@id` is the studio's string shape id (`shape.shape_id`),
+  not python-pptx's integer. A copy gets a new id, so a recipe's id
+  renumbering (`cNvPr.id = ...`) is not needed and raises.
+- **Refused operations** raise `UnsupportedAttributeError` naming the
+  supported API: property-level XML (`spPr`, `txBody`, `xfrm`), XML built
+  elsewhere (`parse_xml`, a new element), writes to `p:cNvPr`, `descr` and
+  `title` reads (the studio does not report them), moving a shape to another
+  slide or into another group, a copy into a group, and a notes slide's,
+  layout's or master's tree. Use `shape.text_frame`, `shape.fill` /
+  `shape.line`, `shape.delete()`, `shape.bring_to_front()` /
+  `send_to_back()` / `bring_forward()` / `send_backward()`,
+  `shape.clone(target_slide=...)` and `slide.shapes.add_group_shape([...])`.
+
+### `paragraph._p`, `run._r`, `text_frame._bodyPr` — python-pptx's text XML recipes (v0.17.0)
+
+python-pptx has no public API for bullets, hanging indents, superscript, letter
+spacing or autofit details, so the recipes everyone copies edit the text's lxml
+tree. They work here, line for line:
+
+```python
+from lxml import etree
+from pptx.oxml.ns import qn
+from pptx.oxml.xmlchemy import OxmlElement
+
+pPr = paragraph._p.get_or_add_pPr()
+pPr.set("marL", str(Emu(Pt(18))))                  # hanging indent
+pPr.set("indent", str(-Emu(Pt(18))))
+pPr.insert(0, pPr.makeelement(qn("a:buChar"), {"char": "•"}))   # bullet on
+etree.SubElement(other_paragraph._p.get_or_add_pPr(), qn("a:buNone"))  # off
+buAutoNum = OxmlElement("a:buAutoNum")             # numbered
+buAutoNum.set("type", "arabicPeriod")
+run.font._rPr.set("baseline", "30000")             # superscript
+run._r.get_or_add_rPr().set("spc", "300")          # letter spacing (3pt)
+etree.SubElement(text_frame._bodyPr, qn("a:normAutofit"))
+```
+
+`text_frame._txBody` (also `_element`), `text_frame._bodyPr`, `paragraph._p`
+(`_element`, `_pPr`, `_defRPr`), `run._r` and `font._rPr` (`_element`) are real
+lxml elements of python-pptx's classes (`pptx.oxml.text.CT_TextBody`,
+`CT_TextParagraph`, ...), one tree per text frame, built from the deck, with
+python-pptx's helpers (`get_or_add_pPr()`, `get_or_add_rPr()`,
+`insert_element_before()`, `pPr.lvl`, `rPr.sz`, `bodyPr.autofit`, ...).
+`run._rPr` is the run's `a:rPr` too (python-pptx spells it
+`run._r.get_or_add_rPr()`). `pptx.oxml.parse_xml` and
+`pptx.oxml.xmlchemy.OxmlElement` build loose elements of the same classes;
+they reach the deck once attached to such a tree.
+
+- **What differs from lxml:** an edit is not applied when its line runs.
+  - The edits collect, and the change is sent before the next command,
+    before an explicit flush (`flush()`, `refresh()`, a batch's end) and
+    before any public call on that text frame's paragraphs, runs and fonts.
+    The idle auto-flush never sends it. So a later API write wins
+    (`pPr.set("lvl", "2")` then `paragraph.level = 1` leaves level 1), and
+    `paragraph.alignment` reads an alignment the XML just set.
+  - A `prs.batch()` body (or an executor `with prs:` block) that raises
+    drops the XML edits made inside it, as it drops its commands; edits made
+    before it are sent when it starts.
+  - Requested again after that, the tree shows the deck's state (an API write
+    in between included), updated in place: elements a recipe kept stay
+    valid. An edit to a kept element after its change was sent is sent too,
+    before the next write on that text, the next request or the next
+    explicit flush.
+  - A change no command carries raises `UnsupportedAttributeError` when it
+    resolves (the line that resolved it, or the flush), naming the XML path
+    and the supported API. The change is dropped: the tree goes back to the
+    deck's state and nothing of it is sent.
+- **What is sent** (through the setters the public API uses, so validation
+  and coalescing are the same):
+  - `a:pPr` as one `SetParagraphStyle`: `marL`, `indent`, `lvl`, `algn`
+    (`l` / `ctr` / `r` / `just`), `a:lnSpc` (`a:spcPct` or `a:spcPts`),
+    `a:spcBef` / `a:spcAft` (`a:spcPts`), `a:buClr` (`a:srgbClr`), and the
+    bullet: `a:buNone`, `a:buChar` with `•` (U+2022), `◦` (U+25E6) or `▪`
+    (U+25AA), `a:buAutoNum type="arabicPeriod"`. A bullet element added next
+    to an old one replaces it. Its `a:defRPr` is `paragraph.font`.
+  - `a:rPr` as `SetRunStyle`: `b`, `i`, `u`, `sz`, `strike` (`sngStrike` /
+    `noStrike`), `baseline`, `cap`, `spc`, `lang` (removing it clears the
+    language), `a:solidFill` (`a:srgbClr`, or `a:schemeClr` with python-pptx's
+    `a:lumMod` / `a:lumOff` brightness), `a:highlight`, `a:latin`.
+    `a:hlinkClick` carries a link of this text frame: a copied run keeps it.
+  - `a:bodyPr` as one `SetTextFrameProperties`: `wrap`, `anchor` (`t` /
+    `ctr` / `b`), `lIns` / `tIns` / `rIns` / `bIns` (removing one sets
+    python-pptx's default) and `a:noAutofit` / `a:normAutofit` /
+    `a:spAutoFit`.
+  - The text of an `a:r` (`SetRunText`); an `a:r` or `a:br` appended to a
+    paragraph and an `a:p` appended to the frame (`add_run()`,
+    `add_line_break()`, `add_paragraph()`, with their properties), and
+    trailing `a:r` / `a:p` removed (one frame rewrite, as `paragraph.clear()`).
+- **Warns once:** an `a:buFont` with a text font (the studio draws its
+  bullets in the text's font), and a `baseline` other than python-pptx's
+  30000 / -25000 / 0 (the studio stores superscript / subscript at the
+  default offset).
+- **Refused operations** (the studio's commands cannot carry them):
+  - any other bullet character, numbering scheme or `startAt`; bullet size
+    (`a:buSzPct` / `a:buSzPts`), `a:buSzTx`, `a:buClrTx`, `a:buFontTx`, a
+    symbol-font `a:buFont` and picture bullets; changing a paragraph's
+    imported bullet character or numbering;
+  - removing an attribute or element whose value the studio cannot clear
+    (`algn`, `marL`, `indent`, `b`, `sz`, a color, `a:latin`, the bullet, the
+    autofit, ...): set a value instead;
+  - spacing in percent for `a:spcBef` / `a:spcAft`, other `algn` values, tab
+    stops, an `a:normAutofit` `fontScale` / `lnSpcReduction`, other `a:bodyPr`
+    attributes and children (`vert`, `rot`, `numCol`, 3-D, ...), `a:ea` /
+    `a:cs` / `a:sym`, text outlines and effects, `a:endParaRPr`, `a:lstStyle`;
+  - inserting, moving or removing `a:p` / `a:r` / `a:br` other than at the end,
+    editing `a:fld` text fields, and editing an element of a paragraph or run
+    that `text_frame.text` / `paragraph.text` replaced since it was read.
+- **Not mirrored:** the text of table cells (read only in `cell._tc`, see
+  below), charts and notes.
+- **Lengths in attributes:** as in python-pptx, `str(Emu(...))` and
+  f-strings give the EMU integer the recipes write (`repr()` stays `Emu(...)`).
+
+### `cell._tc`, `row._tr`, `table._tbl` — python-pptx's table XML recipes (v0.17.0)
+
+python-pptx has no public API for cell borders or for deleting a row or a
+column, so the recipes everyone copies edit the table's lxml tree. They work
+here, line for line:
+
+```python
+from pptx.oxml.xmlchemy import OxmlElement
+
+def SubElement(parent, tagname, **kwargs):
+    element = OxmlElement(tagname)
+    element.attrib.update(kwargs)
+    parent.append(element)
+    return element
+
+tcPr = cell._tc.get_or_add_tcPr()                  # cell borders
+for edge in ("a:lnL", "a:lnR", "a:lnT", "a:lnB"):
+    ln = SubElement(tcPr, edge, w=str(Pt(1)), cmpd="sng", algn="ctr")
+    fill = SubElement(ln, "a:solidFill")
+    SubElement(fill, "a:srgbClr", val="1F497D")
+    SubElement(ln, "a:prstDash", val="solid")
+table.rows[1]._tr.h = Inches(0.8)                  # row height
+table.columns[0]._gridCol.w = Inches(2.5)          # column width
+tbl = table._tbl
+tbl.firstRow = False                               # look flags
+tbl.remove(table.rows[2]._tr)                      # delete a row
+```
+
+`table._tbl` (also `table.rows._tbl` / `table.columns._tbl`), `cell._tc`,
+`row._tr` and `column._gridCol` are real lxml elements of python-pptx's
+classes (`pptx.oxml.table.CT_Table`, `CT_TableCell`, `CT_TableRow`,
+`CT_TableCol`, ...), one tree per table, built from the deck, with python-pptx's
+helpers (`get_or_add_tcPr()`, `tc.marL`, `tc.anchor`, `tbl.firstRow`,
+`tcPr.get_or_change_to_solidFill()`, `tbl.tc(row, col)`, `tbl.iter_tcs()`, ...).
+
+- **When it is sent:** as for the text XML above. The edits collect and are
+  sent before the next command, an explicit flush and any public call that
+  reads or writes what the XML can change (a cell's margins, anchor, fill and
+  borders, the row heights and column widths, the look flags), never by the
+  idle auto-flush; a failed `prs.batch()` or `with prs:` block drops the edits
+  made inside it. Walking the table (`table.cell(r, c)`, `table.rows`,
+  `row.cells`, a cell's text) does not send them unless rows or columns were
+  removed, so a recipe that edits every cell sends its edits together.
+  Requested again, the tree shows what the API changed since, updated in
+  place; a cell the recipe edited stays as it wrote it (a border's `cap`
+  included) until an API write on it, so the elements a recipe holds stay
+  valid. Rows the API added or removed leave the other rows' elements valid,
+  and an edit to a kept element lands on its cell even after rows were
+  inserted above it. A kept `table.rows[i]` / `table.columns[i]` follows its
+  row or column the same way (`row._tr`, `row.height`), and raises
+  `IndexError` once its row or column was removed.
+- **What is sent** (through the setters the public API uses):
+  - a cell's `a:lnL` / `a:lnR` / `a:lnT` / `a:lnB` (`w`, `a:solidFill` with
+    an `a:srgbClr`, `a:noFill`, `a:prstDash`) as one `SetCellBorders` per
+    cell; removing an edge clears it (`cell.border_left.no_border()`), and
+    `cell.border_*` reads what the XML set (a later `width` or `dash_style`
+    write keeps an edge's `a:noFill` or theme color). On an uploaded table a
+    border's color may also be an `a:schemeClr`.
+  - `marL` / `marR` / `marT` / `marB` as one `SetCellMargins` per cell
+    (removing one resets it), `anchor` (`t` / `ctr` / `b`) as
+    `SetCellAnchor`, and the cell's fill as `SetTableCell`: an `a:solidFill`
+    holding an `a:srgbClr` (`cell.fill.fore_color.rgb`) or `a:noFill`
+    (`cell.fill.background()`);
+  - `a:tr/@h` as `SetRowHeight` and `a:gridCol/@w` as `SetColWidth`;
+  - the `a:tblPr` flags `firstRow` / `firstCol` / `lastRow` / `lastCol` /
+    `bandRow` / `bandCol` as one `SetTableLook`;
+  - an `a:tr` removed as `DeleteTableRow`, and a column removed (its
+    `a:gridCol` and its `a:tc` in every row) as `DeleteTableColumn`.
+- **Accepted as the line the studio draws:** `cmpd="sng"`, `algn="ctr"`, the
+  line joins (`a:round`, `a:bevel`, `a:miter`) and arrow ends of type `none`.
+  A border's `cap` is not stored: it warns once.
+- **Refused operations** (the studio's commands cannot carry them):
+  - the table style: an edit to `a:tblPr/a:tableStyleId`. The studio sets a
+    table's style when the table is added (`AddTable` / `AddLinkedTable`) and
+    has no command to change it; the error names what can change instead (the
+    look flags and each cell's fill and borders);
+  - other border properties (compound or inset lines, gradient lines, custom
+    dashes, arrowheads, a color with modifiers, a theme color on a table the
+    SDK added), diagonal borders, `vert`, `anchorCtr` and the other `a:tcPr`
+    attributes and children, gradient, picture, pattern and theme-color cell
+    fills, and removing a cell's fill (handing it back to the table style);
+  - merges (`gridSpan` / `rowSpan` / `hMerge` / `vMerge`: use `cell.merge()` /
+    `cell.split()`), a cell's text (use `cell.text` / `cell.text_frame`), rows
+    or columns added or moved through XML (use `table.rows.add()` /
+    `insert()`, `table.columns.add()`), a column removed from some rows only,
+    and removing every row or column;
+  - an edit to an element of a row, column or cell the API removed since it
+    was read.
+- **Read only:** an uploaded table's tree also shows what its snapshot
+  records that no command sets (diagonal borders, `vert`, `anchorCtr`,
+  gradient fills); a cell's text is plain `a:p` / `a:r` / `a:t`, without run
+  properties.
+
 ### `NotesSlide.shapes` / `.placeholders` / `.notes_placeholder` / `.background` / `.name` — not yet exposed
 
 Upstream's `NotesSlide` exposes a full shape tree (`notes_slide.shapes`,
@@ -541,6 +878,17 @@ paragraph.
 - Assigning `None` to `font.name` / `font.italic` cannot clear a value this
   session wrote (the wire format has no inherit marker): the cell keeps it and
   the SDK emits a `UserWarning`. Assign `False` to turn italic off.
+- The text frame's `vertical_anchor` and `margin_left` / `margin_right` /
+  `margin_top` / `margin_bottom` are the cell's own (`cell.vertical_anchor`,
+  `cell.margin_left`, ...) and send the same command (v0.17.0).
+- `text_frame.word_wrap` / `auto_size` and the paragraph's `line_spacing` /
+  `space_before` / `space_after` / `level` exist as in python-pptx, but the
+  studio cannot apply them to a one-paragraph cell. A write warns once per
+  presentation (table above) instead of raising `AttributeError`, and the value
+  is kept for read-after-write. Otherwise an uploaded cell's paragraph reads
+  its own `a:pPr` as python-pptx does (`lvl`; `a:lnSpc` as a multiple or a
+  pitch; `a:spcBef` / `a:spcAft` in points, a percent reading `None`) until its
+  text is replaced, and other reads return `None` (`level` 0) (v0.17.0).
 
 ```python
 cell.text = "Revenue"
@@ -2646,7 +2994,6 @@ python-pptx. Generated from `pptx._athena_extension.iter_athena_extensions()`.
 | `pptx.kit.Kit` | class | 0.13.0 | Athena | Kit — slide composition helpers with overflow-safe, server-measured text. |
 | `pptx.kit.Palette` | class | 0.13.0 | Athena | Palette — named hex colours the kit paints with (Athena defaults). |
 | `pptx.kit.Region` | class | 0.13.0 | Athena | Region — EMU rectangle with inset / split helpers for slide composition. |
-| `pptx.oxml` | module | 0.9.2 |  | pptx.oxml import-compatibility shim (REST-SDK only — no local XML tree). |
 | `pptx.presentation.Presentation.asset_id` | property | 0.1.0 |  | Presentation.asset_id — Athena asset id alias for deck_id. |
 | `pptx.presentation.Presentation.batch` | method | 0.1.0 |  | Presentation.batch — context manager for batched commands. |
 | `pptx.presentation.Presentation.close` | method | 0.1.0 |  | Presentation.close — flush pending commands and release resources. |