python-pptx2 2.13.0__py3-none-any.whl

pptx2/parts/slide.py

@@ -0,0 +1,371 @@
+"""Slide and related objects."""
+
+from __future__ import annotations
+
+from typing import IO, TYPE_CHECKING, cast
+
+from pptx2.enum.shapes import PROG_ID
+from pptx2.opc.constants import CONTENT_TYPE as CT
+from pptx2.opc.constants import RELATIONSHIP_TYPE as RT
+from pptx2.opc.package import XmlPart
+from pptx2.opc.oxml import serialize_part_xml
+from pptx2.opc.packuri import PackURI
+from pptx2.oxml import parse_xml
+from pptx2.oxml.slide import (
+    CT_NotesMaster,
+    CT_NotesSlide,
+    CT_Slide,
+    slide_has_p14_transition,
+    unwrap_p14_transitions,
+    wrap_p14_transitions,
+)
+from pptx2.oxml.theme import CT_OfficeStyleSheet
+from pptx2.parts.chart import ChartPart
+from pptx2.parts.embeddedpackage import EmbeddedPackagePart
+from pptx2.slide import NotesMaster, NotesSlide, Slide, SlideLayout, SlideMaster
+from pptx2.util import lazyproperty
+
+if TYPE_CHECKING:
+    from pptx2.chart.data import ChartData
+    from pptx2.enum.chart import XL_CHART_TYPE
+    from pptx2.media import Video
+    from pptx2.parts.image import Image, ImagePart
+
+
+class BaseSlidePart(XmlPart):
+    """Base class for slide parts.
+
+    This includes slide, slide-layout, and slide-master parts, but also notes-slide,
+    notes-master, and handout-master parts.
+    """
+
+    _element: CT_Slide
+
+    @classmethod
+    def load(cls, partname, content_type, package, blob):
+        """Parse *blob* and normalise any PowerPoint-2010 transition wrapper.
+
+        A morph/p14 transition is stored on disk inside ``<mc:AlternateContent>``;
+        we unwrap it to a plain ``<p:transition>`` so the high-level
+        ``slide.transition`` accessors see a normal element.  ``blob`` re-wraps it
+        on save.
+        """
+        element = cast("CT_Slide", parse_xml(blob))
+        unwrap_p14_transitions(element)
+        return cls(partname, content_type, package, element)
+
+    @property
+    def blob(self) -> bytes:
+        """XML serialization, re-wrapping p14 transitions in mc:AlternateContent.
+
+        The wrap is done on a copy so the live element tree keeps its plain
+        ``<p:transition>`` (and the accessors that read it) intact after a save.
+        """
+        element = self._element
+        if not slide_has_p14_transition(element):
+            return serialize_part_xml(element)
+        from copy import deepcopy
+
+        copy = deepcopy(element)
+        wrap_p14_transitions(copy)
+        return serialize_part_xml(copy)
+
+    def get_image(self, rId: str) -> Image:
+        """Return an |Image| object containing the image related to this slide by *rId*.
+
+        Raises |KeyError| if no image is related by that id, which would generally indicate a
+        corrupted .pptx file.
+        """
+        return cast("ImagePart", self.related_part(rId)).image
+
+    def get_or_add_image_part(self, image_file: str | IO[bytes]):
+        """Return `(image_part, rId)` pair corresponding to `image_file`.
+
+        The returned |ImagePart| object contains the image in `image_file` and is
+        related to this slide with the key `rId`. If either the image part or
+        relationship already exists, they are reused, otherwise they are newly created.
+        """
+        image_part = self._package.get_or_add_image_part(image_file)
+        rId = self.relate_to(image_part, RT.IMAGE)
+        return image_part, rId
+
+    @property
+    def name(self) -> str:
+        """Internal name of this slide."""
+        return self._element.cSld.name
+
+
+class NotesMasterPart(BaseSlidePart):
+    """Notes master part.
+
+    Corresponds to package file `ppt/notesMasters/notesMaster1.xml`.
+    """
+
+    @classmethod
+    def create_default(cls, package):
+        """
+        Create and return a default notes master part, including creating the
+        new theme it requires.
+        """
+        notes_master_part = cls._new(package)
+        theme_part = cls._new_theme_part(package)
+        notes_master_part.relate_to(theme_part, RT.THEME)
+        return notes_master_part
+
+    @lazyproperty
+    def notes_master(self):
+        """
+        Return the |NotesMaster| object that proxies this notes master part.
+        """
+        return NotesMaster(self._element, self)
+
+    @classmethod
+    def _new(cls, package):
+        """
+        Create and return a standalone, default notes master part based on
+        the built-in template (without any related parts, such as theme).
+        """
+        return NotesMasterPart(
+            PackURI("/ppt/notesMasters/notesMaster1.xml"),
+            CT.PML_NOTES_MASTER,
+            package,
+            CT_NotesMaster.new_default(),
+        )
+
+    @classmethod
+    def _new_theme_part(cls, package):
+        """Return new default theme-part suitable for use with a notes master."""
+        return ThemePart(
+            package.next_partname("/ppt/theme/theme%d.xml"),
+            CT.OFC_THEME,
+            package,
+            CT_OfficeStyleSheet.new_default(),
+        )
+
+
+class ThemePart(XmlPart):
+    """Package part for an Office theme (``ppt/theme/themeN.xml``).
+
+    Themes were previously loaded as generic |Part| blobs which made
+    high-level write operations on |Theme| transient (every read parsed
+    a fresh element).  Promoting them to |XmlPart| keeps a single live
+    ``<a:theme>`` element on the part so that mutations from
+    :class:`pptx2.theme.Theme` round-trip on save.
+    """
+
+    _element: CT_OfficeStyleSheet
+
+
+class NotesSlidePart(BaseSlidePart):
+    """Notes slide part.
+
+    Contains the slide notes content and the layout for the slide handout page.
+    Corresponds to package file `ppt/notesSlides/notesSlide[1-9][0-9]*.xml`.
+    """
+
+    @classmethod
+    def new(cls, package, slide_part):
+        """Return new |NotesSlidePart| for the slide in `slide_part`.
+
+        The new notes-slide part is based on the (singleton) notes master and related to
+        both the notes-master part and `slide_part`. If no notes-master is present,
+        one is created based on the default template.
+        """
+        notes_master_part = package.presentation_part.notes_master_part
+        notes_slide_part = cls._add_notes_slide_part(package, slide_part, notes_master_part)
+        notes_slide = notes_slide_part.notes_slide
+        notes_slide.clone_master_placeholders(notes_master_part.notes_master)
+        return notes_slide_part
+
+    @lazyproperty
+    def notes_master(self):
+        """Return the |NotesMaster| object this notes slide inherits from."""
+        notes_master_part = self.part_related_by(RT.NOTES_MASTER)
+        return notes_master_part.notes_master
+
+    @lazyproperty
+    def notes_slide(self):
+        """Return the |NotesSlide| object that proxies this notes slide part."""
+        return NotesSlide(self._element, self)
+
+    @classmethod
+    def _add_notes_slide_part(cls, package, slide_part, notes_master_part):
+        """Create and return a new notes-slide part.
+
+        The return part is fully related, but has no shape content (i.e. placeholders
+        not cloned).
+        """
+        notes_slide_part = NotesSlidePart(
+            package.next_partname("/ppt/notesSlides/notesSlide%d.xml"),
+            CT.PML_NOTES_SLIDE,
+            package,
+            CT_NotesSlide.new(),
+        )
+        notes_slide_part.relate_to(notes_master_part, RT.NOTES_MASTER)
+        notes_slide_part.relate_to(slide_part, RT.SLIDE)
+        return notes_slide_part
+
+
+class SlidePart(BaseSlidePart):
+    """Slide part. Corresponds to package files ppt/slides/slide[1-9][0-9]*.xml."""
+
+    @classmethod
+    def new(cls, partname, package, slide_layout_part):
+        """Return newly-created blank slide part.
+
+        The new slide-part has `partname` and a relationship to `slide_layout_part`.
+        """
+        slide_part = cls(partname, CT.PML_SLIDE, package, CT_Slide.new())
+        slide_part.relate_to(slide_layout_part, RT.SLIDE_LAYOUT)
+        return slide_part
+
+    def add_chart_part(self, chart_type: XL_CHART_TYPE, chart_data: ChartData):
+        """Return str rId of new |ChartPart| object containing chart of `chart_type`.
+
+        The chart depicts `chart_data` and is related to the slide contained in this
+        part by `rId`.
+        """
+        return self.relate_to(ChartPart.new(chart_type, chart_data, self._package), RT.CHART)
+
+    def add_embedded_ole_object_part(
+        self, prog_id: PROG_ID | str, ole_object_file: str | IO[bytes]
+    ):
+        """Return rId of newly-added OLE-object part formed from `ole_object_file`."""
+        relationship_type = RT.PACKAGE if isinstance(prog_id, PROG_ID) else RT.OLE_OBJECT
+        return self.relate_to(
+            EmbeddedPackagePart.factory(
+                prog_id, self._blob_from_file(ole_object_file), self._package
+            ),
+            relationship_type,
+        )
+
+    def get_or_add_video_media_part(self, video: Video) -> tuple[str, str]:
+        """Return rIds for media and video relationships to media part.
+
+        A new |MediaPart| object is created if it does not already exist
+        (such as would occur if the same video appeared more than once in
+         a presentation). Two relationships to the media part are created,
+        one each with MEDIA and VIDEO relationship types. The need for two
+        appears to be for legacy support for an earlier (pre-Office 2010)
+        PowerPoint media embedding strategy.
+        """
+        media_part = self._package.get_or_add_media_part(video)
+        media_rId = self.relate_to(media_part, RT.MEDIA)
+        video_rId = self.relate_to(media_part, RT.VIDEO)
+        return media_rId, video_rId
+
+    @property
+    def has_notes_slide(self):
+        """
+        Return True if this slide has a notes slide, False otherwise. A notes
+        slide is created by the :attr:`notes_slide` property when one doesn't
+        exist; use this property to test for a notes slide without the
+        possible side-effect of creating one.
+        """
+        try:
+            self.part_related_by(RT.NOTES_SLIDE)
+        except KeyError:
+            return False
+        return True
+
+    @lazyproperty
+    def notes_slide(self) -> NotesSlide:
+        """The |NotesSlide| instance associated with this slide.
+
+        If the slide does not have a notes slide, a new one is created. The same single instance
+        is returned on each call.
+        """
+        try:
+            notes_slide_part = self.part_related_by(RT.NOTES_SLIDE)
+        except KeyError:
+            notes_slide_part = self._add_notes_slide_part()
+        return notes_slide_part.notes_slide
+
+    @lazyproperty
+    def slide(self):
+        """
+        The |Slide| object representing this slide part.
+        """
+        return Slide(self._element, self)
+
+    @property
+    def slide_id(self) -> int:
+        """Return the slide identifier stored in the presentation part for this slide part."""
+        presentation_part = self.package.presentation_part
+        return presentation_part.slide_id(self)
+
+    @property
+    def slide_layout(self) -> SlideLayout:
+        """|SlideLayout| object the slide in this part inherits appearance from."""
+        slide_layout_part = self.part_related_by(RT.SLIDE_LAYOUT)
+        return slide_layout_part.slide_layout
+
+    def _add_notes_slide_part(self):
+        """
+        Return a newly created |NotesSlidePart| object related to this slide
+        part. Caller is responsible for ensuring this slide doesn't already
+        have a notes slide part.
+        """
+        notes_slide_part = NotesSlidePart.new(self.package, self)
+        self.relate_to(notes_slide_part, RT.NOTES_SLIDE)
+        return notes_slide_part
+
+
+class SlideLayoutPart(BaseSlidePart):
+    """Slide layout part.
+
+    Corresponds to package files ``ppt/slideLayouts/slideLayout[1-9][0-9]*.xml``.
+    """
+
+    @lazyproperty
+    def slide_layout(self):
+        """
+        The |SlideLayout| object representing this part.
+        """
+        return SlideLayout(self._element, self)
+
+    @property
+    def slide_master(self) -> SlideMaster:
+        """Slide master from which this slide layout inherits properties."""
+        return self.part_related_by(RT.SLIDE_MASTER).slide_master
+
+
+class SlideMasterPart(BaseSlidePart):
+    """Slide master part.
+
+    Corresponds to package files ppt/slideMasters/slideMaster[1-9][0-9]*.xml.
+    """
+
+    def related_slide_layout(self, rId: str) -> SlideLayout:
+        """Return |SlideLayout| related to this slide-master by key `rId`."""
+        return self.related_part(rId).slide_layout
+
+    @lazyproperty
+    def slide_master(self):
+        """
+        The |SlideMaster| object representing this part.
+        """
+        return SlideMaster(self._element, self)
+
+    @property
+    def theme(self):
+        """Return a |Theme| object for the theme related to this slide master.
+
+        Returns ``None`` when no theme relationship is present.
+        """
+        from pptx2.oxml import parse_xml
+        from pptx2.theme import Theme
+
+        try:
+            theme_part = self.part_related_by(RT.THEME)
+        except KeyError:
+            return None
+        # Theme parts are typed as ThemePart (an XmlPart subclass) and
+        # always carry a live `_element`.  Older packages or generic
+        # Parts fall through to a fresh parse so the read still works
+        # (writes won't persist on a generic Part — but they do on
+        # any presentation loaded through the registered factory).
+        elm = getattr(theme_part, "_element", None)
+        if elm is None:
+            elm = parse_xml(theme_part.blob)
+        return Theme(elm)