ps-python-pptx 1.1.0__py3-none-any.whl

pptx/shapes/graphfrm.py

@@ -0,0 +1,166 @@
+"""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 pptx.enum.shapes import MSO_SHAPE_TYPE
+from pptx.shapes.base import BaseShape
+from pptx.shared import ParentedElementProxy
+from pptx.spec import (
+    GRAPHIC_DATA_URI_CHART,
+    GRAPHIC_DATA_URI_OLEOBJ,
+    GRAPHIC_DATA_URI_TABLE,
+)
+from pptx.table import Table
+from pptx.util import lazyproperty
+
+if TYPE_CHECKING:
+    from pptx.chart.chart import Chart
+    from pptx.dml.effect import ShadowFormat
+    from pptx.oxml.shapes.graphfrm import CT_GraphicalObjectData, CT_GraphicalObjectFrame
+    from pptx.parts.chart import ChartPart
+    from pptx.parts.slide import BaseSlidePart
+    from pptx.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")
+        return self.chart_part.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 shadow(self) -> ShadowFormat:
+        """Unconditionally raises |NotImplementedError|.
+
+        Access to the shadow effect for graphic-frame objects is content-specific (i.e. different
+        for charts, tables, etc.) and has not yet been implemented.
+        """
+        raise NotImplementedError("shadow 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)
+
+
+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

pptx/shapes/group.py

@@ -0,0 +1,69 @@
+"""GroupShape and related objects."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pptx.dml.effect import ShadowFormat
+from pptx.enum.shapes import MSO_SHAPE_TYPE
+from pptx.shapes.base import BaseShape
+from pptx.util import lazyproperty
+
+if TYPE_CHECKING:
+    from pptx.action import ActionSetting
+    from pptx.oxml.shapes.groupshape import CT_GroupShape
+    from pptx.shapes.shapetree import GroupShapes
+    from pptx.types import ProvidesPart
+
+
+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 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)
+
+    @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 pptx.shapes.shapetree import GroupShapes
+
+        return GroupShapes(self._element, self)

pptx/shapes/picture.py

@@ -0,0 +1,203 @@
+"""Shapes based on the `p:pic` element, including Picture and Movie."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pptx.dml.line import LineFormat
+from pptx.enum.shapes import MSO_SHAPE, MSO_SHAPE_TYPE, PP_MEDIA_TYPE
+from pptx.shapes.base import BaseShape
+from pptx.shared import ParentedElementProxy
+from pptx.util import lazyproperty
+
+if TYPE_CHECKING:
+    from pptx.oxml.shapes.picture import CT_Picture
+    from pptx.oxml.shapes.shared import CT_LineProperties
+    from pptx.types import ProvidesPart
+
+
+class _BasePicture(BaseShape):
+    """Base class for shapes based on a `p:pic` element."""
+
+    def __init__(self, pic: CT_Picture, parent: ProvidesPart):
+        super(_BasePicture, self).__init__(pic, parent)
+        self._pic = pic
+
+    @property
+    def crop_bottom(self) -> float:
+        """|float| representing relative portion cropped from shape bottom.
+
+        Read/write. 1.0 represents 100%. For example, 25% is represented by 0.25. Negative values
+        are valid as are values greater than 1.0.
+        """
+        return self._pic.srcRect_b
+
+    @crop_bottom.setter
+    def crop_bottom(self, value: float):
+        self._pic.srcRect_b = value
+
+    @property
+    def crop_left(self) -> float:
+        """|float| representing relative portion cropped from left of shape.
+
+        Read/write. 1.0 represents 100%. A negative value extends the side beyond the image
+        boundary.
+        """
+        return self._pic.srcRect_l
+
+    @crop_left.setter
+    def crop_left(self, value: float):
+        self._pic.srcRect_l = value
+
+    @property
+    def crop_right(self) -> float:
+        """|float| representing relative portion cropped from right of shape.
+
+        Read/write. 1.0 represents 100%.
+        """
+        return self._pic.srcRect_r
+
+    @crop_right.setter
+    def crop_right(self, value: float):
+        self._pic.srcRect_r = value
+
+    @property
+    def crop_top(self) -> float:
+        """|float| representing relative portion cropped from shape top.
+
+        Read/write. 1.0 represents 100%.
+        """
+        return self._pic.srcRect_t
+
+    @crop_top.setter
+    def crop_top(self, value: float):
+        self._pic.srcRect_t = value
+
+    def get_or_add_ln(self):
+        """Return the `a:ln` element for this `p:pic`-based image.
+
+        The `a:ln` element contains the line format properties XML.
+        """
+        return self._pic.get_or_add_ln()
+
+    @lazyproperty
+    def line(self) -> LineFormat:
+        """Provides access to properties of the picture outline, such as its color and width."""
+        return LineFormat(self)
+
+    @property
+    def ln(self) -> CT_LineProperties | None:
+        """The `a:ln` element for this `p:pic`.
+
+        Contains the line format properties such as line color and width. |None| if no `a:ln`
+        element is present.
+        """
+        return self._pic.ln
+
+
+class Movie(_BasePicture):
+    """A movie shape, one that places a video on a slide.
+
+    Like |Picture|, a movie shape is based on the `p:pic` element. A movie is composed of a video
+    and a *poster frame*, the placeholder image that represents the video before it is played.
+    """
+
+    @lazyproperty
+    def media_format(self) -> _MediaFormat:
+        """The |_MediaFormat| object for this movie.
+
+        The |_MediaFormat| object provides access to formatting properties for the movie.
+        """
+        return _MediaFormat(self._pic, self)
+
+    @property
+    def media_type(self) -> PP_MEDIA_TYPE:
+        """Member of :ref:`PpMediaType` describing this shape.
+
+        The return value is unconditionally `PP_MEDIA_TYPE.MOVIE` in this case.
+        """
+        return PP_MEDIA_TYPE.MOVIE
+
+    @property
+    def poster_frame(self):
+        """Return |Image| object containing poster frame for this movie.
+
+        Returns |None| if this movie has no poster frame (uncommon).
+        """
+        slide_part, rId = self.part, self._pic.blip_rId
+        if rId is None:
+            return None
+        return slide_part.get_image(rId)
+
+    @property
+    def shape_type(self) -> MSO_SHAPE_TYPE:
+        """Return member of :ref:`MsoShapeType` describing this shape.
+
+        The return value is unconditionally `MSO_SHAPE_TYPE.MEDIA` in this
+        case.
+        """
+        return MSO_SHAPE_TYPE.MEDIA
+
+
+class Picture(_BasePicture):
+    """A picture shape, one that places an image on a slide.
+
+    Based on the `p:pic` element.
+    """
+
+    @property
+    def auto_shape_type(self) -> MSO_SHAPE | None:
+        """Member of MSO_SHAPE indicating masking shape.
+
+        A picture can be masked by any of the so-called "auto-shapes" available in PowerPoint,
+        such as an ellipse or triangle. When a picture is masked by a shape, the shape assumes the
+        same dimensions as the picture and the portion of the picture outside the shape boundaries
+        does not appear. Note the default value for a newly-inserted picture is
+        `MSO_AUTO_SHAPE_TYPE.RECTANGLE`, which performs no cropping because the extents of the
+        rectangle exactly correspond to the extents of the picture.
+
+        The available shapes correspond to the members of :ref:`MsoAutoShapeType`.
+
+        The return value can also be |None|, indicating the picture either has no geometry (not
+        expected) or has custom geometry, like a freeform shape. A picture with no geometry will
+        have no visible representation on the slide, although it can be selected. This is because
+        without geometry, there is no "inside-the-shape" for it to appear in.
+        """
+        prstGeom = self._pic.spPr.prstGeom
+        if prstGeom is None:  # ---generally means cropped with freeform---
+            return None
+        return prstGeom.prst
+
+    @auto_shape_type.setter
+    def auto_shape_type(self, member: MSO_SHAPE):
+        MSO_SHAPE.validate(member)
+        spPr = self._pic.spPr
+        prstGeom = spPr.prstGeom
+        if prstGeom is None:
+            spPr._remove_custGeom()  # pyright: ignore[reportPrivateUsage]
+            prstGeom = spPr._add_prstGeom()  # pyright: ignore[reportPrivateUsage]
+        prstGeom.prst = member
+
+    @property
+    def image(self):
+        """The |Image| object for this picture.
+
+        Provides access to the properties and bytes of the image in this picture shape.
+        """
+        slide_part, rId = self.part, self._pic.blip_rId
+        if rId is None:
+            raise ValueError("no embedded image")
+        return slide_part.get_image(rId)
+
+    @property
+    def shape_type(self) -> MSO_SHAPE_TYPE:
+        """Unconditionally `MSO_SHAPE_TYPE.PICTURE` in this case."""
+        return MSO_SHAPE_TYPE.PICTURE
+
+
+class _MediaFormat(ParentedElementProxy):
+    """Provides access to formatting properties for a Media object.
+
+    Media format properties are things like start point, volume, and
+    compression type.
+    """