python-pptx2 2.13.0__py3-none-any.whl

pptx2/package.py

@@ -0,0 +1,222 @@
+"""Overall .pptx package."""
+
+from __future__ import annotations
+
+from typing import IO, Iterator
+
+from pptx2.opc.constants import RELATIONSHIP_TYPE as RT
+from pptx2.opc.package import OpcPackage
+from pptx2.opc.packuri import PackURI
+from pptx2.parts.coreprops import CorePropertiesPart
+from pptx2.parts.image import Image, ImagePart
+from pptx2.parts.media import MediaPart
+from pptx2.util import lazyproperty
+
+
+class Package(OpcPackage):
+    """An overall .pptx package."""
+
+    @lazyproperty
+    def core_properties(self) -> CorePropertiesPart:
+        """Instance of |CoreProperties| holding read/write Dublin Core doc properties.
+
+        Creates a default core properties part if one is not present (not common).
+        """
+        try:
+            return self.part_related_by(RT.CORE_PROPERTIES)
+        except KeyError:
+            core_props = CorePropertiesPart.default(self)
+            self.relate_to(core_props, RT.CORE_PROPERTIES)
+            return core_props
+
+    def get_or_add_image_part(self, image_file: str | IO[bytes]):
+        """
+        Return an |ImagePart| object containing the image in *image_file*. If
+        the image part already exists in this package, it is reused,
+        otherwise a new one is created.
+        """
+        return self._image_parts.get_or_add_image_part(image_file)
+
+    def get_or_add_media_part(self, media):
+        """Return a |MediaPart| object containing the media in *media*.
+
+        If a media part for this media bytestream ("file") is already present
+        in this package, it is reused, otherwise a new one is created.
+        """
+        return self._media_parts.get_or_add_media_part(media)
+
+    def next_image_partname(self, ext: str) -> PackURI:
+        """Return a |PackURI| instance representing the next available image partname.
+
+        Partname uses the next available sequence number. *ext* is used as the extention on the
+        returned partname.
+        """
+
+        def first_available_image_idx():
+            image_idxs = sorted(
+                [
+                    part.partname.idx
+                    for part in self.iter_parts()
+                    if (
+                        part.partname.startswith("/ppt/media/image")
+                        and part.partname.idx is not None
+                    )
+                ]
+            )
+            for i, image_idx in enumerate(image_idxs):
+                idx = i + 1
+                if idx < image_idx:
+                    return idx
+            return len(image_idxs) + 1
+
+        idx = first_available_image_idx()
+        return PackURI("/ppt/media/image%d.%s" % (idx, ext))
+
+    def next_media_partname(self, ext):
+        """Return |PackURI| instance for next available media partname.
+
+        Partname is first available, starting at sequence number 1. Empty
+        sequence numbers are reused. *ext* is used as the extension on the
+        returned partname.
+        """
+
+        def first_available_media_idx():
+            media_idxs = sorted(
+                [
+                    part.partname.idx
+                    for part in self.iter_parts()
+                    if part.partname.startswith("/ppt/media/media")
+                ]
+            )
+            for i, media_idx in enumerate(media_idxs):
+                idx = i + 1
+                if idx < media_idx:
+                    return idx
+            return len(media_idxs) + 1
+
+        idx = first_available_media_idx()
+        return PackURI("/ppt/media/media%d.%s" % (idx, ext))
+
+    @property
+    def presentation_part(self):
+        """
+        Reference to the |Presentation| instance contained in this package.
+        """
+        return self.main_document_part
+
+    @lazyproperty
+    def _image_parts(self):
+        """
+        |_ImageParts| object providing access to the image parts in this
+        package.
+        """
+        return _ImageParts(self)
+
+    @lazyproperty
+    def _media_parts(self):
+        """Return |_MediaParts| object for this package.
+
+        The media parts object provides access to all the media parts in this
+        package.
+        """
+        return _MediaParts(self)
+
+
+class _ImageParts(object):
+    """Provides access to the image parts in a package."""
+
+    def __init__(self, package):
+        super(_ImageParts, self).__init__()
+        self._package = package
+
+    def __iter__(self) -> Iterator[ImagePart]:
+        """Generate a reference to each |ImagePart| object in the package."""
+        image_parts = []
+        for rel in self._package.iter_rels():
+            if rel.is_external:
+                continue
+            if rel.reltype != RT.IMAGE:
+                continue
+            image_part = rel.target_part
+            if image_part in image_parts:
+                continue
+            image_parts.append(image_part)
+            yield image_part
+
+    def get_or_add_image_part(self, image_file: str | IO[bytes]) -> ImagePart:
+        """Return |ImagePart| object containing the image in `image_file`.
+
+        `image_file` can be either a path to an image file or a file-like object
+        containing an image. If an image part containing this same image already exists,
+        that instance is returned, otherwise a new image part is created.
+        """
+        image = Image.from_file(image_file)
+        image_part = self._find_by_sha1(image.sha1)
+        return image_part if image_part else ImagePart.new(self._package, image)
+
+    def _find_by_sha1(self, sha1: str) -> ImagePart | None:
+        """
+        Return an |ImagePart| object belonging to this package or |None| if
+        no matching image part is found. The image part is identified by the
+        SHA1 hash digest of the image binary it contains.
+        """
+        for image_part in self:
+            # ---skip unknown/unsupported image types, like SVG---
+            if not hasattr(image_part, "sha1"):
+                continue
+            if image_part.sha1 == sha1:
+                return image_part
+        return None
+
+
+class _MediaParts(object):
+    """Provides access to the media parts in a package.
+
+    Supports iteration and :meth:`get()` using the media object SHA1 hash as
+    its key.
+    """
+
+    def __init__(self, package):
+        super(_MediaParts, self).__init__()
+        self._package = package
+
+    def __iter__(self):
+        """Generate a reference to each |MediaPart| object in the package."""
+        # A media part can appear in more than one relationship (and commonly
+        # does in the case of video). Use media_parts to keep track of those
+        # that have been "yielded"; they can be skipped if they occur again.
+        media_parts = []
+        for rel in self._package.iter_rels():
+            if rel.is_external:
+                continue
+            if rel.reltype not in (RT.MEDIA, RT.VIDEO):
+                continue
+            media_part = rel.target_part
+            if media_part in media_parts:
+                continue
+            media_parts.append(media_part)
+            yield media_part
+
+    def get_or_add_media_part(self, media):
+        """Return a |MediaPart| object containing the media in *media*.
+
+        If this package already contains a media part for the same
+        bytestream, that instance is returned, otherwise a new media part is
+        created.
+        """
+        media_part = self._find_by_sha1(media.sha1)
+        if media_part is None:
+            media_part = MediaPart.new(self._package, media)
+        return media_part
+
+    def _find_by_sha1(self, sha1):
+        """Return |MediaPart| object having *sha1* hash or None if not found.
+
+        All media parts belonging to this package are considered. A media
+        part is identified by the SHA1 hash digest of its bytestream
+        ("file").
+        """
+        for media_part in self:
+            if media_part.sha1 == sha1:
+                return media_part
+        return None

pptx2/parts/chart.py

@@ -0,0 +1,95 @@
+"""Chart part objects, including Chart and Charts."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pptx2.chart.chart import Chart
+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.parts.embeddedpackage import EmbeddedXlsxPart
+from pptx2.util import lazyproperty
+
+if TYPE_CHECKING:
+    from pptx2.chart.data import ChartData
+    from pptx2.enum.chart import XL_CHART_TYPE
+    from pptx2.package import Package
+
+
+class ChartPart(XmlPart):
+    """A chart part.
+
+    Corresponds to parts having partnames matching ppt/charts/chart[1-9][0-9]*.xml
+    """
+
+    partname_template = "/ppt/charts/chart%d.xml"
+
+    @classmethod
+    def new(cls, chart_type: XL_CHART_TYPE, chart_data: ChartData, package: Package):
+        """Return new |ChartPart| instance added to `package`.
+
+        Returned chart-part contains a chart of `chart_type` depicting `chart_data`.
+        """
+        chart_part = cls.load(
+            package.next_partname(cls.partname_template),
+            CT.DML_CHART,
+            package,
+            chart_data.xml_bytes(chart_type),
+        )
+        chart_part.chart_workbook.update_from_xlsx_blob(chart_data.xlsx_blob)
+        return chart_part
+
+    @lazyproperty
+    def chart(self):
+        """|Chart| object representing the chart in this part."""
+        return Chart(self._element, self)
+
+    @lazyproperty
+    def chart_workbook(self):
+        """
+        The |ChartWorkbook| object providing access to the external chart
+        data in a linked or embedded Excel workbook.
+        """
+        return ChartWorkbook(self._element, self)
+
+
+class ChartWorkbook(object):
+    """Provides access to external chart data in a linked or embedded Excel workbook."""
+
+    def __init__(self, chartSpace, chart_part):
+        super(ChartWorkbook, self).__init__()
+        self._chartSpace = chartSpace
+        self._chart_part = chart_part
+
+    def update_from_xlsx_blob(self, xlsx_blob):
+        """
+        Replace the Excel spreadsheet in the related |EmbeddedXlsxPart| with
+        the Excel binary in *xlsx_blob*, adding a new |EmbeddedXlsxPart| if
+        there isn't one.
+        """
+        xlsx_part = self.xlsx_part
+        if xlsx_part is None:
+            self.xlsx_part = EmbeddedXlsxPart.new(xlsx_blob, self._chart_part.package)
+            return
+        xlsx_part.blob = xlsx_blob
+
+    @property
+    def xlsx_part(self):
+        """Optional |EmbeddedXlsxPart| object containing data for this chart.
+
+        This related part has its rId at `c:chartSpace/c:externalData/@rId`. This value
+        is |None| if there is no `<c:externalData>` element.
+        """
+        xlsx_part_rId = self._chartSpace.xlsx_part_rId
+        return None if xlsx_part_rId is None else self._chart_part.related_part(xlsx_part_rId)
+
+    @xlsx_part.setter
+    def xlsx_part(self, xlsx_part):
+        """
+        Set the related |EmbeddedXlsxPart| to *xlsx_part*. Assume one does
+        not already exist.
+        """
+        rId = self._chart_part.relate_to(xlsx_part, RT.PACKAGE)
+        externalData = self._chartSpace.get_or_add_externalData()
+        externalData.rId = rId

pptx2/parts/coreprops.py

@@ -0,0 +1,167 @@
+"""Core properties part, corresponds to ``/docProps/core.xml`` part in package."""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import TYPE_CHECKING
+
+from pptx2.opc.constants import CONTENT_TYPE as CT
+from pptx2.opc.package import XmlPart
+from pptx2.opc.packuri import PackURI
+from pptx2.oxml.coreprops import CT_CoreProperties
+
+if TYPE_CHECKING:
+    from pptx2.package import Package
+
+
+class CorePropertiesPart(XmlPart):
+    """Corresponds to part named `/docProps/core.xml`.
+
+    Contains the core document properties for this document package.
+    """
+
+    _element: CT_CoreProperties
+
+    @classmethod
+    def default(cls, package: Package):
+        """Return default new |CorePropertiesPart| instance suitable as starting point.
+
+        This provides a base for adding core-properties to a package that doesn't yet
+        have any.
+        """
+        core_props = cls._new(package)
+        core_props.title = "PowerPoint Presentation"
+        core_props.last_modified_by = "python-pptx"
+        core_props.revision = 1
+        core_props.modified = dt.datetime.now(dt.timezone.utc).replace(tzinfo=None)
+        return core_props
+
+    @property
+    def author(self) -> str:
+        return self._element.author_text
+
+    @author.setter
+    def author(self, value: str):
+        self._element.author_text = value
+
+    @property
+    def category(self) -> str:
+        return self._element.category_text
+
+    @category.setter
+    def category(self, value: str):
+        self._element.category_text = value
+
+    @property
+    def comments(self) -> str:
+        return self._element.comments_text
+
+    @comments.setter
+    def comments(self, value: str):
+        self._element.comments_text = value
+
+    @property
+    def content_status(self) -> str:
+        return self._element.contentStatus_text
+
+    @content_status.setter
+    def content_status(self, value: str):
+        self._element.contentStatus_text = value
+
+    @property
+    def created(self):
+        return self._element.created_datetime
+
+    @created.setter
+    def created(self, value: dt.datetime):
+        self._element.created_datetime = value
+
+    @property
+    def identifier(self) -> str:
+        return self._element.identifier_text
+
+    @identifier.setter
+    def identifier(self, value: str):
+        self._element.identifier_text = value
+
+    @property
+    def keywords(self) -> str:
+        return self._element.keywords_text
+
+    @keywords.setter
+    def keywords(self, value: str):
+        self._element.keywords_text = value
+
+    @property
+    def language(self) -> str:
+        return self._element.language_text
+
+    @language.setter
+    def language(self, value: str):
+        self._element.language_text = value
+
+    @property
+    def last_modified_by(self) -> str:
+        return self._element.lastModifiedBy_text
+
+    @last_modified_by.setter
+    def last_modified_by(self, value: str):
+        self._element.lastModifiedBy_text = value
+
+    @property
+    def last_printed(self):
+        return self._element.lastPrinted_datetime
+
+    @last_printed.setter
+    def last_printed(self, value: dt.datetime):
+        self._element.lastPrinted_datetime = value
+
+    @property
+    def modified(self):
+        return self._element.modified_datetime
+
+    @modified.setter
+    def modified(self, value: dt.datetime):
+        self._element.modified_datetime = value
+
+    @property
+    def revision(self):
+        return self._element.revision_number
+
+    @revision.setter
+    def revision(self, value: int):
+        self._element.revision_number = value
+
+    @property
+    def subject(self) -> str:
+        return self._element.subject_text
+
+    @subject.setter
+    def subject(self, value: str):
+        self._element.subject_text = value
+
+    @property
+    def title(self) -> str:
+        return self._element.title_text
+
+    @title.setter
+    def title(self, value: str):
+        self._element.title_text = value
+
+    @property
+    def version(self) -> str:
+        return self._element.version_text
+
+    @version.setter
+    def version(self, value: str):
+        self._element.version_text = value
+
+    @classmethod
+    def _new(cls, package: Package) -> CorePropertiesPart:
+        """Return new empty |CorePropertiesPart| instance."""
+        return CorePropertiesPart(
+            PackURI("/docProps/core.xml"),
+            CT.OPC_CORE_PROPERTIES,
+            package,
+            CT_CoreProperties.new_coreProperties(),
+        )

pptx2/parts/diagram.py

@@ -0,0 +1,37 @@
+"""Diagram part objects for SmartArt diagrams."""
+
+from __future__ import annotations
+
+from pptx2.opc.package import XmlPart
+
+
+class DiagramDataPart(XmlPart):
+    """Part wrapping a ``diagrams/data#.xml`` file (SmartArt data model).
+
+    Content-type:
+        ``application/vnd.openxmlformats-officedocument.drawingml.diagramData+xml``
+    """
+
+
+class DiagramLayoutPart(XmlPart):
+    """Part wrapping a ``diagrams/layout#.xml`` file (SmartArt layout definition).
+
+    Content-type:
+        ``application/vnd.openxmlformats-officedocument.drawingml.diagramLayout+xml``
+    """
+
+
+class DiagramStylePart(XmlPart):
+    """Part wrapping a ``diagrams/quickStyle#.xml`` file (SmartArt quick-style).
+
+    Content-type:
+        ``application/vnd.openxmlformats-officedocument.drawingml.diagramStyle+xml``
+    """
+
+
+class DiagramColorsPart(XmlPart):
+    """Part wrapping a ``diagrams/colors#.xml`` file (SmartArt color style).
+
+    Content-type:
+        ``application/vnd.openxmlformats-officedocument.drawingml.diagramColors+xml``
+    """

pptx2/parts/embeddedpackage.py

@@ -0,0 +1,93 @@
+"""Embedded Package part objects.
+
+"Package" in this context means another OPC package, i.e. a DOCX, PPTX, or XLSX "file".
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pptx2.enum.shapes import PROG_ID
+from pptx2.opc.constants import CONTENT_TYPE as CT
+from pptx2.opc.package import Part
+
+if TYPE_CHECKING:
+    from pptx2.package import Package
+
+
+class EmbeddedPackagePart(Part):
+    """A distinct OPC package, e.g. an Excel file, embedded in this PPTX package.
+
+    Has a partname like: `ppt/embeddings/Microsoft_Excel_Sheet1.xlsx`.
+    """
+
+    @classmethod
+    def factory(cls, prog_id: PROG_ID | str, object_blob: bytes, package: Package):
+        """Return a new |EmbeddedPackagePart| subclass instance added to *package*.
+
+        The subclass is determined by `prog_id` which corresponds to the "application"
+        used to open the "file-type" of `object_blob`. The returned part contains the
+        bytes of `object_blob` and has the content-type also determined by `prog_id`.
+        """
+        # --- a generic OLE object has no subclass ---
+        if not isinstance(prog_id, PROG_ID):
+            return cls(
+                package.next_partname("/ppt/embeddings/oleObject%d.bin"),
+                CT.OFC_OLE_OBJECT,
+                package,
+                object_blob,
+            )
+
+        # --- A Microsoft Office file-type is a distinguished package object ---
+        EmbeddedPartCls = {
+            PROG_ID.DOCX: EmbeddedDocxPart,
+            PROG_ID.PPTX: EmbeddedPptxPart,
+            PROG_ID.XLSX: EmbeddedXlsxPart,
+        }[prog_id]
+
+        return EmbeddedPartCls.new(object_blob, package)
+
+    @classmethod
+    def new(cls, blob: bytes, package: Package):
+        """Return new |EmbeddedPackagePart| subclass object.
+
+        The returned part object contains `blob` and is added to `package`.
+        """
+        return cls(
+            package.next_partname(cls.partname_template),
+            cls.content_type,
+            package,
+            blob,
+        )
+
+
+class EmbeddedDocxPart(EmbeddedPackagePart):
+    """A Word .docx file stored in a part.
+
+    This part-type arises when a Word document appears as an embedded OLE-object shape.
+    """
+
+    partname_template = "/ppt/embeddings/Microsoft_Word_Document%d.docx"
+    content_type = CT.WML_DOCUMENT
+
+
+class EmbeddedPptxPart(EmbeddedPackagePart):
+    """A PowerPoint file stored in a part.
+
+    This part-type arises when a PowerPoint presentation (.pptx file) appears as an
+    embedded OLE-object shape.
+    """
+
+    partname_template = "/ppt/embeddings/Microsoft_PowerPoint_Presentation%d.pptx"
+    content_type = CT.PML_PRESENTATION
+
+
+class EmbeddedXlsxPart(EmbeddedPackagePart):
+    """An Excel file stored in a part.
+
+    This part-type arises as the data source for a chart, but may also be the OLE-object
+    for an embedded object shape.
+    """
+
+    partname_template = "/ppt/embeddings/Microsoft_Excel_Sheet%d.xlsx"
+    content_type = CT.SML_SHEET