python-pptx2 2.13.0__py3-none-any.whl

pptx2/oxml/shapes/graphfrm.py

@@ -0,0 +1,347 @@
+"""lxml custom element class for CT_GraphicalObjectFrame XML element."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from pptx2.oxml import parse_xml
+from pptx2.oxml.chart.chart import CT_Chart
+from pptx2.oxml.ns import nsdecls
+from pptx2.oxml.shapes.shared import BaseShapeElement
+from pptx2.oxml.simpletypes import XsdBoolean, XsdString
+from pptx2.oxml.table import CT_Table
+from pptx2.oxml.xmlchemy import (
+    BaseOxmlElement,
+    OneAndOnlyOne,
+    OptionalAttribute,
+    RequiredAttribute,
+    ZeroOrOne,
+)
+from pptx2.spec import (
+    GRAPHIC_DATA_URI_CHART,
+    GRAPHIC_DATA_URI_OLEOBJ,
+    GRAPHIC_DATA_URI_TABLE,
+)
+
+if TYPE_CHECKING:
+    from pptx2.oxml.shapes.shared import (
+        CT_ApplicationNonVisualDrawingProps,
+        CT_NonVisualDrawingProps,
+        CT_Transform2D,
+    )
+
+
+class CT_GraphicalObject(BaseOxmlElement):
+    """`a:graphic` element.
+
+    The container for the reference to or definition of the framed graphical object (table, chart,
+    etc.).
+    """
+
+    graphicData: CT_GraphicalObjectData = OneAndOnlyOne(  # pyright: ignore[reportAssignmentType]
+        "a:graphicData"
+    )
+
+    @property
+    def chart(self) -> CT_Chart | None:
+        """The `c:chart` grandchild element, or |None| if not present."""
+        return self.graphicData.chart
+
+
+class CT_GraphicalObjectData(BaseShapeElement):
+    """`p:graphicData` element.
+
+    The direct container for a table, a chart, or another graphical object.
+    """
+
+    chart: CT_Chart | None = ZeroOrOne("c:chart")  # pyright: ignore[reportAssignmentType]
+    tbl: CT_Table | None = ZeroOrOne("a:tbl")  # pyright: ignore[reportAssignmentType]
+    uri: str = RequiredAttribute("uri", XsdString)  # pyright: ignore[reportAssignmentType]
+
+    @property
+    def blob_rId(self) -> str | None:
+        """Optional `r:id` attribute value of `p:oleObj` descendent element.
+
+        This value is `None` when this `p:graphicData` element does not enclose an OLE object.
+        This value could also be `None` if an enclosed OLE object does not specify this attribute
+        (it is specified optional in the schema) but so far, all OLE objects we've encountered
+        specify this value.
+        """
+        return None if self._oleObj is None else self._oleObj.rId
+
+    @property
+    def is_embedded_ole_obj(self) -> bool | None:
+        """Optional boolean indicating an embedded OLE object.
+
+        Returns `None` when this `p:graphicData` element does not enclose an OLE object. `True`
+        indicates an embedded OLE object and `False` indicates a linked OLE object.
+        """
+        return None if self._oleObj is None else self._oleObj.is_embedded
+
+    @property
+    def progId(self) -> str | None:
+        """Optional str value of "progId" attribute of `p:oleObj` descendent.
+
+        This value identifies the "type" of the embedded object in terms of the application used
+        to open it.
+
+        This value is `None` when this `p:graphicData` element does not enclose an OLE object.
+        This could also be `None` if an enclosed OLE object does not specify this attribute (it is
+        specified optional in the schema) but so far, all OLE objects we've encountered specify
+        this value.
+        """
+        return None if self._oleObj is None else self._oleObj.progId
+
+    @property
+    def showAsIcon(self) -> bool | None:
+        """Optional value of "showAsIcon" attribute value of `p:oleObj` descendent.
+
+        This value is `None` when this `p:graphicData` element does not enclose an OLE object. It
+        is False when the `showAsIcon` attribute is omitted on the `p:oleObj` element.
+        """
+        return None if self._oleObj is None else self._oleObj.showAsIcon
+
+    @property
+    def _oleObj(self) -> CT_OleObject | None:
+        """Optional `p:oleObj` element contained in this `p:graphicData' element.
+
+        Returns `None` when this graphic-data element does not enclose an OLE object. Note that
+        this returns the last `p:oleObj` element found. There can be more than one `p:oleObj`
+        element because an `mc.AlternateContent` element may appear as the child of
+        `p:graphicData` and that alternate-content subtree can contain multiple compatibility
+        choices. The last one should suit best for reading purposes because it contains the lowest
+        common denominator.
+        """
+        oleObjs = cast("list[CT_OleObject]", self.xpath(".//p:oleObj"))
+        return oleObjs[-1] if oleObjs else None
+
+
+class CT_GraphicalObjectFrame(BaseShapeElement):
+    """`p:graphicFrame` element.
+
+    A container for a table, a chart, or another graphical object.
+    """
+
+    nvGraphicFramePr: CT_GraphicalObjectFrameNonVisual = (  # pyright: ignore[reportAssignmentType]
+        OneAndOnlyOne("p:nvGraphicFramePr")
+    )
+    xfrm: CT_Transform2D = OneAndOnlyOne("p:xfrm")  # pyright: ignore
+    graphic: CT_GraphicalObject = OneAndOnlyOne(  # pyright: ignore[reportAssignmentType]
+        "a:graphic"
+    )
+
+    @property
+    def chart(self) -> CT_Chart | None:
+        """The `c:chart` great-grandchild element, or |None| if not present."""
+        return self.graphic.chart
+
+    @property
+    def chart_rId(self) -> str | None:
+        """The `rId` attribute of the `c:chart` great-grandchild element.
+
+        |None| if not present.
+        """
+        chart = self.chart
+        if chart is None:
+            return None
+        return chart.rId
+
+    def get_or_add_xfrm(self) -> CT_Transform2D:
+        """Return the required `p:xfrm` child element.
+
+        Overrides version on BaseShapeElement.
+        """
+        return self.xfrm
+
+    @property
+    def graphicData(self) -> CT_GraphicalObjectData:
+        """`a:graphicData` grandchild of this graphic-frame element."""
+        return self.graphic.graphicData
+
+    @property
+    def graphicData_uri(self) -> str:
+        """str value of `uri` attribute of `a:graphicData` grandchild."""
+        return self.graphic.graphicData.uri
+
+    @property
+    def has_oleobj(self) -> bool:
+        """`True` for graphicFrame containing an OLE object, `False` otherwise."""
+        return self.graphicData.uri == GRAPHIC_DATA_URI_OLEOBJ
+
+    @property
+    def is_embedded_ole_obj(self) -> bool | None:
+        """Optional boolean indicating an embedded OLE object.
+
+        Returns `None` when this `p:graphicFrame` element does not enclose an OLE object. `True`
+        indicates an embedded OLE object and `False` indicates a linked OLE object.
+        """
+        return self.graphicData.is_embedded_ole_obj
+
+    @classmethod
+    def new_chart_graphicFrame(
+        cls, id_: int, name: str, rId: str, x: int, y: int, cx: int, cy: int
+    ) -> CT_GraphicalObjectFrame:
+        """Return a `p:graphicFrame` element tree populated with a chart element."""
+        graphicFrame = CT_GraphicalObjectFrame.new_graphicFrame(id_, name, x, y, cx, cy)
+        graphicData = graphicFrame.graphic.graphicData
+        graphicData.uri = GRAPHIC_DATA_URI_CHART
+        graphicData.append(CT_Chart.new_chart(rId))
+        return graphicFrame
+
+    @classmethod
+    def new_graphicFrame(
+        cls, id_: int, name: str, x: int, y: int, cx: int, cy: int
+    ) -> CT_GraphicalObjectFrame:
+        """Return a new `p:graphicFrame` element tree suitable for containing a table or chart.
+
+        Note that a graphicFrame element is not a valid shape until it contains a graphical object
+        such as a table.
+        """
+        return cast(
+            CT_GraphicalObjectFrame,
+            parse_xml(
+                f"<p:graphicFrame {nsdecls('a', 'p')}>\n"
+                f"  <p:nvGraphicFramePr>\n"
+                f'    <p:cNvPr id="{id_}" name="{name}"/>\n'
+                f"    <p:cNvGraphicFramePr>\n"
+                f'      <a:graphicFrameLocks noGrp="1"/>\n'
+                f"    </p:cNvGraphicFramePr>\n"
+                f"    <p:nvPr/>\n"
+                f"  </p:nvGraphicFramePr>\n"
+                f"  <p:xfrm>\n"
+                f'    <a:off x="{x}" y="{y}"/>\n'
+                f'    <a:ext cx="{cx}" cy="{cy}"/>\n'
+                f"  </p:xfrm>\n"
+                f"  <a:graphic>\n"
+                f"    <a:graphicData/>\n"
+                f"  </a:graphic>\n"
+                f"</p:graphicFrame>"
+            ),
+        )
+
+    @classmethod
+    def new_ole_object_graphicFrame(
+        cls,
+        id_: int,
+        name: str,
+        ole_object_rId: str,
+        progId: str,
+        icon_rId: str,
+        x: int,
+        y: int,
+        cx: int,
+        cy: int,
+        imgW: int,
+        imgH: int,
+        pic_id: int,
+    ) -> CT_GraphicalObjectFrame:
+        """Return newly-created `p:graphicFrame` for embedded OLE-object.
+
+        `ole_object_rId` identifies the relationship to the OLE-object part.
+
+        `progId` is a str identifying the object-type in terms of the application (program) used
+        to open it. This becomes an attribute of the same name in the `p:oleObj` element.
+
+        `icon_rId` identifies the relationship to an image part used to display the OLE-object as
+        an icon (vs. a preview).
+
+        `pic_id` is the shape id for the inner "show-as-icon" ``p:pic``. It must be unique within
+        the slide: two OLE objects sharing the hardcoded ``id="0"`` used previously collide on a
+        duplicate shape id, which PowerPoint reports as a file needing repair.
+        """
+        return cast(
+            CT_GraphicalObjectFrame,
+            parse_xml(
+                f"<p:graphicFrame {nsdecls('a', 'p', 'r')}>\n"
+                f"  <p:nvGraphicFramePr>\n"
+                f'    <p:cNvPr id="{id_}" name="{name}"/>\n'
+                f"    <p:cNvGraphicFramePr>\n"
+                f'      <a:graphicFrameLocks noGrp="1"/>\n'
+                f"    </p:cNvGraphicFramePr>\n"
+                f"    <p:nvPr/>\n"
+                f"  </p:nvGraphicFramePr>\n"
+                f"  <p:xfrm>\n"
+                f'    <a:off x="{x}" y="{y}"/>\n'
+                f'    <a:ext cx="{cx}" cy="{cy}"/>\n'
+                f"  </p:xfrm>\n"
+                f"  <a:graphic>\n"
+                f"    <a:graphicData"
+                f'        uri="http://schemas.openxmlformats.org/presentationml/2006/ole">\n'
+                f'      <p:oleObj showAsIcon="1"'
+                f'                r:id="{ole_object_rId}"'
+                f'                imgW="{imgW}"'
+                f'                imgH="{imgH}"'
+                f'                progId="{progId}">\n'
+                f"        <p:embed/>\n"
+                f"        <p:pic>\n"
+                f"          <p:nvPicPr>\n"
+                f'            <p:cNvPr id="{pic_id}" name=""/>\n'
+                f"            <p:cNvPicPr/>\n"
+                f"            <p:nvPr/>\n"
+                f"          </p:nvPicPr>\n"
+                f"          <p:blipFill>\n"
+                f'            <a:blip r:embed="{icon_rId}"/>\n'
+                f"            <a:stretch>\n"
+                f"              <a:fillRect/>\n"
+                f"            </a:stretch>\n"
+                f"          </p:blipFill>\n"
+                f"          <p:spPr>\n"
+                f"            <a:xfrm>\n"
+                f'              <a:off x="{x}" y="{y}"/>\n'
+                f'              <a:ext cx="{cx}" cy="{cy}"/>\n'
+                f"            </a:xfrm>\n"
+                f'            <a:prstGeom prst="rect">\n'
+                f"              <a:avLst/>\n"
+                f"            </a:prstGeom>\n"
+                f"          </p:spPr>\n"
+                f"        </p:pic>\n"
+                f"      </p:oleObj>\n"
+                f"    </a:graphicData>\n"
+                f"  </a:graphic>\n"
+                f"</p:graphicFrame>"
+            ),
+        )
+
+    @classmethod
+    def new_table_graphicFrame(
+        cls, id_: int, name: str, rows: int, cols: int, x: int, y: int, cx: int, cy: int
+    ) -> CT_GraphicalObjectFrame:
+        """Return a `p:graphicFrame` element tree populated with a table element."""
+        graphicFrame = cls.new_graphicFrame(id_, name, x, y, cx, cy)
+        graphicFrame.graphic.graphicData.uri = GRAPHIC_DATA_URI_TABLE
+        graphicFrame.graphic.graphicData.append(CT_Table.new_tbl(rows, cols, cx, cy))
+        return graphicFrame
+
+
+class CT_GraphicalObjectFrameNonVisual(BaseOxmlElement):
+    """`p:nvGraphicFramePr` element.
+
+    This contains the non-visual properties of a graphic frame, such as name, id, etc.
+    """
+
+    cNvPr: CT_NonVisualDrawingProps = OneAndOnlyOne(  # pyright: ignore[reportAssignmentType]
+        "p:cNvPr"
+    )
+    nvPr: CT_ApplicationNonVisualDrawingProps = (  # pyright: ignore[reportAssignmentType]
+        OneAndOnlyOne("p:nvPr")
+    )
+
+
+class CT_OleObject(BaseOxmlElement):
+    """`p:oleObj` element, container for an OLE object (e.g. Excel file).
+
+    An OLE object can be either linked or embedded (hence the name).
+    """
+
+    progId: str | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
+        "progId", XsdString
+    )
+    rId: str | None = OptionalAttribute("r:id", XsdString)  # pyright: ignore[reportAssignmentType]
+    showAsIcon: bool = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
+        "showAsIcon", XsdBoolean, default=False
+    )
+
+    @property
+    def is_embedded(self) -> bool:
+        """True when this OLE object is embedded, False when it is linked."""
+        return len(self.xpath("./p:embed")) > 0

pptx2/oxml/shapes/groupshape.py

@@ -0,0 +1,329 @@
+"""lxml custom element classes for shape-tree-related XML elements."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable, Iterator
+
+from pptx2.dml.fill import CT_GradientFillProperties
+from pptx2.enum.shapes import MSO_CONNECTOR_TYPE
+from pptx2.oxml import parse_xml
+from pptx2.oxml.ns import nsdecls, qn
+from pptx2.oxml.shapes.autoshape import CT_Shape
+from pptx2.oxml.shapes.connector import CT_Connector
+from pptx2.oxml.shapes.graphfrm import CT_GraphicalObjectFrame
+from pptx2.oxml.shapes.picture import CT_Picture
+from pptx2.oxml.shapes.shared import BaseShapeElement
+from pptx2.oxml.xmlchemy import (
+    BaseOxmlElement,
+    Choice,
+    OneAndOnlyOne,
+    ZeroOrOne,
+    ZeroOrOneChoice,
+)
+from pptx2.util import Emu
+
+if TYPE_CHECKING:
+    from pptx2.enum.shapes import PP_PLACEHOLDER
+    from pptx2.oxml.shapes import ShapeElement
+    from pptx2.oxml.shapes.shared import CT_Transform2D
+
+
+class CT_GroupShape(BaseShapeElement):
+    """Used for shape tree (`p:spTree`) as well as the group shape (`p:grpSp`) elements."""
+
+    nvGrpSpPr: CT_GroupShapeNonVisual = OneAndOnlyOne(  # pyright: ignore[reportAssignmentType]
+        "p:nvGrpSpPr"
+    )
+    grpSpPr: CT_GroupShapeProperties = OneAndOnlyOne(  # pyright: ignore[reportAssignmentType]
+        "p:grpSpPr"
+    )
+
+    _shape_tags = (
+        qn("p:sp"),
+        qn("p:grpSp"),
+        qn("p:graphicFrame"),
+        qn("p:cxnSp"),
+        qn("p:pic"),
+        qn("p:contentPart"),
+    )
+
+    def add_autoshape(
+        self, id_: int, name: str, prst: str, x: int, y: int, cx: int, cy: int
+    ) -> CT_Shape:
+        """Return new `p:sp` appended to the group/shapetree with specified attributes."""
+        sp = CT_Shape.new_autoshape_sp(id_, name, prst, x, y, cx, cy)
+        self.insert_element_before(sp, "p:extLst")
+        return sp
+
+    def add_cxnSp(
+        self,
+        id_: int,
+        name: str,
+        type_member: MSO_CONNECTOR_TYPE,
+        x: int,
+        y: int,
+        cx: int,
+        cy: int,
+        flipH: bool,
+        flipV: bool,
+    ) -> CT_Connector:
+        """Return new `p:cxnSp` appended to the group/shapetree with the specified attribues."""
+        prst = MSO_CONNECTOR_TYPE.to_xml(type_member)
+        cxnSp = CT_Connector.new_cxnSp(id_, name, prst, x, y, cx, cy, flipH, flipV)
+        self.insert_element_before(cxnSp, "p:extLst")
+        return cxnSp
+
+    def add_freeform_sp(self, x: int, y: int, cx: int, cy: int) -> CT_Shape:
+        """Append a new freeform `p:sp` with specified position and size."""
+        shape_id = self._next_shape_id
+        name = "Freeform %d" % (shape_id - 1,)
+        sp = CT_Shape.new_freeform_sp(shape_id, name, x, y, cx, cy)
+        self.insert_element_before(sp, "p:extLst")
+        return sp
+
+    def add_grpSp(self) -> CT_GroupShape:
+        """Return `p:grpSp` element newly appended to this shape tree.
+
+        The element contains no sub-shapes, is positioned at (0, 0), and has
+        width and height of zero.
+        """
+        shape_id = self._next_shape_id
+        name = "Group %d" % (shape_id - 1,)
+        grpSp = CT_GroupShape.new_grpSp(shape_id, name)
+        self.insert_element_before(grpSp, "p:extLst")
+        return grpSp
+
+    def add_pic(
+        self, id_: int, name: str, desc: str, rId: str, x: int, y: int, cx: int, cy: int
+    ) -> CT_Picture:
+        """Append a `p:pic` shape to the group/shapetree having properties as specified in call."""
+        pic = CT_Picture.new_pic(id_, name, desc, rId, x, y, cx, cy)
+        self.insert_element_before(pic, "p:extLst")
+        return pic
+
+    def add_placeholder(
+        self, id_: int, name: str, ph_type: PP_PLACEHOLDER, orient: str, sz: str, idx: int
+    ) -> CT_Shape:
+        """Append a newly-created placeholder `p:sp` shape having the specified properties."""
+        sp = CT_Shape.new_placeholder_sp(id_, name, ph_type, orient, sz, idx)
+        self.insert_element_before(sp, "p:extLst")
+        return sp
+
+    def add_table(
+        self, id_: int, name: str, rows: int, cols: int, x: int, y: int, cx: int, cy: int
+    ) -> CT_GraphicalObjectFrame:
+        """Append a `p:graphicFrame` shape containing a table as specified in call."""
+        graphicFrame = CT_GraphicalObjectFrame.new_table_graphicFrame(
+            id_, name, rows, cols, x, y, cx, cy
+        )
+        self.insert_element_before(graphicFrame, "p:extLst")
+        return graphicFrame
+
+    def add_textbox(self, id_: int, name: str, x: int, y: int, cx: int, cy: int) -> CT_Shape:
+        """Append a newly-created textbox `p:sp` shape having the specified position and size."""
+        sp = CT_Shape.new_textbox_sp(id_, name, x, y, cx, cy)
+        self.insert_element_before(sp, "p:extLst")
+        return sp
+
+    @property
+    def chExt(self):
+        """Descendent `p:grpSpPr/a:xfrm/a:chExt` element."""
+        return self.grpSpPr.get_or_add_xfrm().get_or_add_chExt()
+
+    @property
+    def chOff(self):
+        """Descendent `p:grpSpPr/a:xfrm/a:chOff` element."""
+        return self.grpSpPr.get_or_add_xfrm().get_or_add_chOff()
+
+    def get_or_add_xfrm(self) -> CT_Transform2D:
+        """Return the `a:xfrm` grandchild element, newly-added if not present."""
+        return self.grpSpPr.get_or_add_xfrm()
+
+    def iter_ph_elms(self):
+        """Generate each placeholder shape child element in document order."""
+        for e in self.iter_shape_elms():
+            if e.has_ph_elm:
+                yield e
+
+    def iter_shape_elms(self) -> Iterator[ShapeElement]:
+        """Generate each child of this `p:spTree` element that corresponds to a shape.
+
+        Items appear in XML document order.
+        """
+        for elm in self.iterchildren():
+            if elm.tag in self._shape_tags:
+                yield elm
+
+    @property
+    def max_shape_id(self) -> int:
+        """Maximum int value assigned as @id in this slide.
+
+        This is generally a shape-id, but ids can be assigned to other
+        objects so we just check all @id values anywhere in the document
+        (XML id-values have document scope).
+
+        In practice, its minimum value is 1 because the spTree element itself
+        is always assigned id="1".
+
+        First access scans the document; the result is then cached on the
+        document-root element and kept current as ids are allocated via
+        :meth:`allocate_shape_id`.
+        """
+        return self._ensure_id_cache()
+
+    def allocate_shape_id(self) -> int:
+        """Reserve and return the next unused id for a new shape.
+
+        Caches the running maximum on the document-root element so consecutive
+        adds are O(1) instead of triggering a fresh ``//@id`` scan each call
+        (which is what produced the historical O(N²) behavior over a slide).
+        Callers that mutate the document outside the shape-tree API can call
+        :meth:`invalidate_shape_id_cache` to force a re-scan.
+        """
+        cursor = self._ensure_id_cache() + 1
+        self._set_id_cache(cursor)
+        return cursor
+
+    def invalidate_shape_id_cache(self) -> None:
+        """Drop the cached max-shape-id; next access will re-scan ``//@id``."""
+        root = self.getroottree().getroot()
+        if hasattr(root, "_pptx_shape_id_cursor"):
+            delattr(root, "_pptx_shape_id_cursor")
+
+    def _ensure_id_cache(self) -> int:
+        """Return the cached max shape id, populating it on first access."""
+        root = self.getroottree().getroot()
+        cursor = getattr(root, "_pptx_shape_id_cursor", None)
+        if cursor is None:
+            used_ids = (int(s) for s in self.xpath("//@id") if s.isdigit())
+            cursor = max(used_ids, default=0)
+            self._set_id_cache(cursor)
+        return cursor
+
+    def _set_id_cache(self, value: int) -> None:
+        self.getroottree().getroot()._pptx_shape_id_cursor = value
+
+    @classmethod
+    def new_grpSp(cls, id_: int, name: str) -> CT_GroupShape:
+        """Return new "loose" `p:grpSp` element having `id_` and `name`."""
+        xml = (
+            "<p:grpSp %s>\n"
+            "  <p:nvGrpSpPr>\n"
+            '    <p:cNvPr id="%%d" name="%%s"/>\n'
+            "    <p:cNvGrpSpPr/>\n"
+            "    <p:nvPr/>\n"
+            "  </p:nvGrpSpPr>\n"
+            "  <p:grpSpPr>\n"
+            "    <a:xfrm>\n"
+            '      <a:off x="0" y="0"/>\n'
+            '      <a:ext cx="0" cy="0"/>\n'
+            '      <a:chOff x="0" y="0"/>\n'
+            '      <a:chExt cx="0" cy="0"/>\n'
+            "    </a:xfrm>\n"
+            "  </p:grpSpPr>\n"
+            "</p:grpSp>" % nsdecls("a", "p", "r")
+        ) % (id_, name)
+        grpSp = parse_xml(xml)
+        return grpSp
+
+    def recalculate_extents(self) -> None:
+        """Adjust x, y, cx, and cy to incorporate all contained shapes.
+
+        This would typically be called when a contained shape is added,
+        removed, or its position or size updated.
+
+        This method is recursive "upwards" since a change in a group shape
+        can change the position and size of its containing group.
+        """
+        if not self.tag == qn("p:grpSp"):
+            return
+
+        x, y, cx, cy = self._child_extents
+
+        self.chOff.x = self.x = x
+        self.chOff.y = self.y = y
+        self.chExt.cx = self.cx = cx
+        self.chExt.cy = self.cy = cy
+        self.getparent().recalculate_extents()
+
+    @property
+    def xfrm(self) -> CT_Transform2D | None:
+        """The `a:xfrm` grandchild element or |None| if not found."""
+        return self.grpSpPr.xfrm
+
+    @property
+    def _child_extents(self) -> tuple[int, int, int, int]:
+        """(x, y, cx, cy) tuple representing net position and size.
+
+        The values are formed as a composite of the contained child shapes.
+        """
+        child_shape_elms = list(self.iter_shape_elms())
+
+        if not child_shape_elms:
+            return Emu(0), Emu(0), Emu(0), Emu(0)
+
+        min_x = min([xSp.x for xSp in child_shape_elms])
+        min_y = min([xSp.y for xSp in child_shape_elms])
+        max_x = max([(xSp.x + xSp.cx) for xSp in child_shape_elms])
+        max_y = max([(xSp.y + xSp.cy) for xSp in child_shape_elms])
+
+        x = min_x
+        y = min_y
+        cx = max_x - min_x
+        cy = max_y - min_y
+
+        return x, y, cx, cy
+
+    @property
+    def _next_shape_id(self) -> int:
+        """Return unique shape id suitable for use with a new shape element.
+
+        Equivalent to :meth:`allocate_shape_id`; preserved for OXML-internal
+        callers (`add_freeform_sp`, `add_grpSp`).
+        """
+        return self.allocate_shape_id()
+
+
+class CT_GroupShapeNonVisual(BaseShapeElement):
+    """`p:nvGrpSpPr` element."""
+
+    cNvPr = OneAndOnlyOne("p:cNvPr")
+
+
+class CT_GroupShapeProperties(BaseOxmlElement):
+    """p:grpSpPr element"""
+
+    get_or_add_xfrm: Callable[[], CT_Transform2D]
+
+    _tag_seq = (
+        "a:xfrm",
+        "a:noFill",
+        "a:solidFill",
+        "a:gradFill",
+        "a:blipFill",
+        "a:pattFill",
+        "a:grpFill",
+        "a:effectLst",
+        "a:effectDag",
+        "a:scene3d",
+        "a:extLst",
+    )
+    xfrm: CT_Transform2D | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:xfrm", successors=_tag_seq[1:]
+    )
+    eg_fillProperties = ZeroOrOneChoice(
+        (
+            Choice("a:noFill"),
+            Choice("a:solidFill"),
+            Choice("a:gradFill"),
+            Choice("a:blipFill"),
+            Choice("a:pattFill"),
+            Choice("a:grpFill"),
+        ),
+        successors=_tag_seq[7:],
+    )
+    effectLst = ZeroOrOne("a:effectLst", successors=_tag_seq[8:])
+    del _tag_seq
+
+    def _new_gradFill(self):
+        return CT_GradientFillProperties.new_gradFill()