python-pptx2 2.13.0__py3-none-any.whl

pptx2/shapes/graphfrm.py

@@ -0,0 +1,316 @@
+"""Graphic Frame shape and related objects.
+
+A graphic frame is a common container for table, chart, smart art, and media
+objects.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from pptx2.dml.effect import (
+    BlurFormat,
+    GlowFormat,
+    ReflectionFormat,
+    ShadowFormat,
+    SoftEdgeFormat,
+)
+from pptx2.enum.shapes import MSO_SHAPE_TYPE
+from pptx2.shapes.base import BaseShape
+from pptx2.shared import ParentedElementProxy
+from pptx2.spec import (
+    GRAPHIC_DATA_URI_CHART,
+    GRAPHIC_DATA_URI_OLEOBJ,
+    GRAPHIC_DATA_URI_TABLE,
+)
+from pptx2.table import Table
+from pptx2.util import lazyproperty
+
+if TYPE_CHECKING:
+    from pptx2.chart.chart import Chart
+    from pptx2.dml.effect import InnerShadowFormat, PresetShadowFormat, ShadowFormat
+    from pptx2.oxml.shapes.graphfrm import CT_GraphicalObjectData, CT_GraphicalObjectFrame
+    from pptx2.parts.chart import ChartPart
+    from pptx2.parts.slide import BaseSlidePart
+    from pptx2.types import ProvidesPart
+
+
+class GraphicFrame(BaseShape):
+    """Container shape for table, chart, smart art, and media objects.
+
+    Corresponds to a `p:graphicFrame` element in the shape tree.
+    """
+
+    def __init__(self, graphicFrame: CT_GraphicalObjectFrame, parent: ProvidesPart):
+        super().__init__(graphicFrame, parent)
+        self._graphicFrame = graphicFrame
+
+    @property
+    def chart(self) -> Chart:
+        """The |Chart| object containing the chart in this graphic frame.
+
+        Raises |ValueError| if this graphic frame does not contain a chart.
+        """
+        if not self.has_chart:
+            raise ValueError("shape does not contain a chart")
+        chart = self.chart_part.chart
+        # Cache the parent shape ref on the chart so callers can reach
+        # back to the GraphicFrame without keeping the ``add_chart``
+        # return value around.  ``Chart.shape`` reads this attribute.
+        chart._parent_shape = self  # type: ignore[attr-defined]
+        return chart
+
+    @property
+    def chart_part(self) -> ChartPart:
+        """The |ChartPart| object containing the chart in this graphic frame."""
+        chart_rId = self._graphicFrame.chart_rId
+        if chart_rId is None:
+            raise ValueError("this graphic frame does not contain a chart")
+        return cast("ChartPart", self.part.related_part(chart_rId))
+
+    @property
+    def has_chart(self) -> bool:
+        """|True| if this graphic frame contains a chart object. |False| otherwise.
+
+        When |True|, the chart object can be accessed using the `.chart` property.
+        """
+        return self._graphicFrame.graphicData_uri == GRAPHIC_DATA_URI_CHART
+
+    @property
+    def has_table(self) -> bool:
+        """|True| if this graphic frame contains a table object, |False| otherwise.
+
+        When |True|, the table object can be accessed using the `.table` property.
+        """
+        return self._graphicFrame.graphicData_uri == GRAPHIC_DATA_URI_TABLE
+
+    @property
+    def ole_format(self) -> _OleFormat:
+        """_OleFormat object for this graphic-frame shape.
+
+        Raises `ValueError` on a GraphicFrame instance that does not contain an OLE object.
+
+        An shape that contains an OLE object will have `.shape_type` of either
+        `EMBEDDED_OLE_OBJECT` or `LINKED_OLE_OBJECT`.
+        """
+        if not self._graphicFrame.has_oleobj:
+            raise ValueError("not an OLE-object shape")
+        return _OleFormat(self._graphicFrame.graphicData, self._parent)
+
+    @lazyproperty
+    def blur(self) -> BlurFormat:
+        """Unconditionally raises |NotImplementedError|.
+
+        Gaussian blur access for graphic-frame objects is content-specific
+        (i.e. different for charts, tables, etc.) and has not yet been
+        implemented.
+        """
+        raise NotImplementedError("blur property on GraphicFrame not yet supported")
+
+    @lazyproperty
+    def glow(self) -> GlowFormat:
+        """Unconditionally raises |NotImplementedError|.
+
+        Glow effect access for graphic-frame objects is not yet implemented.
+        """
+        raise NotImplementedError("glow property on GraphicFrame not yet supported")
+
+    @lazyproperty
+    def reflection(self) -> ReflectionFormat:
+        """Unconditionally raises |NotImplementedError|.
+
+        Reflection effect access for graphic-frame objects is not yet
+        implemented.
+        """
+        raise NotImplementedError("reflection property on GraphicFrame not yet supported")
+
+    @lazyproperty
+    def shadow(self) -> ShadowFormat | None:
+        """Returns ``None``: shadow access on a |GraphicFrame| is unsupported.
+
+        Charts and tables expose their effect tree at content-specific
+        locations (e.g. ``c:spPr/a:effectLst`` on a chart) and the unified
+        :class:`~pptx2.dml.effect.ShadowFormat` facade doesn't apply.
+        Returning ``None`` keeps callers that probe ``shape.shadow`` across
+        every shape on a slide free from per-type ``try/except`` guards;
+        ``if shape.shadow is None`` is the supported "no facade available"
+        check.
+        """
+        return None
+
+    @lazyproperty
+    def inner_shadow(self) -> InnerShadowFormat | None:
+        """Returns ``None``: inner-shadow access on a |GraphicFrame| is unsupported.
+
+        A graphic frame has no ``spPr``, so (like :attr:`shadow`) the unified
+        effect facade doesn't apply; ``None`` lets callers probe every shape
+        without a per-type ``try/except``.
+        """
+        return None
+
+    @lazyproperty
+    def preset_shadow(self) -> PresetShadowFormat | None:
+        """Returns ``None``: preset-shadow access on a |GraphicFrame| is unsupported."""
+        return None
+
+    @lazyproperty
+    def soft_edges(self) -> SoftEdgeFormat:
+        """Unconditionally raises |NotImplementedError|.
+
+        Soft-edge effect access for graphic-frame objects is not yet implemented.
+        """
+        raise NotImplementedError("soft_edges property on GraphicFrame not yet supported")
+
+    @property
+    def three_d(self):
+        """Unconditionally raises |NotImplementedError|.
+
+        A graphic frame has no ``p:spPr``, so the |ThreeDFormat| facade does
+        not apply (mirrors :attr:`blur` / :attr:`glow` behaviour).
+        """
+        raise NotImplementedError("three_d property on GraphicFrame not yet supported")
+
+    @property
+    def shape_type(self) -> MSO_SHAPE_TYPE:
+        """Optional member of `MSO_SHAPE_TYPE` identifying the type of this shape.
+
+        Possible values are `MSO_SHAPE_TYPE.CHART`, `MSO_SHAPE_TYPE.TABLE`,
+        `MSO_SHAPE_TYPE.EMBEDDED_OLE_OBJECT`, `MSO_SHAPE_TYPE.LINKED_OLE_OBJECT`.
+
+        This value is `None` when none of these four types apply, for example when the shape
+        contains SmartArt.
+        """
+        graphicData_uri = self._graphicFrame.graphicData_uri
+        if graphicData_uri == GRAPHIC_DATA_URI_CHART:
+            return MSO_SHAPE_TYPE.CHART
+        elif graphicData_uri == GRAPHIC_DATA_URI_TABLE:
+            return MSO_SHAPE_TYPE.TABLE
+        elif graphicData_uri == GRAPHIC_DATA_URI_OLEOBJ:
+            return (
+                MSO_SHAPE_TYPE.EMBEDDED_OLE_OBJECT
+                if self._graphicFrame.is_embedded_ole_obj
+                else MSO_SHAPE_TYPE.LINKED_OLE_OBJECT
+            )
+        else:
+            return None  # pyright: ignore[reportReturnType]
+
+    @property
+    def table(self) -> Table:
+        """The |Table| object contained in this graphic frame.
+
+        Raises |ValueError| if this graphic frame does not contain a table.
+        """
+        if not self.has_table:
+            raise ValueError("shape does not contain a table")
+        tbl = self._graphicFrame.graphic.graphicData.tbl
+        return Table(tbl, self)
+
+    def render_to_png(self, **kwargs):
+        """Render this graphic frame's region to a PNG.
+
+        Renders the parent slide via headless LibreOffice (the same path
+        used by :meth:`Slide.render_thumbnail`), then crops the result to
+        this frame's bounding box.  Useful for getting a standalone
+        chart / table image out of a deck.
+
+        Forwards keyword arguments (``out_path``, ``soffice_bin``,
+        ``timeout``) to :meth:`Slide.render_thumbnail`.  ``return_bytes``
+        is also supported and returns the cropped PNG bytes directly.
+
+        Requires :pypi:`Pillow` for cropping (already a python-pptx2
+        dependency) and ``soffice`` on PATH.
+        """
+        from io import BytesIO
+
+        try:
+            from PIL import Image
+        except ImportError as e:  # pragma: no cover - Pillow is a dep
+            raise RuntimeError(
+                "render_to_png requires Pillow; install python-pptx2[render]"
+            ) from e
+
+        return_bytes = kwargs.pop("return_bytes", False)
+        out_path = kwargs.pop("out_path", None)
+
+        slide = self.part.slide
+        png_bytes = slide.render_thumbnail(return_bytes=True, **kwargs)
+
+        with Image.open(BytesIO(png_bytes)) as img:
+            # Compute pixel bounds of this graphic frame from the EMU-vs-pixel
+            # scale of the rendered slide.
+            prs = self.part.package.presentation_part.presentation
+            slide_w_emu = int(prs.slide_width or 9144000)
+            slide_h_emu = int(prs.slide_height or 6858000)
+            scale_x = img.width / slide_w_emu
+            scale_y = img.height / slide_h_emu
+            left = int(int(self.left) * scale_x)
+            top = int(int(self.top) * scale_y)
+            right = int((int(self.left) + int(self.width)) * scale_x)
+            bottom = int((int(self.top) + int(self.height)) * scale_y)
+            cropped = img.crop((left, top, right, bottom))
+            buf = BytesIO()
+            cropped.save(buf, format="PNG")
+            data = buf.getvalue()
+
+        if return_bytes:
+            return data
+        if out_path is not None:
+            from pathlib import Path
+
+            target = Path(out_path)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(data)
+            return target
+        # No destination given: persist to a stable temp file.
+        import os
+        import tempfile
+        from pathlib import Path
+
+        fd, persistent = tempfile.mkstemp(prefix="pptx-frame-", suffix=".png")
+        os.close(fd)
+        try:
+            Path(persistent).write_bytes(data)
+        except Exception:
+            # Don't leak the empty temp file when the write fails.
+            try:
+                os.remove(persistent)
+            except OSError:
+                pass
+            raise
+        return Path(persistent)
+
+
+class _OleFormat(ParentedElementProxy):
+    """Provides attributes on an embedded OLE object."""
+
+    part: BaseSlidePart  # pyright: ignore[reportIncompatibleMethodOverride]
+
+    def __init__(self, graphicData: CT_GraphicalObjectData, parent: ProvidesPart):
+        super().__init__(graphicData, parent)
+        self._graphicData = graphicData
+
+    @property
+    def blob(self) -> bytes | None:
+        """Optional bytes of OLE object, suitable for loading or saving as a file.
+
+        This value is `None` if the embedded object does not represent a "file".
+        """
+        blob_rId = self._graphicData.blob_rId
+        if blob_rId is None:
+            return None
+        return self.part.related_part(blob_rId).blob
+
+    @property
+    def prog_id(self) -> str | None:
+        """str "progId" attribute of this embedded OLE object.
+
+        The progId is a str like "Excel.Sheet.12" that identifies the "file-type" of the embedded
+        object, or perhaps more precisely, the application (aka. "server" in OLE parlance) to be
+        used to open this object.
+        """
+        return self._graphicData.progId
+
+    @property
+    def show_as_icon(self) -> bool | None:
+        """True when OLE object should appear as an icon (rather than preview)."""
+        return self._graphicData.showAsIcon

pptx2/shapes/group.py

@@ -0,0 +1,264 @@
+"""GroupShape and related objects."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterator
+
+from pptx2.dml.effect import (
+    BlurFormat,
+    GlowFormat,
+    InnerShadowFormat,
+    PresetShadowFormat,
+    ReflectionFormat,
+    ShadowFormat,
+    SoftEdgeFormat,
+)
+from pptx2.dml.fill import FillFormat
+from pptx2.enum.shapes import MSO_SHAPE_TYPE
+from pptx2.shapes.base import BaseShape
+from pptx2.util import Emu, _coerce_emu, lazyproperty
+
+if TYPE_CHECKING:
+    from pptx2.action import ActionSetting
+    from pptx2.oxml.shapes import ShapeElement
+    from pptx2.oxml.shapes.groupshape import CT_GroupShape
+    from pptx2.shapes.shapetree import GroupShapes
+    from pptx2.types import ProvidesPart
+    from pptx2.util import Length
+
+
+class GroupShape(BaseShape):
+    """A shape that acts as a container for other shapes."""
+
+    def __init__(self, grpSp: CT_GroupShape, parent: ProvidesPart):
+        super().__init__(grpSp, parent)
+        self._grpSp = grpSp
+
+    @lazyproperty
+    def click_action(self) -> ActionSetting:
+        """Unconditionally raises `TypeError`.
+
+        A group shape cannot have a click action or hover action.
+        """
+        raise TypeError("a group shape cannot have a click action")
+
+    @property
+    def has_text_frame(self) -> bool:
+        """Unconditionally |False|.
+
+        A group shape does not have a textframe and cannot itself contain text. This does not
+        impact the ability of shapes contained by the group to each have their own text.
+        """
+        return False
+
+    @lazyproperty
+    def blur(self) -> BlurFormat:
+        """|BlurFormat| object representing the Gaussian blur on this group."""
+        return BlurFormat(self._grpSp.grpSpPr)
+
+    @lazyproperty
+    def glow(self) -> GlowFormat:
+        """|GlowFormat| object representing glow effect for this group."""
+        return GlowFormat(self._grpSp.grpSpPr)
+
+    @lazyproperty
+    def reflection(self) -> ReflectionFormat:
+        """|ReflectionFormat| object representing the reflection on this group."""
+        return ReflectionFormat(self._grpSp.grpSpPr)
+
+    @lazyproperty
+    def shadow(self) -> ShadowFormat:
+        """|ShadowFormat| object representing shadow effect for this group.
+
+        A |ShadowFormat| object is always returned, even when no shadow is explicitly defined on
+        this group shape (i.e. when the group inherits its shadow behavior).
+        """
+        return ShadowFormat(self._grpSp.grpSpPr)
+
+    @lazyproperty
+    def soft_edges(self) -> SoftEdgeFormat:
+        """|SoftEdgeFormat| object representing soft-edge effect for this group."""
+        return SoftEdgeFormat(self._grpSp.grpSpPr)
+
+    @lazyproperty
+    def inner_shadow(self) -> InnerShadowFormat:
+        """|InnerShadowFormat| for this group (over ``p:grpSpPr``).
+
+        Overrides the |BaseShape| version, which targets ``spPr`` — a group
+        exposes ``grpSpPr`` instead, so the inherited accessor would raise.
+        """
+        return InnerShadowFormat(self._grpSp.grpSpPr)
+
+    @lazyproperty
+    def preset_shadow(self) -> PresetShadowFormat:
+        """|PresetShadowFormat| for this group (over ``p:grpSpPr``)."""
+        return PresetShadowFormat(self._grpSp.grpSpPr)
+
+    @property
+    def three_d(self):
+        """Unconditionally raises |NotImplementedError|.
+
+        A group shape's ``p:grpSpPr`` legally carries ``a:scene3d`` but not
+        ``a:sp3d`` (bevel / extrusion), so the |ThreeDFormat| facade — which
+        writes both — cannot target it without emitting schema-invalid XML.
+        Apply 3-D formatting to the member shapes instead.
+        """
+        raise NotImplementedError("three_d property on GroupShape not supported")
+
+    @property
+    def fill(self) -> FillFormat:
+        """|FillFormat| instance for this group, providing access to fill properties.
+
+        A group's ``p:grpSpPr`` admits a fill (but, unlike a regular shape, *not* a
+        line — the OOXML schema does not allow ``a:ln`` on a group). Setting a fill
+        tints the whole group; member shapes that declare their own fill are
+        unaffected and paint on top. Use ``fill.solid()``, ``fill.gradient()``,
+        ``fill.background()`` (transparent), etc., exactly as on an autoshape::
+
+            group.fill.solid()
+            group.fill.fore_color.rgb = "1F4E79"
+        """
+        return FillFormat.from_fill_parent(self._grpSp.grpSpPr)
+
+    @property
+    def shape_type(self) -> MSO_SHAPE_TYPE:
+        """Member of :ref:`MsoShapeType` identifying the type of this shape.
+
+        Unconditionally `MSO_SHAPE_TYPE.GROUP` in this case
+        """
+        return MSO_SHAPE_TYPE.GROUP
+
+    @lazyproperty
+    def shapes(self) -> GroupShapes:
+        """|GroupShapes| object for this group.
+
+        The |GroupShapes| object provides access to the group's member shapes and provides methods
+        for adding new ones.
+        """
+        from pptx2.shapes.shapetree import GroupShapes
+
+        return GroupShapes(self._element, self)
+
+    def move(self, dx: Length | int | float, dy: Length | int | float) -> GroupShape:
+        """Translate the entire group by (*dx*, *dy*) and return self.
+
+        *dx* and *dy* are lengths (e.g. ``Inches(1)``, ``Emu(...)``, or a bare
+        EMU ``int``)::
+
+            group.move(Inches(0.5), Inches(-0.25))
+
+        The group's offset, its child-coordinate origin, and every member are
+        shifted by the same translation. Shifting the members + ``chOff`` (not
+        just the group's own ``off``) is what makes the move *durable*: a later
+        ``recalculate_extents()`` — triggered by ``group.shapes.add_*`` or
+        ``fit_to_children()`` — recomputes ``off`` from the member geometry, so
+        a move that only touched ``off`` would silently snap back.
+        """
+        grpSp = self._grpSp
+        edx = int(_coerce_emu(dx))
+        edy = int(_coerce_emu(dy))
+        # Express the translation in the group's child-coordinate space too, in
+        # case the group is scaled (ext != chExt); for the common unscaled
+        # group this is just (edx, edy).
+        ext_cx = int(self.width) if self.width is not None else 0
+        ext_cy = int(self.height) if self.height is not None else 0
+        chExt = grpSp.chExt
+        ch_cx, ch_cy = int(chExt.cx or 0), int(chExt.cy or 0)
+        cdx = round(edx * ch_cx / ext_cx) if ext_cx else edx
+        cdy = round(edy * ch_cy / ext_cy) if ext_cy else edy
+
+        self.left = Emu((int(self.left) if self.left is not None else 0) + edx)
+        self.top = Emu((int(self.top) if self.top is not None else 0) + edy)
+        chOff = grpSp.chOff
+        chOff.x = Emu(int(chOff.x or 0) + cdx)
+        chOff.y = Emu(int(chOff.y or 0) + cdy)
+        for elm in grpSp.iter_shape_elms():
+            elm.x = Emu(int(elm.x or 0) + cdx)
+            elm.y = Emu(int(elm.y or 0) + cdy)
+        return self
+
+    def walk(self) -> Iterator[BaseShape]:
+        """Generate every descendant shape, recursing into nested groups.
+
+        Yields shapes depth-first in document (z-order) order. Nested
+        |GroupShape| objects are themselves yielded *before* their children, so
+        callers that only want leaf shapes can filter with
+        ``s.shape_type != MSO_SHAPE_TYPE.GROUP``. This makes whole-tree layout,
+        measurement, and lint passes possible without hand-rolled recursion::
+
+            for shape in group.walk():
+                ...
+        """
+        for shape in self.shapes:
+            yield shape
+            if isinstance(shape, GroupShape):
+                yield from shape.walk()
+
+    def fit_to_children(self) -> GroupShape:
+        """Shrink-wrap the group's offset/extent to tightly bound its children.
+
+        Recalculates the group's position and size (``a:off`` / ``a:ext``) from
+        the current geometry of its member shapes — the same recalculation that
+        runs automatically when a shape is added through ``group.shapes.add_*``.
+        Call it after moving or resizing member shapes directly so the group's
+        ``bbox`` (and any lint that relies on it) stays accurate. Returns self.
+        """
+        self._grpSp.recalculate_extents()
+        return self
+
+    def ungroup(self) -> list[BaseShape]:
+        """Dissolve the group, promoting its member shapes to the parent and return them.
+
+        Each child is re-parented to the group's container (the slide shape tree
+        or an enclosing group) with its position and size transformed from the
+        group's child coordinate space into the container's space, so shapes do
+        not move or resize visually. Z-order is preserved: the promoted shapes
+        occupy the group's former slot. The (now empty) group element is removed.
+
+        Raises ``ValueError`` if the group is rotated or flipped — baking such a
+        transform into each child is ambiguous and unsupported; reset rotation
+        and flip to zero before ungrouping.
+        """
+        grpSp = self._grpSp
+        container = grpSp.getparent()
+        if container is None:
+            raise ValueError("cannot ungroup a group that is not in a shape tree")
+        if self.rotation or grpSp.flipH or grpSp.flipV:
+            raise ValueError(
+                "ungroup() does not support a rotated or flipped group; reset "
+                "rotation and flip to 0 before ungrouping"
+            )
+
+        # Group offset/extent (in the container's coordinate space) and the
+        # group's own child coordinate space (chOff/chExt).
+        off_x = int(self.left) if self.left is not None else 0
+        off_y = int(self.top) if self.top is not None else 0
+        ext_cx = int(self.width) if self.width is not None else 0
+        ext_cy = int(self.height) if self.height is not None else 0
+        chOff, chExt = grpSp.chOff, grpSp.chExt
+        ch_x, ch_y = int(chOff.x or 0), int(chOff.y or 0)
+        ch_cx, ch_cy = int(chExt.cx or 0), int(chExt.cy or 0)
+        sx = (ext_cx / ch_cx) if ch_cx else 1.0
+        sy = (ext_cy / ch_cy) if ch_cy else 1.0
+
+        # Pre-compute each child's container-space geometry from its child-space
+        # coords before re-parenting (so the read isn't affected by the moves).
+        placements: list[tuple[ShapeElement, int, int, int, int]] = []
+        for elm in grpSp.iter_shape_elms():
+            cx0 = int(elm.x or 0)
+            cy0 = int(elm.y or 0)
+            cw = int(elm.cx or 0)
+            chgt = int(elm.cy or 0)
+            new_x = off_x + round((cx0 - ch_x) * sx)
+            new_y = off_y + round((cy0 - ch_y) * sy)
+            placements.append((elm, new_x, new_y, round(cw * sx), round(chgt * sy)))
+
+        promoted: list[BaseShape] = []
+        for elm, nx, ny, nw, nh in placements:
+            grpSp.remove(elm)
+            container.insert(container.index(grpSp), elm)
+            elm.x, elm.y, elm.cx, elm.cy = Emu(nx), Emu(ny), Emu(nw), Emu(nh)
+            promoted.append(self._parent._shape_factory(elm))  # pyright: ignore[reportAttributeAccessIssue]
+
+        container.remove(grpSp)
+        return promoted