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

{athena_python_pptx-0.17.0 → athena_python_pptx-0.18.0}/API_PARITY_REPORT.md

@@ -110,7 +110,6 @@ 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 |
-| `Picture.image.blob` | Image bytes live in the studio's asset store — not materialized into Python |
 
 ## Closed Parity Gaps (added 2026-05-18)
 

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

@@ -2,6 +2,52 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.18.0 — chart.chart_area / chart.plot_area format and add_chart(name=)
+
+- `chart.chart_area.format` and `chart.plot_area.format` now round-trip fill
+  and line edits through chart specs, OOXML export, import and preview
+  rendering. Use `fill.background()` for a transparent chart or plot area.
+  `slide.shapes.add_chart(..., name=...)` also accepts an Athena-only shape
+  name.
+- `Picture.image` returns python-pptx's `Image`, so `picture.image.blob`,
+  `.content_type`, `.ext`, `.sha1`, `.size` and `.filename` work. It returned
+  None for every picture, and code reading an existing deck's images had to
+  fetch `image_url` by hand with the sandbox key. A picture added in this
+  session gives back the bytes it was added from; a picture read from the deck
+  fetches its bytes once from the studio's `/media` route with the SDK's own
+  credentials (redirects refused, 50 MB cap) and caches them on the shape. A
+  picture with no media raises `ValueError("no embedded image")`, as
+  python-pptx does.
+
+## 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

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

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

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

@@ -463,7 +463,10 @@ other_slide.shapes._spTree.insert_element_before(new_el, "p:extLst")
     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`,
+  `shape_name`, `has_ph_elm`, `txBody` (a `p:sp`'s is its text frame's
+  `_txBody`, the same element, as in python-pptx, with `get_or_add_txBody()`;
+  the other elements' is None, as python-pptx answers; see the text XML
+  section below), 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`,
@@ -474,7 +477,7 @@ other_slide.shapes._spTree.insert_element_before(new_el, "p:extLst")
   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
+  supported API: property-level XML (`spPr`, `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,
@@ -506,7 +509,8 @@ 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`
+`text_frame._txBody` (also `_element`, and a `p:sp`'s `shape._element.txBody`),
+`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
@@ -635,7 +639,8 @@ helpers (`get_or_add_tcPr()`, `tc.marL`, `tc.anchor`, `tbl.firstRow`,
 - **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; an edge with no line is an `a:lnX` holding `a:noFill`
+    (`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`.
@@ -661,7 +666,10 @@ helpers (`get_or_add_tcPr()`, `tc.marL`, `tc.anchor`, `tbl.firstRow`,
     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);
+    fills, removing a cell's fill (handing it back to the table style), and
+    removing a cell's `a:lnL` / `a:lnR` / `a:lnT` / `a:lnB` (which hands that
+    edge back to the table style: the studio stores an edge as a line or as no
+    line, so for no line keep the `a:lnX` and give it an `a:noFill`);
   - 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()` /
@@ -1277,6 +1285,24 @@ a later `runs[0].text` edit then wrote the empty run and doubled the text.
 
 These properties/methods were added because LLM agents (Claude, GPT, etc.) frequently generate code using these patterns. Without them, agent-generated table code fails at runtime.
 
+### `Chart.chart_area` and `Chart.plot_area` formatting
+
+python-pptx does not expose chart-area or plot-area fill and line formatting.
+The Athena SDK carries these edits through the chart spec and export patches,
+so a transparent chart background does not require editing private XML:
+
+```python
+chart.chart_area.format.fill.background()
+chart.plot_area.format.fill.background()
+```
+
+Both areas also support solid RGB or theme fills, brightness, line color,
+width and dash style. Use `chart.chart_area` for the whole chart frame and
+`chart.plot_area` for the plotting region.
+These edits apply to classic charts (authored or uploaded); Office 2016
+chartEx charts, such as waterfall and treemap, refuse them
+(`chartExEditsRefusal`).
+
 ### `Font.cap` — PowerPoint-native capitalization mode
 
 The SDK exposes PowerPoint's OOXML run capitalization property as
@@ -1547,10 +1573,13 @@ slide.shapes.add_picture(img.url, Inches(1), Inches(1), width=Inches(6))
 
 ### `Picture.image_url` — owner-scoped media URL for cross-deck image copy
 
-python-pptx upstream exposes `Picture.image` returning an `Image` with
-`.blob` bytes. The REST SDK can't materialize bytes locally, so `.image`
-stays `None` (see the omissions list above). **Additionally**, when a
-picture is loaded from a server snapshot it now carries `image_url`: a
+`Picture.image` returns python-pptx's `Image` (`.blob`, `.content_type`,
+`.ext`, `.filename`, `.sha1`, `.size`, `.dpi`): a picture added in this
+session carries the bytes it was added from, and a picture read from the deck
+fetches its bytes once from the studio's `/media` route with the SDK's own
+credentials (it raises `ValueError("no embedded image")`, as python-pptx
+does, for a picture with no media). **Additionally**, when a
+picture is loaded from a server snapshot it carries `image_url`: a
 stable `{base_url}/media?key=<assetId>` URL that streams the picture's
 bytes. It returns `None` for pictures with no backing media asset (an
 SDK-added picture not yet flushed/refreshed, a placeholder with no image,
@@ -1576,12 +1605,13 @@ dst.save()
 **Portable code that needs to run against stock python-pptx cannot rely
 on `image_url`** — it is an Athena-only accessor.
 
-### `name=` kwarg on `add_textbox()` / `add_shape()` / `add_picture()`
+### `name=` kwarg on `add_textbox()` / `add_shape()` / `add_picture()` / `add_chart()`
 
 Optional keyword for setting a stable shape name at creation. python-pptx
 upstream auto-assigns names like `"Rectangle 47"` and only exposes
 `shape.name = "..."` as a setter; ours additionally accepts `name=` at
-construction. **Portable code that needs to run against stock python-pptx
+construction on `add_textbox()`, `add_shape()`, `add_picture()` and
+`add_chart()`. **Portable code that needs to run against stock python-pptx
 should omit `name=` and assign after the fact.**
 
 When `name=` is omitted, Athena's generated name skips any identical name in
@@ -1599,6 +1629,13 @@ card = slide.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE,
                               name="kpi_card_revenue")
 ```
 
+Charts accept the same keyword:
+
+```python
+frame = slide.shapes.add_chart(chart_type, left, top, width, height, data,
+                               name="quarterly_revenue")
+```
+
 ### `Presentation.reorder_slides(new_order)`
 
 Reorder slides by passing a permutation of indices. Already shipped in
@@ -2008,7 +2045,7 @@ cell.border_top.color.rgb = RGBColor(0x1F, 0x49, 0x7D)
 cell.border_top.width = Pt(1.5)
 cell.border_top.dash_style = "solid"
 
-cell.border_bottom.no_border()   # remove the bottom edge
+cell.border_bottom.no_border()   # no line on the bottom edge
 ```
 
 Each edge stores `colorHex`, `widthEmu`, `dashStyle` and the
@@ -2024,11 +2061,17 @@ indirectly.
 
 ## `Table.table_style` is read-only
 
-python-pptx exposes `Table.table_style` as a writable property that
-swaps the OOXML `<a:tableStyleId>` GUID. Our SDK exposes it as read-only
-today. Pass `table_style` to `slide.shapes.add_table(table_style=...)`
-at creation time to choose the style; modifying it on an existing table
-will be unlocked when the server gains a `SetTableStyle` command.
+python-pptx has no `Table.table_style`: python-pptx code reads a table's
+style GUID from its XML, the text of `table._tbl.tblPr`'s
+`<a:tableStyleId>`. The SDK's read-only `Table.table_style` returns that
+same GUID: an uploaded table's style from the deck, or the one the studio
+gave a table the SDK added (`add_table()` uses python-pptx's default,
+`{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}`; `add_linked_table()` takes
+`table_style_id`). It is None for a table without a style, and
+`table._tbl` shows the same value. The studio has no command that changes
+an existing table's style, so assigning the property raises
+`AttributeError`, and an edit to `a:tableStyleId` through `table._tbl`
+raises `UnsupportedAttributeError`.
 
 ---
 

{athena_python_pptx-0.17.0 → athena_python_pptx-0.18.0}/pptx/__init__.py

@@ -327,7 +327,7 @@ def validate_all_touched() -> dict[int, list[str]]:
     return results
 
 
-__version__ = "0.17.0"
+__version__ = "0.18.0"
 
 __all__ = [
     # Main entry point

{athena_python_pptx-0.17.0 → athena_python_pptx-0.18.0}/pptx/_unsupported.py

@@ -335,7 +335,9 @@ _TEXT_FRAME = (
 _SHAPE = "Use the Shape API: text_frame, fill, line, shadow, left / top / width / height, rotation, delete()."
 _CHART = (
     "Use the Chart API: chart.plots, chart.series, chart.replace_data(chart_data), "
-    "chart.has_title / chart.chart_title, chart.value_axis, chart.category_axis."
+    "chart.has_title / chart.chart_title, chart.value_axis, chart.category_axis. "
+    "For the chart's background use chart.chart_area.format / chart.plot_area.format "
+    "(fill.background() makes it transparent)."
 )
 # python-pptx's private lxml attributes that recipes reach for (``series._element``,
 # ``chart._chartSpace``, ...) on objects this SDK has no mirror of. Whatever the
@@ -423,18 +425,27 @@ def keep_getter_error(obj: Any, name: str, error: UnsupportedAttributeError) ->
             pass
 
 
+def take_getter_error(obj: Any, name: str) -> UnsupportedAttributeError | None:
+    """The error the getter of property ``name`` left on ``obj``
+    (:func:`keep_getter_error`), taken off it, for a guard's ``__getattr__`` to
+    raise; None when it left none. A class whose own ``__getattr__`` does this
+    flags it ``__athena_member_guard__``."""
+    try:
+        stashed = vars(obj).pop(_GETTER_ERROR, None)
+    except TypeError:
+        return None
+    return stashed[1] if stashed is not None and stashed[0] == name else None
+
+
 def _make_guard(
     cls: type, members: dict[str, str], guessed: dict[str, str]
 ) -> Callable[[Any, str], Any]:
     own = cls.__dict__.get("__getattr__")
 
     def __getattr__(self: Any, name: str) -> Any:
-        try:
-            stashed = vars(self).pop(_GETTER_ERROR, None)
-        except TypeError:
-            stashed = None
-        if stashed is not None and stashed[0] == name:
-            raise stashed[1]
+        stashed = take_getter_error(self, name)
+        if stashed is not None:
+            raise stashed
         reason = members.get(name)
         if reason is not None:
             raise UnsupportedAttributeError(f"{type(self).__name__}.{name}", REASONS[reason])

athena_python_pptx-0.18.0/pptx/chart/chart.py

@@ -0,0 +1,7 @@
+"""Shim re-exporting upstream's ``pptx.chart.chart`` surface."""
+
+from __future__ import annotations
+
+from ..shapes import Chart, ChartArea, ChartTitle, PlotArea
+
+__all__ = ["Chart", "ChartArea", "ChartTitle", "PlotArea"]

{athena_python_pptx-0.17.0 → athena_python_pptx-0.18.0}/pptx/client.py

@@ -808,6 +808,54 @@ class Client:
         except requests.RequestException as e:
             raise ConnectionError(f"Failed to download render from {url}: {e}", url=url)
 
+    def _download_media(self, *, key: str, max_bytes: int) -> bytes:
+        """Download one deck media object's bytes with this client's credentials.
+
+        ``/media`` runs the same deck-access check as every deck op, so the
+        bearer stays on the configured API host and a redirect is refused
+        rather than followed. Reads stop at ``max_bytes``.
+        """
+        path = "/media"
+        url = f"{self.base_url.rstrip('/')}{path}?key={quote(key, safe='')}"
+        headers = self._get_headers(path)
+        headers.pop("Content-Type", None)
+        headers["Accept"] = "*/*"
+        try:
+            response = self._session.get(
+                url,
+                headers=headers,
+                timeout=self.timeout,
+                allow_redirects=False,
+                stream=True,
+            )
+            try:
+                if 300 <= response.status_code < 400:
+                    raise RemoteError(
+                        message="Media download redirected; refusing to follow it",
+                        status_code=response.status_code,
+                        error_code="MEDIA_REDIRECT",
+                    )
+                if not response.ok:
+                    self._handle_response(response)
+                chunks: list[bytes] = []
+                received = 0
+                for chunk in response.iter_content(chunk_size=65536):
+                    if not chunk:
+                        continue
+                    received += len(chunk)
+                    if received > max_bytes:
+                        raise RemoteError(
+                            message=f"Media object exceeds the {max_bytes}-byte read cap",
+                            status_code=response.status_code,
+                            error_code="MEDIA_TOO_LARGE",
+                        )
+                    chunks.append(chunk)
+                return b"".join(chunks)
+            finally:
+                response.close()
+        except requests.RequestException as e:
+            raise ConnectionError(f"Failed to download media from {url}: {e}", url=url) from e
+
     # -------------------------------------------------------------------------
     # Deck operations
     # -------------------------------------------------------------------------

{athena_python_pptx-0.17.0 → athena_python_pptx-0.18.0}/pptx/commands.py

@@ -1542,13 +1542,14 @@ class SetCellBorders(Command):
         ``"dashDot"`` / ``"lgDash"`` / ``"lgDashDot"`` / ``"lgDashDotDot"`` /
         ``"sysDash"`` / ``"sysDot"`` / ``"sysDashDot"`` / ``"sysDashDotDot"``)
 
-    Passing ``None`` for an edge removes that edge's border.
+    Passing ``None`` for an edge gives that edge no line (the studio stores
+    and exports it as ``<a:lnX><a:noFill/></a:lnX>``).
 
     Args:
         shape_id: ID of the table shape
         row: Row index (0-based)
         col: Column index (0-based)
-        border_left: Left-edge border spec, or ``None`` to clear
+        border_left: Left-edge border spec, or ``None`` for no line
         border_right: Right-edge border spec
         border_top: Top-edge border spec
         border_bottom: Bottom-edge border spec

{athena_python_pptx-0.17.0 → athena_python_pptx-0.18.0}/pptx/oxml/_tbl.py

@@ -8,7 +8,7 @@ commands the public API sends (:mod:`pptx.oxml._mirror` runs the lifecycle):
 
 * ``a:tcPr`` borders ``a:lnL`` / ``a:lnR`` / ``a:lnT`` / ``a:lnB`` (``w``,
   ``a:solidFill``, ``a:noFill``, ``a:prstDash``) as one ``SetCellBorders`` per
-  cell; removing an edge's ``a:lnX`` clears that border;
+  cell; an edge with no line is an ``a:lnX`` holding ``a:noFill``;
 * ``a:tcPr`` ``marL`` / ``marR`` / ``marT`` / ``marB`` as ``SetCellMargins``,
   ``anchor`` as ``SetCellAnchor``, and the cell's fill (an RGB ``a:solidFill``
   or ``a:noFill``) as ``SetTableCell``;
@@ -18,8 +18,9 @@ commands the public API sends (:mod:`pptx.oxml._mirror` runs the lifecycle):
   ``a:gridCol`` and its ``a:tc`` in every row) as ``DeleteTableColumn``.
 
 The studio has no command that changes an existing table's style, so an edit
-to ``a:tblPr/a:tableStyleId`` raises, as does anything else no command carries
-(merges, rows or columns added through XML, the cells' text).
+to ``a:tblPr/a:tableStyleId`` raises, as does removing an edge's ``a:lnX``
+(which hands the edge back to the table style) and anything else no command
+carries (merges, rows or columns added through XML, the cells' text).
 """
 
 from __future__ import annotations
@@ -165,6 +166,11 @@ _ADD = (
     "column's formatting), and table.delete_row(i) / table.delete_column(i)."
 )
 _MERGE = "Merge and split cells with cell.merge(other_cell) / cell.split()."
+_EDGE_REMOVED = (
+    "Removing a cell's a:lnX hands the edge back to the table style, and the studio has no "
+    "command for that: it stores an edge as a line or as no line. For no line, keep the "
+    "a:lnX and give it an a:noFill (cell.border_left.no_border())."
+)
 _TEXT = (
     "A cell's text is not edited through XML here: use cell.text, or "
     "cell.text_frame.paragraphs[0].runs[0].font for its formatting."
@@ -207,11 +213,12 @@ def _fill_type(cell: TableCell) -> str | None:
 
 def _border_spec(cell: TableCell, edge: str, tag: str) -> dict[str, Any] | None:
     """An edge's border as the studio stores it (``widthEmu``, ``colorHex`` /
-    ``schemeColor`` / ``noFill``, ``dashStyle``): what this session wrote,
-    else the snapshot's; None when the cell has none of its own."""
+    ``schemeColor`` / ``noFill``, ``dashStyle``): what this session wrote (an
+    edge it cleared has no line), else the snapshot's; None when the cell has
+    none of its own."""
     written = cell._border_specs
     if written is not None and edge in written:
-        return written[edge]
+        return written[edge] or {"noFill": True}
     spec = (cell._snapshot_borders or {}).get(tag)
     return spec if isinstance(spec, dict) and spec else None
 
@@ -295,8 +302,9 @@ def _render_tblPr(table: Table) -> Any:
     for flag, name, _ in _LOOK:
         if getattr(table, name):
             tblPr.set(flag, "1")
-    if table._table_style_id:
-        _sub(tblPr, "a:tableStyleId").text = table._table_style_id
+    style_id = table._style_id()
+    if style_id:
+        _sub(tblPr, "a:tableStyleId").text = style_id
     return tblPr
 
 
@@ -922,6 +930,8 @@ class TableMirror(XmlMirror):
         for edge, tag in _EDGES:
             if base.edges.get(tag) == cur.edges.get(tag):
                 continue
+            if not cur.edges.get(tag):
+                raise unsupported(f"{tcpr_path}/a:{tag}", _EDGE_REMOVED)
             spec, cap = self._edge_spec(cur.tcpr, tag, f"{tcpr_path}/a:{tag}")
             edges[edge] = spec
             warn_cap = warn_cap or cap
@@ -942,14 +952,12 @@ class TableMirror(XmlMirror):
             steps.append(self._plan_fill(cell, cur.tcpr, tcpr_path))
         return steps
 
-    def _edge_spec(self, tcPr: Any, tag: str, path: str) -> tuple[dict[str, Any] | None, bool]:
-        """An edge's ``a:lnX`` as the border spec ``SetCellBorders`` sends (None: no
-        border of its own), and whether it set a line cap."""
+    def _edge_spec(self, tcPr: Any, tag: str, path: str) -> tuple[dict[str, Any], bool]:
+        """An edge's ``a:lnX`` (the cell has one) as the border spec
+        ``SetCellBorders`` sends, and whether it set a line cap."""
         lines = tcPr.findall(qn(f"a:{tag}")) if tcPr is not None else []
         if len(lines) > 1:
             raise unsupported(path, f"Keep one a:{tag} in an a:tcPr.")
-        if not lines:
-            return None, False
         return _line_spec(lines[0], path, scheme_colors=self._table._source in _uploaded_sources())
 
     def _plan_fill(self, cell: TableCell, tcPr: Any, path: str) -> Callable[[], None]:
@@ -1078,7 +1086,7 @@ def _line_spec(line: Any, path: str, *, scheme_colors: bool) -> tuple[dict[str,
     if not spec:
         raise unsupported(
             path,
-            "A border sets a width (w), a fill or a:prstDash; remove the a:lnX to clear the border "
+            "A border sets a width (w), a fill or a:prstDash; for no line put an a:noFill in it "
             "(cell.border_left.no_border()).",
         )
     return spec, cap

athena_python_pptx-0.18.0/pptx/oxml/shapes/autoshape.py

@@ -0,0 +1,75 @@
+"""``p:sp``, python-pptx's ``pptx.oxml.shapes.autoshape``.
+
+The element of an autoshape, a text box, a freeform or a placeholder:
+``shape._element`` / ``shape._sp``. See :mod:`pptx.oxml.shapes.shared` for what
+it mirrors. Its ``p:txBody`` is the shape's text frame's: ``sp.txBody`` is
+``shape.text_frame._txBody`` (:mod:`pptx.oxml._txbody`), so what a recipe changes
+in it is held and sent as that text's commands.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..._unsupported import keep_getter_errors
+from ...errors import UnsupportedAttributeError
+from ..ns import qn
+from .shared import BaseShapeElement, _NonVisualProps
+
+
+class CT_ShapeNonVisual(_NonVisualProps):
+    """``p:nvSpPr``: the shape's non-visual properties (its ``cNvPr``)."""
+
+    _tag = qn("p:nvSpPr")
+
+
+class CT_Shape(BaseShapeElement):
+    """``p:sp``: an autoshape, text box, freeform or placeholder. Its
+    ``p:nvSpPr`` (the id and name) and its ``p:txBody`` (the text frame's) are
+    mirrored; its ``p:spPr`` and ``p:style`` are not."""
+
+    _tag = qn("p:sp")
+    _nv_class = CT_ShapeNonVisual
+
+    @property
+    def nvSpPr(self) -> CT_ShapeNonVisual:
+        """The ``p:nvSpPr`` child."""
+        return self._nvXxPr  # type: ignore[return-value]
+
+    @property
+    @keep_getter_errors
+    def txBody(self) -> Any:
+        """The ``p:txBody`` child: the shape's text frame's ``_txBody``, the same
+        element (``sp.txBody is shape.text_frame._txBody``, as in python-pptx).
+        What a recipe changes in it is held and sent before the next command, an
+        explicit flush or an API call on that text, and it shows the text's
+        current state when requested again. None for a shape without a text frame,
+        as python-pptx answers for a ``p:sp`` without a ``p:txBody``."""
+        shape = self._shape
+        if shape is None:
+            raise UnsupportedAttributeError(
+                "CT_Shape.txBody",
+                "this is a copy (copy.deepcopy()) that is not in a shape tree yet, and the "
+                "studio clones a shape with the text its original has when the copy is "
+                "inserted: insert the copy, then edit the text of the shape it becomes "
+                "(slide.shapes[-1].text_frame).",
+            )
+        if not shape.has_text_frame:
+            return None
+        return shape.text_frame._txBody
+
+    def get_or_add_txBody(self) -> Any:
+        """The ``p:txBody`` (:attr:`txBody`). python-pptx adds one to a ``p:sp``
+        without one; here every shape that can hold text has its text frame's,
+        and no command gives one to a shape that cannot."""
+        txBody = self.txBody
+        if txBody is None:
+            raise UnsupportedAttributeError(
+                "CT_Shape.get_or_add_txBody",
+                "this shape has no text frame (shape.has_text_frame is False), and no studio "
+                "command gives it one: put the text in a text box or an autoshape.",
+            )
+        return txBody
+
+
+__all__ = ["CT_Shape", "CT_ShapeNonVisual"]

{athena_python_pptx-0.17.0 → athena_python_pptx-0.18.0}/pptx/oxml/shapes/shared.py

@@ -6,7 +6,8 @@ what python-pptx's delete, z-order and duplicate recipes do with one: read its
 ``tag``, find it in its tree (``getparent()``, ``getnext()``, ``getprevious()``),
 place another shape beside it (``addnext()``, ``addprevious()``) and copy it
 (``copy.deepcopy()``). Its non-visual properties (``sp.nvSpPr.cNvPr``) give the
-shape's id and name, read-only.
+shape's id and name, read-only. A ``p:sp``'s ``p:txBody`` is its text frame's
+(:class:`~pptx.oxml.shapes.autoshape.CT_Shape`).
 
 Edits go through :class:`_ShapeTreeEdit`, one per presentation, which turns
 them into studio commands once they are complete (see
@@ -20,6 +21,7 @@ import contextlib
 from collections.abc import Iterator, Mapping
 from typing import TYPE_CHECKING, Any, ClassVar
 
+from ..._unsupported import take_getter_error
 from ...errors import UnsupportedAttributeError
 from ..ns import qn
 
@@ -32,8 +34,9 @@ _MIRRORED: str = (
     "athena-python-pptx mirrors the shape-tree XML python-pptx's delete, z-order and "
     "duplicate recipes use: an element's tag, getparent(), getnext() / getprevious(), "
     "addnext() / addprevious() and copy.deepcopy(); the read-only p:cNvPr id and name "
-    "(sp.nvSpPr.cNvPr.get('name')); and the shape tree's len, iteration, indexing, "
-    "index, remove, del, insert, append, extend and insert_element_before."
+    "(sp.nvSpPr.cNvPr.get('name')); a p:sp's p:txBody (sp.txBody, its text frame's "
+    "_txBody); and the shape tree's len, iteration, indexing, index, remove, del, "
+    "insert, append, extend and insert_element_before."
 )
 _SHAPE_API: str = (
     "For the rest use the shape API: shape.text_frame for text, shape.fill / shape.line "
@@ -55,9 +58,9 @@ _PROPERTY_HINTS: dict[str, str] = {
         "Its a:xfrm is not mirrored: use shape.left / top / width / height, rotation, "
         "flip_h and flip_v.",
     ),
-    **dict.fromkeys(
-        ("txBody", "get_or_add_txBody"),
-        "Its p:txBody is not mirrored: use shape.text_frame (paragraphs, runs, font).",
+    "get_or_add_txBody": (
+        "Only a p:sp (an autoshape, text box or placeholder) holds a p:txBody; there "
+        "sp.txBody is its text frame's (shape.text_frame._txBody)."
     ),
     **dict.fromkeys(
         ("blipFill", "blip_rId", "srcRect_l", "srcRect_t", "srcRect_r", "srcRect_b"),
@@ -369,6 +372,13 @@ class BaseShapeElement:
         """True for a placeholder (a ``p:sp`` / ``p:pic`` / ``p:graphicFrame`` with ``p:ph``)."""
         return bool(self._source.is_placeholder)
 
+    @property
+    def txBody(self) -> Any:
+        """The ``p:txBody`` child: None, as python-pptx answers for every shape
+        element but a ``p:sp``, the only one that holds one (there it is the
+        text frame's: :class:`~pptx.oxml.shapes.autoshape.CT_Shape`)."""
+        return None
+
     # -- its place in a tree -------------------------------------------------
 
     def _edit(self) -> _ShapeTreeEdit:
@@ -514,8 +524,15 @@ class BaseShapeElement:
     def __getattr__(self, name: str) -> Any:
         if name.startswith("__"):
             raise AttributeError(name)
+        # The explanation a property getter raised (keep_getter_errors), which
+        # Python would otherwise replace with this lookup's.
+        kept = take_getter_error(self, name)
+        if kept is not None:
+            raise kept
         raise unsupported(f"{type(self).__name__}.{name}", name)
 
+    __getattr__.__athena_member_guard__ = True  # type: ignore[attr-defined]
+
     def __repr__(self) -> str:
         return f"<{type(self).__name__} '<{nsptag(self.tag)}>' at 0x{id(self):x}>"