python-pptx2 2.13.0__py3-none-any.whl

pptx2/dml/line.py

@@ -0,0 +1,287 @@
+"""DrawingML objects related to line formatting."""
+
+from __future__ import annotations
+
+from pptx2.dml.color import _LazyColorFormat
+from pptx2.dml.fill import FillFormat
+from pptx2.enum.dml import MSO_LINE_JOIN_STYLE
+from pptx2.oxml.ns import qn
+from pptx2.util import Emu, lazyproperty
+
+
+_JOIN_TAG = {
+    MSO_LINE_JOIN_STYLE.ROUND: "a:round",
+    MSO_LINE_JOIN_STYLE.BEVEL: "a:bevel",
+    MSO_LINE_JOIN_STYLE.MITER: "a:miter",
+}
+_JOIN_FROM_TAG = {qn(tag): join for join, tag in _JOIN_TAG.items()}
+
+
+class LineEndFormat(object):
+    """Provides access to one end (head or tail) of a stroked line.
+
+    Wraps an ``<a:headEnd>`` or ``<a:tailEnd>`` element. The element is
+    created lazily; assigning |None| to a property removes the corresponding
+    attribute, and removing the last attribute drops the element entirely so
+    inheritance is not silently broken.
+    """
+
+    def __init__(self, line_format, end_tag):
+        # `end_tag` is "headEnd" or "tailEnd"
+        self._line_format = line_format
+        self._end_tag = end_tag
+
+    @property
+    def type(self):
+        """Arrowhead type as :ref:`MsoLineEndType`, or |None| if not set."""
+        end = self._end
+        if end is None:
+            return None
+        return end.type
+
+    @type.setter
+    def type(self, value):
+        self._set_attr("type", value)
+
+    @property
+    def width(self):
+        """Arrowhead width as :ref:`MsoLineEndSize`, or |None| if not set."""
+        end = self._end
+        if end is None:
+            return None
+        return end.w
+
+    @width.setter
+    def width(self, value):
+        self._set_attr("w", value)
+
+    @property
+    def length(self):
+        """Arrowhead length as :ref:`MsoLineEndSize`, or |None| if not set."""
+        end = self._end
+        if end is None:
+            return None
+        return end.len
+
+    @length.setter
+    def length(self, value):
+        self._set_attr("len", value)
+
+    @property
+    def _end(self):
+        ln = self._line_format._ln
+        if ln is None:
+            return None
+        return getattr(ln, self._end_tag)
+
+    def _set_attr(self, attr_name, value):
+        if value is None:
+            end = self._end
+            if end is None:
+                return
+            end.attrib.pop(attr_name, None)
+            if not end.attrib:
+                ln = self._line_format._ln
+                if ln is not None:
+                    getattr(ln, "_remove_%s" % self._end_tag)()
+            return
+        ln = self._line_format._get_or_add_ln()
+        end = getattr(ln, "get_or_add_%s" % self._end_tag)()
+        setattr(end, attr_name, value)
+
+
+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 color settings for this line; a shortcut for ``line.fill.fore_color``.
+
+        Reads are non-mutating: when no explicit ``<a:ln>`` element exists or its
+        fill is not solid, accessing color properties returns the "no explicit
+        color" sentinel (preserving theme inheritance) instead of injecting line
+        and fill XML. The line element and a solid fill are only created when
+        ``rgb`` or ``theme_color`` is assigned.
+        """
+        return _LazyColorFormat(peek_fill=self._peek_fill, ensure_fill=lambda: self.fill)
+
+    def _peek_fill(self):
+        """Return |FillFormat| for the current ``<a:ln>`` element, or |None|.
+
+        Read-only: never injects an ``<a:ln>`` element if one is not already
+        present.
+        """
+        ln = self._ln
+        if ln is None:
+            return None
+        return FillFormat.from_fill_parent(ln)
+
+    @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
+
+    @property
+    def cap(self):
+        """End-cap style as :ref:`MsoLineCapStyle`, or |None| if unset.
+
+        Maps to the ``cap`` attribute on ``<a:ln>``. Reads are non-mutating:
+        no ``<a:ln>`` element is created if one doesn't already exist.
+        """
+        ln = self._ln
+        if ln is None:
+            return None
+        return ln.cap
+
+    @cap.setter
+    def cap(self, value):
+        if value is None:
+            ln = self._ln
+            if ln is None:
+                return
+            ln.cap = None
+            return
+        ln = self._get_or_add_ln()
+        ln.cap = value
+
+    @property
+    def compound(self):
+        """Compound (multi-stroke) style as :ref:`MsoLineCompoundStyle`, or |None|.
+
+        Maps to the ``cmpd`` attribute on ``<a:ln>``.
+        """
+        ln = self._ln
+        if ln is None:
+            return None
+        return ln.cmpd
+
+    @compound.setter
+    def compound(self, value):
+        if value is None:
+            ln = self._ln
+            if ln is None:
+                return
+            ln.cmpd = None
+            return
+        ln = self._get_or_add_ln()
+        ln.cmpd = value
+
+    @property
+    def join(self):
+        """Corner-join style as :ref:`MsoLineJoinStyle`, or |None| if unset.
+
+        Returns whichever of ``<a:round/>``, ``<a:bevel/>``, or ``<a:miter/>``
+        is currently a child of ``<a:ln>``. Assigning |None| removes any
+        existing join element; assigning a member writes the matching
+        element (replacing any other join element if present).
+        """
+        ln = self._ln
+        if ln is None:
+            return None
+        join_elm = ln.eg_lineJoinProperties
+        if join_elm is None:
+            return None
+        return _JOIN_FROM_TAG.get(join_elm.tag)
+
+    @join.setter
+    def join(self, value):
+        if value is None:
+            ln = self._ln
+            if ln is None:
+                return
+            ln._remove_eg_lineJoinProperties()
+            return
+        if value not in _JOIN_TAG:
+            raise ValueError("invalid line-join style %r" % (value,))
+        ln = self._get_or_add_ln()
+        ln._remove_eg_lineJoinProperties()
+        # -- ZeroOrOneChoice's `_add_x` writes the child in the right slot --
+        getattr(ln, "_add_%s" % _JOIN_TAG[value].split(":", 1)[1])()
+
+    @lazyproperty
+    def head_end(self):
+        """:class:`LineEndFormat` for the start (head) of this line.
+
+        Provides access to the ``<a:headEnd>`` element's ``type``, ``width``,
+        and ``length`` attributes.
+        """
+        return LineEndFormat(self, "headEnd")
+
+    @lazyproperty
+    def tail_end(self):
+        """:class:`LineEndFormat` for the end (tail) of this line.
+
+        Provides access to the ``<a:tailEnd>`` element's ``type``, ``width``,
+        and ``length`` attributes.
+        """
+        return LineEndFormat(self, "tailEnd")
+
+    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

pptx2/dml/picture.py

@@ -0,0 +1,212 @@
+"""Picture image effects: transparency, brightness, contrast, and recolor."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pptx2.dml.color import RGBColor
+    from pptx2.oxml.dml.fill import CT_Blip
+
+
+# Sepia duotone: dark warm brown → light cream, matching PowerPoint's built-in preset.
+_SEPIA_DARK = "532400"
+_SEPIA_LIGHT = "FFEFCA"
+
+
+class PictureEffects:
+    """Provides access to image-level visual effects on a |Picture| shape.
+
+    Exposes transparency (alpha), brightness, contrast, and recolor.  All reads
+    are non-mutating — if no explicit effect is present the property returns a
+    neutral sentinel value (``0.0`` for numeric adjustments, ``None`` for recolor).
+    Writes lazily create the required ``<a:blip>`` child elements.
+
+    Access via :attr:`pptx2.shapes.picture.Picture.effects`.
+    """
+
+    def __init__(self, blip: CT_Blip):
+        self._blip = blip
+
+    # ------------------------------------------------------------------
+    # transparency
+    # ------------------------------------------------------------------
+
+    @property
+    def transparency(self) -> float:
+        """Read/write float in ``[0.0, 1.0]``: ``0.0`` = fully opaque (default), ``1.0`` = invisible.
+
+        Maps to ``<a:alphaModFix amt="N"/>`` where ``amt`` is the *remaining* opacity
+        (``100000`` = fully opaque).  Setting to ``0.0`` removes the element entirely,
+        restoring full opacity.
+        """
+        alphaModFix = self._blip.alphaModFix
+        if alphaModFix is None:
+            return 0.0
+        amt = alphaModFix.amt
+        return round(1.0 - amt, 10)
+
+    @transparency.setter
+    def transparency(self, value: float) -> None:
+        if not 0.0 <= value <= 1.0:
+            raise ValueError(f"transparency must be between 0.0 and 1.0, got {value!r}")
+        if value == 0.0:
+            self._blip._remove_alphaModFix()  # pyright: ignore[reportPrivateUsage]
+        else:
+            self._blip.get_or_add_alphaModFix().amt = 1.0 - value  # type: ignore[assignment]
+
+    # ------------------------------------------------------------------
+    # brightness
+    # ------------------------------------------------------------------
+
+    @property
+    def brightness(self) -> float:
+        """Read/write float in ``[-1.0, 1.0]``: ``0.0`` = no change (default).
+
+        Maps to the ``bright`` attribute of ``<a:lum>``.  A value of ``0.4``
+        means +40% brightness; ``-0.25`` means 25% darker.
+        """
+        lum = self._blip.lum
+        return 0.0 if lum is None else lum.bright
+
+    @brightness.setter
+    def brightness(self, value: float) -> None:
+        if not -1.0 <= value <= 1.0:
+            raise ValueError(f"brightness must be between -1.0 and 1.0, got {value!r}")
+        if value == 0.0 and self._blip.lum is None:
+            return  # -- "no change" on a picture with no `a:lum`: nothing to write
+        lum = self._blip.get_or_add_lum()
+        lum.bright = value  # type: ignore[assignment]
+        self._drop_lum_if_neutral()
+
+    # ------------------------------------------------------------------
+    # contrast
+    # ------------------------------------------------------------------
+
+    @property
+    def contrast(self) -> float:
+        """Read/write float in ``[-1.0, 1.0]``: ``0.0`` = no change (default).
+
+        Maps to the ``contrast`` attribute of ``<a:lum>``.  Shares the same
+        ``<a:lum>`` element as :attr:`brightness`.
+        """
+        lum = self._blip.lum
+        return 0.0 if lum is None else lum.contrast
+
+    @contrast.setter
+    def contrast(self, value: float) -> None:
+        if not -1.0 <= value <= 1.0:
+            raise ValueError(f"contrast must be between -1.0 and 1.0, got {value!r}")
+        if value == 0.0 and self._blip.lum is None:
+            return  # -- "no change" on a picture with no `a:lum`: nothing to write
+        lum = self._blip.get_or_add_lum()
+        lum.contrast = value  # type: ignore[assignment]
+        self._drop_lum_if_neutral()
+
+    def _drop_lum_if_neutral(self) -> None:
+        """Remove `a:lum` once both adjustments are back at their defaults.
+
+        Writing ``0.0`` drops the corresponding attribute (the schema
+        default), so a lum whose adjustments are both reset would otherwise
+        linger as a dead empty ``<a:lum/>``.
+        """
+        lum = self._blip.lum
+        if lum is not None and lum.get("bright") is None and lum.get("contrast") is None:
+            self._blip.remove(lum)
+
+    # ------------------------------------------------------------------
+    # recolor
+    # ------------------------------------------------------------------
+
+    @property
+    def recolor(self) -> str | None:
+        """Read/write recolor mode.  One of ``"grayscale"``, ``"washout"``,
+        ``"sepia"``, ``"duotone"``, or ``None`` (no recolor).
+
+        Assigning a value removes any previously applied recolor before
+        applying the new one.  Setting to ``None`` clears recolor entirely.
+        For custom duotone colors use :meth:`set_duotone`.
+        """
+        if self._blip.grayscl is not None:
+            return "grayscale"
+        biLevel = self._blip.biLevel
+        if biLevel is not None:
+            return "washout"
+        duotone = self._blip.duotone
+        if duotone is not None:
+            children = list(duotone)
+            if len(children) == 2:
+                from pptx2.oxml.ns import qn
+
+                vals = [c.get("val") for c in children if c.tag == qn("a:srgbClr")]
+                if vals == [_SEPIA_DARK, _SEPIA_LIGHT]:
+                    return "sepia"
+            return "duotone"
+        return None
+
+    @recolor.setter
+    def recolor(self, value: str | None) -> None:
+        # Validate before mutating so an invalid value leaves the existing effect intact.
+        _VALID_RECOLOR = frozenset({"grayscale", "washout", "sepia", "duotone"})
+        if value is not None and value not in _VALID_RECOLOR:
+            raise ValueError(
+                f"recolor must be 'grayscale', 'washout', 'sepia', 'duotone', or None; got {value!r}"
+            )
+        self._clear_recolor()
+        if value is None:
+            return
+        if value == "grayscale":
+            self._blip.get_or_add_grayscl()
+        elif value == "washout":
+            self._blip.get_or_add_biLevel().thresh = 0.5  # type: ignore[assignment]
+        elif value == "sepia":
+            self.set_duotone(_SEPIA_DARK, _SEPIA_LIGHT)
+        elif value == "duotone":
+            # Default neutral duotone (dark grey → light grey).
+            # For custom colors use set_duotone() instead.
+            self.set_duotone("333333", "EBEBEB")
+
+    def set_duotone(self, dark_color: RGBColor | tuple, light_color: RGBColor | tuple) -> None:
+        """Apply a duotone recolor using custom dark and light colors.
+
+        Each color can be an :class:`~pptx2.dml.color.RGBColor` instance or a
+        3-tuple of ``(r, g, b)`` integers.  The dark color maps to shadows, the
+        light color to highlights.
+        """
+        self._clear_recolor()
+        from lxml import etree
+
+        from pptx2.oxml.ns import qn
+
+        duotone = self._blip.get_or_add_duotone()
+        for child in list(duotone):
+            duotone.remove(child)
+        for hex_val in (_color_to_hex(dark_color), _color_to_hex(light_color)):
+            clr = etree.SubElement(duotone, qn("a:srgbClr"))
+            clr.set("val", hex_val)
+
+    # ------------------------------------------------------------------
+    # internals
+    # ------------------------------------------------------------------
+
+    def _clear_recolor(self) -> None:
+        """Remove any existing recolor effects from the blip."""
+        self._blip._remove_grayscl()  # pyright: ignore[reportPrivateUsage]
+        self._blip._remove_biLevel()  # pyright: ignore[reportPrivateUsage]
+        self._blip._remove_duotone()  # pyright: ignore[reportPrivateUsage]
+
+
+def _color_to_hex(color: RGBColor | tuple | str) -> str:
+    """Return uppercase 6-char hex string for *color*.
+
+    Accepts an :class:`~pptx2.dml.color.RGBColor`, a hex string (with or
+    without ``#``), or a 3-tuple of ``(r, g, b)`` integers.
+    """
+    from pptx2.dml.color import RGBColor as _RGBColor
+
+    if isinstance(color, _RGBColor):
+        return str(color).upper()
+    if isinstance(color, str):
+        return color.upper().lstrip("#")
+    r, g, b = color
+    return f"{r:02X}{g:02X}{b:02X}"