ps-python-pptx 1.1.0__tar.gz → 1.3.0__tar.gz

{ps_python_pptx-1.1.0/src/ps_python_pptx.egg-info → ps_python_pptx-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ps-python-pptx
-Version: 1.1.0
+Version: 1.3.0
 Summary: Python-pptx fork with public APIs for themes, backgrounds, lists, and rich text.
 Author-email: Steve Canny <stcanny@gmail.com>
 License: MIT

{ps_python_pptx-1.1.0 → ps_python_pptx-1.3.0}/src/pptx/__init__.py

@@ -26,7 +26,7 @@ from pptx.parts.slide import (
 if TYPE_CHECKING:
     from pptx.opc.package import Part
 
-__version__ = "1.1.0"
+__version__ = "1.3.0"
 
 sys.modules["pptx.exceptions"] = exceptions
 del sys

{ps_python_pptx-1.1.0 → ps_python_pptx-1.3.0}/src/pptx/action.py

@@ -237,6 +237,29 @@ class Hyperlink(Subshape):
             hlink = self._get_or_add_hlink()
             hlink.rId = rId
 
+    @property
+    def screen_tip(self) -> str | None:
+        """Text shown by PowerPoint when pointing at this hyperlink.
+
+        Assign the address or action before setting a ScreenTip. Assigning None
+        or an empty string removes the tip without changing the link. Setting
+        a new address uses the existing address setter behavior and clears the
+        old tip. Reading this property does not create a hyperlink element.
+        """
+        hlink = self._hlink
+        return hlink.tooltip if hlink is not None else None
+
+    @screen_tip.setter
+    def screen_tip(self, value: str | None):
+        if value is not None and not isinstance(value, str):
+            raise TypeError("screen_tip must be a string or None")
+        hlink = self._hlink
+        if hlink is None:
+            if value:
+                raise ValueError("Set a hyperlink address or action before its ScreenTip")
+            return
+        hlink.tooltip = value or None
+
     def _get_or_add_hlink(self) -> CT_Hyperlink:
         """Get the `a:hlinkClick` or `a:hlinkHover` element for the Hyperlink object.
 

ps_python_pptx-1.3.0/src/pptx/background.py

@@ -0,0 +1,198 @@
+"""Read-only snapshots of slide background fills.
+
+This models the background fill, not graphics drawn on a slide or master.
+Unsupported fills are reported explicitly rather than changing the document.
+"""
+
+from __future__ import annotations
+
+import colorsys
+from dataclasses import dataclass
+
+from pptx.dml.color import RGBColor
+from pptx.enum.dml import MSO_THEME_COLOR
+from pptx.opc.constants import RELATIONSHIP_TYPE as RT
+from pptx.oxml.ns import qn
+
+
+@dataclass(frozen=True)
+class BackgroundInfo:
+    """Resolved background data, independent of the source XML.
+
+    kind is solid, gradient, picture, none, or unknown. Gradient angles are
+    counter-clockwise degrees. Picture crop values are fractional insets in
+    left, top, right, bottom order. Only stretched picture fills are supported.
+    reason explains unsupported data. No getter creates or changes XML.
+    """
+
+    kind: str
+    color: RGBColor | None = None
+    stops: tuple = ()
+    angle: float = 0.0
+    radial: bool = False
+    center: tuple = (0.5, 0.5)
+    image: bytes | None = None
+    crop: tuple = (0.0, 0.0, 0.0, 0.0)
+    reason: str | None = None
+
+
+def background_info(owner):
+    """Resolve inheritance and theme background styles without modifying XML."""
+    chain = [owner]
+    if hasattr(owner, "slide_layout"):
+        chain.append(owner.slide_layout)
+    if hasattr(chain[-1], "slide_master"):
+        chain.append(chain[-1].slide_master)
+    master = chain[-1]
+    try:
+        if any(rel.reltype == RT.THEME_OVERRIDE for item in chain for rel in item.part.rels.values()):
+            raise ValueError("theme overrides are not supported")
+        theme = master.theme
+        color_map = {}
+        for item in reversed(chain):
+            mapping = item._element.find(qn("p:clrMap"))
+            override = item._element.find(qn("p:clrMapOvr"))
+            if override is not None:
+                mapping = override.find(qn("a:overrideClrMapping"))
+            if mapping is not None:
+                color_map.update(mapping.attrib)
+        for item in chain:
+            bg = item._element.cSld.find(qn("p:bg"))
+            if bg is None:
+                continue
+            explicit = bg.find(qn("p:bgPr"))
+            if explicit is not None:
+                return _fill_info(explicit, item.part, theme, color_map)
+            reference = bg.find(qn("p:bgRef"))
+            if reference is None:
+                raise ValueError("background has no fill or style reference")
+            index = int(reference.get("idx", "0"))
+            if index == 0:
+                return BackgroundInfo("none")
+            path = "a:themeElements/a:fmtScheme/" + (
+                "a:bgFillStyleLst" if index >= 1001 else "a:fillStyleLst"
+            )
+            styles = theme._element
+            for name in path.split("/"):
+                styles = styles.find(qn(name))
+                if styles is None:
+                    raise ValueError("theme background style list is missing")
+            offset = index - 1001 if index >= 1001 else index - 1
+            if offset < 0 or offset >= len(styles):
+                raise ValueError("theme background style index is out of range")
+            placeholder = _color(reference, theme, color_map)
+            return _fill_info(
+                styles[offset], master.part.part_related_by(RT.THEME), theme, color_map, placeholder
+            )
+        return BackgroundInfo("solid", color=RGBColor(255, 255, 255))
+    except (ValueError, KeyError, AttributeError, TypeError) as exc:
+        return BackgroundInfo("unknown", reason=str(exc))
+
+
+def _color(parent, theme, mapping, placeholder=None):
+    choices = {"srgbClr", "schemeClr", "sysClr"}
+    node = next((child for child in parent if child.tag.rsplit("}", 1)[-1] in choices), None)
+    if node is None:
+        raise ValueError("unsupported or missing background color")
+    kind = node.tag.rsplit("}", 1)[-1]
+    if kind == "srgbClr":
+        rgb = RGBColor.from_string(node.get("val"))
+    elif kind == "sysClr":
+        rgb = RGBColor.from_string(node.get("lastClr"))
+    else:
+        slot = node.get("val")
+        if slot == "phClr":
+            if placeholder is None:
+                raise ValueError("unresolved placeholder color")
+            rgb = placeholder
+        else:
+            slot = mapping.get(slot, slot)
+            rgb = theme.color_scheme[MSO_THEME_COLOR.from_xml(slot)]
+    channels = tuple(c / 255 for c in rgb)
+    for transform in node:
+        name = transform.tag.rsplit("}", 1)[-1]
+        value = int(transform.get("val", "0")) / 100000
+        if name == "alpha" and value == 1:
+            continue
+        if name in {"lumMod", "lumOff", "satMod"}:
+            h, light, saturation = colorsys.rgb_to_hls(*channels)
+            if name == "lumMod":
+                light *= value
+            elif name == "lumOff":
+                light += value
+            else:
+                saturation *= value
+            channels = colorsys.hls_to_rgb(h, max(0, min(1, light)), max(0, min(1, saturation)))
+        elif name == "tint":
+            channels = tuple(1 - (1 - c) * value for c in channels)
+        elif name == "shade":
+            channels = tuple(c * value for c in channels)
+        else:
+            raise ValueError("unsupported background color transform: " + name)
+    return RGBColor(*(round(max(0, min(1, c)) * 255) for c in channels))
+
+
+def _fill_info(parent, part, theme, mapping, placeholder=None):
+    if any(parent.find(qn(name)) is not None for name in ("a:effectLst", "a:effectDag")):
+        effects = [parent.find(qn(name)) for name in ("a:effectLst", "a:effectDag")]
+        if any(effect is not None and len(effect) for effect in effects):
+            raise ValueError("background effects are not supported")
+    fills = {"solidFill", "gradFill", "blipFill", "noFill"}
+    tag = parent.tag.rsplit("}", 1)[-1]
+    node = (
+        parent
+        if tag in fills
+        else next((child for child in parent if child.tag.rsplit("}", 1)[-1] in fills), None)
+    )
+    if node is None:
+        raise ValueError("unsupported background fill")
+    kind = node.tag.rsplit("}", 1)[-1]
+    if kind == "noFill":
+        return BackgroundInfo("none")
+    if kind == "solidFill":
+        return BackgroundInfo("solid", color=_color(node, theme, mapping, placeholder))
+    if kind == "blipFill":
+        if node.find(qn("a:tile")) is not None:
+            raise ValueError("tiled background pictures are not supported")
+        stretch = node.find(qn("a:stretch"))
+        if stretch is None:
+            raise ValueError("background picture has no stretch geometry")
+        rect = stretch.find(qn("a:fillRect"))
+        if rect is not None and any(int(rect.get(k, "0")) for k in ("l", "t", "r", "b")):
+            raise ValueError("inset picture fills are not supported")
+        blip = node.find(qn("a:blip"))
+        if blip is None or len(blip):
+            raise ValueError("missing background picture or unsupported picture effects")
+        image = part.related_part(blip.get(qn("r:embed"))).blob
+        rect = node.find(qn("a:srcRect"))
+        crop = (
+            tuple(int(rect.get(k, "0")) / 100000 for k in ("l", "t", "r", "b"))
+            if rect is not None
+            else (0.0, 0.0, 0.0, 0.0)
+        )
+        return BackgroundInfo("picture", image=image, crop=crop)
+    stop_list = node.find(qn("a:gsLst"))
+    if stop_list is None or len(stop_list) < 2:
+        raise ValueError("background gradient needs at least two stops")
+    stops = tuple(
+        (int(s.get("pos")) / 100000, _color(s, theme, mapping, placeholder)) for s in stop_list
+    )
+    linear = node.find(qn("a:lin"))
+    if linear is not None:
+        if linear.get("scaled", "0") not in {"0", "false"}:
+            raise ValueError("scaled gradient geometry is not supported")
+        return BackgroundInfo(
+            "gradient", stops=stops, angle=(-int(linear.get("ang", "0")) / 60000) % 360
+        )
+    path = node.find(qn("a:path"))
+    if path is None or path.get("path") != "circle":
+        raise ValueError("unsupported gradient path")
+    rect = path.find(qn("a:fillToRect"))
+    values = (
+        tuple(int(rect.get(k, "0")) / 100000 for k in ("l", "t", "r", "b"))
+        if rect is not None
+        else (0.0, 0.0, 0.0, 0.0)
+    )
+    if abs(values[0] + values[2] - 1) > 0.00001 or abs(values[1] + values[3] - 1) > 0.00001:
+        raise ValueError("radial gradient focal region must be a point")
+    return BackgroundInfo("gradient", stops=stops, radial=True, center=values[:2])

{ps_python_pptx-1.1.0 → ps_python_pptx-1.3.0}/src/pptx/oxml/action.py

@@ -14,6 +14,8 @@ class CT_Hyperlink(BaseOxmlElement):
         "action", XsdString
     )
 
+    tooltip: str | None = OptionalAttribute("tooltip", XsdString)  # pyright: ignore[reportAssignmentType]
+
     @property
     def action_fields(self) -> dict[str, str]:
         """Query portion of the `ppaction://` URL as dict.

{ps_python_pptx-1.1.0 → ps_python_pptx-1.3.0}/src/pptx/slide.py

@@ -56,6 +56,13 @@ class _BaseSlide(PartElementProxy):
         """
         return _Background(self._element.cSld)
 
+    @property
+    def background_info(self):
+        """Read-only effective background fill snapshot, including inherited styles."""
+        from pptx.background import background_info
+
+        return background_info(self)
+
     def set_background_picture(self, image_file) -> None:
         """Use an image path or file-like object as a stretched slide background.
 

{ps_python_pptx-1.1.0 → ps_python_pptx-1.3.0}/src/pptx/text/text.py

@@ -488,6 +488,29 @@ class _Hyperlink(Subshape):
         if url:
             self._add_hlinkClick(url)
 
+    @property
+    def screen_tip(self) -> str | None:
+        """Text shown by PowerPoint when pointing at this hyperlink.
+
+        Assign the address or action before setting a ScreenTip. Assigning None
+        or an empty string removes the tip without changing the link. Setting
+        a new address uses the existing address setter behavior and clears the
+        old tip. Reading this property does not create a hyperlink element.
+        """
+        hlink = self._hlinkClick
+        return hlink.tooltip if hlink is not None else None
+
+    @screen_tip.setter
+    def screen_tip(self, value: str | None):
+        if value is not None and not isinstance(value, str):
+            raise TypeError("screen_tip must be a string or None")
+        hlink = self._hlinkClick
+        if hlink is None:
+            if value:
+                raise ValueError("Set a hyperlink address or action before its ScreenTip")
+            return
+        hlink.tooltip = value or None
+
     def _add_hlinkClick(self, url: str):
         rId = self.part.relate_to(url, RT.HYPERLINK, is_external=True)
         self._rPr.add_hlinkClick(rId)

{ps_python_pptx-1.1.0 → ps_python_pptx-1.3.0/src/ps_python_pptx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ps-python-pptx
-Version: 1.1.0
+Version: 1.3.0
 Summary: Python-pptx fork with public APIs for themes, backgrounds, lists, and rich text.
 Author-email: Steve Canny <stcanny@gmail.com>
 License: MIT

{ps_python_pptx-1.1.0 → ps_python_pptx-1.3.0}/src/ps_python_pptx.egg-info/SOURCES.txt

@@ -204,6 +204,7 @@ features/steps/test_files/extracted-pptx/ppt/theme/theme1.xml
 src/pptx/__init__.py
 src/pptx/action.py
 src/pptx/api.py
+src/pptx/background.py
 src/pptx/exc.py
 src/pptx/media.py
 src/pptx/package.py
@@ -324,11 +325,13 @@ tests/test_action.py
 tests/test_alternative_text_roundtrip.py
 tests/test_api.py
 tests/test_background_authoring_roundtrip.py
+tests/test_background_info.py
 tests/test_character_formatting_roundtrip.py
 tests/test_media.py
 tests/test_package.py
 tests/test_paragraph_formatting_roundtrip.py
 tests/test_presentation.py
+tests/test_screen_tips.py
 tests/test_shared.py
 tests/test_slide.py
 tests/test_slide_management_roundtrip.py

ps_python_pptx-1.3.0/tests/test_background_info.py

@@ -0,0 +1,91 @@
+"""Round-trip checks for the read-only background snapshot API."""
+
+import io
+
+from PIL import Image
+from pptx import Presentation
+from pptx.dml.color import RGBColor
+from pptx.enum.dml import MSO_THEME_COLOR
+from pptx.oxml.xmlchemy import OxmlElement
+
+
+def test_inherited_default_background_does_not_change_xml():
+    prs = Presentation()
+    slide = prs.slides.add_slide(prs.slide_layouts[1])
+    before = (slide._element.xml, slide.slide_layout._element.xml, prs.slide_master._element.xml)
+    info = slide.background_info
+    assert info.kind == "solid"
+    assert info.color == RGBColor(255, 255, 255)
+    assert before == (
+        slide._element.xml,
+        slide.slide_layout._element.xml,
+        prs.slide_master._element.xml,
+    )
+
+
+def test_layout_and_slide_overrides_resolve_theme_colors():
+    prs = Presentation()
+    layout = prs.slide_layouts[1]
+    layout.background.fill.solid()
+    layout.background.fill.fore_color.theme_color = MSO_THEME_COLOR.ACCENT_1
+    prs.slide_master.theme.color_scheme[MSO_THEME_COLOR.ACCENT_1] = RGBColor(20, 50, 80)
+    slide = prs.slides.add_slide(layout)
+    assert slide.background_info.color == RGBColor(20, 50, 80)
+    slide.background.fill.solid()
+    slide.background.fill.fore_color.rgb = RGBColor(40, 50, 60)
+    assert slide.background_info.color == RGBColor(40, 50, 60)
+    target = io.BytesIO()
+    prs.save(target)
+    assert Presentation(target).slides[0].background_info.color == RGBColor(40, 50, 60)
+
+
+def test_gradient_snapshot_includes_geometry_and_resolved_stops():
+    prs = Presentation()
+    slide = prs.slides.add_slide(prs.slide_layouts[1])
+    stops = [(0, RGBColor(0, 0, 0)), (1, RGBColor(255, 255, 255))]
+    slide.background.fill.set_gradient(stops, angle=135)
+    info = slide.background_info
+    assert info.kind == "gradient"
+    assert info.stops == tuple(stops)
+    assert info.angle == 135
+    assert not info.radial
+    slide.background.fill.set_gradient(stops, radial=True, center=(0.25, 0.75))
+    info = slide.background_info
+    assert info.radial and info.center == (0.25, 0.75)
+
+
+def test_picture_snapshot_returns_embedded_bytes():
+    image = io.BytesIO()
+    Image.new("RGB", (20, 10), "blue").save(image, format="PNG")
+    prs = Presentation()
+    prs.slide_master.set_background_picture(image)
+    slide = prs.slides.add_slide(prs.slide_layouts[1])
+    before = slide._element.xml
+    info = slide.background_info
+    assert info.kind == "picture"
+    assert info.image == image.getvalue()
+    assert before == slide._element.xml
+
+
+def test_unsupported_fill_is_reported_without_mutation():
+    prs = Presentation()
+    slide = prs.slides.add_slide(prs.slide_layouts[1])
+    slide.background.fill.patterned()
+    before = slide._element.xml
+    assert slide.background_info.kind == "unknown"
+    assert "unsupported" in slide.background_info.reason
+    assert before == slide._element.xml
+
+
+def test_brightness_transforms_are_resolved():
+    prs = Presentation()
+    slide = prs.slides.add_slide(prs.slide_layouts[1])
+    slide.background.fill.solid()
+    color = slide.background.fill.fore_color
+    color.rgb = RGBColor(255, 255, 255)
+    color.brightness = -0.5
+    assert slide.background_info.color == RGBColor(128, 128, 128)
+    alpha = OxmlElement("a:alpha")
+    alpha.set("val", "50000")
+    color._color._xClr.append(alpha)
+    assert slide.background_info.kind == "unknown"

ps_python_pptx-1.3.0/tests/test_screen_tips.py

@@ -0,0 +1,82 @@
+"""ScreenTips on text, shape click, and shape hover hyperlinks."""
+
+import io
+
+import pytest
+from pptx import Presentation
+from pptx.action import ActionSetting
+from pptx.enum.shapes import MSO_SHAPE
+from pptx.util import Inches
+
+
+def link(prs, kind):
+    slide = prs.slides.add_slide(prs.slide_layouts[6])
+    shape = slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, 0, 0, Inches(2), Inches(1))
+    if kind == "text":
+        run = shape.text_frame.paragraphs[0].add_run()
+        run.text = "Documentation"
+        return run.hyperlink
+    return (
+        shape.click_action
+        if kind == "click"
+        else ActionSetting(shape._element._nvXxPr.cNvPr, shape, hover=True)
+    ).hyperlink
+
+
+@pytest.mark.parametrize("kind", ["text", "click", "hover"])
+def test_screen_tip_round_trip_and_clear(kind):
+    prs = Presentation()
+    hyperlink = link(prs, kind)
+    hyperlink.address = "https://example.com"
+    hyperlink.screen_tip = 'Guide <&> "notes" café'
+    output = io.BytesIO()
+    prs.save(output)
+    shape = Presentation(output).slides[0].shapes[0]
+    restored = (
+        shape.text_frame.paragraphs[0].runs[0].hyperlink
+        if kind == "text"
+        else (
+            shape.click_action
+            if kind == "click"
+            else ActionSetting(shape._element._nvXxPr.cNvPr, shape, hover=True)
+        ).hyperlink
+    )
+    assert restored.screen_tip == 'Guide <&> "notes" café'
+    assert restored.address == "https://example.com"
+    restored.screen_tip = ""
+    assert restored.screen_tip is None
+    assert restored.address == "https://example.com"
+    restored.screen_tip = "Again"
+    restored.screen_tip = None
+    assert restored.address == "https://example.com"
+    assert restored.screen_tip is None
+
+
+@pytest.mark.parametrize("kind", ["text", "click", "hover"])
+def test_missing_link_is_not_created_by_screen_tip_access(kind):
+    prs = Presentation()
+    hyperlink = link(prs, kind)
+    slide = prs.slides[0]
+    before = slide._element.xml
+    assert hyperlink.screen_tip is None
+    hyperlink.screen_tip = None
+    hyperlink.screen_tip = ""
+    with pytest.raises(ValueError):
+        hyperlink.screen_tip = "No target"
+    with pytest.raises(TypeError):
+        hyperlink.screen_tip = 123
+    assert before == slide._element.xml
+
+
+@pytest.mark.parametrize("kind", ["text", "click", "hover"])
+def test_address_removal_clears_tip(kind):
+    prs = Presentation()
+    hyperlink = link(prs, kind)
+    hyperlink.address = "https://example.com"
+    hyperlink.screen_tip = "Old target"
+    hyperlink.address = "https://example.org"
+    assert hyperlink.screen_tip is None
+    hyperlink.screen_tip = "New target"
+    hyperlink.address = None
+    assert hyperlink.screen_tip is None
+    assert hyperlink.address is None