python-pptx2 2.13.0__py3-none-any.whl

pptx2/parts/image.py

@@ -0,0 +1,275 @@
+"""ImagePart and related objects."""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import os
+from typing import IO, TYPE_CHECKING, Any, cast
+
+from PIL import Image as PIL_Image
+
+from pptx2.opc.package import Part
+from pptx2.opc.spec import image_content_types
+from pptx2.util import Emu, lazyproperty
+
+if TYPE_CHECKING:
+    from pptx2.opc.packuri import PackURI
+    from pptx2.package import Package
+    from pptx2.util import Length
+
+
+class ImagePart(Part):
+    """An image part.
+
+    An image part generally has a partname matching the regex `ppt/media/image[1-9][0-9]*.*`.
+    """
+
+    def __init__(
+        self,
+        partname: PackURI,
+        content_type: str,
+        package: Package,
+        blob: bytes,
+        filename: str | None = None,
+    ):
+        super(ImagePart, self).__init__(partname, content_type, package, blob)
+        self._blob = blob
+        self._filename = filename
+
+    @classmethod
+    def new(cls, package: Package, image: Image) -> ImagePart:
+        """Return new |ImagePart| instance containing `image`.
+
+        `image` is an |Image| object.
+        """
+        return cls(
+            package.next_image_partname(image.ext),
+            image.content_type,
+            package,
+            image.blob,
+            image.filename,
+        )
+
+    @property
+    def desc(self) -> str:
+        """The filename associated with this image.
+
+        Either the filename of the original image or a generic name of the form `image.ext` where
+        `ext` is appropriate to the image file format, e.g. `'jpg'`. An image created using a path
+        will have that filename; one created with a file-like object will have a generic name.
+        """
+        # -- return generic filename if original filename is unknown --
+        if self._filename is None:
+            return f"image.{self.ext}"
+        return self._filename
+
+    @property
+    def ext(self) -> str:
+        """File-name extension for this image e.g. `'png'`."""
+        return self.partname.ext
+
+    @property
+    def image(self) -> Image:
+        """An |Image| object containing the image in this image part.
+
+        Note this is a `pptx2.image.Image` object, not a PIL Image.
+        """
+        return Image(self._blob, self.desc)
+
+    def scale(self, scaled_cx: int | None, scaled_cy: int | None) -> tuple[int, int]:
+        """Return scaled image dimensions in EMU based on the combination of parameters supplied.
+
+        If `scaled_cx` and `scaled_cy` are both |None|, the native image size is returned. If
+        neither `scaled_cx` nor `scaled_cy` is |None|, their values are returned unchanged. If a
+        value is provided for either `scaled_cx` or `scaled_cy` and the other is |None|, the
+        missing value is calculated such that the image's aspect ratio is preserved.
+        """
+        image_cx, image_cy = self._native_size
+
+        if scaled_cx and scaled_cy:
+            return scaled_cx, scaled_cy
+
+        if scaled_cx and not scaled_cy:
+            scaling_factor = float(scaled_cx) / float(image_cx)
+            scaled_cy = int(round(image_cy * scaling_factor))
+            return scaled_cx, scaled_cy
+
+        if not scaled_cx and scaled_cy:
+            scaling_factor = float(scaled_cy) / float(image_cy)
+            scaled_cx = int(round(image_cx * scaling_factor))
+            return scaled_cx, scaled_cy
+
+        # -- only remaining case is both `scaled_cx` and `scaled_cy` are `None` --
+        return image_cx, image_cy
+
+    @lazyproperty
+    def sha1(self) -> str:
+        """The 40-character SHA1 hash digest for the image binary of this image part.
+
+        like: `"1be010ea47803b00e140b852765cdf84f491da47"`.
+        """
+        return hashlib.sha1(self._blob).hexdigest()
+
+    @property
+    def _dpi(self) -> tuple[int, int]:
+        """(horz_dpi, vert_dpi) pair representing the dots-per-inch resolution of this image."""
+        image = Image.from_blob(self._blob)
+        return image.dpi
+
+    @property
+    def _native_size(self) -> tuple[Length, Length]:
+        """A (width, height) 2-tuple representing the native dimensions of the image in EMU.
+
+        Calculated based on the image DPI value, if present, assuming 72 dpi as a default.
+        """
+        EMU_PER_INCH = 914400
+        horz_dpi, vert_dpi = self._dpi
+        width_px, height_px = self._px_size
+
+        width = EMU_PER_INCH * width_px / horz_dpi
+        height = EMU_PER_INCH * height_px / vert_dpi
+
+        return Emu(int(width)), Emu(int(height))
+
+    @property
+    def _px_size(self) -> tuple[int, int]:
+        """A (width, height) 2-tuple representing the dimensions of this image in pixels."""
+        image = Image.from_blob(self._blob)
+        return image.size
+
+
+class Image(object):
+    """Immutable value object representing an image such as a JPEG, PNG, or GIF."""
+
+    def __init__(self, blob: bytes, filename: str | None):
+        super(Image, self).__init__()
+        self._blob = blob
+        self._filename = filename
+
+    @classmethod
+    def from_blob(cls, blob: bytes, filename: str | None = None) -> Image:
+        """Return a new |Image| object loaded from the image binary in `blob`."""
+        return cls(blob, filename)
+
+    @classmethod
+    def from_file(cls, image_file: str | IO[bytes]) -> Image:
+        """Return a new |Image| object loaded from `image_file`.
+
+        `image_file` can be either a path (str) or a file-like object.
+        """
+        if isinstance(image_file, str):
+            # treat image_file as a path
+            with open(image_file, "rb") as f:
+                blob = f.read()
+            filename = os.path.basename(image_file)
+        else:
+            # assume image_file is a file-like object
+            # ---reposition file cursor if it has one---
+            if callable(getattr(image_file, "seek")):
+                image_file.seek(0)
+            blob = image_file.read()
+            filename = None
+
+        return cls.from_blob(blob, filename)
+
+    @property
+    def blob(self) -> bytes:
+        """The binary image bytestream of this image."""
+        return self._blob
+
+    @lazyproperty
+    def content_type(self) -> str:
+        """MIME-type of this image, e.g. `"image/jpeg"`."""
+        return image_content_types[self.ext]
+
+    @lazyproperty
+    def dpi(self) -> tuple[int, int]:
+        """A (horz_dpi, vert_dpi) 2-tuple specifying the dots-per-inch resolution of this image.
+
+        A default value of (72, 72) is used if the dpi is not specified in the image file.
+        """
+
+        def int_dpi(dpi: Any):
+            """Return an integer dots-per-inch value corresponding to `dpi`.
+
+            If `dpi` is |None|, a non-numeric type, less than 1 or greater than 2048, 72 is
+            returned.
+            """
+            try:
+                int_dpi = int(round(float(dpi)))
+                if int_dpi < 1 or int_dpi > 2048:
+                    int_dpi = 72
+            except (TypeError, ValueError):
+                int_dpi = 72
+            return int_dpi
+
+        def normalize_pil_dpi(pil_dpi: tuple[int, int] | None):
+            """Return a (horz_dpi, vert_dpi) 2-tuple corresponding to `pil_dpi`.
+
+            The value for the 'dpi' key in the `info` dict of a PIL image. If the 'dpi' key is not
+            present or contains an invalid value, `(72, 72)` is returned.
+            """
+            if isinstance(pil_dpi, tuple):
+                return (int_dpi(pil_dpi[0]), int_dpi(pil_dpi[1]))
+            return (72, 72)
+
+        return normalize_pil_dpi(self._pil_props[2])
+
+    @lazyproperty
+    def ext(self) -> str:
+        """Canonical file extension for this image e.g. `'png'`.
+
+        The returned extension is all lowercase and is the canonical extension for the content type
+        of this image, regardless of what extension may have been used in its filename, if any.
+        """
+        ext_map = {
+            "BMP": "bmp",
+            "GIF": "gif",
+            "JPEG": "jpg",
+            "PNG": "png",
+            "TIFF": "tiff",
+            "WMF": "wmf",
+        }
+        format = self._format
+        if format not in ext_map:
+            tmpl = "unsupported image format, expected one of: %s, got '%s'"
+            raise ValueError(tmpl % (ext_map.keys(), format))
+        return ext_map[format]
+
+    @property
+    def filename(self) -> str | None:
+        """Filename from path used to load this image, if loaded from the filesystem.
+
+        |None| if no filename was used in loading, such as when loaded from an in-memory stream.
+        """
+        return self._filename
+
+    @lazyproperty
+    def sha1(self) -> str:
+        """SHA1 hash digest of the image blob."""
+        return hashlib.sha1(self._blob).hexdigest()
+
+    @lazyproperty
+    def size(self) -> tuple[int, int]:
+        """A (width, height) 2-tuple specifying the dimensions of this image in pixels."""
+        return self._pil_props[1]
+
+    @property
+    def _format(self) -> str | None:
+        """The PIL Image format of this image, e.g. 'PNG'."""
+        return self._pil_props[0]
+
+    @lazyproperty
+    def _pil_props(self) -> tuple[str | None, tuple[int, int], tuple[int, int] | None]:
+        """tuple of image properties extracted from this image using Pillow."""
+        stream = io.BytesIO(self._blob)
+        pil_image = PIL_Image.open(stream)  # pyright: ignore[reportUnknownMemberType]
+        format = pil_image.format
+        width_px, height_px = pil_image.size
+        dpi = cast(
+            "tuple[int, int] | None",
+            pil_image.info.get("dpi"),  # pyright: ignore[reportUnknownMemberType]
+        )
+        stream.close()
+        return (format, (width_px, height_px), dpi)

pptx2/parts/media.py

@@ -0,0 +1,37 @@
+"""MediaPart and related objects."""
+
+from __future__ import annotations
+
+import hashlib
+
+from pptx2.opc.package import Part
+from pptx2.util import lazyproperty
+
+
+class MediaPart(Part):
+    """A media part, containing an audio or video resource.
+
+    A media part generally has a partname matching the regex
+    `ppt/media/media[1-9][0-9]*.*`.
+    """
+
+    @classmethod
+    def new(cls, package, media):
+        """Return new |MediaPart| instance containing `media`.
+
+        `media` must be a |Media| object.
+        """
+        return cls(
+            package.next_media_partname(media.ext),
+            media.content_type,
+            package,
+            media.blob,
+        )
+
+    @lazyproperty
+    def sha1(self):
+        """The SHA1 hash digest for the media binary of this media part.
+
+        Example: `'1be010ea47803b00e140b852765cdf84f491da47'`
+        """
+        return hashlib.sha1(self._blob).hexdigest()

pptx2/parts/presentation.py

@@ -0,0 +1,136 @@
+"""Presentation part, the main part in a .pptx package."""
+
+from __future__ import annotations
+
+from typing import IO, TYPE_CHECKING, Iterable
+
+from pptx2.opc.constants import RELATIONSHIP_TYPE as RT
+from pptx2.opc.package import XmlPart
+from pptx2.opc.packuri import PackURI
+from pptx2.parts.slide import NotesMasterPart, SlidePart
+from pptx2.presentation import Presentation
+from pptx2.util import lazyproperty
+
+if TYPE_CHECKING:
+    from pptx2.parts.coreprops import CorePropertiesPart
+    from pptx2.slide import NotesMaster, Slide, SlideLayout, SlideMaster
+
+
+class PresentationPart(XmlPart):
+    """Top level class in object model.
+
+    Represents the contents of the /ppt directory of a .pptx file.
+    """
+
+    def add_slide(self, slide_layout: SlideLayout):
+        """Return (rId, slide) pair of a newly created blank slide.
+
+        New slide inherits appearance from `slide_layout`.
+        """
+        partname = self._next_slide_partname
+        slide_layout_part = slide_layout.part
+        slide_part = SlidePart.new(partname, self.package, slide_layout_part)
+        rId = self.relate_to(slide_part, RT.SLIDE)
+        return rId, slide_part.slide
+
+    @property
+    def core_properties(self) -> CorePropertiesPart:
+        """A |CoreProperties| object for the presentation.
+
+        Provides read/write access to the Dublin Core properties of this presentation.
+        """
+        return self.package.core_properties
+
+    def get_slide(self, slide_id: int) -> Slide | None:
+        """Return optional related |Slide| object identified by `slide_id`.
+
+        Returns |None| if no slide with `slide_id` is related to this presentation.
+        """
+        for sldId in self._element.sldIdLst:
+            if sldId.id == slide_id:
+                return self.related_part(sldId.rId).slide
+        return None
+
+    @lazyproperty
+    def notes_master(self) -> NotesMaster:
+        """
+        Return the |NotesMaster| object for this presentation. If the
+        presentation does not have a notes master, one is created from
+        a default template. The same single instance is returned on each
+        call.
+        """
+        return self.notes_master_part.notes_master
+
+    @lazyproperty
+    def notes_master_part(self) -> NotesMasterPart:
+        """Return the |NotesMasterPart| object for this presentation.
+
+        If the presentation does not have a notes master, one is created from a default template.
+        The same single instance is returned on each call.
+        """
+        try:
+            return self.part_related_by(RT.NOTES_MASTER)
+        except KeyError:
+            notes_master_part = NotesMasterPart.create_default(self.package)
+            self.relate_to(notes_master_part, RT.NOTES_MASTER)
+            return notes_master_part
+
+    @lazyproperty
+    def presentation(self):
+        """
+        A |Presentation| object providing access to the content of this
+        presentation.
+        """
+        return Presentation(self._element, self)
+
+    def related_slide(self, rId: str) -> Slide:
+        """Return |Slide| object for related |SlidePart| related by `rId`."""
+        return self.related_part(rId).slide
+
+    def related_slide_master(self, rId: str) -> SlideMaster:
+        """Return |SlideMaster| object for |SlideMasterPart| related by `rId`."""
+        return self.related_part(rId).slide_master
+
+    def rename_slide_parts(self, rIds: Iterable[str]):
+        """Assign incrementing partnames to the slide parts identified by `rIds`.
+
+        Partnames are like `/ppt/slides/slide9.xml` and are assigned in the order their id appears
+        in the `rIds` sequence. The name portion is always `slide`. The number part forms a
+        continuous sequence starting at 1 (e.g. 1, 2, ... 10, ...). The extension is always
+        `.xml`.
+        """
+        for idx, rId in enumerate(rIds):
+            slide_part = self.related_part(rId)
+            slide_part.partname = PackURI("/ppt/slides/slide%d.xml" % (idx + 1))
+
+    def save(self, path_or_stream: str | IO[bytes]):
+        """Save this presentation package to `path_or_stream`.
+
+        `path_or_stream` can be either a path to a filesystem location (a string) or a
+        file-like object.
+        """
+        self.package.save(path_or_stream)
+
+    def slide_id(self, slide_part):
+        """Return the slide-id associated with `slide_part`."""
+        for sldId in self._element.sldIdLst:
+            if self.related_part(sldId.rId) is slide_part:
+                return sldId.id
+        raise ValueError("matching slide_part not found")
+
+    @property
+    def _next_slide_partname(self):
+        """Return |PackURI| instance containing next available slide partname.
+
+        Scans the actual partnames in the package rather than counting
+        `p:sldIdLst` entries — the package can hold slide parts beyond those
+        registered in the id list (e.g. after a cross-deck import), and
+        writing two different parts under one partname corrupts the package.
+        """
+        existing = {part.partname for part in self.package.iter_parts()}
+        n = len(self._element.get_or_add_sldIdLst()) + 1
+        while True:
+            candidate = PackURI("/ppt/slides/slide%d.xml" % n)
+            if candidate not in existing:
+                return candidate
+            n += 1