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

pptx/parts/slide.py

@@ -0,0 +1,297 @@
+"""Slide and related objects."""
+
+from __future__ import annotations
+
+from typing import IO, TYPE_CHECKING, cast
+
+from pptx.enum.shapes import PROG_ID
+from pptx.opc.constants import CONTENT_TYPE as CT
+from pptx.opc.constants import RELATIONSHIP_TYPE as RT
+from pptx.opc.package import XmlPart
+from pptx.opc.packuri import PackURI
+from pptx.oxml.slide import CT_NotesMaster, CT_NotesSlide, CT_Slide
+from pptx.oxml.theme import CT_OfficeStyleSheet
+from pptx.parts.chart import ChartPart
+from pptx.parts.embeddedpackage import EmbeddedPackagePart
+from pptx.slide import NotesMaster, NotesSlide, Slide, SlideLayout, SlideMaster
+from pptx.util import lazyproperty
+
+if TYPE_CHECKING:
+    from pptx.chart.data import ChartData
+    from pptx.enum.chart import XL_CHART_TYPE
+    from pptx.media import Video
+    from pptx.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
+
+    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 XmlPart(
+            package.next_partname("/ppt/theme/theme%d.xml"),
+            CT.OFC_THEME,
+            package,
+            CT_OfficeStyleSheet.new_default(),
+        )
+
+
+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)

pptx/parts/theme.py

@@ -0,0 +1,13 @@
+"""Theme package part."""
+
+from pptx.opc.package import XmlPart
+from pptx.theme import Theme
+from pptx.util import lazyproperty
+
+
+class ThemePart(XmlPart):
+    """DrawingML theme with editable colors and fonts."""
+
+    @lazyproperty
+    def theme(self):
+        return Theme(self._element)

pptx/presentation.py

@@ -0,0 +1,113 @@
+"""Main presentation object."""
+
+from __future__ import annotations
+
+from typing import IO, TYPE_CHECKING, cast
+
+from pptx.shared import PartElementProxy
+from pptx.slide import SlideMasters, Slides
+from pptx.util import lazyproperty
+
+if TYPE_CHECKING:
+    from pptx.oxml.presentation import CT_Presentation, CT_SlideId
+    from pptx.parts.presentation import PresentationPart
+    from pptx.slide import NotesMaster, SlideLayouts
+    from pptx.util import Length
+
+
+class Presentation(PartElementProxy):
+    """PresentationML (PML) presentation.
+
+    Not intended to be constructed directly. Use :func:`pptx.Presentation` to open or
+    create a presentation.
+    """
+
+    _element: CT_Presentation
+    part: PresentationPart  # pyright: ignore[reportIncompatibleMethodOverride]
+
+    @property
+    def core_properties(self):
+        """|CoreProperties| instance for this presentation.
+
+        Provides read/write access to the Dublin Core document properties for the presentation.
+        """
+        return self.part.core_properties
+
+    @property
+    def notes_master(self) -> NotesMaster:
+        """Instance of |NotesMaster| for this presentation.
+
+        If the presentation does not have a notes master, one is created from a default template
+        and returned. The same single instance is returned on each call.
+        """
+        return self.part.notes_master
+
+    def save(self, file: str | IO[bytes]):
+        """Writes this presentation to `file`.
+
+        `file` can be either a file-path or a file-like object open for writing bytes.
+        """
+        self.part.save(file)
+
+    @property
+    def slide_height(self) -> Length | None:
+        """Height of slides in this presentation, in English Metric Units (EMU).
+
+        Returns |None| if no slide width is defined. Read/write.
+        """
+        sldSz = self._element.sldSz
+        if sldSz is None:
+            return None
+        return sldSz.cy
+
+    @slide_height.setter
+    def slide_height(self, height: Length):
+        sldSz = self._element.get_or_add_sldSz()
+        sldSz.cy = height
+
+    @property
+    def slide_layouts(self) -> SlideLayouts:
+        """|SlideLayouts| collection belonging to the first |SlideMaster| of this presentation.
+
+        A presentation can have more than one slide master and each master will have its own set
+        of layouts. This property is a convenience for the common case where the presentation has
+        only a single slide master.
+        """
+        return self.slide_masters[0].slide_layouts
+
+    @property
+    def slide_master(self):
+        """
+        First |SlideMaster| object belonging to this presentation. Typically,
+        presentations have only a single slide master. This property provides
+        simpler access in that common case.
+        """
+        return self.slide_masters[0]
+
+    @lazyproperty
+    def slide_masters(self) -> SlideMasters:
+        """|SlideMasters| collection of slide-masters belonging to this presentation."""
+        return SlideMasters(self._element.get_or_add_sldMasterIdLst(), self)
+
+    @property
+    def slide_width(self):
+        """
+        Width of slides in this presentation, in English Metric Units (EMU).
+        Returns |None| if no slide width is defined. Read/write.
+        """
+        sldSz = self._element.sldSz
+        if sldSz is None:
+            return None
+        return sldSz.cx
+
+    @slide_width.setter
+    def slide_width(self, width: Length):
+        sldSz = self._element.get_or_add_sldSz()
+        sldSz.cx = width
+
+    @lazyproperty
+    def slides(self):
+        """|Slides| object containing the slides in this presentation."""
+        sldIdLst = self._element.get_or_add_sldIdLst()
+        self.part.rename_slide_parts([cast("CT_SlideId", sldId).rId for sldId in sldIdLst])
+        return Slides(sldIdLst, self)

pptx/shapes/__init__.py

@@ -0,0 +1,26 @@
+"""Objects used across sub-package."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pptx.opc.package import XmlPart
+    from pptx.types import ProvidesPart
+
+
+class Subshape(object):
+    """Provides access to the containing part for drawing elements that occur below a shape.
+
+    Access to the part is required for example to add or drop a relationship. Provides
+    `self._parent` attribute to subclasses.
+    """
+
+    def __init__(self, parent: ProvidesPart):
+        super(Subshape, self).__init__()
+        self._parent = parent
+
+    @property
+    def part(self) -> XmlPart:
+        """The package part containing this object."""
+        return self._parent.part