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

pptx/__init__.py

@@ -0,0 +1,84 @@
+"""Initialization module for python-pptx package."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+import pptx.exc as exceptions
+from pptx.api import Presentation
+from pptx.opc.constants import CONTENT_TYPE as CT
+from pptx.opc.package import PartFactory
+from pptx.parts.chart import ChartPart
+from pptx.parts.coreprops import CorePropertiesPart
+from pptx.parts.image import ImagePart
+from pptx.parts.media import MediaPart
+from pptx.parts.theme import ThemePart
+from pptx.parts.presentation import PresentationPart
+from pptx.parts.slide import (
+    NotesMasterPart,
+    NotesSlidePart,
+    SlideLayoutPart,
+    SlideMasterPart,
+    SlidePart,
+)
+
+if TYPE_CHECKING:
+    from pptx.opc.package import Part
+
+__version__ = "1.1.0"
+
+sys.modules["pptx.exceptions"] = exceptions
+del sys
+
+__all__ = ["Presentation"]
+
+content_type_to_part_class_map: dict[str, type[Part]] = {
+    CT.PML_PRESENTATION_MAIN: PresentationPart,
+    CT.PML_PRES_MACRO_MAIN: PresentationPart,
+    CT.PML_TEMPLATE_MAIN: PresentationPart,
+    CT.PML_SLIDESHOW_MAIN: PresentationPart,
+    CT.OPC_CORE_PROPERTIES: CorePropertiesPart,
+    CT.PML_NOTES_MASTER: NotesMasterPart,
+    CT.PML_NOTES_SLIDE: NotesSlidePart,
+    CT.PML_SLIDE: SlidePart,
+    CT.PML_SLIDE_LAYOUT: SlideLayoutPart,
+    CT.PML_SLIDE_MASTER: SlideMasterPart,
+    CT.DML_CHART: ChartPart,
+    CT.OFC_THEME: ThemePart,
+    CT.BMP: ImagePart,
+    CT.GIF: ImagePart,
+    CT.JPEG: ImagePart,
+    CT.MS_PHOTO: ImagePart,
+    CT.PNG: ImagePart,
+    CT.TIFF: ImagePart,
+    CT.X_EMF: ImagePart,
+    CT.X_WMF: ImagePart,
+    CT.ASF: MediaPart,
+    CT.AVI: MediaPart,
+    CT.MOV: MediaPart,
+    CT.MP4: MediaPart,
+    CT.MPG: MediaPart,
+    CT.MS_VIDEO: MediaPart,
+    CT.SWF: MediaPart,
+    CT.VIDEO: MediaPart,
+    CT.WMV: MediaPart,
+    CT.X_MS_VIDEO: MediaPart,
+    # -- accommodate "image/jpg" as an alias for "image/jpeg" --
+    "image/jpg": ImagePart,
+}
+
+PartFactory.part_type_for.update(content_type_to_part_class_map)
+
+del (
+    ChartPart,
+    CorePropertiesPart,
+    ImagePart,
+    MediaPart,
+    SlidePart,
+    SlideLayoutPart,
+    SlideMasterPart,
+    PresentationPart,
+    CT,
+    PartFactory,
+)

pptx/action.py

@@ -0,0 +1,270 @@
+"""Objects related to mouse click and hover actions on a shape or text."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from pptx.enum.action import PP_ACTION
+from pptx.opc.constants import RELATIONSHIP_TYPE as RT
+from pptx.shapes import Subshape
+from pptx.util import lazyproperty
+
+if TYPE_CHECKING:
+    from pptx.oxml.action import CT_Hyperlink
+    from pptx.oxml.shapes.shared import CT_NonVisualDrawingProps
+    from pptx.oxml.text import CT_TextCharacterProperties
+    from pptx.parts.slide import SlidePart
+    from pptx.shapes.base import BaseShape
+    from pptx.slide import Slide, Slides
+
+
+class ActionSetting(Subshape):
+    """Properties specifying how a shape or run reacts to mouse actions."""
+
+    # -- The Subshape base class provides access to the Slide Part, which is needed to access
+    # -- relationships, which is where hyperlinks live.
+
+    def __init__(
+        self,
+        xPr: CT_NonVisualDrawingProps | CT_TextCharacterProperties,
+        parent: BaseShape,
+        hover: bool = False,
+    ):
+        super(ActionSetting, self).__init__(parent)
+        # xPr is either a cNvPr or rPr element
+        self._element = xPr
+        # _hover determines use of `a:hlinkClick` or `a:hlinkHover`
+        self._hover = hover
+
+    @property
+    def action(self):
+        """Member of :ref:`PpActionType` enumeration, such as `PP_ACTION.HYPERLINK`.
+
+        The returned member indicates the type of action that will result when the
+        specified shape or text is clicked or the mouse pointer is positioned over the
+        shape during a slide show.
+
+        If there is no click-action or the click-action value is not recognized (is not
+        one of the official `MsoPpAction` values) then `PP_ACTION.NONE` is returned.
+        """
+        hlink = self._hlink
+
+        if hlink is None:
+            return PP_ACTION.NONE
+
+        action_verb = hlink.action_verb
+
+        if action_verb == "hlinkshowjump":
+            relative_target = hlink.action_fields["jump"]
+            return {
+                "firstslide": PP_ACTION.FIRST_SLIDE,
+                "lastslide": PP_ACTION.LAST_SLIDE,
+                "lastslideviewed": PP_ACTION.LAST_SLIDE_VIEWED,
+                "nextslide": PP_ACTION.NEXT_SLIDE,
+                "previousslide": PP_ACTION.PREVIOUS_SLIDE,
+                "endshow": PP_ACTION.END_SHOW,
+            }[relative_target]
+
+        return {
+            None: PP_ACTION.HYPERLINK,
+            "hlinksldjump": PP_ACTION.NAMED_SLIDE,
+            "hlinkpres": PP_ACTION.PLAY,
+            "hlinkfile": PP_ACTION.OPEN_FILE,
+            "customshow": PP_ACTION.NAMED_SLIDE_SHOW,
+            "ole": PP_ACTION.OLE_VERB,
+            "macro": PP_ACTION.RUN_MACRO,
+            "program": PP_ACTION.RUN_PROGRAM,
+        }.get(action_verb, PP_ACTION.NONE)
+
+    @lazyproperty
+    def hyperlink(self) -> Hyperlink:
+        """
+        A |Hyperlink| object representing the hyperlink action defined on
+        this click or hover mouse event. A |Hyperlink| object is always
+        returned, even if no hyperlink or other click action is defined.
+        """
+        return Hyperlink(self._element, self._parent, self._hover)
+
+    @property
+    def target_slide(self) -> Slide | None:
+        """
+        A reference to the slide in this presentation that is the target of
+        the slide jump action in this shape. Slide jump actions include
+        `PP_ACTION.FIRST_SLIDE`, `LAST_SLIDE`, `NEXT_SLIDE`,
+        `PREVIOUS_SLIDE`, and `NAMED_SLIDE`. Returns |None| for all other
+        actions. In particular, the `LAST_SLIDE_VIEWED` action and the `PLAY`
+        (start other presentation) actions are not supported.
+
+        A slide object may be assigned to this property, which makes the
+        shape an "internal hyperlink" to the assigened slide::
+
+            slide, target_slide = prs.slides[0], prs.slides[1]
+            shape = slide.shapes[0]
+            shape.target_slide = target_slide
+
+        Assigning |None| removes any slide jump action. Note that this is
+        accomplished by removing any action present (such as a hyperlink),
+        without first checking that it is a slide jump action.
+        """
+        slide_jump_actions = (
+            PP_ACTION.FIRST_SLIDE,
+            PP_ACTION.LAST_SLIDE,
+            PP_ACTION.NEXT_SLIDE,
+            PP_ACTION.PREVIOUS_SLIDE,
+            PP_ACTION.NAMED_SLIDE,
+        )
+
+        if self.action not in slide_jump_actions:
+            return None
+
+        if self.action == PP_ACTION.FIRST_SLIDE:
+            return self._slides[0]
+        elif self.action == PP_ACTION.LAST_SLIDE:
+            return self._slides[-1]
+        elif self.action == PP_ACTION.NEXT_SLIDE:
+            next_slide_idx = self._slide_index + 1
+            if next_slide_idx >= len(self._slides):
+                raise ValueError("no next slide")
+            return self._slides[next_slide_idx]
+        elif self.action == PP_ACTION.PREVIOUS_SLIDE:
+            prev_slide_idx = self._slide_index - 1
+            if prev_slide_idx < 0:
+                raise ValueError("no previous slide")
+            return self._slides[prev_slide_idx]
+        elif self.action == PP_ACTION.NAMED_SLIDE:
+            assert self._hlink is not None
+            rId = self._hlink.rId
+            slide_part = cast("SlidePart", self.part.related_part(rId))
+            return slide_part.slide
+
+    @target_slide.setter
+    def target_slide(self, slide: Slide | None):
+        self._clear_click_action()
+        if slide is None:
+            return
+        hlink = self._element.get_or_add_hlinkClick()
+        hlink.action = "ppaction://hlinksldjump"
+        hlink.rId = self.part.relate_to(slide.part, RT.SLIDE)
+
+    def _clear_click_action(self):
+        """Remove any existing click action."""
+        hlink = self._hlink
+        if hlink is None:
+            return
+        rId = hlink.rId
+        if rId:
+            self.part.drop_rel(rId)
+        self._element.remove(hlink)
+
+    @property
+    def _hlink(self) -> CT_Hyperlink | None:
+        """
+        Reference to the `a:hlinkClick` or `a:hlinkHover` element for this
+        click action. Returns |None| if the element is not present.
+        """
+        if self._hover:
+            assert isinstance(self._element, CT_NonVisualDrawingProps)
+            return self._element.hlinkHover
+        return self._element.hlinkClick
+
+    @lazyproperty
+    def _slide(self):
+        """
+        Reference to the slide containing the shape having this click action.
+        """
+        return self.part.slide
+
+    @lazyproperty
+    def _slide_index(self):
+        """
+        Position in the slide collection of the slide containing the shape
+        having this click action.
+        """
+        return self._slides.index(self._slide)
+
+    @lazyproperty
+    def _slides(self) -> Slides:
+        """
+        Reference to the slide collection for this presentation.
+        """
+        return self.part.package.presentation_part.presentation.slides
+
+
+class Hyperlink(Subshape):
+    """Represents a hyperlink action on a shape or text run."""
+
+    def __init__(
+        self,
+        xPr: CT_NonVisualDrawingProps | CT_TextCharacterProperties,
+        parent: BaseShape,
+        hover: bool = False,
+    ):
+        super(Hyperlink, self).__init__(parent)
+        # xPr is either a cNvPr or rPr element
+        self._element = xPr
+        # _hover determines use of `a:hlinkClick` or `a:hlinkHover`
+        self._hover = hover
+
+    @property
+    def address(self) -> str | None:
+        """Read/write. The URL of the hyperlink.
+
+        URL can be on http, https, mailto, or file scheme; others may work. Returns |None| if no
+        hyperlink is defined, including when another action such as `RUN_MACRO` is defined on the
+        object. Assigning |None| removes any action defined on the object, whether it is a hyperlink
+        action or not.
+        """
+        hlink = self._hlink
+
+        # there's no URL if there's no click action
+        if hlink is None:
+            return None
+
+        # a click action without a relationship has no URL
+        rId = hlink.rId
+        if not rId:
+            return None
+
+        return self.part.target_ref(rId)
+
+    @address.setter
+    def address(self, url: str | None):
+        # implements all three of add, change, and remove hyperlink
+        self._remove_hlink()
+
+        if url:
+            rId = self.part.relate_to(url, RT.HYPERLINK, is_external=True)
+            hlink = self._get_or_add_hlink()
+            hlink.rId = rId
+
+    def _get_or_add_hlink(self) -> CT_Hyperlink:
+        """Get the `a:hlinkClick` or `a:hlinkHover` element for the Hyperlink object.
+
+        The actual element depends on the value of `self._hover`. Create the element if not present.
+        """
+        if self._hover:
+            return cast("CT_NonVisualDrawingProps", self._element).get_or_add_hlinkHover()
+        return self._element.get_or_add_hlinkClick()
+
+    @property
+    def _hlink(self) -> CT_Hyperlink | None:
+        """Reference to the `a:hlinkClick` or `h:hlinkHover` element for this click action.
+
+        Returns |None| if the element is not present.
+        """
+        if self._hover:
+            return cast("CT_NonVisualDrawingProps", self._element).hlinkHover
+        return self._element.hlinkClick
+
+    def _remove_hlink(self):
+        """Remove the a:hlinkClick or a:hlinkHover element.
+
+        Also drops any relationship it might have.
+        """
+        hlink = self._hlink
+        if hlink is None:
+            return
+        rId = hlink.rId
+        if rId:
+            self.part.drop_rel(rId)
+        self._element.remove(hlink)

pptx/api.py

@@ -0,0 +1,49 @@
+"""Directly exposed API classes, Presentation for now.
+
+Provides some syntactic sugar for interacting with the pptx.presentation.Package graph and also
+provides some insulation so not so many classes in the other modules need to be named as internal
+(leading underscore).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import IO, TYPE_CHECKING
+
+from pptx.opc.constants import CONTENT_TYPE as CT
+from pptx.package import Package
+
+if TYPE_CHECKING:
+    from pptx import presentation
+    from pptx.parts.presentation import PresentationPart
+
+
+def Presentation(pptx: str | IO[bytes] | None = None) -> presentation.Presentation:
+    """
+    Return a |Presentation| object loaded from *pptx*, where *pptx* can be
+    either a path to a ``.pptx`` file (a string) or a file-like object. If
+    *pptx* is missing or ``None``, the built-in default presentation
+    "template" is loaded.
+    """
+    if pptx is None:
+        pptx = _default_pptx_path()
+
+    presentation_part = Package.open(pptx).main_document_part
+
+    if not _is_pptx_package(presentation_part):
+        tmpl = "file '%s' is not a PowerPoint file, content type is '%s'"
+        raise ValueError(tmpl % (pptx, presentation_part.content_type))
+
+    return presentation_part.presentation
+
+
+def _default_pptx_path() -> str:
+    """Return the path to the built-in default .pptx package."""
+    _thisdir = os.path.split(__file__)[0]
+    return os.path.join(_thisdir, "templates", "default.pptx")
+
+
+def _is_pptx_package(prs_part: PresentationPart):
+    """Return |True| if *prs_part* is a valid main document part, |False| otherwise."""
+    valid_content_types = (CT.PML_PRESENTATION_MAIN, CT.PML_PRES_MACRO_MAIN)
+    return prs_part.content_type in valid_content_types