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

{ps_python_pptx-1.2.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.2.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.2.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.2.0"
+__version__ = "1.3.0"
 
 sys.modules["pptx.exceptions"] = exceptions
 del sys

{ps_python_pptx-1.2.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.2.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.2.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.2.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.2.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.2.0 → ps_python_pptx-1.3.0}/src/ps_python_pptx.egg-info/SOURCES.txt

@@ -331,6 +331,7 @@ 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_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