Merge pull request #6 from MHoroszowski/feature/shadow-effects

MHoroszowski · web-flow · commit 14ee64cf8947 · 2026-03-22T13:50:24.000-04:00
feature: add full shadow effect API to ShadowFormat
diff --git a/src/pptx/dml/effect.py b/src/pptx/dml/effect.py
@@ -2,6 +2,15 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
+from pptx.dml.color import ColorFormat
+from pptx.util import Emu, lazyproperty
+
+if TYPE_CHECKING:
+    from pptx.oxml.dml.effect import CT_OuterShadowEffect
+    from pptx.util import Length
+
 
 class ShadowFormat(object):
     """Provides access to shadow effect on a shape."""
@@ -10,6 +19,71 @@ def __init__(self, spPr):
         # ---spPr may also be a grpSpPr; both have a:effectLst child---
         self._element = spPr
 
+    @property
+    def angle(self) -> float | None:
+        """Direction of shadow in degrees (0 = right, 90 = below, etc.).
+
+        Read/write. Returns |None| if no shadow is explicitly defined. Setting this property
+        creates an outer shadow if one doesn't exist.
+        """
+        outerShdw = self._outerShdw
+        if outerShdw is None:
+            return None
+        return outerShdw.dir
+
+    @angle.setter
+    def angle(self, value: float | None) -> None:
+        if value is None:
+            return
+        outerShdw = self._get_or_add_outerShdw()
+        outerShdw.dir = value
+
+    @property
+    def blur_radius(self) -> Length | None:
+        """Blur radius of shadow in EMU.
+
+        Read/write. Returns |None| if no shadow is explicitly defined.
+        """
+        outerShdw = self._outerShdw
+        if outerShdw is None:
+            return None
+        return Emu(outerShdw.blurRad)
+
+    @blur_radius.setter
+    def blur_radius(self, value: Length | None) -> None:
+        if value is None:
+            return
+        outerShdw = self._get_or_add_outerShdw()
+        outerShdw.blurRad = int(value)
+
+    @lazyproperty
+    def color(self) -> ColorFormat:
+        """Color of the shadow.
+
+        Returns a |ColorFormat| object. Setting color properties creates an outer shadow with a
+        solid color fill if one doesn't exist.
+        """
+        outerShdw = self._get_or_add_outerShdw()
+        return ColorFormat.from_colorchoice_parent(outerShdw)
+
+    @property
+    def distance(self) -> Length | None:
+        """Distance of shadow from shape in EMU.
+
+        Read/write. Returns |None| if no shadow is explicitly defined.
+        """
+        outerShdw = self._outerShdw
+        if outerShdw is None:
+            return None
+        return Emu(outerShdw.dist)
+
+    @distance.setter
+    def distance(self, value: Length | None) -> None:
+        if value is None:
+            return
+        outerShdw = self._get_or_add_outerShdw()
+        outerShdw.dist = int(value)
+
     @property
     def inherit(self):
         """True if shape inherits shadow settings.
@@ -39,3 +113,52 @@ def inherit(self, value):
         else:
             # ---ensure at least the effectLst element is present
             self._element.get_or_add_effectLst()
+
+    @property
+    def rotate_with_shape(self) -> bool | None:
+        """Whether the shadow rotates with the shape.
+
+        Read/write. Returns |None| if no shadow is explicitly defined.
+        """
+        outerShdw = self._outerShdw
+        if outerShdw is None:
+            return None
+        return outerShdw.rotWithShape
+
+    @rotate_with_shape.setter
+    def rotate_with_shape(self, value: bool | None) -> None:
+        if value is None:
+            return
+        outerShdw = self._get_or_add_outerShdw()
+        outerShdw.rotWithShape = value
+
+    @property
+    def visible(self) -> bool:
+        """Whether a shadow is visible on this shape.
+
+        Read/write. Returns |True| if an outer shadow element is present. Assigning |True| creates
+        a default outer shadow. Assigning |False| removes any outer shadow.
+        """
+        return self._outerShdw is not None
+
+    @visible.setter
+    def visible(self, value: bool) -> None:
+        if value:
+            self._get_or_add_outerShdw()
+        else:
+            effectLst = self._element.effectLst
+            if effectLst is not None:
+                effectLst._remove_outerShdw()
+
+    def _get_or_add_outerShdw(self) -> CT_OuterShadowEffect:
+        """Return the `a:outerShdw` element, creating parent elements as needed."""
+        effectLst = self._element.get_or_add_effectLst()
+        return effectLst.get_or_add_outerShdw()
+
+    @property
+    def _outerShdw(self) -> CT_OuterShadowEffect | None:
+        """Return `a:outerShdw` element or None if not present."""
+        effectLst = self._element.effectLst
+        if effectLst is None:
+            return None
+        return effectLst.outerShdw
diff --git a/src/pptx/oxml/__init__.py b/src/pptx/oxml/__init__.py
@@ -267,6 +267,17 @@ def register_element_cls(nsptagname: str, cls: Type[BaseOxmlElement]):
 register_element_cls("a:srcRect", CT_RelativeRect)
 
 
+from pptx.oxml.dml.effect import (  # noqa: E402
+    CT_EffectList,
+    CT_InnerShadowEffect,
+    CT_OuterShadowEffect,
+)
+
+register_element_cls("a:effectLst", CT_EffectList)
+register_element_cls("a:innerShdw", CT_InnerShadowEffect)
+register_element_cls("a:outerShdw", CT_OuterShadowEffect)
+
+
 from pptx.oxml.dml.line import CT_PresetLineDashProperties  # noqa: E402
 
 register_element_cls("a:prstDash", CT_PresetLineDashProperties)
diff --git a/src/pptx/oxml/dml/effect.py b/src/pptx/oxml/dml/effect.py
@@ -0,0 +1,82 @@
+"""lxml custom element classes for DrawingML effect-related XML elements."""
+
+from __future__ import annotations
+
+from typing import Callable, cast
+
+from pptx.oxml import parse_xml
+from pptx.oxml.ns import nsdecls
+from pptx.oxml.simpletypes import ST_Angle, ST_PositiveCoordinate, XsdBoolean
+from pptx.oxml.xmlchemy import (
+    BaseOxmlElement,
+    Choice,
+    OptionalAttribute,
+    ZeroOrOne,
+    ZeroOrOneChoice,
+)
+
+
+class CT_OuterShadowEffect(BaseOxmlElement):
+    """`a:outerShdw` custom element class."""
+
+    eg_colorChoice = ZeroOrOneChoice(
+        (
+            Choice("a:scrgbClr"),
+            Choice("a:srgbClr"),
+            Choice("a:hslClr"),
+            Choice("a:sysClr"),
+            Choice("a:schemeClr"),
+            Choice("a:prstClr"),
+        ),
+        successors=(),
+    )
+    blurRad = OptionalAttribute("blurRad", ST_PositiveCoordinate, default=0)
+    dist = OptionalAttribute("dist", ST_PositiveCoordinate, default=0)
+    dir = OptionalAttribute("dir", ST_Angle, default=0)
+    rotWithShape: bool = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
+        "rotWithShape", XsdBoolean, default=True
+    )
+
+
+class CT_InnerShadowEffect(BaseOxmlElement):
+    """`a:innerShdw` custom element class."""
+
+    blurRad = OptionalAttribute("blurRad", ST_PositiveCoordinate, default=0)
+    dist = OptionalAttribute("dist", ST_PositiveCoordinate, default=0)
+    dir = OptionalAttribute("dir", ST_Angle, default=0)
+
+
+class CT_EffectList(BaseOxmlElement):
+    """`a:effectLst` custom element class."""
+
+    get_or_add_outerShdw: Callable[[], CT_OuterShadowEffect]
+    _remove_outerShdw: Callable[[], None]
+    _remove_innerShdw: Callable[[], None]
+
+    _tag_seq = ("a:blur", "a:fillOverlay", "a:glow", "a:innerShdw", "a:outerShdw",
+                "a:prstShdw", "a:reflection", "a:softEdge")
+    innerShdw: CT_InnerShadowEffect | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:innerShdw", successors=_tag_seq[4:]
+    )
+    outerShdw: CT_OuterShadowEffect | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:outerShdw", successors=_tag_seq[5:]
+    )
+    del _tag_seq
+
+    def _new_outerShdw(self) -> CT_OuterShadowEffect:
+        """Return a new `a:outerShdw` element with default shadow properties.
+
+        PowerPoint requires a color child element on `a:outerShdw`, so this provides a reasonable
+        default: 45-degree angle, 3pt distance, 4pt blur, 40% transparent black.
+        """
+        return cast(
+            CT_OuterShadowEffect,
+            parse_xml(
+                f'<a:outerShdw {nsdecls("a")} blurRad="50800" dist="38100"'
+                f' dir="2700000" algn="tl" rotWithShape="0">'
+                f'  <a:srgbClr val="000000">'
+                f'    <a:alpha val="40000"/>'
+                f"  </a:srgbClr>"
+                f"</a:outerShdw>"
+            ),
+        )
diff --git a/tests/dml/test_effect.py b/tests/dml/test_effect.py
@@ -4,12 +4,114 @@
 
 import pytest
 
+from pptx.dml.color import ColorFormat
 from pptx.dml.effect import ShadowFormat
+from pptx.util import Emu, Pt
 
 from ..unitutil.cxml import element, xml
 
 
 class DescribeShadowFormat(object):
+    @pytest.mark.parametrize(
+        ("spPr_cxml", "expected_value"),
+        [
+            ("p:spPr", False),
+            ("p:spPr/a:effectLst", False),
+            ("p:spPr/a:effectLst/a:outerShdw", True),
+        ],
+    )
+    def it_knows_whether_a_shadow_is_visible(self, spPr_cxml: str, expected_value: bool):
+        shadow = ShadowFormat(element(spPr_cxml))
+        assert shadow.visible is expected_value
+
+    def it_can_make_a_shadow_visible(self):
+        spPr = element("p:spPr")
+        shadow = ShadowFormat(spPr)
+        shadow.visible = True
+        assert shadow.visible is True
+        assert spPr.effectLst is not None
+        assert spPr.effectLst.outerShdw is not None
+
+    def it_can_make_a_shadow_invisible(self):
+        spPr = element("p:spPr/a:effectLst/a:outerShdw")
+        shadow = ShadowFormat(spPr)
+        shadow.visible = False
+        assert shadow.visible is False
+
+    @pytest.mark.parametrize(
+        ("spPr_cxml", "expected_value"),
+        [
+            ("p:spPr", None),
+            ("p:spPr/a:effectLst", None),
+            ("p:spPr/a:effectLst/a:outerShdw", 0.0),
+            ("p:spPr/a:effectLst/a:outerShdw{dir=2700000}", 45.0),
+            ("p:spPr/a:effectLst/a:outerShdw{dir=5400000}", 90.0),
+        ],
+    )
+    def it_knows_the_shadow_angle(self, spPr_cxml: str, expected_value: float | None):
+        shadow = ShadowFormat(element(spPr_cxml))
+        assert shadow.angle == expected_value
+
+    def it_can_set_the_shadow_angle(self):
+        spPr = element("p:spPr")
+        shadow = ShadowFormat(spPr)
+        shadow.angle = 45.0
+        assert shadow.angle == 45.0
+
+    @pytest.mark.parametrize(
+        ("spPr_cxml", "expected_value"),
+        [
+            ("p:spPr", None),
+            ("p:spPr/a:effectLst/a:outerShdw", 0),
+            ("p:spPr/a:effectLst/a:outerShdw{blurRad=50800}", 50800),
+        ],
+    )
+    def it_knows_the_blur_radius(self, spPr_cxml: str, expected_value: int | None):
+        shadow = ShadowFormat(element(spPr_cxml))
+        assert shadow.blur_radius == expected_value
+
+    def it_can_set_the_blur_radius(self):
+        spPr = element("p:spPr")
+        shadow = ShadowFormat(spPr)
+        shadow.blur_radius = Pt(4)
+        assert shadow.blur_radius == Pt(4)
+
+    @pytest.mark.parametrize(
+        ("spPr_cxml", "expected_value"),
+        [
+            ("p:spPr", None),
+            ("p:spPr/a:effectLst/a:outerShdw", 0),
+            ("p:spPr/a:effectLst/a:outerShdw{dist=38100}", 38100),
+        ],
+    )
+    def it_knows_the_shadow_distance(self, spPr_cxml: str, expected_value: int | None):
+        shadow = ShadowFormat(element(spPr_cxml))
+        assert shadow.distance == expected_value
+
+    def it_can_set_the_shadow_distance(self):
+        spPr = element("p:spPr")
+        shadow = ShadowFormat(spPr)
+        shadow.distance = Pt(3)
+        assert shadow.distance == Pt(3)
+
+    def it_provides_access_to_the_shadow_color(self):
+        spPr = element("p:spPr")
+        shadow = ShadowFormat(spPr)
+        assert isinstance(shadow.color, ColorFormat)
+
+    @pytest.mark.parametrize(
+        ("spPr_cxml", "expected_value"),
+        [
+            ("p:spPr", None),
+            ("p:spPr/a:effectLst/a:outerShdw", True),
+            ("p:spPr/a:effectLst/a:outerShdw{rotWithShape=0}", False),
+            ("p:spPr/a:effectLst/a:outerShdw{rotWithShape=1}", True),
+        ],
+    )
+    def it_knows_rotate_with_shape(self, spPr_cxml: str, expected_value: bool | None):
+        shadow = ShadowFormat(element(spPr_cxml))
+        assert shadow.rotate_with_shape == expected_value
+
     def it_knows_whether_it_inherits(self, inherit_get_fixture):
         shadow, expected_value = inherit_get_fixture
         inherit = shadow.inherit
