athena-python-pptx 0.3.1__tar.gz → 0.4.1__tar.gz

{athena_python_pptx-0.3.1 → athena_python_pptx-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-pptx
-Version: 0.3.1
+Version: 0.4.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.3.1 → athena_python_pptx-0.4.1}/docs/API_PARITY_EXCEPTIONS.md

@@ -352,19 +352,30 @@ public reorder API (callers manipulate `slides.sldIdLst` XML directly).
 prs.reorder_slides([2, 0, 1])  # move slide 2 to the front
 ```
 
-### Strict positive-dimension validation on every `Add*` command
-
-`AddTextBox`, `AddShape`, `AddPicture`, `AddTable`, and `SetTransform`
-now reject **zero** width/height client-side, not just negative values.
-This matches the server's Zod schema (`z.number().int().positive()`) so
-a stray `Inches(0)` raises a clear, field-named `ValidationError` locally
-instead of becoming a generic `commands.N.hEmu: Too small` 400 after the
-batch is on the wire. (For `AddPicture`, omit `width=`/`height=` entirely
-to fall back to the image's native dimensions — that path is still
-supported; the validation only fires when an explicit zero is passed.)
-
-`SetColWidth` and `SetRowHeight` still allow zero (`min(0)` server-side)
-because zero means "auto-fit" for table dimensions.
+### Non-negative dimension validation on every `Add*` command
+
+`AddTextBox`, `AddShape`, `AddPicture`, `AddTable`, `SetTransform`,
+`AddOleObject`, `AddLinkedOleObject`, `AddLinkedTable`, `AddChart`,
+`AddChart2016`, and `AddMovie` reject **negative** width/height
+client-side (the server's Zod schema is `z.number().int().nonnegative()`).
+
+**Zero is allowed**, matching python-pptx and OOXML — `a:ext` cx/cy are
+`ST_PositiveCoordinate` whose XSD facet is `minInclusive="0"`, so a
+zero-area shape (e.g. a degenerate divider line/connector) is valid and
+python-pptx accepts it without complaint. Earlier SDK versions rejected
+zero too; that was a parity departure that broke the common
+"thin divider" idiom and aborted whole command batches when an agent
+passed `height=0`, so it was reverted. A negative value still raises a
+clear, field-named `ValidationError` locally (and `400` server-side)
+rather than producing an invalid `<a:ext>`.
+
+(For `AddPicture`, omit `width=`/`height=` entirely to fall back to the
+image's native dimensions — that path is unchanged.)
+
+`SetColWidth` and `SetRowHeight` also allow zero (`min(0)` server-side)
+because zero means "auto-fit" for table dimensions. `SetPresentationSize`
+still requires strictly positive dimensions (a zero-size slide is
+degenerate, not a valid OOXML construct).
 
 ### Server fail-fast on partial batch failure
 

{athena_python_pptx-0.3.1 → athena_python_pptx-0.4.1}/pptx/__init__.py

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

{athena_python_pptx-0.3.1 → athena_python_pptx-0.4.1}/pptx/client.py

@@ -72,7 +72,11 @@ class Client:
             base_url: Base URL of the API (e.g., "https://api.pptx-studio.com").
                      If not provided, uses ATHENA_PPTX_BASE_URL environment variable.
             api_key: Optional API key for authentication.
-                    If not provided, uses ATHENA_PPTX_API_KEY environment variable.
+                    If not provided, falls back to the ATHENA_PPTX_API_KEY
+                    environment variable, then to ATHENA_API_KEY (the canonical
+                    Athena user API key — same value, accepted as a fallback so
+                    code running in sandboxes that only inject ATHENA_API_KEY
+                    still authenticates).
             timeout: Request timeout in seconds
 
         Raises:
@@ -83,11 +87,13 @@ class Client:
             base_url = os.environ.get("ATHENA_PPTX_BASE_URL")
             if base_url is None:
                 raise ValueError(
-                    "base_url must be provided or ATHENA_PPTX_BASE_URL environment variable must be set"
+                    "base_url must be provided or the ATHENA_PPTX_BASE_URL "
+                    "environment variable must be set. Example: "
+                    'ATHENA_PPTX_BASE_URL="https://pptx-studio.prd.athenaintel.com".'
                 )
 
         if api_key is None:
-            api_key = os.environ.get("ATHENA_PPTX_API_KEY")
+            api_key = os.environ.get("ATHENA_PPTX_API_KEY") or os.environ.get("ATHENA_API_KEY")
 
         self.base_url = base_url.rstrip("/")
         self.api_key = api_key
@@ -129,7 +135,18 @@ class Client:
     def _handle_response(self, response: requests.Response) -> Any:
         """Handle API response, raising appropriate errors."""
         if response.status_code == 401:
-            raise AuthenticationError("Invalid or expired API key")
+            if not self.api_key:
+                raise AuthenticationError(
+                    "No API key was sent. Pass api_key= to Presentation(...) "
+                    "or set ATHENA_PPTX_API_KEY (or ATHENA_API_KEY as a "
+                    "fallback) in the environment."
+                )
+            raise AuthenticationError(
+                "Invalid or expired API key. The pptx-studio API rejected the "
+                "credentials. Verify ATHENA_PPTX_API_KEY (or the ATHENA_API_KEY "
+                "fallback) is set to a valid Athena user API key for the "
+                "current workspace."
+            )
 
         if response.status_code == 409:
             data = response.json() if response.text else {}
@@ -416,7 +433,7 @@ class Client:
         if name is None:
             name = os.path.basename(file_path)
             # Remove extension
-            if name.endswith('.pptx') or name.endswith('.potx'):
+            if name.endswith(".pptx") or name.endswith(".potx"):
                 name = name[:-5]
 
         # Step 1: Create deck to get presigned URL
@@ -496,7 +513,7 @@ class Client:
         # Use filename as name if not provided
         if name is None:
             name = os.path.basename(file_path)
-            if name.endswith('.pptx') or name.endswith('.potx'):
+            if name.endswith(".pptx") or name.endswith(".potx"):
                 name = name[:-5]
 
         # Step 1: Create deck to get presigned URL
@@ -649,6 +666,7 @@ class Client:
                     flipV=transform_data.get("flipV"),
                 ),
                 preview_text=elem_data.get("previewText"),
+                rich_content=elem_data.get("richContent"),
                 placeholder=placeholder,
                 properties=elem_data.get("properties"),
                 source=elem_data.get("source"),
@@ -800,9 +818,7 @@ class Client:
                 return self._download(download_url)
 
             if status["status"] in ("failed", "error"):
-                raise ExportError(
-                    status.get("error", "Export failed"), job_id
-                )
+                raise ExportError(status.get("error", "Export failed"), job_id)
 
             time.sleep(poll_interval)
 
@@ -870,9 +886,7 @@ class Client:
                 return self._download(image_url)
 
             if status["status"] in ("failed", "error"):
-                raise RenderError(
-                    status.get("error", "Render failed"), job_id
-                )
+                raise RenderError(status.get("error", "Render failed"), job_id)
 
             time.sleep(poll_interval)
 

{athena_python_pptx-0.3.1 → athena_python_pptx-0.4.1}/pptx/commands.py

@@ -87,14 +87,14 @@ class AddTextBox(Command):
     def validate(self) -> None:
         if self.slide_index < 0:
             raise ValidationError("slide_index must be non-negative", "slide_index")
-        # Server Zod schema is z.number().int().positive() → rejects 0 and
-        # negatives. Reject locally too so a stray Inches(0) raises with a
-        # clear field name + value instead of becoming a generic
-        # "commands.N.hEmu: Too small" 400 after the round-trip.
-        if self.w_emu <= 0:
-            raise ValidationError(f"width must be > 0 EMU (got {self.w_emu})", "w_emu")
-        if self.h_emu <= 0:
-            raise ValidationError(f"height must be > 0 EMU (got {self.h_emu})", "h_emu")
+        # OOXML `a:ext` cx/cy are ST_PositiveCoordinate (minInclusive=0), so
+        # zero-area shapes are valid (e.g. a degenerate divider/connector) and
+        # python-pptx accepts them. Only negatives are rejected, matching the
+        # server Zod schema (z.number().int().nonnegative()).
+        if self.w_emu < 0:
+            raise ValidationError(f"width must be >= 0 EMU (got {self.w_emu})", "w_emu")
+        if self.h_emu < 0:
+            raise ValidationError(f"height must be >= 0 EMU (got {self.h_emu})", "h_emu")
 
 
 @dataclass
@@ -155,14 +155,15 @@ class SetTransform(Command):
     def validate(self) -> None:
         if not self.shape_id:
             raise ValidationError("shape_id is required", "shape_id")
-        # Server Zod schema: wEmu / hEmu are z.number().int().positive() —
-        # rejects 0 and negatives. Mirror locally so a stray Inches(0) raises
-        # synchronously with the offending field rather than failing
-        # validation server-side after the round-trip.
-        if self.w_emu is not None and self.w_emu <= 0:
-            raise ValidationError(f"width must be > 0 EMU (got {self.w_emu})", "w_emu")
-        if self.h_emu is not None and self.h_emu <= 0:
-            raise ValidationError(f"height must be > 0 EMU (got {self.h_emu})", "h_emu")
+        # Server Zod schema: wEmu / hEmu are z.number().int().nonnegative() —
+        # zero is valid (OOXML a:ext cx/cy are ST_PositiveCoordinate,
+        # minInclusive=0; python-pptx accepts zero-area shapes). Only negatives
+        # are rejected, mirrored locally so they surface synchronously with the
+        # offending field rather than failing server-side after the round-trip.
+        if self.w_emu is not None and self.w_emu < 0:
+            raise ValidationError(f"width must be >= 0 EMU (got {self.w_emu})", "w_emu")
+        if self.h_emu is not None and self.h_emu < 0:
+            raise ValidationError(f"height must be >= 0 EMU (got {self.h_emu})", "h_emu")
 
 
 @dataclass
@@ -352,10 +353,10 @@ class AddShape(Command):
             raise ValidationError("slide_index must be non-negative", "slide_index")
         if not self.shape_type:
             raise ValidationError("shape_type is required", "shape_type")
-        if self.w_emu <= 0:
-            raise ValidationError(f"width must be > 0 EMU (got {self.w_emu})", "w_emu")
-        if self.h_emu <= 0:
-            raise ValidationError(f"height must be > 0 EMU (got {self.h_emu})", "h_emu")
+        if self.w_emu < 0:
+            raise ValidationError(f"width must be >= 0 EMU (got {self.w_emu})", "w_emu")
+        if self.h_emu < 0:
+            raise ValidationError(f"height must be >= 0 EMU (got {self.h_emu})", "h_emu")
 
 
 @dataclass
@@ -492,12 +493,13 @@ class AddPicture(Command):
             raise ValidationError(
                 "image_format must be 'png', 'jpeg', 'gif', 'bmp', or 'tiff'", "image_format"
             )
-        # Server schema treats wEmu / hEmu as positive() when present (omit
-        # them entirely to fall back to the image's native size).
-        if self.w_emu is not None and self.w_emu <= 0:
-            raise ValidationError(f"width must be > 0 EMU (got {self.w_emu})", "w_emu")
-        if self.h_emu is not None and self.h_emu <= 0:
-            raise ValidationError(f"height must be > 0 EMU (got {self.h_emu})", "h_emu")
+        # Server schema treats wEmu / hEmu as nonnegative() when present (zero
+        # is allowed; omit them entirely to fall back to the image's native
+        # size). Only negatives are rejected.
+        if self.w_emu is not None and self.w_emu < 0:
+            raise ValidationError(f"width must be >= 0 EMU (got {self.w_emu})", "w_emu")
+        if self.h_emu is not None and self.h_emu < 0:
+            raise ValidationError(f"height must be >= 0 EMU (got {self.h_emu})", "h_emu")
 
 
 @dataclass
@@ -547,10 +549,10 @@ class AddOleObject(Command):
     def validate(self) -> None:
         if self.slide_index < 0:
             raise ValidationError("slide_index must be non-negative", "slide_index")
-        if self.w_emu <= 0:
-            raise ValidationError(f"width must be > 0 EMU (got {self.w_emu})", "w_emu")
-        if self.h_emu <= 0:
-            raise ValidationError(f"height must be > 0 EMU (got {self.h_emu})", "h_emu")
+        if self.w_emu < 0:
+            raise ValidationError(f"width must be >= 0 EMU (got {self.w_emu})", "w_emu")
+        if self.h_emu < 0:
+            raise ValidationError(f"height must be >= 0 EMU (got {self.h_emu})", "h_emu")
         if not self.preview_base64:
             raise ValidationError("preview_base64 is required", "preview_base64")
         if self.preview_format not in ("png", "jpeg"):
@@ -635,10 +637,10 @@ class AddLinkedOleObject(Command):
     def validate(self) -> None:
         if self.slide_index < 0:
             raise ValidationError("slide_index must be non-negative", "slide_index")
-        if self.w_emu <= 0:
-            raise ValidationError(f"width must be > 0 EMU (got {self.w_emu})", "w_emu")
-        if self.h_emu <= 0:
-            raise ValidationError(f"height must be > 0 EMU (got {self.h_emu})", "h_emu")
+        if self.w_emu < 0:
+            raise ValidationError(f"width must be >= 0 EMU (got {self.w_emu})", "w_emu")
+        if self.h_emu < 0:
+            raise ValidationError(f"height must be >= 0 EMU (got {self.h_emu})", "h_emu")
         if not isinstance(self.source_ref, dict) or not self.source_ref.get("id"):
             raise ValidationError(
                 "source_ref must be an AssetReference dict with an 'id' field",
@@ -730,10 +732,10 @@ class AddLinkedTable(Command):
     def validate(self) -> None:
         if self.slide_index < 0:
             raise ValidationError("slide_index must be non-negative", "slide_index")
-        if self.w_emu <= 0:
-            raise ValidationError(f"width must be > 0 EMU (got {self.w_emu})", "w_emu")
-        if self.h_emu <= 0:
-            raise ValidationError(f"height must be > 0 EMU (got {self.h_emu})", "h_emu")
+        if self.w_emu < 0:
+            raise ValidationError(f"width must be >= 0 EMU (got {self.w_emu})", "w_emu")
+        if self.h_emu < 0:
+            raise ValidationError(f"height must be >= 0 EMU (got {self.h_emu})", "h_emu")
         if not isinstance(self.source_ref, dict) or not self.source_ref.get("id"):
             raise ValidationError(
                 "source_ref must be an AssetReference dict with an 'id' field",
@@ -803,10 +805,10 @@ class AddTable(Command):
             raise ValidationError("rows must be between 1 and 100", "rows")
         if self.cols < 1 or self.cols > 26:
             raise ValidationError("cols must be between 1 and 26", "cols")
-        if self.w_emu <= 0:
-            raise ValidationError(f"width must be > 0 EMU (got {self.w_emu})", "w_emu")
-        if self.h_emu <= 0:
-            raise ValidationError(f"height must be > 0 EMU (got {self.h_emu})", "h_emu")
+        if self.w_emu < 0:
+            raise ValidationError(f"width must be >= 0 EMU (got {self.w_emu})", "w_emu")
+        if self.h_emu < 0:
+            raise ValidationError(f"height must be >= 0 EMU (got {self.h_emu})", "h_emu")
 
 
 @dataclass
@@ -1464,6 +1466,23 @@ class SetGradientFill(Command):
                         "stops"
                     )
 
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize, camelCasing each stop's ``color_hex`` to ``colorHex`` for the server schema."""
+        result = super().to_dict()
+        if self.stops is not None:
+            camel_stops: list[dict[str, Any]] = []
+            for stop in self.stops:
+                camel: dict[str, Any] = {
+                    "position": stop.get("position"),
+                    "colorHex": stop.get("color_hex"),
+                }
+                transparency = stop.get("transparency")
+                if transparency is not None:
+                    camel["transparency"] = transparency
+                camel_stops.append(camel)
+            result["stops"] = camel_stops
+        return result
+
 
 @dataclass
 class SetShapeZOrder(Command):
@@ -2243,10 +2262,10 @@ class AddChart(Command):
                 f"chart_type must be one of {sorted(valid_types)}",
                 "chart_type",
             )
-        if self.w_emu <= 0:
-            raise ValidationError("w_emu must be positive", "w_emu")
-        if self.h_emu <= 0:
-            raise ValidationError("h_emu must be positive", "h_emu")
+        if self.w_emu < 0:
+            raise ValidationError("w_emu must be >= 0", "w_emu")
+        if self.h_emu < 0:
+            raise ValidationError("h_emu must be >= 0", "h_emu")
         if not self.series:
             raise ValidationError("at least one series is required", "series")
         if self.grouping is not None and self.grouping not in (
@@ -2559,10 +2578,10 @@ class AddChart2016(Command):
                 f"chart_type must be one of {sorted(valid)} (got {self.chart_type!r})",
                 "chart_type",
             )
-        if self.w_emu <= 0:
-            raise ValidationError("w_emu must be positive", "w_emu")
-        if self.h_emu <= 0:
-            raise ValidationError("h_emu must be positive", "h_emu")
+        if self.w_emu < 0:
+            raise ValidationError("w_emu must be >= 0", "w_emu")
+        if self.h_emu < 0:
+            raise ValidationError("h_emu must be >= 0", "h_emu")
         if not self.series:
             raise ValidationError("at least one series is required", "series")
 
@@ -2935,10 +2954,10 @@ class AddMovie(Command):
     def validate(self) -> None:
         if self.slide_index < 0:
             raise ValidationError("slide_index must be >= 0", "slide_index")
-        if self.w_emu <= 0:
-            raise ValidationError("w_emu must be positive", "w_emu")
-        if self.h_emu <= 0:
-            raise ValidationError("h_emu must be positive", "h_emu")
+        if self.w_emu < 0:
+            raise ValidationError("w_emu must be >= 0", "w_emu")
+        if self.h_emu < 0:
+            raise ValidationError("h_emu must be >= 0", "h_emu")
         # Reject empty strings — they look "set" but ship no payload.
         has_embedded = bool(self.movie_base64)
         has_url = bool(self.url)

{athena_python_pptx-0.3.1 → athena_python_pptx-0.4.1}/pptx/shapes/__init__.py

@@ -2963,6 +2963,43 @@ class _ChartPlotCollection:
 # (rather than in their own file) so they're visible from the chart
 # adapters above.
 
+# python-pptx ``XL_DATA_LABEL_POSITION`` (IntEnum) -> the OOXML ``dLblPos``
+# string symbols the server accepts. Assigning the enum member directly
+# (``data_labels.position = XL_LABEL_POSITION.OUTSIDE_END``) must serialize to
+# ``'outEnd'`` rather than the raw int ``2``, otherwise the commands endpoint
+# rejects the patch with a 400. The accepted set is mirrored from
+# ``packages/chart-core/src/schema.ts`` (``'ctr'|'inEnd'|'inBase'|'outEnd'|
+# 'bestFit'|'t'|'b'|'l'|'r'``). Mirrors the ``Legend._POSITION_INT_TO_STR``
+# pattern.
+_DATA_LABEL_POSITION_INT_TO_STR = {
+    -4108: 'ctr',     # CENTER
+    3: 'inEnd',       # INSIDE_END
+    4: 'inBase',      # INSIDE_BASE
+    2: 'outEnd',      # OUTSIDE_END
+    5: 'bestFit',     # BEST_FIT
+    0: 't',           # ABOVE
+    1: 'b',           # BELOW
+    -4131: 'l',       # LEFT
+    -4152: 'r',       # RIGHT
+}
+
+
+def _coerce_data_label_position(value: Any) -> Optional[str]:
+    """Normalize a data-label position to its OOXML ``dLblPos`` string.
+
+    Accepts an ``XL_DATA_LABEL_POSITION`` member (or raw int), in which case
+    it maps to the OOXML symbol, or an already-valid string, which passes
+    through unchanged. Unmappable ints resolve to ``None`` so no invalid
+    patch is emitted (matching ``Legend.position``'s behavior)."""
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return _DATA_LABEL_POSITION_INT_TO_STR.get(int(value))
+    return str(value)
+
+
 class DataLabel:
     """python-pptx parity for a single data label on a chart series.
 
@@ -3047,9 +3084,10 @@ class DataLabel:
 
     @position.setter
     def position(self, value: Optional[str]) -> None:
-        self._position = value
-        if value is not None:
-            self._emit(position=str(value))
+        coerced = _coerce_data_label_position(value)
+        self._position = coerced
+        if coerced is not None:
+            self._emit(position=coerced)
 
     @property
     @athena_extension(
@@ -3357,9 +3395,10 @@ class DataLabels:
 
     @position.setter
     def position(self, value: Optional[str]) -> None:
-        self._position = value
-        if value is not None:
-            self._emit_style(position=value)
+        coerced = _coerce_data_label_position(value)
+        self._position = coerced
+        if coerced is not None:
+            self._emit_style(position=coerced)
 
     @property
     def show_category_name(self) -> bool:
@@ -5292,6 +5331,7 @@ class Shape:
         element_type: str = "text",
         transform: Optional[Transform] = None,
         preview_text: Optional[str] = None,
+        rich_content: Optional[dict[str, Any]] = None,
         properties: Optional[dict[str, Any]] = None,
         placeholder: Optional[PlaceholderSnapshot] = None,
         source: Optional[str] = None,
@@ -5310,7 +5350,10 @@ class Shape:
 
         # Auto-shapes also support text in PowerPoint (phase-1 behavior).
         if element_type in ("text", "shape"):
-            rich_content = properties.get("richContent") if properties else None
+            if rich_content is None and properties:
+                # Older snapshot experiments nested richContent under
+                # properties. Current API snapshots send it top-level.
+                rich_content = properties.get("richContent")
             self._text_frame = TextFrame(
                 shape_id=shape_id,
                 buffer=buffer,
@@ -5318,6 +5361,7 @@ class Shape:
                 rich_content=rich_content,
                 text_frame_properties=text_frame_properties,
             )
+            self._text_frame._shape = self
 
     # Known misspelled/non-existent attributes with specific fix guidance
     _ATTRIBUTE_FIXES: dict[str, str] = {
@@ -7183,9 +7227,11 @@ class Shapes:
                                 element_type=elem.type,
                                 transform=elem.transform,
                                 preview_text=elem.preview_text,
+                                rich_content=elem.rich_content,
                                 properties=elem.properties,
                                 placeholder=elem.placeholder,
                                 source=elem.source,
+                                text_frame_properties=elem.text_frame_properties,
                             )
                     self._shapes_by_id[elem.id] = shape
                     is_inherited = shape._is_inherited
@@ -9220,7 +9266,6 @@ class Shapes:
                 properties=elem.properties,
                 placeholder=elem.placeholder,
                 source=elem.source,
-                text_frame_properties=elem.text_frame_properties,
             )
         elif elem.type == "connector":
             shape = Connector(
@@ -9232,7 +9277,6 @@ class Shapes:
                 properties=elem.properties,
                 placeholder=elem.placeholder,
                 source=elem.source,
-                text_frame_properties=elem.text_frame_properties,
             )
         elif elem.type == "group":
             shape = GroupShape(
@@ -9244,7 +9288,6 @@ class Shapes:
                 properties=elem.properties,
                 placeholder=elem.placeholder,
                 source=elem.source,
-                text_frame_properties=elem.text_frame_properties,
             )
         else:
             shape = Shape(
@@ -9254,6 +9297,7 @@ class Shapes:
                 element_type=elem.type,
                 transform=elem.transform,
                 preview_text=elem.preview_text,
+                rich_content=elem.rich_content,
                 properties=elem.properties,
                 placeholder=elem.placeholder,
                 source=elem.source,

{athena_python_pptx-0.3.1 → athena_python_pptx-0.4.1}/pptx/text/__init__.py

@@ -162,6 +162,7 @@ class Font:
         size: Optional[int] = None,
         name: Optional[str] = None,
         color_hex: Optional[str] = None,
+        font_ref: Optional[str] = None,
         spacing_pt: Optional[float] = None,
         strike: Optional[bool] = None,
         baseline: Optional[int] = None,
@@ -174,6 +175,7 @@ class Font:
         self._underline = underline
         self._size = size  # In EMU
         self._name = name
+        self._font_ref = font_ref
         self._color_hex = color_hex
         self._spacing_pt = spacing_pt  # Character spacing in points
         # OOXML theme color name (e.g. ``"accent1"``, ``"tx1"``) when the
@@ -258,6 +260,7 @@ class Font:
     @name.setter
     def name(self, value: str) -> None:
         self._name = value
+        self._font_ref = None
         self._emit_style_change()
 
     @property
@@ -428,6 +431,8 @@ class Font:
             style["underline"] = self._underline
         if self._name is not None:
             style["fontFamily"] = self._name
+        if self._font_ref is not None:
+            style["fontRef"] = self._font_ref
         if self._spacing_pt is not None:
             style["spacingPt"] = self._spacing_pt
         if self._strike is not None:
@@ -471,6 +476,8 @@ class Font:
             style["fontSizePt"] = self._size / EMU_PER_PT
         if self._name is not None:
             style["fontFamily"] = self._name
+        if self._font_ref is not None:
+            style["fontRef"] = self._font_ref
         if self._color_hex is not None:
             style["colorHex"] = self._color_hex
         if self._theme_color_name is not None:
@@ -510,13 +517,13 @@ class Font:
         ``000000`` / ``ENGLISH_US (1033)`` for the Athena blank-template
         baseline.
 
-        Returns a dict with keys ``name``, ``size_pt``, ``bold``,
-        ``italic``, ``underline``, ``strike``, ``color_hex`` (RGB hex
-        or scheme name), ``language_id`` (int).
+        Returns a dict with keys ``name``, ``font_ref``, ``size_pt``,
+        ``bold``, ``italic``, ``underline``, ``strike``, ``color_hex``
+        (RGB hex or scheme name), ``language_id`` (int).
 
         Closes python-pptx#1063, #765, #883.
         """
-        para = self._run._paragraph if self._run else None
+        para = self._run._paragraph if self._run is not None else None
         tf = para._text_frame if para else None
         shape = getattr(tf, "_shape", None) if tf else None
 
@@ -527,6 +534,9 @@ class Font:
             return None
 
         para_font = getattr(para, "font", None) if para is not None else None
+        paragraph_default: TextStyle = {}
+        if para is not None:
+            paragraph_default = getattr(para, "_default_run_style", {}) or {}
 
         # Shape-level font default (rare; populated for placeholder
         # snapshots that carry ``shape._properties["fontDefault"]``).
@@ -554,6 +564,8 @@ class Font:
             size_pt = self._size / EMU_PER_PT
         elif para_font is not None and getattr(para_font, "_size", None) is not None:
             size_pt = para_font._size / EMU_PER_PT
+        elif paragraph_default.get("fontSizePt") is not None:
+            size_pt = float(paragraph_default["fontSizePt"])
         elif shape_default.get("sizePt") is not None:
             size_pt = float(shape_default["sizePt"])
 
@@ -561,31 +573,42 @@ class Font:
             "name": _first_non_none(
                 self._name,
                 getattr(para_font, "_name", None) if para_font else None,
+                paragraph_default.get("fontFamily"),
                 shape_default.get("name"),
                 DEFAULTS["name"],
             ),
+            "font_ref": _first_non_none(
+                self._font_ref,
+                getattr(para_font, "_font_ref", None) if para_font else None,
+                paragraph_default.get("fontRef"),
+                shape_default.get("fontRef"),
+            ),
             "size_pt": _first_non_none(size_pt, DEFAULTS["size_pt"]),
             "bold": _first_non_none(
                 self._bold,
                 getattr(para_font, "_bold", None) if para_font else None,
+                paragraph_default.get("bold"),
                 shape_default.get("bold"),
                 DEFAULTS["bold"],
             ),
             "italic": _first_non_none(
                 self._italic,
                 getattr(para_font, "_italic", None) if para_font else None,
+                paragraph_default.get("italic"),
                 shape_default.get("italic"),
                 DEFAULTS["italic"],
             ),
             "underline": _first_non_none(
                 self._underline,
                 getattr(para_font, "_underline", None) if para_font else None,
+                paragraph_default.get("underline"),
                 shape_default.get("underline"),
                 DEFAULTS["underline"],
             ),
             "strike": _first_non_none(
                 self._strike,
                 getattr(para_font, "_strike", None) if para_font else None,
+                paragraph_default.get("strike"),
                 shape_default.get("strike"),
                 DEFAULTS["strike"],
             ),
@@ -594,13 +617,17 @@ class Font:
                 self._theme_color_name,
                 getattr(para_font, "_color_hex", None) if para_font else None,
                 getattr(para_font, "_theme_color_name", None) if para_font else None,
+                paragraph_default.get("colorHex"),
+                paragraph_default.get("schemeColor"),
                 shape_default.get("colorHex"),
+                shape_default.get("schemeColor"),
                 shape_default.get("themeColor"),
                 DEFAULTS["color_hex"],
             ),
             "language_id": _first_non_none(
                 self._language_id,
                 getattr(para_font, "_language_id", None) if para_font else None,
+                paragraph_default.get("languageId"),
                 shape_default.get("languageId"),
                 DEFAULTS["language_id"],
             ),
@@ -810,6 +837,7 @@ class Run:
             underline=style.get("underline") if style else None,
             size=int(style.get("fontSizePt", 0) * 12700) if style and style.get("fontSizePt") else None,
             name=style.get("fontFamily") if style else None,
+            font_ref=style.get("fontRef") if style else None,
             color_hex=style.get("colorHex") if style else None,
             spacing_pt=style.get("spacingPt") if style else None,
         )
@@ -1013,6 +1041,7 @@ class Run:
             'underline': self._font._underline,
             'size_emu': self._font._size,
             'font_name': self._font._name,
+            'font_ref': self._font._font_ref,
             'color_hex': self._font._color_hex,
         }
 
@@ -1110,6 +1139,7 @@ class Paragraph:
         space_after: Optional[int] = None,
         margin_left: Optional[int] = None,
         indent: Optional[int] = None,
+        default_run_style: Optional[TextStyle] = None,
     ):
         self._text_frame = text_frame
         self._index = index
@@ -1123,6 +1153,7 @@ class Paragraph:
         self._space_after = space_after
         self._margin_left = margin_left
         self._indent = indent
+        self._default_run_style = default_run_style or {}
 
         if runs:
             for i, run_data in enumerate(runs):
@@ -1761,6 +1792,7 @@ class Paragraph:
             'alignment': self._alignment,
             'level': self._level,
             'bullet': self._bullet,
+            'default_run_style': self._default_run_style,
             'run_count': len(self._runs),
             'runs': [run.to_dict() for run in self._runs],
         }
@@ -1831,6 +1863,7 @@ class TextFrame:
         self._shape_id = shape_id
         self._buffer = buffer
         self._preview_text = preview_text or ""
+        self._shape: Any | None = None
         self._paragraphs: list[Paragraph] = []
 
         # Seed internal text-frame-properties state from the source snapshot so
@@ -1860,7 +1893,21 @@ class TextFrame:
         if rich_content and rich_content.get("paragraphs"):
             for i, para_data in enumerate(rich_content["paragraphs"]):
                 self._paragraphs.append(
-                    Paragraph(self, i, runs=para_data.get("runs"))
+                    Paragraph(
+                        self,
+                        i,
+                        runs=para_data.get("runs"),
+                        alignment=para_data.get("alignment"),
+                        level=para_data.get("level", 0),
+                        bullet=para_data.get("bullet"),
+                        bullet_color_hex=para_data.get("bulletColor"),
+                        line_spacing=para_data.get("lineSpacing"),
+                        space_before=para_data.get("spaceBeforeEmu"),
+                        space_after=para_data.get("spaceAfterEmu"),
+                        margin_left=para_data.get("marginLeftEmu"),
+                        indent=para_data.get("indentEmu"),
+                        default_run_style=para_data.get("defaultRunStyle"),
+                    )
                 )
         elif preview_text:
             # Split plain text into paragraphs
@@ -1943,6 +1990,20 @@ class TextFrame:
             if len(para._runs) > 1:
                 needs_rich = True
                 break
+            if (
+                para._alignment is not None
+                or bool(para._level)
+                or para._bullet is not None
+                or para._bullet_color_hex is not None
+                or para._line_spacing is not None
+                or para._space_before is not None
+                or para._space_after is not None
+                or para._margin_left is not None
+                or para._indent is not None
+                or bool(para._default_run_style)
+            ):
+                needs_rich = True
+                break
             for run in para._runs:
                 if run._hyperlink._address:
                     needs_rich = True
@@ -1973,7 +2034,28 @@ class TextFrame:
             # regress to zero runs and break later SetRunStyle calls.
             if not runs:
                 runs.append({"text": ""})
-            paragraphs.append({"runs": runs})
+            paragraph_data: dict = {"runs": runs}
+            if para._alignment is not None:
+                paragraph_data["alignment"] = para._alignment
+            if para._level:
+                paragraph_data["level"] = para._level
+            if para._bullet is not None:
+                paragraph_data["bullet"] = para._bullet
+            if para._bullet_color_hex is not None:
+                paragraph_data["bulletColor"] = para._bullet_color_hex
+            if para._line_spacing is not None:
+                paragraph_data["lineSpacing"] = para._line_spacing
+            if para._space_before is not None:
+                paragraph_data["spaceBeforeEmu"] = para._space_before
+            if para._space_after is not None:
+                paragraph_data["spaceAfterEmu"] = para._space_after
+            if para._margin_left is not None:
+                paragraph_data["marginLeftEmu"] = para._margin_left
+            if para._indent is not None:
+                paragraph_data["indentEmu"] = para._indent
+            if para._default_run_style:
+                paragraph_data["defaultRunStyle"] = para._default_run_style
+            paragraphs.append(paragraph_data)
 
         return {"paragraphs": paragraphs}
 
@@ -2789,6 +2871,7 @@ class TextFrame:
                     'size_emu': run.font._size,
                     'size_pt': run.font.size_pt,
                     'font_name': run.font._name,
+                    'font_ref': run.font._font_ref,
                     'color_hex': run.font._color_hex,
                 })
         return styled_runs

{athena_python_pptx-0.3.1 → athena_python_pptx-0.4.1}/pptx/typing.py

@@ -137,6 +137,9 @@ class TextStyle(TypedDict, total=False):
 
     fontSizePt: float
     fontFamily: str
+    # OOXML theme font reference (for example ``+mj-lt`` or ``+mn-lt``).
+    # When present, export preserves this over hardcoding fontFamily.
+    fontRef: str
     bold: bool
     italic: bool
     underline: bool
@@ -206,6 +209,7 @@ class ElementSnapshot:
     slide_id: SlideId
     transform: Transform
     preview_text: Optional[str] = None
+    rich_content: Optional[dict[str, Any]] = None
     placeholder: Optional[PlaceholderSnapshot] = None
     properties: Optional[dict[str, Any]] = None
     source: Optional[Literal["ingested", "sdk", "layout", "master"]] = None

{athena_python_pptx-0.3.1 → athena_python_pptx-0.4.1}/pyproject.toml

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