athena-python-pptx 0.8.1__tar.gz → 0.9.1__tar.gz

{athena_python_pptx-0.8.1 → athena_python_pptx-0.9.1}/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## 0.9.0 — eager validation, table overflow diagnostics, and text caps
+
+Publishes the SDK changes already deployed with PPTX Studio after 0.8.1.
+
+- Invalid buffered commands now raise at the originating SDK call instead of
+  waiting until `flush()`. Validation errors include command context such as
+  the slide index, shape ID, or name, making the offending edit actionable
+  without sacrificing the final send-time validation backstop.
+- `Slide.validate()` now warns when table-cell text is likely to wrap beyond
+  the available column width. The offline heuristic accounts for cell margins,
+  font size, merged-column spans, digits, and common punctuation.
+- `Font.cap` and the `TextCap` type expose PowerPoint's native `none`, `all`,
+  and `small` capitalization modes. The value hydrates from existing decks and
+  survives full-frame text re-emission.
+
+The public text-capitalization surface makes this a minor release.
+
+## 0.8.1 — version-string fix (re-cut of 0.8.0)
+
+Functionally identical to 0.8.0. The 0.8.0 wheel was auto-published from a
+tree where `pptx/__init__.py::__version__` was never bumped off `0.7.1`, so
+`import pptx; pptx.__version__` reported `0.7.1` even though the wheel
+contained the surgical-`SetRunText` + faithful-hydration code. PyPI versions
+are immutable, so 0.8.1 re-cuts the release with the corrected `__version__`
+string. No behavior change vs 0.8.0; use 0.8.1 (the `presentation-exec:v55`
+snapshot bundles it).
+
 ## 0.8.0 — Surgical run text + faithful style hydration
 
 Closes the "agent edited deck text and the styling vanished" class of bugs

{athena_python_pptx-0.8.1 → athena_python_pptx-0.9.1}/PKG-INFO

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

{athena_python_pptx-0.8.1 → athena_python_pptx-0.9.1}/docs/API_PARITY_EXCEPTIONS.md

@@ -164,6 +164,19 @@ takes the rest of the queued edits down with it.
 
 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.
 
+### `Font.cap` — PowerPoint-native capitalization mode
+
+The SDK exposes PowerPoint's OOXML run capitalization property as
+`run.font.cap`, accepting `"none"`, `"all"`, or `"small"`. Stock
+python-pptx 1.0.2 does not expose `a:rPr/@cap`, but the Athena SDK needs a
+typed surface so template-authored all-caps and small-caps text survives
+agent edits and full-frame text re-emission.
+
+```python
+run.font.cap = "all"
+assert run.font.cap == "all"
+```
+
 ### `TableCell` — RGB tuple aliases
 
 | Property | Type | Maps to | Why |

{athena_python_pptx-0.8.1 → athena_python_pptx-0.9.1}/pptx/__init__.py

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

{athena_python_pptx-0.8.1 → athena_python_pptx-0.9.1}/pptx/batching.py

@@ -19,7 +19,7 @@ from threading import local
 from typing import TYPE_CHECKING, Any, Generator, Optional
 
 from . import _ptc
-from .commands import AnyCommand
+from .commands import AnyCommand, validate_command
 from .errors import BatchPartialError
 from .typing import CommandsResponse
 
@@ -234,12 +234,21 @@ class CommandBuffer:
 
         Returns:
             Response if sent immediately, None if buffered
+
+        Raises:
+            ValidationError: If the command's parameters are invalid. Raised
+                here — at the API call that created the command — rather than
+                at the eventual ``flush()``, so the traceback points at the
+                offending user line and the invalid command is never buffered
+                (a flush-time failure would discard the whole pending batch).
         """
         # Surface any error captured by the background auto-flush timer
         # before accepting more work — otherwise the user could continue
         # queueing commands on top of a partially-failed batch.
         self._raise_deferred_error()
 
+        validate_command(command)
+
         # PTC begin: emit only for commands in the allow-list. Other
         # commands still flow through the buffer (and through the batched
         # HTTP POST), they just don't produce a sub-tool-card. ``emit_end``
@@ -365,7 +374,7 @@ class CommandBuffer:
         if len(chunks) > 1:
             try:
                 for command in commands:
-                    command.validate()
+                    validate_command(command)
             except Exception:
                 with self._commands_lock:
                     self._commands = commands + self._commands

{athena_python_pptx-0.8.1 → athena_python_pptx-0.9.1}/pptx/client.py

@@ -37,7 +37,7 @@ from .typing import (
     ExportStatus,
     RenderStatus,
 )
-from .commands import AnyCommand
+from .commands import AnyCommand, validate_command
 
 
 SDK_VERSION = "0.1.0"
@@ -647,9 +647,11 @@ class Client:
         Returns:
             Response with applied status, created IDs, and optional snapshot
         """
-        # Validate all commands
+        # Validate all commands (backstop — CommandBuffer.add validates
+        # eagerly at the creating call site; this covers direct client use
+        # and commands mutated after they were buffered).
         for cmd in commands:
-            cmd.validate()
+            validate_command(cmd)
 
         payload = {
             "client": {"type": SDK_CLIENT_TYPE, "version": SDK_VERSION},

{athena_python_pptx-0.8.1 → athena_python_pptx-0.9.1}/pptx/commands.py

@@ -14,7 +14,7 @@ __athena_extension_description__: str = (
 __athena_extension_since__: str = "0.1.0"
 
 from dataclasses import dataclass, field, asdict
-from typing import Any, Optional, Union
+from typing import Any, ClassVar, Optional, Union
 from ._citations import normalize_citation_string
 from .errors import ValidationError
 from .typing import ShapeId, SlideId, TextRunPath, TextStyle
@@ -39,6 +39,26 @@ class Command:
         components = snake_str.split("_")
         return components[0] + "".join(x.title() for x in components[1:])
 
+    # Identifying fields surfaced in validation errors so a failure names the
+    # exact command instance ("AddShape(slide_index=4, name='Card 2')") rather
+    # than only the bad value.
+    _CONTEXT_FIELDS: ClassVar[tuple[str, ...]] = (
+        "slide_index",
+        "index",
+        "shape_id",
+        "name",
+    )
+
+    def context_label(self) -> str:
+        """Short human-readable identity for this command instance."""
+        parts: list[str] = []
+        for field_name in self._CONTEXT_FIELDS:
+            value = getattr(self, field_name, None)
+            if value is not None:
+                parts.append(f"{field_name}={value!r}")
+        label = type(self).__name__
+        return f"{label}({', '.join(parts)})" if parts else label
+
     def validate(self) -> None:
         """Validate command parameters. Raises ValidationError if invalid."""
         pass
@@ -49,6 +69,23 @@ class Command:
         raise NotImplementedError
 
 
+def validate_command(command: "Command") -> None:
+    """Validate ``command``, prefixing any ValidationError with its identity.
+
+    The bare per-command ``validate()`` messages name only the bad field/value
+    ("height must be >= 0 EMU"); when validation runs away from the creating
+    call site (batched flush, multi-command POST) that alone can't be traced
+    back to a shape or slide. Every SDK-internal validation path goes through
+    this wrapper so the error always carries the command context.
+    """
+    try:
+        command.validate()
+    except ValidationError as exc:
+        raise ValidationError(
+            f"{command.context_label()}: {exc.message}", exc.field
+        ) from None
+
+
 @dataclass
 class AddTextBox(Command):
     """

{athena_python_pptx-0.8.1 → athena_python_pptx-0.9.1}/pptx/slides.py

@@ -41,6 +41,106 @@ def _normalize_layout_name(name: str) -> str:
     return " ".join(name.strip().lower().replace("_", " ").split())
 
 
+# --- table text-overflow heuristic (used by Slide.validate) ----------------
+# Approximate per-glyph advance widths in em units (Arial-ish). Deliberately
+# conservative and digit/punctuation-aware because the common overflow case is
+# wide numeric values (currency / counts) in narrow columns.
+_TABLE_GLYPH_EM = {
+    **{d: 0.556 for d in "0123456789"},
+    ",": 0.278, ".": 0.278, "(": 0.333, ")": 0.333,
+    "%": 0.889, "$": 0.556, "-": 0.333, " ": 0.278, "/": 0.278,
+}
+_EMU_PER_PT = 12700
+# PowerPoint's default table body font when a cell exposes no explicit size.
+_DEFAULT_TABLE_FONT_PT = 18.0
+
+
+def _estimate_text_width_emu(text: str, font_pt: float) -> float:
+    """Conservative single-line width estimate for ``text`` at ``font_pt``."""
+    return sum(_TABLE_GLYPH_EM.get(ch, 0.5) for ch in text) * font_pt * _EMU_PER_PT
+
+
+def _cell_font_pt(cell: Any) -> Optional[float]:
+    """Resolve a cell's font size (pt): cell-level, else first run, else None."""
+    fp = getattr(cell, "font_size_pt", None)
+    if fp:
+        return float(fp)
+    try:
+        for para in cell.text_frame.paragraphs:
+            for run in para.runs:
+                if run.font is not None and run.font.size is not None:
+                    # SDK run font size is a raw EMU int (no .pt); Length
+                    # objects do expose .pt — handle both.
+                    size = run.font.size
+                    return float(getattr(size, "pt", size / _EMU_PER_PT))
+    except Exception:
+        pass
+    return None
+
+
+def _table_overflow_warnings(table: Any, label: str) -> list[str]:
+    """Heuristic warnings for table cells whose single-line text likely
+    exceeds the column width (minus cell margins) and would wrap — growing the
+    row and breaking alignment — in PowerPoint. No rendering; uses a
+    conservative font-metric estimate.
+
+    Skips columns whose width is unknown (e.g. tables cloned server-side whose
+    widths are not in the local model) and resolves the font size per cell
+    (cell-level -> first run -> the PowerPoint default). Being a heuristic it
+    can occasionally false-positive on intentionally tight cells.
+    """
+    out: list[str] = []
+    try:
+        ncols = int(table.cols)
+        nrows = len(table.rows)
+    except Exception:
+        return out
+
+    def _colw(i: int) -> int:
+        try:
+            w = table.columns[i].width
+            return int(w) if w and int(w) > 0 else 0
+        except Exception:
+            return 0
+
+    for r in range(nrows):
+        for c in range(ncols):
+            try:
+                cell = table.cell(r, c)
+            except Exception:
+                continue
+            # Continuation cells of a horizontal merge hold no text of their
+            # own — their width belongs to the merge origin.
+            if getattr(cell, "_h_merge", False):
+                continue
+            text = (cell.text or "").strip()
+            if not text:
+                continue
+            # A horizontally-merged origin cell spans grid_span columns; its
+            # usable width is the sum of those columns (PowerPoint semantics).
+            span = getattr(cell, "grid_span", None) or getattr(cell, "_grid_span", 1) or 1
+            colw = sum(_colw(c + k) for k in range(int(span)))
+            if colw <= 0:
+                continue  # unknown/zero width — cannot judge overflow
+            font_pt = _cell_font_pt(cell) or _DEFAULT_TABLE_FONT_PT
+            try:
+                avail = colw - int(cell.margin_left) - int(cell.margin_right)
+            except Exception:
+                avail = colw
+            if avail <= 0:
+                continue
+            est = _estimate_text_width_emu(text, font_pt)
+            if est > avail:
+                span_note = f" across {int(span)} cols" if int(span) > 1 else ""
+                out.append(
+                    f"table '{label}' cell r{r}c{c} text {text!r} "
+                    f"(~{int(est)} EMU at {font_pt:g}pt) likely overflows column "
+                    f"width {colw} EMU{span_note} (~{avail} EMU after cell "
+                    f"margins) — will wrap and grow the row in PowerPoint"
+                )
+    return out
+
+
 def _visible_element_ids(
     *,
     slide_snapshot: SlideSnapshot,
@@ -645,6 +745,7 @@ class Slide:
         notes: Optional[str] = None,
         layout_index: Optional[int] = None,
         layout_name: Optional[str] = None,
+        layout_path: Optional[str] = None,
     ):
         self._presentation = presentation
         self._slide_id = slide_id
@@ -656,6 +757,7 @@ class Slide:
         # Layout tracking
         self._layout_index = layout_index
         self._layout_name = layout_name
+        self._layout_path = layout_path
         self._layout: Optional[SlideLayout] = None
 
         # Initialize shapes collection
@@ -780,6 +882,8 @@ class Slide:
                 name=self._layout_name or "Unknown",
                 index=self._layout_index or 0,
                 slide=self,
+                presentation=self._presentation,
+                path=getattr(self, "_layout_path", None),
             )
         return self._layout
 
@@ -810,6 +914,7 @@ class Slide:
 
         self._layout_index = layout_index
         self._layout_name = layout_name
+        self._layout_path = getattr(value, "_path", None) if isinstance(value, SlideLayout) else None
         self._layout = None  # Reset cached layout
 
         if self._buffer:
@@ -1158,10 +1263,16 @@ class Slide:
           can ignore those warnings; the goal is to catch the *accidental*
           on-top-of-each-other case (the "235 shapes layered" failure
           from the agent retrospective).
+        * **Table cell text overflow** — for shapes that carry a table, cells
+          whose single-line text is likely wider than the column (minus cell
+          margins) and would wrap — growing the row and breaking alignment —
+          when opened in PowerPoint. Uses a conservative font-metric estimate
+          (no rendering), so it catches the "looks fine in the Studio preview
+          but wraps in PowerPoint" class for tables. Heuristic: may
+          occasionally false-positive; skips columns of unknown width.
 
-        Limitations: does *not* render text and so cannot detect text
-        overflowing its container; for that, render the slide and
-        inspect the PNG.
+        Limitations: for *non-table* text it does not render and so cannot
+        detect overflow — for that, render the slide and inspect the PNG.
         """
         prs = self._presentation
         slide_w = int(prs.slide_width) if prs.slide_width else 12192000
@@ -1200,6 +1311,16 @@ class Slide:
                         f"({overlap_area} EMU² ≈ "
                         f"{overlap_area / (slide_w * slide_h) * 100:.2f}% of slide)"
                     )
+
+        # Table cell text-overflow (heuristic; no render). Catches the
+        # "looks fine in Studio, wraps in PowerPoint" class for tables.
+        for shape in list(self._shapes):
+            if getattr(shape, "has_table", False):
+                try:
+                    label = shape.name or shape.shape_id
+                    warnings.extend(_table_overflow_warnings(shape.table, label))
+                except Exception:
+                    pass
         return warnings
 
     @athena_only(
@@ -1722,6 +1843,7 @@ class Slide:
         self._notes = slide_snapshot.notes
         self._layout_index = _parse_layout_index(slide_snapshot.layout_path)
         self._layout_name = slide_snapshot.layout_name
+        self._layout_path = slide_snapshot.layout_path
         self._layout = None
 
         # Rebuild shapes collection
@@ -1774,6 +1896,7 @@ class Slides:
                     notes=slide_snapshot.notes,
                     layout_index=_parse_layout_index(slide_snapshot.layout_path),
                     layout_name=slide_snapshot.layout_name,
+                    layout_path=slide_snapshot.layout_path,
                 )
                 self._slides.append(slide)
                 self._slides_by_id[slide_snapshot.id] = slide
@@ -2528,6 +2651,7 @@ class Slides:
                     notes=slide_snapshot.notes,
                     layout_index=_parse_layout_index(slide_snapshot.layout_path),
                     layout_name=slide_snapshot.layout_name,
+                    layout_path=slide_snapshot.layout_path,
                 )
             else:
                 slide._update_from_snapshot(slide_snapshot, snapshot.elements)
@@ -2874,11 +2998,37 @@ class SlideLayout:
     def slide_master(self) -> Optional["SlideMaster"]:
         """The :class:`SlideMaster` this layout belongs to.
 
-        Returns ``None`` if the layout was constructed without a master
-        reference (e.g., from the legacy hardcoded fallback set used when no
-        snapshot is available).
+        python-pptx resolves this through the layout part's relationship to
+        its master and never returns ``None``. Layout proxies here are often
+        constructed without a master backreference (e.g. ``slide.slide_layout``),
+        so the master is resolved lazily from the presentation's theme
+        hierarchy: first by layout path, then by layout name, falling back to
+        the first master. Returns ``None`` only when the deck snapshot carries
+        no master data at all.
         """
-        return self._slide_master_ref
+        if self._slide_master_ref is not None:
+            return self._slide_master_ref
+        prs = self._presentation
+        if prs is None and self._slide is not None:
+            prs = self._slide._presentation
+        if prs is None:
+            return None
+        masters = prs.slide_masters
+        by_name: Optional["SlideMaster"] = None
+        for master in masters:
+            for layout in master.slide_layouts:
+                if self._path is not None and layout._path == self._path:
+                    self._slide_master_ref = master
+                    return master
+                if by_name is None and self._name is not None and layout._name == self._name:
+                    by_name = master
+        if by_name is not None:
+            self._slide_master_ref = by_name
+            return by_name
+        if len(masters) > 0:
+            self._slide_master_ref = masters[0]
+            return masters[0]
+        return None
 
     @property
     def background(self) -> "_LayoutBackground":

{athena_python_pptx-0.8.1 → athena_python_pptx-0.9.1}/pptx/text/__init__.py

@@ -16,7 +16,7 @@ from ..commands import (
 )
 from ..dml.color import RGBColor, ColorFormat, scheme_name_to_theme_color, theme_color_to_scheme_name
 from ..errors import UnsupportedFeatureError
-from ..typing import ShapeId, TextStyle, TextFramePropertiesSnapshot
+from ..typing import ShapeId, TextCap, TextStyle, TextFramePropertiesSnapshot
 from .._athena_extension import athena_extension
 
 if TYPE_CHECKING:
@@ -36,7 +36,7 @@ class PP_ALIGN:
 
 
 # Wire style keys the SDK hydrates into typed Font state. Anything else the
-# server sends (``cap``, ``highlightColorHex``, ``highlightSchemeColor``,
+# server sends (``highlightColorHex``, ``highlightSchemeColor``,
 # future keys) is carried verbatim in ``Font._extra_style`` so full-frame
 # re-emits (run.text / paragraph.text / add_paragraph) don't silently strip
 # properties the SDK doesn't model.
@@ -44,6 +44,7 @@ _TYPED_WIRE_STYLE_KEYS = frozenset({
     "bold", "italic", "underline", "fontSizePt", "fontFamily", "fontRef",
     "colorHex", "spacingPt", "strike", "strikethrough", "baseline",
     "subscript", "superscript", "languageId", "schemeColor", "brightness",
+    "cap",
 })
 
 
@@ -212,6 +213,7 @@ class Font:
         strike: Optional[bool] = None,
         baseline: Optional[int] = None,
         language_id: Optional[int] = None,
+        cap: Optional[TextCap] = None,
         change_listener: Optional[Any] = None,
     ):
         self._run = run
@@ -254,8 +256,9 @@ class Font:
         self._language_id: Optional[int] = (
             int(language_id) if language_id is not None else None
         )
+        self._cap = cap
         # Wire style properties hydrated from the server that the SDK doesn't
-        # model as typed fields (``cap``, highlights, …). Carried verbatim so
+        # model as typed fields (highlights, …). Carried verbatim so
         # ``_build_style_dict`` reproduces them on full-frame re-emits instead
         # of stripping them from the deck.
         self._extra_style: dict[str, Any] = {}
@@ -293,6 +296,23 @@ class Font:
         self._underline = value
         self._emit_style_change()
 
+    @property
+    def cap(self) -> Optional[TextCap]:
+        """Text capitalization mode (``none``, ``all``, or ``small``).
+
+        This Athena extension maps directly to OOXML ``a:rPr/@cap``. Use
+        ``"all"`` for template titles whose uppercase appearance is authored
+        as a run property rather than baked into the text value.
+        """
+        return self._cap
+
+    @cap.setter
+    def cap(self, value: TextCap) -> None:
+        if value not in {"none", "all", "small"}:
+            raise ValueError("cap must be one of: 'none', 'all', 'small'")
+        self._cap = value
+        self._emit_style_change()
+
     @property
     def size(self) -> Optional[int]:
         """Font size in EMU."""
@@ -533,6 +553,8 @@ class Font:
             style["baseline"] = self._baseline
         if self._language_id is not None:
             style["languageId"] = self._language_id
+        if self._cap is not None:
+            style["cap"] = self._cap
         return style
 
     def _style_payload(self) -> "TextStyle":
@@ -605,6 +627,8 @@ class Font:
             style["baseline"] = self._baseline
         if self._language_id is not None:
             style["languageId"] = self._language_id
+        if self._cap is not None:
+            style["cap"] = self._cap
 
     @athena_extension(
         issue=1063,
@@ -959,6 +983,7 @@ class Run:
             strike=strike,
             baseline=_baseline_from_wire(style_dict),
             language_id=style_dict.get("languageId"),
+            cap=style_dict.get("cap"),
         )
         self._font._hydrate_theme_color(
             style_dict.get("schemeColor"), style_dict.get("brightness")

{athena_python_pptx-0.8.1 → athena_python_pptx-0.9.1}/pptx/typing.py

@@ -16,6 +16,7 @@ from enum import IntEnum
 
 
 # Type aliases for IDs
+TextCap = Literal["none", "all", "small"]
 DeckId = str
 SlideId = str
 ShapeId = str
@@ -153,6 +154,7 @@ class TextStyle(TypedDict, total=False):
     strike: bool
     baseline: int
     languageId: int
+    cap: TextCap
 
 
 @dataclass

{athena_python_pptx-0.8.1 → athena_python_pptx-0.9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-pptx"
-version = "0.8.1"
+version = "0.9.1"
 description = "Drop-in replacement for python-pptx that connects to PPTX Studio for real-time collaboration"
 readme = "README.md"
 license = "MIT"