ps-python-docx 1.3.0__py3-none-any.whl

docx/opc/pkgreader.py

@@ -0,0 +1,254 @@
+"""Low-level, read-only API to a serialized Open Packaging Convention (OPC) package."""
+
+from docx.opc.constants import RELATIONSHIP_TARGET_MODE as RTM
+from docx.opc.oxml import parse_xml
+from docx.opc.packuri import PACKAGE_URI, PackURI
+from docx.opc.phys_pkg import PhysPkgReader
+from docx.opc.shared import CaseInsensitiveDict
+
+
+class PackageReader:
+    """Provides access to the contents of a zip-format OPC package via its
+    :attr:`serialized_parts` and :attr:`pkg_srels` attributes."""
+
+    def __init__(self, content_types, pkg_srels, sparts):
+        super(PackageReader, self).__init__()
+        self._pkg_srels = pkg_srels
+        self._sparts = sparts
+
+    @staticmethod
+    def from_file(pkg_file):
+        """Return a |PackageReader| instance loaded with contents of `pkg_file`."""
+        phys_reader = PhysPkgReader(pkg_file)
+        content_types = _ContentTypeMap.from_xml(phys_reader.content_types_xml)
+        pkg_srels = PackageReader._srels_for(phys_reader, PACKAGE_URI)
+        sparts = PackageReader._load_serialized_parts(phys_reader, pkg_srels, content_types)
+        phys_reader.close()
+        return PackageReader(content_types, pkg_srels, sparts)
+
+    def iter_sparts(self):
+        """Generate a 4-tuple `(partname, content_type, reltype, blob)` for each of the
+        serialized parts in the package."""
+        for s in self._sparts:
+            yield (s.partname, s.content_type, s.reltype, s.blob)
+
+    def iter_srels(self):
+        """Generate a 2-tuple `(source_uri, srel)` for each of the relationships in the
+        package."""
+        for srel in self._pkg_srels:
+            yield (PACKAGE_URI, srel)
+        for spart in self._sparts:
+            for srel in spart.srels:
+                yield (spart.partname, srel)
+
+    @staticmethod
+    def _load_serialized_parts(phys_reader, pkg_srels, content_types):
+        """Return a list of |_SerializedPart| instances corresponding to the parts in
+        `phys_reader` accessible by walking the relationship graph starting with
+        `pkg_srels`."""
+        sparts = []
+        part_walker = PackageReader._walk_phys_parts(phys_reader, pkg_srels)
+        for partname, blob, reltype, srels in part_walker:
+            content_type = content_types[partname]
+            spart = _SerializedPart(partname, content_type, reltype, blob, srels)
+            sparts.append(spart)
+        return tuple(sparts)
+
+    @staticmethod
+    def _srels_for(phys_reader, source_uri):
+        """Return |_SerializedRelationships| instance populated with relationships for
+        source identified by `source_uri`."""
+        rels_xml = phys_reader.rels_xml_for(source_uri)
+        return _SerializedRelationships.load_from_xml(source_uri.baseURI, rels_xml)
+
+    @staticmethod
+    def _walk_phys_parts(phys_reader, srels, visited_partnames=None):
+        """Generate a 4-tuple `(partname, blob, reltype, srels)` for each of the parts
+        in `phys_reader` by walking the relationship graph rooted at srels."""
+        if visited_partnames is None:
+            visited_partnames = []
+        for srel in srels:
+            if srel.is_external:
+                continue
+            partname = srel.target_partname
+            if partname in visited_partnames:
+                continue
+            visited_partnames.append(partname)
+            reltype = srel.reltype
+            part_srels = PackageReader._srels_for(phys_reader, partname)
+            blob = phys_reader.blob_for(partname)
+            yield (partname, blob, reltype, part_srels)
+            next_walker = PackageReader._walk_phys_parts(phys_reader, part_srels, visited_partnames)
+            for partname, blob, reltype, srels in next_walker:
+                yield (partname, blob, reltype, srels)
+
+
+class _ContentTypeMap:
+    """Value type providing dictionary semantics for looking up content type by part
+    name, e.g. ``content_type = cti['/ppt/presentation.xml']``."""
+
+    def __init__(self):
+        super(_ContentTypeMap, self).__init__()
+        self._overrides = CaseInsensitiveDict()
+        self._defaults = CaseInsensitiveDict()
+
+    def __getitem__(self, partname):
+        """Return content type for part identified by `partname`."""
+        if not isinstance(partname, PackURI):
+            tmpl = "_ContentTypeMap key must be <type 'PackURI'>, got %s"
+            raise KeyError(tmpl % type(partname))
+        if partname in self._overrides:
+            return self._overrides[partname]
+        if partname.ext in self._defaults:
+            return self._defaults[partname.ext]
+        tmpl = "no content type for partname '%s' in [Content_Types].xml"
+        raise KeyError(tmpl % partname)
+
+    @staticmethod
+    def from_xml(content_types_xml):
+        """Return a new |_ContentTypeMap| instance populated with the contents of
+        `content_types_xml`."""
+        types_elm = parse_xml(content_types_xml)
+        ct_map = _ContentTypeMap()
+        for o in types_elm.overrides:
+            ct_map._add_override(o.partname, o.content_type)
+        for d in types_elm.defaults:
+            ct_map._add_default(d.extension, d.content_type)
+        return ct_map
+
+    def _add_default(self, extension, content_type):
+        """Add the default mapping of `extension` to `content_type` to this content type
+        mapping."""
+        self._defaults[extension] = content_type
+
+    def _add_override(self, partname, content_type):
+        """Add the default mapping of `partname` to `content_type` to this content type
+        mapping."""
+        self._overrides[partname] = content_type
+
+
+class _SerializedPart:
+    """Value object for an OPC package part.
+
+    Provides access to the partname, content type, blob, and serialized relationships
+    for the part.
+    """
+
+    def __init__(self, partname, content_type, reltype, blob, srels):
+        super(_SerializedPart, self).__init__()
+        self._partname = partname
+        self._content_type = content_type
+        self._reltype = reltype
+        self._blob = blob
+        self._srels = srels
+
+    @property
+    def partname(self):
+        return self._partname
+
+    @property
+    def content_type(self):
+        return self._content_type
+
+    @property
+    def blob(self):
+        return self._blob
+
+    @property
+    def reltype(self):
+        """The referring relationship type of this part."""
+        return self._reltype
+
+    @property
+    def srels(self):
+        return self._srels
+
+
+class _SerializedRelationship:
+    """Value object representing a serialized relationship in an OPC package.
+
+    Serialized, in this case, means any target part is referred to via its partname
+    rather than a direct link to an in-memory |Part| object.
+    """
+
+    def __init__(self, baseURI, rel_elm):
+        super(_SerializedRelationship, self).__init__()
+        self._baseURI = baseURI
+        self._rId = rel_elm.rId
+        self._reltype = rel_elm.reltype
+        self._target_mode = rel_elm.target_mode
+        self._target_ref = rel_elm.target_ref
+
+    @property
+    def is_external(self):
+        """True if target_mode is ``RTM.EXTERNAL``"""
+        return self._target_mode == RTM.EXTERNAL
+
+    @property
+    def reltype(self):
+        """Relationship type, like ``RT.OFFICE_DOCUMENT``"""
+        return self._reltype
+
+    @property
+    def rId(self):
+        """Relationship id, like 'rId9', corresponds to the ``Id`` attribute on the
+        ``CT_Relationship`` element."""
+        return self._rId
+
+    @property
+    def target_mode(self):
+        """String in ``TargetMode`` attribute of ``CT_Relationship`` element, one of
+        ``RTM.INTERNAL`` or ``RTM.EXTERNAL``."""
+        return self._target_mode
+
+    @property
+    def target_ref(self):
+        """String in ``Target`` attribute of ``CT_Relationship`` element, a relative
+        part reference for internal target mode or an arbitrary URI, e.g. an HTTP URL,
+        for external target mode."""
+        return self._target_ref
+
+    @property
+    def target_partname(self):
+        """|PackURI| instance containing partname targeted by this relationship.
+
+        Raises ``ValueError`` on reference if target_mode is ``'External'``. Use
+        :attr:`target_mode` to check before referencing.
+        """
+        if self.is_external:
+            msg = (
+                "target_partname attribute on Relationship is undefined w"
+                'here TargetMode == "External"'
+            )
+            raise ValueError(msg)
+        # lazy-load _target_partname attribute
+        if not hasattr(self, "_target_partname"):
+            self._target_partname = PackURI.from_rel_ref(self._baseURI, self.target_ref)
+        return self._target_partname
+
+
+class _SerializedRelationships:
+    """Read-only sequence of |_SerializedRelationship| instances corresponding to the
+    relationships item XML passed to constructor."""
+
+    def __init__(self):
+        super(_SerializedRelationships, self).__init__()
+        self._srels = []
+
+    def __iter__(self):
+        """Support iteration, e.g. 'for x in srels:'."""
+        return self._srels.__iter__()
+
+    @staticmethod
+    def load_from_xml(baseURI, rels_item_xml):
+        """Return |_SerializedRelationships| instance loaded with the relationships
+        contained in `rels_item_xml`.
+
+        Returns an empty collection if `rels_item_xml` is |None|.
+        """
+        srels = _SerializedRelationships()
+        if rels_item_xml is not None:
+            rels_elm = parse_xml(rels_item_xml)
+            for rel_elm in rels_elm.Relationship_lst:
+                srels._srels.append(_SerializedRelationship(baseURI, rel_elm))
+        return srels

docx/opc/pkgwriter.py

@@ -0,0 +1,115 @@
+"""Provides low-level, write-only API to serialized (OPC) package.
+
+OPC stands for Open Packaging Convention. This is e, essentially an implementation of
+OpcPackage.save().
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterable
+
+from docx.opc.constants import CONTENT_TYPE as CT
+from docx.opc.oxml import CT_Types, serialize_part_xml
+from docx.opc.packuri import CONTENT_TYPES_URI, PACKAGE_URI
+from docx.opc.phys_pkg import PhysPkgWriter
+from docx.opc.shared import CaseInsensitiveDict
+from docx.opc.spec import default_content_types
+
+if TYPE_CHECKING:
+    from docx.opc.part import Part
+
+
+class PackageWriter:
+    """Writes a zip-format OPC package to `pkg_file`, where `pkg_file` can be either a
+    path to a zip file (a string) or a file-like object.
+
+    Its single API method, :meth:`write`, is static, so this class is not intended to be
+    instantiated.
+    """
+
+    @staticmethod
+    def write(pkg_file, pkg_rels, parts):
+        """Write a physical package (.pptx file) to `pkg_file` containing `pkg_rels` and
+        `parts` and a content types stream based on the content types of the parts."""
+        phys_writer = PhysPkgWriter(pkg_file)
+        PackageWriter._write_content_types_stream(phys_writer, parts)
+        PackageWriter._write_pkg_rels(phys_writer, pkg_rels)
+        PackageWriter._write_parts(phys_writer, parts)
+        phys_writer.close()
+
+    @staticmethod
+    def _write_content_types_stream(phys_writer, parts):
+        """Write ``[Content_Types].xml`` part to the physical package with an
+        appropriate content type lookup target for each part in `parts`."""
+        cti = _ContentTypesItem.from_parts(parts)
+        phys_writer.write(CONTENT_TYPES_URI, cti.blob)
+
+    @staticmethod
+    def _write_parts(phys_writer: PhysPkgWriter, parts: Iterable[Part]):
+        """Write the blob of each part in `parts` to the package, along with a rels item
+        for its relationships if and only if it has any."""
+        for part in parts:
+            phys_writer.write(part.partname, part.blob)
+            if len(part.rels):
+                phys_writer.write(part.partname.rels_uri, part.rels.xml)
+
+    @staticmethod
+    def _write_pkg_rels(phys_writer, pkg_rels):
+        """Write the XML rels item for `pkg_rels` ('/_rels/.rels') to the package."""
+        phys_writer.write(PACKAGE_URI.rels_uri, pkg_rels.xml)
+
+
+class _ContentTypesItem:
+    """Service class that composes a content types item ([Content_Types].xml) based on a
+    list of parts.
+
+    Not meant to be instantiated directly, its single interface method is xml_for(),
+    e.g. ``_ContentTypesItem.xml_for(parts)``.
+    """
+
+    def __init__(self):
+        self._defaults = CaseInsensitiveDict()
+        self._overrides = {}
+
+    @property
+    def blob(self):
+        """Return XML form of this content types item, suitable for storage as
+        ``[Content_Types].xml`` in an OPC package."""
+        return serialize_part_xml(self._element)
+
+    @classmethod
+    def from_parts(cls, parts):
+        """Return content types XML mapping each part in `parts` to the appropriate
+        content type and suitable for storage as ``[Content_Types].xml`` in an OPC
+        package."""
+        cti = cls()
+        cti._defaults["rels"] = CT.OPC_RELATIONSHIPS
+        cti._defaults["xml"] = CT.XML
+        for part in parts:
+            cti._add_content_type(part.partname, part.content_type)
+        return cti
+
+    def _add_content_type(self, partname, content_type):
+        """Add a content type for the part with `partname` and `content_type`, using a
+        default or override as appropriate."""
+        ext = partname.ext
+        if (ext.lower(), content_type) in default_content_types:
+            self._defaults[ext] = content_type
+        else:
+            self._overrides[partname] = content_type
+
+    @property
+    def _element(self):
+        """Return XML form of this content types item, suitable for storage as
+        ``[Content_Types].xml`` in an OPC package.
+
+        Although the sequence of elements is not strictly significant, as an aid to
+        testing and readability Default elements are sorted by extension and Override
+        elements are sorted by partname.
+        """
+        _types_elm = CT_Types.new()
+        for ext in sorted(self._defaults.keys()):
+            _types_elm.add_default(ext, self._defaults[ext])
+        for partname in sorted(self._overrides.keys()):
+            _types_elm.add_override(partname, self._overrides[partname])
+        return _types_elm

docx/opc/rel.py

@@ -0,0 +1,153 @@
+"""Relationship-related objects."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, cast
+
+from docx.opc.oxml import CT_Relationships
+
+if TYPE_CHECKING:
+    from docx.opc.part import Part
+
+
+class Relationships(Dict[str, "_Relationship"]):
+    """Collection object for |_Relationship| instances, having list semantics."""
+
+    def __init__(self, baseURI: str):
+        super(Relationships, self).__init__()
+        self._baseURI = baseURI
+        self._target_parts_by_rId: dict[str, Any] = {}
+
+    def add_relationship(
+        self, reltype: str, target: Part | str, rId: str, is_external: bool = False
+    ) -> "_Relationship":
+        """Return a newly added |_Relationship| instance."""
+        rel = _Relationship(rId, reltype, target, self._baseURI, is_external)
+        self[rId] = rel
+        if not is_external:
+            self._target_parts_by_rId[rId] = target
+        return rel
+
+    def get_or_add(self, reltype: str, target_part: Part) -> _Relationship:
+        """Return relationship of `reltype` to `target_part`, newly added if not already
+        present in collection."""
+        rel = self._get_matching(reltype, target_part)
+        if rel is None:
+            rId = self._next_rId
+            rel = self.add_relationship(reltype, target_part, rId)
+        return rel
+
+    def get_or_add_ext_rel(self, reltype: str, target_ref: str) -> str:
+        """Return rId of external relationship of `reltype` to `target_ref`, newly added
+        if not already present in collection."""
+        rel = self._get_matching(reltype, target_ref, is_external=True)
+        if rel is None:
+            rId = self._next_rId
+            rel = self.add_relationship(reltype, target_ref, rId, is_external=True)
+        return rel.rId
+
+    def part_with_reltype(self, reltype: str) -> Part:
+        """Return target part of rel with matching `reltype`, raising |KeyError| if not
+        found and |ValueError| if more than one matching relationship is found."""
+        rel = self._get_rel_of_type(reltype)
+        return rel.target_part
+
+    @property
+    def related_parts(self):
+        """Dict mapping rIds to target parts for all the internal relationships in the
+        collection."""
+        return self._target_parts_by_rId
+
+    @property
+    def xml(self) -> str:
+        """Serialize this relationship collection into XML suitable for storage as a
+        .rels file in an OPC package."""
+        rels_elm = CT_Relationships.new()
+        for rel in self.values():
+            rels_elm.add_rel(rel.rId, rel.reltype, rel.target_ref, rel.is_external)
+        return rels_elm.xml
+
+    def _get_matching(
+        self, reltype: str, target: Part | str, is_external: bool = False
+    ) -> _Relationship | None:
+        """Return relationship of matching `reltype`, `target`, and `is_external` from
+        collection, or None if not found."""
+
+        def matches(rel: _Relationship, reltype: str, target: Part | str, is_external: bool):
+            if rel.reltype != reltype:
+                return False
+            if rel.is_external != is_external:
+                return False
+            rel_target = rel.target_ref if rel.is_external else rel.target_part
+            return rel_target == target
+
+        for rel in self.values():
+            if matches(rel, reltype, target, is_external):
+                return rel
+        return None
+
+    def _get_rel_of_type(self, reltype: str):
+        """Return single relationship of type `reltype` from the collection.
+
+        Raises |KeyError| if no matching relationship is found. Raises |ValueError| if
+        more than one matching relationship is found.
+        """
+        matching = [rel for rel in self.values() if rel.reltype == reltype]
+        if len(matching) == 0:
+            tmpl = "no relationship of type '%s' in collection"
+            raise KeyError(tmpl % reltype)
+        if len(matching) > 1:
+            tmpl = "multiple relationships of type '%s' in collection"
+            raise ValueError(tmpl % reltype)
+        return matching[0]
+
+    @property
+    def _next_rId(self) -> str:  # pyright: ignore[reportReturnType]
+        """Next available rId in collection, starting from 'rId1' and making use of any
+        gaps in numbering, e.g. 'rId2' for rIds ['rId1', 'rId3']."""
+        for n in range(1, len(self) + 2):
+            rId_candidate = "rId%d" % n  # like 'rId19'
+            if rId_candidate not in self:
+                return rId_candidate
+
+
+class _Relationship:
+    """Value object for relationship to part."""
+
+    def __init__(
+        self, rId: str, reltype: str, target: Part | str, baseURI: str, external: bool = False
+    ):
+        super(_Relationship, self).__init__()
+        self._rId = rId
+        self._reltype = reltype
+        self._target = target
+        self._baseURI = baseURI
+        self._is_external = bool(external)
+
+    @property
+    def is_external(self) -> bool:
+        return self._is_external
+
+    @property
+    def reltype(self) -> str:
+        return self._reltype
+
+    @property
+    def rId(self) -> str:
+        return self._rId
+
+    @property
+    def target_part(self) -> Part:
+        if self._is_external:
+            raise ValueError(
+                "target_part property on _Relationship is undefined when target mode is External"
+            )
+        return cast("Part", self._target)
+
+    @property
+    def target_ref(self) -> str:
+        if self._is_external:
+            return cast(str, self._target)
+        else:
+            target = cast("Part", self._target)
+            return target.partname.relative_ref(self._baseURI)

docx/opc/shared.py

@@ -0,0 +1,31 @@
+"""Objects shared by opc modules."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, TypeVar
+
+_T = TypeVar("_T")
+
+
+class CaseInsensitiveDict(Dict[str, Any]):
+    """Mapping type that behaves like dict except that it matches without respect to the
+    case of the key.
+
+    E.g. cid['A'] == cid['a']. Note this is not general-purpose, just complete enough to
+    satisfy opc package needs. It assumes str keys, and that it is created empty; keys
+    passed in constructor are not accounted for
+    """
+
+    def __contains__(self, key):
+        return super(CaseInsensitiveDict, self).__contains__(key.lower())
+
+    def __getitem__(self, key):
+        return super(CaseInsensitiveDict, self).__getitem__(key.lower())
+
+    def __setitem__(self, key, value):
+        return super(CaseInsensitiveDict, self).__setitem__(key.lower(), value)
+
+
+def cls_method_fn(cls: type, method_name: str):
+    """Return method of `cls` having `method_name`."""
+    return getattr(cls, method_name)

docx/opc/spec.py

@@ -0,0 +1,24 @@
+"""Provides mappings that embody aspects of the Open XML spec ISO/IEC 29500."""
+
+from docx.opc.constants import CONTENT_TYPE as CT
+
+default_content_types = (
+    ("bin", CT.PML_PRINTER_SETTINGS),
+    ("bin", CT.SML_PRINTER_SETTINGS),
+    ("bin", CT.WML_PRINTER_SETTINGS),
+    ("bmp", CT.BMP),
+    ("emf", CT.X_EMF),
+    ("fntdata", CT.X_FONTDATA),
+    ("gif", CT.GIF),
+    ("jpe", CT.JPEG),
+    ("jpeg", CT.JPEG),
+    ("jpg", CT.JPEG),
+    ("png", CT.PNG),
+    ("rels", CT.OPC_RELATIONSHIPS),
+    ("tif", CT.TIFF),
+    ("tiff", CT.TIFF),
+    ("wdp", CT.MS_PHOTO),
+    ("wmf", CT.X_WMF),
+    ("xlsx", CT.SML_SHEET),
+    ("xml", CT.XML),
+)