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

pptx/dml/fill.py

@@ -0,0 +1,468 @@
+"""DrawingML objects related to fill."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from pptx.dml.color import ColorFormat, RGBColor
+from pptx.enum.dml import MSO_FILL, MSO_THEME_COLOR
+from pptx.oxml.dml.fill import (
+    CT_BlipFillProperties,
+    CT_GradientFillProperties,
+    CT_GroupFillProperties,
+    CT_NoFillProperties,
+    CT_PatternFillProperties,
+    CT_SolidColorFillProperties,
+)
+from pptx.oxml.xmlchemy import BaseOxmlElement, OxmlElement
+from pptx.shared import ElementProxy
+from pptx.util import lazyproperty
+
+if TYPE_CHECKING:
+    from pptx.enum.dml import MSO_FILL_TYPE
+    from pptx.oxml.xmlchemy import BaseOxmlElement
+
+
+class FillFormat(object):
+    """Provides access to the current fill properties.
+
+    Also provides methods to change the fill type.
+    """
+
+    def __init__(self, eg_fill_properties_parent: BaseOxmlElement, fill_obj: _Fill):
+        super(FillFormat, self).__init__()
+        self._xPr = eg_fill_properties_parent
+        self._fill = fill_obj
+
+    @classmethod
+    def from_fill_parent(cls, eg_fillProperties_parent: BaseOxmlElement) -> FillFormat:
+        """
+        Return a |FillFormat| instance initialized to the settings contained
+        in *eg_fillProperties_parent*, which must be an element having
+        EG_FillProperties in its child element sequence in the XML schema.
+        """
+        fill_elm = eg_fillProperties_parent.eg_fillProperties
+        fill = _Fill(fill_elm)
+        fill_format = cls(eg_fillProperties_parent, fill)
+        return fill_format
+
+    @property
+    def back_color(self):
+        """Return a |ColorFormat| object representing background color.
+
+        This property is only applicable to pattern fills and lines.
+        """
+        return self._fill.back_color
+
+    def background(self):
+        """
+        Sets the fill type to noFill, i.e. transparent.
+        """
+        noFill = self._xPr.get_or_change_to_noFill()
+        self._fill = _NoFill(noFill)
+
+    @property
+    def fore_color(self):
+        """
+        Return a |ColorFormat| instance representing the foreground color of
+        this fill.
+        """
+        return self._fill.fore_color
+
+    def set_gradient(self, stops, *, angle=0.0, radial=False, center=(0.5, 0.5)):
+        """Replace the fill with an explicit linear or circular radial gradient.
+
+        Stops are (position, color) pairs with ascending positions from 0 to 1.
+        Colors are RGBColor or MSO_THEME_COLOR values. At least two are required.
+        Angle is in counter-clockwise degrees. For radial gradients, center is
+        an (x, y) pair of fractions measured from the upper-left corner.
+        Invalid arguments leave the existing fill unchanged.
+        """
+        values = list(stops)
+        if len(values) < 2:
+            raise ValueError("a gradient requires at least two stops")
+        if not isinstance(radial, bool):
+            raise TypeError("radial must be bool")
+        if not math.isfinite(angle):
+            raise ValueError("gradient angle must be finite")
+        if len(center) != 2 or any(not math.isfinite(v) or not 0 <= v <= 1 for v in center):
+            raise ValueError("center must contain two fractions between 0 and 1")
+        gradient = OxmlElement("a:gradFill")
+        gradient.set("rotWithShape", "1")
+        stop_list = OxmlElement("a:gsLst")
+        previous = -1.0
+        for position, color in values:
+            if not math.isfinite(position) or not previous <= position <= 1 or position < 0:
+                raise ValueError("gradient positions must be ascending fractions from 0 to 1")
+            previous = position
+            stop = OxmlElement("a:gs")
+            stop.pos = position
+            if isinstance(color, RGBColor):
+                color_element = OxmlElement("a:srgbClr")
+                color_element.set("val", str(color))
+            elif isinstance(color, MSO_THEME_COLOR):
+                color_element = OxmlElement("a:schemeClr")
+                color_element.set("val", MSO_THEME_COLOR.to_xml(color))
+            else:
+                raise TypeError("gradient colors must be RGBColor or MSO_THEME_COLOR")
+            stop.append(color_element)
+            stop_list.append(stop)
+        gradient.append(stop_list)
+        if radial:
+            path = OxmlElement("a:path")
+            path.set("path", "circle")
+            rect = OxmlElement("a:fillToRect")
+            x, y = center
+            for name, value in zip(("l", "t", "r", "b"), (x, y, 1 - x, 1 - y)):
+                rect.set(name, str(round(value * 100000)))
+            path.append(rect)
+            gradient.append(path)
+        else:
+            linear = OxmlElement("a:lin")
+            linear.set("ang", str(round(((360.0 - angle) % 360.0) * 60000) % 21600000))
+            linear.set("scaled", "0")
+            gradient.append(linear)
+        old = self._xPr.get_or_change_to_gradFill()
+        old.getparent().replace(old, gradient)
+        self._fill = _GradFill(gradient)
+
+    def _set_picture(self, relationship_id):
+        """Set a stretched picture fill using a relationship owned by the containing part."""
+        fill = self._xPr.get_or_change_to_blipFill()
+        fill[:] = []
+        blip = OxmlElement("a:blip")
+        blip.rEmbed = relationship_id
+        fill.append(blip)
+        stretch = OxmlElement("a:stretch")
+        stretch.append(OxmlElement("a:fillRect"))
+        fill.append(stretch)
+        self._fill = _BlipFill(fill)
+
+    def gradient(self):
+        """Sets the fill type to gradient.
+
+        If the fill is not already a gradient, a default gradient is added.
+        The default gradient corresponds to the default in the built-in
+        PowerPoint "White" template. This gradient is linear at angle
+        90-degrees (upward), with two stops. The first stop is Accent-1 with
+        tint 100%, shade 100%, and satMod 130%. The second stop is Accent-1
+        with tint 50%, shade 100%, and satMod 350%.
+        """
+        gradFill = self._xPr.get_or_change_to_gradFill()
+        self._fill = _GradFill(gradFill)
+
+    @property
+    def gradient_angle(self):
+        """Angle in float degrees of line of a linear gradient.
+
+        Read/Write. May be |None|, indicating the angle should be inherited
+        from the style hierarchy. An angle of 0.0 corresponds to
+        a left-to-right gradient. Increasing angles represent
+        counter-clockwise rotation of the line, for example 90.0 represents
+        a bottom-to-top gradient. Raises |TypeError| when the fill type is
+        not MSO_FILL_TYPE.GRADIENT. Raises |ValueError| for a non-linear
+        gradient (e.g. a radial gradient).
+        """
+        if self.type != MSO_FILL.GRADIENT:
+            raise TypeError("Fill is not of type MSO_FILL_TYPE.GRADIENT")
+        return self._fill.gradient_angle
+
+    @gradient_angle.setter
+    def gradient_angle(self, value):
+        if self.type != MSO_FILL.GRADIENT:
+            raise TypeError("Fill is not of type MSO_FILL_TYPE.GRADIENT")
+        self._fill.gradient_angle = value
+
+    @property
+    def gradient_stops(self):
+        """|GradientStops| object providing access to stops of this gradient.
+
+        Raises |TypeError| when fill is not gradient (call `fill.gradient()`
+        first). Each stop represents a color between which the gradient
+        smoothly transitions.
+        """
+        if self.type != MSO_FILL.GRADIENT:
+            raise TypeError("Fill is not of type MSO_FILL_TYPE.GRADIENT")
+        return self._fill.gradient_stops
+
+    @property
+    def pattern(self):
+        """Return member of :ref:`MsoPatternType` indicating fill pattern.
+
+        Raises |TypeError| when fill is not patterned (call
+        `fill.patterned()` first). Returns |None| if no pattern has been set;
+        PowerPoint may display the default `PERCENT_5` pattern in this case.
+        Assigning |None| will remove any explicit pattern setting, although
+        relying on the default behavior is discouraged and may produce
+        rendering differences across client applications.
+        """
+        return self._fill.pattern
+
+    @pattern.setter
+    def pattern(self, pattern_type):
+        self._fill.pattern = pattern_type
+
+    def patterned(self):
+        """Selects the pattern fill type.
+
+        Note that calling this method does not by itself set a foreground or
+        background color of the pattern. Rather it enables subsequent
+        assignments to properties like fore_color to set the pattern and
+        colors.
+        """
+        pattFill = self._xPr.get_or_change_to_pattFill()
+        self._fill = _PattFill(pattFill)
+
+    def solid(self):
+        """
+        Sets the fill type to solid, i.e. a solid color. Note that calling
+        this method does not set a color or by itself cause the shape to
+        appear with a solid color fill; rather it enables subsequent
+        assignments to properties like fore_color to set the color.
+        """
+        solidFill = self._xPr.get_or_change_to_solidFill()
+        self._fill = _SolidFill(solidFill)
+
+    @property
+    def type(self) -> MSO_FILL_TYPE:
+        """The type of this fill, e.g. `MSO_FILL_TYPE.SOLID`."""
+        return self._fill.type
+
+
+class _Fill(object):
+    """
+    Object factory for fill object of class matching fill element, such as
+    _SolidFill for ``<a:solidFill>``; also serves as the base class for all
+    fill classes
+    """
+
+    def __new__(cls, xFill):
+        if xFill is None:
+            fill_cls = _NoneFill
+        elif isinstance(xFill, CT_BlipFillProperties):
+            fill_cls = _BlipFill
+        elif isinstance(xFill, CT_GradientFillProperties):
+            fill_cls = _GradFill
+        elif isinstance(xFill, CT_GroupFillProperties):
+            fill_cls = _GrpFill
+        elif isinstance(xFill, CT_NoFillProperties):
+            fill_cls = _NoFill
+        elif isinstance(xFill, CT_PatternFillProperties):
+            fill_cls = _PattFill
+        elif isinstance(xFill, CT_SolidColorFillProperties):
+            fill_cls = _SolidFill
+        else:
+            fill_cls = _Fill
+        return super(_Fill, cls).__new__(fill_cls)
+
+    @property
+    def back_color(self):
+        """Raise TypeError for types that do not override this property."""
+        tmpl = "fill type %s has no background color, call .patterned() first"
+        raise TypeError(tmpl % self.__class__.__name__)
+
+    @property
+    def fore_color(self):
+        """Raise TypeError for types that do not override this property."""
+        tmpl = "fill type %s has no foreground color, call .solid() or .patterned() first"
+        raise TypeError(tmpl % self.__class__.__name__)
+
+    @property
+    def pattern(self):
+        """Raise TypeError for fills that do not override this property."""
+        tmpl = "fill type %s has no pattern, call .patterned() first"
+        raise TypeError(tmpl % self.__class__.__name__)
+
+    @property
+    def type(self) -> MSO_FILL_TYPE:  # pragma: no cover
+        raise NotImplementedError(
+            f".type property must be implemented on {self.__class__.__name__}"
+        )
+
+
+class _BlipFill(_Fill):
+    @property
+    def type(self):
+        return MSO_FILL.PICTURE
+
+
+class _GradFill(_Fill):
+    """Proxies an `a:gradFill` element."""
+
+    def __init__(self, gradFill):
+        self._element = self._gradFill = gradFill
+
+    @property
+    def gradient_angle(self):
+        """Angle in float degrees of line of a linear gradient.
+
+        Read/Write. May be |None|, indicating the angle is inherited from the
+        style hierarchy. An angle of 0.0 corresponds to a left-to-right
+        gradient. Increasing angles represent clockwise rotation of the line,
+        for example 90.0 represents a top-to-bottom gradient. Raises
+        |TypeError| when the fill type is not MSO_FILL_TYPE.GRADIENT. Raises
+        |ValueError| for a non-linear gradient (e.g. a radial gradient).
+        """
+        # ---case 1: gradient path is explicit, but not linear---
+        path = self._gradFill.path
+        if path is not None:
+            raise ValueError("not a linear gradient")
+
+        # ---case 2: gradient path is inherited (no a:lin OR a:path)---
+        lin = self._gradFill.lin
+        if lin is None:
+            return None
+
+        # ---case 3: gradient path is explicitly linear---
+        # angle is stored in XML as a clockwise angle, whereas the UI
+        # reports it as counter-clockwise from horizontal-pointing-right.
+        # Since the UI is consistent with trigonometry conventions, we
+        # respect that in the API.
+        clockwise_angle = lin.ang
+        counter_clockwise_angle = 0.0 if clockwise_angle == 0.0 else (360.0 - clockwise_angle)
+        return counter_clockwise_angle
+
+    @gradient_angle.setter
+    def gradient_angle(self, value):
+        lin = self._gradFill.lin
+        if lin is None:
+            raise ValueError("not a linear gradient")
+        lin.ang = 360.0 - value
+
+    @lazyproperty
+    def gradient_stops(self):
+        """|_GradientStops| object providing access to gradient colors.
+
+        Each stop represents a color between which the gradient smoothly
+        transitions.
+        """
+        return _GradientStops(self._gradFill.get_or_add_gsLst())
+
+    @property
+    def type(self):
+        return MSO_FILL.GRADIENT
+
+
+class _GrpFill(_Fill):
+    @property
+    def type(self):
+        return MSO_FILL.GROUP
+
+
+class _NoFill(_Fill):
+    @property
+    def type(self):
+        return MSO_FILL.BACKGROUND
+
+
+class _NoneFill(_Fill):
+    @property
+    def type(self):
+        return None
+
+
+class _PattFill(_Fill):
+    """Provides access to patterned fill properties."""
+
+    def __init__(self, pattFill):
+        super(_PattFill, self).__init__()
+        self._element = self._pattFill = pattFill
+
+    @lazyproperty
+    def back_color(self):
+        """Return |ColorFormat| object that controls background color."""
+        bgClr = self._pattFill.get_or_add_bgClr()
+        return ColorFormat.from_colorchoice_parent(bgClr)
+
+    @lazyproperty
+    def fore_color(self):
+        """Return |ColorFormat| object that controls foreground color."""
+        fgClr = self._pattFill.get_or_add_fgClr()
+        return ColorFormat.from_colorchoice_parent(fgClr)
+
+    @property
+    def pattern(self):
+        """Return member of :ref:`MsoPatternType` indicating fill pattern.
+
+        Returns |None| if no pattern has been set; PowerPoint may display the
+        default `PERCENT_5` pattern in this case. Assigning |None| will
+        remove any explicit pattern setting.
+        """
+        return self._pattFill.prst
+
+    @pattern.setter
+    def pattern(self, pattern_type):
+        self._pattFill.prst = pattern_type
+
+    @property
+    def type(self):
+        return MSO_FILL.PATTERNED
+
+
+class _SolidFill(_Fill):
+    """Provides access to fill properties such as color for solid fills."""
+
+    def __init__(self, solidFill):
+        super(_SolidFill, self).__init__()
+        self._solidFill = solidFill
+
+    @lazyproperty
+    def fore_color(self):
+        """Return |ColorFormat| object controlling fill color."""
+        return ColorFormat.from_colorchoice_parent(self._solidFill)
+
+    @property
+    def type(self):
+        return MSO_FILL.SOLID
+
+
+class _GradientStops(Sequence):
+    """Collection of |GradientStop| objects defining gradient colors.
+
+    A gradient must have a minimum of two stops, but can have as many more
+    than that as required to achieve the desired effect (three is perhaps
+    most common). Stops are sequenced in the order they are transitioned
+    through.
+    """
+
+    def __init__(self, gsLst):
+        self._gsLst = gsLst
+
+    def __getitem__(self, idx):
+        return _GradientStop(self._gsLst[idx])
+
+    def __len__(self):
+        return len(self._gsLst)
+
+
+class _GradientStop(ElementProxy):
+    """A single gradient stop.
+
+    A gradient stop defines a color and a position.
+    """
+
+    def __init__(self, gs):
+        super(_GradientStop, self).__init__(gs)
+        self._gs = gs
+
+    @lazyproperty
+    def color(self):
+        """Return |ColorFormat| object controlling stop color."""
+        return ColorFormat.from_colorchoice_parent(self._gs)
+
+    @property
+    def position(self):
+        """Location of stop in gradient path as float between 0.0 and 1.0.
+
+        The value represents a percentage, where 0.0 (0%) represents the
+        start of the path and 1.0 (100%) represents the end of the path. For
+        a linear gradient, these would represent opposing extents of the
+        filled area.
+        """
+        return self._gs.pos
+
+    @position.setter
+    def position(self, value):
+        self._gs.pos = float(value)

pptx/dml/line.py

@@ -0,0 +1,100 @@
+"""DrawingML objects related to line formatting."""
+
+from __future__ import annotations
+
+from pptx.dml.fill import FillFormat
+from pptx.enum.dml import MSO_FILL
+from pptx.util import Emu, lazyproperty
+
+
+class LineFormat(object):
+    """Provides access to line properties such as color, style, and width.
+
+    A LineFormat object is typically accessed via the ``.line`` property of
+    a shape such as |Shape| or |Picture|.
+    """
+
+    def __init__(self, parent):
+        super(LineFormat, self).__init__()
+        self._parent = parent
+
+    @lazyproperty
+    def color(self):
+        """
+        The |ColorFormat| instance that provides access to the color settings
+        for this line. Essentially a shortcut for ``line.fill.fore_color``.
+        As a side-effect, accessing this property causes the line fill type
+        to be set to ``MSO_FILL.SOLID``. If this sounds risky for your use
+        case, use ``line.fill.type`` to non-destructively discover the
+        existing fill type.
+        """
+        if self.fill.type != MSO_FILL.SOLID:
+            self.fill.solid()
+        return self.fill.fore_color
+
+    @property
+    def dash_style(self):
+        """Return value indicating line style.
+
+        Returns a member of :ref:`MsoLineDashStyle` indicating line style, or
+        |None| if no explicit value has been set. When no explicit value has
+        been set, the line dash style is inherited from the style hierarchy.
+
+        Assigning |None| removes any existing explicitly-defined dash style.
+        """
+        ln = self._ln
+        if ln is None:
+            return None
+        return ln.prstDash_val
+
+    @dash_style.setter
+    def dash_style(self, dash_style):
+        if dash_style is None:
+            ln = self._ln
+            if ln is None:
+                return
+            ln._remove_prstDash()
+            ln._remove_custDash()
+            return
+        ln = self._get_or_add_ln()
+        ln.prstDash_val = dash_style
+
+    @lazyproperty
+    def fill(self):
+        """
+        |FillFormat| instance for this line, providing access to fill
+        properties such as foreground color.
+        """
+        ln = self._get_or_add_ln()
+        return FillFormat.from_fill_parent(ln)
+
+    @property
+    def width(self):
+        """
+        The width of the line expressed as an integer number of :ref:`English
+        Metric Units <EMU>`. The returned value is an instance of |Length|,
+        a value class having properties such as `.inches`, `.cm`, and `.pt`
+        for converting the value into convenient units.
+        """
+        ln = self._ln
+        if ln is None:
+            return Emu(0)
+        return ln.w
+
+    @width.setter
+    def width(self, emu):
+        if emu is None:
+            emu = 0
+        ln = self._get_or_add_ln()
+        ln.w = emu
+
+    def _get_or_add_ln(self):
+        """
+        Return the ``<a:ln>`` element containing the line format properties
+        in the XML.
+        """
+        return self._parent.get_or_add_ln()
+
+    @property
+    def _ln(self):
+        return self._parent.ln

pptx/enum/action.py

@@ -0,0 +1,71 @@
+"""Enumerations that describe click-action settings."""
+
+from __future__ import annotations
+
+from pptx.enum.base import BaseEnum
+
+
+class PP_ACTION_TYPE(BaseEnum):
+    """
+    Specifies the type of a mouse action (click or hover action).
+
+    Alias: ``PP_ACTION``
+
+    Example::
+
+        from pptx.enum.action import PP_ACTION
+
+        assert shape.click_action.action == PP_ACTION.HYPERLINK
+
+    MS API name: `PpActionType`
+
+    https://msdn.microsoft.com/EN-US/library/office/ff744895.aspx
+    """
+
+    END_SHOW = (6, "Slide show ends.")
+    """Slide show ends."""
+
+    FIRST_SLIDE = (3, "Returns to the first slide.")
+    """Returns to the first slide."""
+
+    HYPERLINK = (7, "Hyperlink.")
+    """Hyperlink."""
+
+    LAST_SLIDE = (4, "Moves to the last slide.")
+    """Moves to the last slide."""
+
+    LAST_SLIDE_VIEWED = (5, "Moves to the last slide viewed.")
+    """Moves to the last slide viewed."""
+
+    NAMED_SLIDE = (101, "Moves to slide specified by slide number.")
+    """Moves to slide specified by slide number."""
+
+    NAMED_SLIDE_SHOW = (10, "Runs the slideshow.")
+    """Runs the slideshow."""
+
+    NEXT_SLIDE = (1, "Moves to the next slide.")
+    """Moves to the next slide."""
+
+    NONE = (0, "No action is performed.")
+    """No action is performed."""
+
+    OPEN_FILE = (102, "Opens the specified file.")
+    """Opens the specified file."""
+
+    OLE_VERB = (11, "OLE Verb.")
+    """OLE Verb."""
+
+    PLAY = (12, "Begins the slideshow.")
+    """Begins the slideshow."""
+
+    PREVIOUS_SLIDE = (2, "Moves to the previous slide.")
+    """Moves to the previous slide."""
+
+    RUN_MACRO = (8, "Runs a macro.")
+    """Runs a macro."""
+
+    RUN_PROGRAM = (9, "Runs a program.")
+    """Runs a program."""
+
+
+PP_ACTION = PP_ACTION_TYPE