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

pptx/shapes/autoshape.py

@@ -0,0 +1,355 @@
+"""Autoshape-related objects such as Shape and Adjustment."""
+
+from __future__ import annotations
+
+from numbers import Number
+from typing import TYPE_CHECKING, Iterable
+from xml.sax import saxutils
+
+from pptx.dml.fill import FillFormat
+from pptx.dml.line import LineFormat
+from pptx.enum.shapes import MSO_AUTO_SHAPE_TYPE, MSO_SHAPE_TYPE
+from pptx.shapes.base import BaseShape
+from pptx.spec import autoshape_types
+from pptx.text.text import TextFrame
+from pptx.util import lazyproperty
+
+if TYPE_CHECKING:
+    from pptx.oxml.shapes.autoshape import CT_GeomGuide, CT_PresetGeometry2D, CT_Shape
+    from pptx.spec import AdjustmentValue
+    from pptx.types import ProvidesPart
+
+
+class Adjustment:
+    """An adjustment value for an autoshape.
+
+    An adjustment value corresponds to the position of an adjustment handle on an auto shape.
+    Adjustment handles are the small yellow diamond-shaped handles that appear on certain auto
+    shapes and allow the outline of the shape to be adjusted. For example, a rounded rectangle has
+    an adjustment handle that allows the radius of its corner rounding to be adjusted.
+
+    Values are |float| and generally range from 0.0 to 1.0, although the value can be negative or
+    greater than 1.0 in certain circumstances.
+    """
+
+    def __init__(self, name: str, def_val: int, actual: int | None = None):
+        super(Adjustment, self).__init__()
+        self.name = name
+        self.def_val = def_val
+        self.actual = actual
+
+    @property
+    def effective_value(self) -> float:
+        """Read/write |float| representing normalized adjustment value for this adjustment.
+
+        Actual values are a large-ish integer expressed in shape coordinates, nominally between 0
+        and 100,000. The effective value is normalized to a corresponding value nominally between
+        0.0 and 1.0. Intuitively this represents the proportion of the width or height of the shape
+        at which the adjustment value is located from its starting point. For simple shapes such as
+        a rounded rectangle, this intuitive correspondence holds. For more complicated shapes and
+        at more extreme shape proportions (e.g. width is much greater than height), the value can
+        become negative or greater than 1.0.
+        """
+        raw_value = self.actual if self.actual is not None else self.def_val
+        return self._normalize(raw_value)
+
+    @effective_value.setter
+    def effective_value(self, value: float):
+        if not isinstance(value, Number):
+            raise ValueError(f"adjustment value must be numeric, got {repr(value)}")
+        self.actual = self._denormalize(value)
+
+    @staticmethod
+    def _denormalize(value: float) -> int:
+        """Return integer corresponding to normalized `raw_value` on unit basis of 100,000.
+
+        See Adjustment.normalize for additional details.
+        """
+        return int(value * 100000.0)
+
+    @staticmethod
+    def _normalize(raw_value: int) -> float:
+        """Return normalized value for `raw_value`.
+
+        A normalized value is a |float| between 0.0 and 1.0 for nominal raw values between 0 and
+        100,000. Raw values less than 0 and greater than 100,000 are valid and return values
+        calculated on the same unit basis of 100,000.
+        """
+        return raw_value / 100000.0
+
+    @property
+    def val(self) -> int:
+        """Denormalized effective value.
+
+        Expressed in shape coordinates, this is suitable for using in the XML.
+        """
+        return self.actual if self.actual is not None else self.def_val
+
+
+class AdjustmentCollection:
+    """Sequence of |Adjustment| instances for an auto shape.
+
+    Each represents an available adjustment for a shape of its type. Supports `len()` and indexed
+    access, e.g. `shape.adjustments[1] = 0.15`.
+    """
+
+    def __init__(self, prstGeom: CT_PresetGeometry2D):
+        super(AdjustmentCollection, self).__init__()
+        self._adjustments_ = self._initialized_adjustments(prstGeom)
+        self._prstGeom = prstGeom
+
+    def __getitem__(self, idx: int) -> float:
+        """Provides indexed access, (e.g. 'adjustments[9]')."""
+        return self._adjustments_[idx].effective_value
+
+    def __setitem__(self, idx: int, value: float):
+        """Provides item assignment via an indexed expression, e.g. `adjustments[9] = 999.9`.
+
+        Causes all adjustment values in collection to be written to the XML.
+        """
+        self._adjustments_[idx].effective_value = value
+        self._rewrite_guides()
+
+    def _initialized_adjustments(self, prstGeom: CT_PresetGeometry2D | None) -> list[Adjustment]:
+        """Return an initialized list of adjustment values based on the contents of `prstGeom`."""
+        if prstGeom is None:
+            return []
+        davs = AutoShapeType.default_adjustment_values(prstGeom.prst)
+        adjustments = [Adjustment(name, def_val) for name, def_val in davs]
+        self._update_adjustments_with_actuals(adjustments, prstGeom.gd_lst)
+        return adjustments
+
+    def _rewrite_guides(self):
+        """Write `a:gd` elements to the XML, one for each adjustment value.
+
+        Any existing guide elements are overwritten.
+        """
+        guides = [(adj.name, adj.val) for adj in self._adjustments_]
+        self._prstGeom.rewrite_guides(guides)
+
+    @staticmethod
+    def _update_adjustments_with_actuals(
+        adjustments: Iterable[Adjustment], guides: Iterable[CT_GeomGuide]
+    ):
+        """Update |Adjustment| instances in `adjustments` with actual values held in `guides`.
+
+        `guides` is a list of `a:gd` elements. Guides with a name that does not match an adjustment
+        object are skipped.
+        """
+        adjustments_by_name = dict((adj.name, adj) for adj in adjustments)
+        for gd in guides:
+            name = gd.name
+            actual = int(gd.fmla[4:])
+            try:
+                adjustment = adjustments_by_name[name]
+            except KeyError:
+                continue
+            adjustment.actual = actual
+        return
+
+    @property
+    def _adjustments(self) -> tuple[Adjustment, ...]:
+        """Sequence of |Adjustment| objects contained in collection."""
+        return tuple(self._adjustments_)
+
+    def __len__(self):
+        """Implement built-in function len()"""
+        return len(self._adjustments_)
+
+
+class AutoShapeType:
+    """Provides access to metadata for an auto-shape of type identified by `autoshape_type_id`.
+
+    Instances are cached, so no more than one instance for a particular auto shape type is in
+    memory.
+
+    Instances provide the following attributes:
+
+    .. attribute:: autoshape_type_id
+
+       Integer uniquely identifying this auto shape type. Corresponds to a
+       value in `pptx.constants.MSO` like `MSO_SHAPE.ROUNDED_RECTANGLE`.
+
+    .. attribute:: basename
+
+       Base part of shape name for auto shapes of this type, e.g. `Rounded
+       Rectangle` becomes `Rounded Rectangle 99` when the distinguishing
+       integer is added to the shape name.
+
+    .. attribute:: prst
+
+       String identifier for this auto shape type used in the `a:prstGeom`
+       element.
+
+    """
+
+    _instances: dict[MSO_AUTO_SHAPE_TYPE, AutoShapeType] = {}
+
+    def __new__(cls, autoshape_type_id: MSO_AUTO_SHAPE_TYPE) -> AutoShapeType:
+        """Only create new instance on first call for content_type.
+
+        After that, use cached instance.
+        """
+        # -- if there's not a matching instance in the cache, create one --
+        if autoshape_type_id not in cls._instances:
+            inst = super(AutoShapeType, cls).__new__(cls)
+            cls._instances[autoshape_type_id] = inst
+        # -- return the instance; note that __init__() gets called either way --
+        return cls._instances[autoshape_type_id]
+
+    def __init__(self, autoshape_type_id: MSO_AUTO_SHAPE_TYPE):
+        """Initialize attributes from constant values in `pptx.spec`."""
+        # -- skip loading if this instance is from the cache --
+        if hasattr(self, "_loaded"):
+            return
+        # -- raise on bad autoshape_type_id --
+        if autoshape_type_id not in autoshape_types:
+            raise KeyError(
+                "no autoshape type with id '%s' in pptx.spec.autoshape_types" % autoshape_type_id
+            )
+        # -- otherwise initialize new instance --
+        autoshape_type = autoshape_types[autoshape_type_id]
+        self._autoshape_type_id = autoshape_type_id
+        self._basename = autoshape_type["basename"]
+        self._loaded = True
+
+    @property
+    def autoshape_type_id(self) -> MSO_AUTO_SHAPE_TYPE:
+        """MSO_AUTO_SHAPE_TYPE enumeration member identifying this auto shape type."""
+        return self._autoshape_type_id
+
+    @property
+    def basename(self) -> str:
+        """Base of shape name for this auto shape type.
+
+        A shape name is like "Rounded Rectangle 7" and appears as an XML attribute for example at
+        `p:sp/p:nvSpPr/p:cNvPr{name}`. This basename value is the name less the distinguishing
+        integer. This value is escaped because at least one autoshape-type name includes double
+        quotes ('"No" Symbol').
+        """
+        return saxutils.escape(self._basename, {'"': """})
+
+    @classmethod
+    def default_adjustment_values(cls, prst: MSO_AUTO_SHAPE_TYPE) -> tuple[AdjustmentValue, ...]:
+        """Sequence of (name, value) pair adjustment value defaults for `prst` autoshape-type."""
+        return autoshape_types[prst]["avLst"]
+
+    @classmethod
+    def id_from_prst(cls, prst: str) -> MSO_AUTO_SHAPE_TYPE:
+        """Select auto shape type with matching `prst`.
+
+        e.g. `MSO_SHAPE.RECTANGLE` corresponding to preset geometry keyword `"rect"`.
+        """
+        return MSO_AUTO_SHAPE_TYPE.from_xml(prst)
+
+    @property
+    def prst(self):
+        """
+        Preset geometry identifier string for this auto shape. Used in the
+        `prst` attribute of `a:prstGeom` element to specify the geometry
+        to be used in rendering the shape, for example `'roundRect'`.
+        """
+        return MSO_AUTO_SHAPE_TYPE.to_xml(self._autoshape_type_id)
+
+
+class Shape(BaseShape):
+    """A shape that can appear on a slide.
+
+    Corresponds to the `p:sp` element that can appear in any of the slide-type parts
+    (slide, slideLayout, slideMaster, notesPage, notesMaster, handoutMaster).
+    """
+
+    def __init__(self, sp: CT_Shape, parent: ProvidesPart):
+        super(Shape, self).__init__(sp, parent)
+        self._sp = sp
+
+    @lazyproperty
+    def adjustments(self) -> AdjustmentCollection:
+        """Read-only reference to |AdjustmentCollection| instance for this shape."""
+        return AdjustmentCollection(self._sp.prstGeom)
+
+    @property
+    def auto_shape_type(self):
+        """Enumeration value identifying the type of this auto shape.
+
+        Like `MSO_SHAPE.ROUNDED_RECTANGLE`. Raises |ValueError| if this shape is not an auto shape.
+        """
+        if not self._sp.is_autoshape:
+            raise ValueError("shape is not an auto shape")
+        return self._sp.prst
+
+    @lazyproperty
+    def fill(self):
+        """|FillFormat| instance for this shape.
+
+        Provides access to fill properties such as fill color.
+        """
+        return FillFormat.from_fill_parent(self._sp.spPr)
+
+    def get_or_add_ln(self):
+        """Return the `a:ln` element containing the line format properties XML for this shape."""
+        return self._sp.get_or_add_ln()
+
+    @property
+    def has_text_frame(self) -> bool:
+        """|True| if this shape can contain text. Always |True| for an AutoShape."""
+        return True
+
+    @lazyproperty
+    def line(self):
+        """|LineFormat| instance for this shape.
+
+        Provides access to line properties such as line color.
+        """
+        return LineFormat(self)
+
+    @property
+    def ln(self):
+        """The `a:ln` element containing the line format properties such as line color and width.
+
+        |None| if no `a:ln` element is present.
+        """
+        return self._sp.ln
+
+    @property
+    def shape_type(self) -> MSO_SHAPE_TYPE:
+        """Unique integer identifying the type of this shape, like `MSO_SHAPE_TYPE.TEXT_BOX`."""
+        if self.is_placeholder:
+            return MSO_SHAPE_TYPE.PLACEHOLDER
+        if self._sp.has_custom_geometry:
+            return MSO_SHAPE_TYPE.FREEFORM
+        if self._sp.is_autoshape:
+            return MSO_SHAPE_TYPE.AUTO_SHAPE
+        if self._sp.is_textbox:
+            return MSO_SHAPE_TYPE.TEXT_BOX
+        raise NotImplementedError("Shape instance of unrecognized shape type")
+
+    @property
+    def text(self) -> str:
+        """Read/write. Text in shape as a single string.
+
+        The returned string will contain a newline character (`"\\n"`) separating each paragraph
+        and a vertical-tab (`"\\v"`) character for each line break (soft carriage return) in the
+        shape's text.
+
+        Assignment to `text` replaces any text previously contained in the shape, along with any
+        paragraph or font formatting applied to it. A newline character (`"\\n"`) in the assigned
+        text causes a new paragraph to be started. A vertical-tab (`"\\v"`) character in the
+        assigned text causes a line-break (soft carriage-return) to be inserted. (The vertical-tab
+        character appears in clipboard text copied from PowerPoint as its str encoding of
+        line-breaks.)
+        """
+        return self.text_frame.text
+
+    @text.setter
+    def text(self, text: str):
+        self.text_frame.text = text
+
+    @property
+    def text_frame(self):
+        """|TextFrame| instance for this shape.
+
+        Contains the text of the shape and provides access to text formatting properties.
+        """
+        txBody = self._sp.get_or_add_txBody()
+        return TextFrame(txBody, self)

pptx/shapes/base.py

@@ -0,0 +1,293 @@
+"""Base shape-related objects such as BaseShape."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from pptx.action import ActionSetting
+from pptx.dml.effect import ShadowFormat
+from pptx.shared import ElementProxy
+from pptx.util import lazyproperty
+
+if TYPE_CHECKING:
+    from pptx.enum.shapes import MSO_SHAPE_TYPE, PP_PLACEHOLDER
+    from pptx.oxml.shapes import ShapeElement
+    from pptx.oxml.shapes.shared import CT_Placeholder
+    from pptx.parts.slide import BaseSlidePart
+    from pptx.types import ProvidesPart
+    from pptx.util import Length
+
+
+class BaseShape(object):
+    """Base class for shape objects.
+
+    Subclasses include |Shape|, |Picture|, and |GraphicFrame|.
+    """
+
+    def __init__(self, shape_elm: ShapeElement, parent: ProvidesPart):
+        super().__init__()
+        self._element = shape_elm
+        self._parent = parent
+
+    def __eq__(self, other: object) -> bool:
+        """|True| if this shape object proxies the same element as *other*.
+
+        Equality for proxy objects is defined as referring to the same XML element, whether or not
+        they are the same proxy object instance.
+        """
+        if not isinstance(other, BaseShape):
+            return False
+        return self._element is other._element
+
+    def __ne__(self, other: object) -> bool:
+        if not isinstance(other, BaseShape):
+            return True
+        return self._element is not other._element
+
+    def send_to_back(self) -> None:
+        """Move this shape behind its siblings, within its current slide or group."""
+        siblings = list(self._element.getparent().iter_shape_elms())
+        if siblings and siblings[0] is not self._element:
+            siblings[0].addprevious(self._element)
+
+    def bring_to_front(self) -> None:
+        """Move this shape in front of its siblings, within its current slide or group."""
+        siblings = list(self._element.getparent().iter_shape_elms())
+        if siblings and siblings[-1] is not self._element:
+            siblings[-1].addnext(self._element)
+
+    @lazyproperty
+    def click_action(self) -> ActionSetting:
+        """|ActionSetting| instance providing access to click behaviors.
+
+        Click behaviors are hyperlink-like behaviors including jumping to a hyperlink (web page)
+        or to another slide in the presentation. The click action is that defined on the overall
+        shape, not a run of text within the shape. An |ActionSetting| object is always returned,
+        even when no click behavior is defined on the shape.
+        """
+        cNvPr = self._element._nvXxPr.cNvPr  # pyright: ignore[reportPrivateUsage]
+        return ActionSetting(cNvPr, self)
+
+    @property
+    def element(self) -> ShapeElement:
+        """`lxml` element for this shape, e.g. a CT_Shape instance.
+
+        Note that manipulating this element improperly can produce an invalid presentation file.
+        Make sure you know what you're doing if you use this to change the underlying XML.
+        """
+        return self._element
+
+    @property
+    def has_chart(self) -> bool:
+        """|True| if this shape is a graphic frame containing a chart object.
+
+        |False| otherwise. When |True|, the chart object can be accessed using the ``.chart``
+        property.
+        """
+        # This implementation is unconditionally False, the True version is
+        # on GraphicFrame subclass.
+        return False
+
+    @property
+    def has_table(self) -> bool:
+        """|True| if this shape is a graphic frame containing a table object.
+
+        |False| otherwise. When |True|, the table object can be accessed using the ``.table``
+        property.
+        """
+        # This implementation is unconditionally False, the True version is
+        # on GraphicFrame subclass.
+        return False
+
+    @property
+    def has_text_frame(self) -> bool:
+        """|True| if this shape can contain text."""
+        # overridden on Shape to return True. Only <p:sp> has text frame
+        return False
+
+    @property
+    def height(self) -> Length:
+        """Read/write. Integer distance between top and bottom extents of shape in EMUs."""
+        return self._element.cy
+
+    @height.setter
+    def height(self, value: Length):
+        self._element.cy = value
+
+    @property
+    def is_placeholder(self) -> bool:
+        """True if this shape is a placeholder.
+
+        A shape is a placeholder if it has a <p:ph> element.
+        """
+        return self._element.has_ph_elm
+
+    @property
+    def left(self) -> Length:
+        """Integer distance of the left edge of this shape from the left edge of the slide.
+
+        Read/write. Expressed in English Metric Units (EMU)
+        """
+        return self._element.x
+
+    @left.setter
+    def left(self, value: Length):
+        self._element.x = value
+
+    @property
+    def name(self) -> str:
+        """Name of this shape, e.g. 'Picture 7'."""
+        return self._element.shape_name
+
+    @name.setter
+    def name(self, value: str):
+        self._element._nvXxPr.cNvPr.name = value  # pyright: ignore[reportPrivateUsage]
+
+    @property
+    def part(self) -> BaseSlidePart:
+        """The package part containing this shape.
+
+        A |BaseSlidePart| subclass in this case. Access to a slide part should only be required if
+        you are extending the behavior of |pp| API objects.
+        """
+        return cast("BaseSlidePart", self._parent.part)
+
+    @property
+    def placeholder_format(self) -> _PlaceholderFormat:
+        """Provides access to placeholder-specific properties such as placeholder type.
+
+        Raises |ValueError| on access if the shape is not a placeholder.
+        """
+        ph = self._element.ph
+        if ph is None:
+            raise ValueError("shape is not a placeholder")
+        return _PlaceholderFormat(ph)
+
+    @property
+    def rotation(self) -> float:
+        """Degrees of clockwise rotation.
+
+        Read/write float. Negative values can be assigned to indicate counter-clockwise rotation,
+        e.g. assigning -45.0 will change setting to 315.0.
+        """
+        return self._element.rot
+
+    @rotation.setter
+    def rotation(self, value: float):
+        self._element.rot = value
+
+    @lazyproperty
+    def shadow(self) -> ShadowFormat:
+        """|ShadowFormat| object providing access to shadow for this shape.
+
+        A |ShadowFormat| object is always returned, even when no shadow is
+        explicitly defined on this shape (i.e. it inherits its shadow
+        behavior).
+        """
+        return ShadowFormat(self._element.spPr)
+
+    @property
+    def shape_id(self) -> int:
+        """Read-only positive integer identifying this shape.
+
+        The id of a shape is unique among all shapes on a slide.
+        """
+        return self._element.shape_id
+
+    @property
+    def shape_type(self) -> MSO_SHAPE_TYPE:
+        """A member of MSO_SHAPE_TYPE classifying this shape by type.
+
+        Like ``MSO_SHAPE_TYPE.CHART``. Must be implemented by subclasses.
+        """
+        raise NotImplementedError(f"{type(self).__name__} does not implement `.shape_type`")
+
+    @property
+    def top(self) -> Length:
+        """Distance from the top edge of the slide to the top edge of this shape.
+
+        Read/write. Expressed in English Metric Units (EMU)
+        """
+        return self._element.y
+
+    @top.setter
+    def top(self, value: Length):
+        self._element.y = value
+
+    @property
+    def width(self) -> Length:
+        """Distance between left and right extents of this shape.
+
+        Read/write. Expressed in English Metric Units (EMU).
+        """
+        return self._element.cx
+
+    @width.setter
+    def width(self, value: Length):
+        self._element.cx = value
+
+    @property
+    def alt_text(self) -> str | None:
+        """Alternative-text description. None means absent, while an empty string is explicit."""
+        return self._element._nvXxPr.cNvPr.get("descr")
+
+    @alt_text.setter
+    def alt_text(self, value: str | None):
+        if value is not None and not isinstance(value, str):
+            raise TypeError("alternative text must be a string or None")
+        properties = self._element._nvXxPr.cNvPr
+        if value is None:
+            properties.attrib.pop("descr", None)
+        else:
+            properties.set("descr", value)
+
+    @alt_text.deleter
+    def alt_text(self):
+        self.alt_text = None
+
+    @property
+    def alt_text_title(self) -> str | None:
+        """Alternative-text title. None means absent, while an empty string is explicit."""
+        return self._element._nvXxPr.cNvPr.get("title")
+
+    @alt_text_title.setter
+    def alt_text_title(self, value: str | None):
+        if value is not None and not isinstance(value, str):
+            raise TypeError("alternative text must be a string or None")
+        properties = self._element._nvXxPr.cNvPr
+        if value is None:
+            properties.attrib.pop("title", None)
+        else:
+            properties.set("title", value)
+
+    @alt_text_title.deleter
+    def alt_text_title(self):
+        self.alt_text_title = None
+
+class _PlaceholderFormat(ElementProxy):
+    """Provides properties specific to placeholders, such as the placeholder type.
+
+    Accessed via the :attr:`~.BaseShape.placeholder_format` property of a placeholder shape,
+    """
+
+    def __init__(self, element: CT_Placeholder):
+        super().__init__(element)
+        self._ph = element
+
+    @property
+    def element(self) -> CT_Placeholder:
+        """The `p:ph` element proxied by this object."""
+        return self._ph
+
+    @property
+    def idx(self) -> int:
+        """Integer placeholder 'idx' attribute."""
+        return self._ph.idx
+
+    @property
+    def type(self) -> PP_PLACEHOLDER:
+        """Placeholder type.
+
+        A member of the :ref:`PpPlaceholderType` enumeration, e.g. PP_PLACEHOLDER.CHART
+        """
+        return self._ph.type