python-docx-oss 0.1.0__py3-none-any.whl

docx/opc/oxml.py

@@ -0,0 +1,247 @@
+# pyright: reportPrivateUsage=false
+
+"""Temporary stand-in for main oxml module.
+
+This module came across with the PackageReader transplant. Probably much will get
+replaced with objects from the pptx.oxml.core and then this module will either get
+deleted or only hold the package related custom element classes.
+"""
+
+from __future__ import annotations
+
+from typing import cast
+
+from lxml import etree
+
+from docx.opc.constants import NAMESPACE as NS
+from docx.opc.constants import RELATIONSHIP_TARGET_MODE as RTM
+
+# configure XML parser
+element_class_lookup = etree.ElementNamespaceClassLookup()
+oxml_parser = etree.XMLParser(remove_blank_text=True, resolve_entities=False)
+oxml_parser.set_element_class_lookup(element_class_lookup)
+
+nsmap = {
+    "ct": NS.OPC_CONTENT_TYPES,
+    "pr": NS.OPC_RELATIONSHIPS,
+    "r": NS.OFC_RELATIONSHIPS,
+}
+
+
+# ===========================================================================
+# functions
+# ===========================================================================
+
+
+def parse_xml(text: str) -> etree._Element:
+    """`etree.fromstring()` replacement that uses oxml parser."""
+    return etree.fromstring(text, oxml_parser)
+
+
+def qn(tag: str) -> str:
+    """Stands for "qualified name", a utility function to turn a namespace prefixed tag
+    name into a Clark-notation qualified tag name for lxml.
+
+    For
+    example, ``qn('p:cSld')`` returns ``'{http://schemas.../main}cSld'``.
+    """
+    prefix, tagroot = tag.split(":")
+    uri = nsmap[prefix]
+    return "{%s}%s" % (uri, tagroot)
+
+
+def serialize_part_xml(part_elm: etree._Element) -> bytes:
+    """Serialize `part_elm` etree element to XML suitable for storage as an XML part.
+
+    That is to say, no insignificant whitespace added for readability, and an
+    appropriate XML declaration added with UTF-8 encoding specified.
+    """
+    return etree.tostring(part_elm, encoding="UTF-8", standalone=True)
+
+
+def serialize_for_reading(element: etree._Element) -> str:
+    """Serialize `element` to human-readable XML suitable for tests.
+
+    No XML declaration.
+    """
+    return etree.tostring(element, encoding="unicode", pretty_print=True)
+
+
+# ===========================================================================
+# Custom element classes
+# ===========================================================================
+
+
+class BaseOxmlElement(etree.ElementBase):
+    """Base class for all custom element classes, to add standardized behavior to all
+    classes in one place."""
+
+    @property
+    def xml(self) -> str:
+        """Return XML string for this element, suitable for testing purposes.
+
+        Pretty printed for readability and without an XML declaration at the top.
+        """
+        return serialize_for_reading(self)
+
+
+class CT_Default(BaseOxmlElement):
+    """`<Default>` element that appears in `[Content_Types].xml` part.
+
+    Used to specify a default content type to be applied to any part with the specified extension.
+    """
+
+    @property
+    def content_type(self):
+        """String held in the ``ContentType`` attribute of this ``<Default>``
+        element."""
+        return self.get("ContentType")
+
+    @property
+    def extension(self):
+        """String held in the ``Extension`` attribute of this ``<Default>`` element."""
+        return self.get("Extension")
+
+    @staticmethod
+    def new(ext: str, content_type: str):
+        """Return a new ``<Default>`` element with attributes set to parameter values."""
+        xml = '<Default xmlns="%s"/>' % nsmap["ct"]
+        default = parse_xml(xml)
+        default.set("Extension", ext)
+        default.set("ContentType", content_type)
+        return default
+
+
+class CT_Override(BaseOxmlElement):
+    """``<Override>`` element, specifying the content type to be applied for a part with
+    the specified partname."""
+
+    @property
+    def content_type(self):
+        """String held in the ``ContentType`` attribute of this ``<Override>``
+        element."""
+        return self.get("ContentType")
+
+    @staticmethod
+    def new(partname, content_type):
+        """Return a new ``<Override>`` element with attributes set to parameter values."""
+        xml = '<Override xmlns="%s"/>' % nsmap["ct"]
+        override = parse_xml(xml)
+        override.set("PartName", partname)
+        override.set("ContentType", content_type)
+        return override
+
+    @property
+    def partname(self):
+        """String held in the ``PartName`` attribute of this ``<Override>`` element."""
+        return self.get("PartName")
+
+
+class CT_Relationship(BaseOxmlElement):
+    """`<Relationship>` element, representing a single relationship from source to target part."""
+
+    @staticmethod
+    def new(rId: str, reltype: str, target: str, target_mode: str = RTM.INTERNAL):
+        """Return a new ``<Relationship>`` element."""
+        xml = '<Relationship xmlns="%s"/>' % nsmap["pr"]
+        relationship = parse_xml(xml)
+        relationship.set("Id", rId)
+        relationship.set("Type", reltype)
+        relationship.set("Target", target)
+        if target_mode == RTM.EXTERNAL:
+            relationship.set("TargetMode", RTM.EXTERNAL)
+        return relationship
+
+    @property
+    def rId(self):
+        """String held in the ``Id`` attribute of this ``<Relationship>`` element."""
+        return self.get("Id")
+
+    @property
+    def reltype(self):
+        """String held in the ``Type`` attribute of this ``<Relationship>`` element."""
+        return self.get("Type")
+
+    @property
+    def target_ref(self):
+        """String held in the ``Target`` attribute of this ``<Relationship>``
+        element."""
+        return self.get("Target")
+
+    @property
+    def target_mode(self):
+        """String held in the ``TargetMode`` attribute of this ``<Relationship>``
+        element, either ``Internal`` or ``External``.
+
+        Defaults to ``Internal``.
+        """
+        return self.get("TargetMode", RTM.INTERNAL)
+
+
+class CT_Relationships(BaseOxmlElement):
+    """``<Relationships>`` element, the root element in a .rels file."""
+
+    def add_rel(self, rId: str, reltype: str, target: str, is_external: bool = False):
+        """Add a child ``<Relationship>`` element with attributes set according to
+        parameter values."""
+        target_mode = RTM.EXTERNAL if is_external else RTM.INTERNAL
+        relationship = CT_Relationship.new(rId, reltype, target, target_mode)
+        self.append(relationship)
+
+    @staticmethod
+    def new() -> CT_Relationships:
+        """Return a new ``<Relationships>`` element."""
+        xml = '<Relationships xmlns="%s"/>' % nsmap["pr"]
+        return cast(CT_Relationships, parse_xml(xml))
+
+    @property
+    def Relationship_lst(self):
+        """Return a list containing all the ``<Relationship>`` child elements."""
+        return self.findall(qn("pr:Relationship"))
+
+    @property
+    def xml(self):
+        """Return XML string for this element, suitable for saving in a .rels stream,
+        not pretty printed and with an XML declaration at the top."""
+        return serialize_part_xml(self)
+
+
+class CT_Types(BaseOxmlElement):
+    """``<Types>`` element, the container element for Default and Override elements in
+    [Content_Types].xml."""
+
+    def add_default(self, ext, content_type):
+        """Add a child ``<Default>`` element with attributes set to parameter values."""
+        default = CT_Default.new(ext, content_type)
+        self.append(default)
+
+    def add_override(self, partname, content_type):
+        """Add a child ``<Override>`` element with attributes set to parameter
+        values."""
+        override = CT_Override.new(partname, content_type)
+        self.append(override)
+
+    @property
+    def defaults(self):
+        return self.findall(qn("ct:Default"))
+
+    @staticmethod
+    def new():
+        """Return a new ``<Types>`` element."""
+        xml = '<Types xmlns="%s"/>' % nsmap["ct"]
+        types = parse_xml(xml)
+        return types
+
+    @property
+    def overrides(self):
+        return self.findall(qn("ct:Override"))
+
+
+ct_namespace = element_class_lookup.get_namespace(nsmap["ct"])
+ct_namespace["Default"] = CT_Default
+ct_namespace["Override"] = CT_Override
+ct_namespace["Types"] = CT_Types
+
+pr_namespace = element_class_lookup.get_namespace(nsmap["pr"])
+pr_namespace["Relationship"] = CT_Relationship
+pr_namespace["Relationships"] = CT_Relationships

docx/opc/package.py

@@ -0,0 +1,254 @@
+"""Objects that implement reading and writing OPC packages."""
+
+from __future__ import annotations
+
+from typing import IO, TYPE_CHECKING, Callable, Iterator, cast
+
+from docx.opc.constants import RELATIONSHIP_TYPE as RT
+from docx.opc.packuri import PACKAGE_URI, PackURI
+from docx.opc.part import PartFactory
+from docx.opc.parts.coreprops import CorePropertiesPart
+from docx.opc.parts.customprops import CustomPropertiesPart
+from docx.opc.pkgreader import PackageReader
+from docx.opc.pkgwriter import PackageWriter
+from docx.opc.rel import Relationships, _Relationship
+from docx.shared import lazyproperty
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from docx.opc.coreprops import CoreProperties
+    from docx.opc.customprops import CustomProperties
+    from docx.opc.part import Part
+    from docx.opc.rel import _Relationship  # pyright: ignore[reportPrivateUsage]
+
+
+class OpcPackage:
+    """Main API class for |python-opc|.
+
+    A new instance is constructed by calling the :meth:`open` class method with a path
+    to a package file or file-like object containing one.
+    """
+
+    def after_unmarshal(self):
+        """Entry point for any post-unmarshaling processing.
+
+        May be overridden by subclasses without forwarding call to super.
+        """
+        # don't place any code here, just catch call if not overridden by
+        # subclass
+        pass
+
+    @property
+    def core_properties(self) -> CoreProperties:
+        """|CoreProperties| object providing read/write access to the Dublin Core
+        properties for this document."""
+        return self._core_properties_part.core_properties
+
+    @property
+    def custom_properties(self) -> CustomProperties:
+        """|CustomProperties| object providing read/write access to the custom
+        properties for this document."""
+        return self._custom_properties_part.custom_properties
+
+    def iter_rels(self) -> Iterator[_Relationship]:
+        """Generate exactly one reference to each relationship in the package by
+        performing a depth-first traversal of the rels graph."""
+
+        def walk_rels(
+            source: OpcPackage | Part, visited: list[Part] | None = None
+        ) -> Iterator[_Relationship]:
+            visited = [] if visited is None else visited
+            for rel in source.rels.values():
+                yield rel
+                if rel.is_external:
+                    continue
+                part = rel.target_part
+                if part in visited:
+                    continue
+                visited.append(part)
+                new_source = part
+                for rel in walk_rels(new_source, visited):
+                    yield rel
+
+        for rel in walk_rels(self):
+            yield rel
+
+    def iter_parts(self) -> Iterator[Part]:
+        """Generate exactly one reference to each of the parts in the package by
+        performing a depth-first traversal of the rels graph."""
+
+        def walk_parts(source, visited=[]):
+            for rel in source.rels.values():
+                if rel.is_external:
+                    continue
+                part = rel.target_part
+                if part in visited:
+                    continue
+                visited.append(part)
+                yield part
+                new_source = part
+                for part in walk_parts(new_source, visited):
+                    yield part
+
+        for part in walk_parts(self):
+            yield part
+
+    def load_rel(self, reltype: str, target: Part | str, rId: str, is_external: bool = False):
+        """Return newly added |_Relationship| instance of `reltype` between this part
+        and `target` with key `rId`.
+
+        Target mode is set to ``RTM.EXTERNAL`` if `is_external` is |True|. Intended for
+        use during load from a serialized package, where the rId is well known. Other
+        methods exist for adding a new relationship to the package during processing.
+        """
+        return self.rels.add_relationship(reltype, target, rId, is_external)
+
+    @property
+    def main_document_part(self):
+        """Return a reference to the main document part for this package.
+
+        Examples include a document part for a WordprocessingML package, a presentation
+        part for a PresentationML package, or a workbook part for a SpreadsheetML
+        package.
+        """
+        return self.part_related_by(RT.OFFICE_DOCUMENT)
+
+    def next_partname(self, template: str) -> PackURI:
+        """Return a |PackURI| instance representing partname matching `template`.
+
+        The returned part-name has the next available numeric suffix to distinguish it
+        from other parts of its type. `template` is a printf (%)-style template string
+        containing a single replacement item, a '%d' to be used to insert the integer
+        portion of the partname. Example: "/word/header%d.xml"
+        """
+        partnames = {part.partname for part in self.iter_parts()}
+        for n in range(1, len(partnames) + 2):
+            candidate_partname = template % n
+            if candidate_partname not in partnames:
+                return PackURI(candidate_partname)
+
+    @classmethod
+    def open(cls, pkg_file: str | IO[bytes]) -> Self:
+        """Return an |OpcPackage| instance loaded with the contents of `pkg_file`."""
+        pkg_reader = PackageReader.from_file(pkg_file)
+        package = cls()
+        Unmarshaller.unmarshal(pkg_reader, package, PartFactory)
+        return package
+
+    def part_related_by(self, reltype: str) -> Part:
+        """Return part to which this package has a relationship of `reltype`.
+
+        Raises |KeyError| if no such relationship is found and |ValueError| if more than
+        one such relationship is found.
+        """
+        return self.rels.part_with_reltype(reltype)
+
+    @property
+    def parts(self) -> list[Part]:
+        """Return a list containing a reference to each of the parts in this package."""
+        return list(self.iter_parts())
+
+    def relate_to(self, part: Part, reltype: str):
+        """Return rId key of new or existing relationship to `part`.
+
+        If a relationship of `reltype` to `part` already exists, its rId is returned. Otherwise a
+        new relationship is created and that rId is returned.
+        """
+        rel = self.rels.get_or_add(reltype, part)
+        return rel.rId
+
+    @property
+    def rels(self) -> Relationships:
+        """Return a reference to the |Relationships| instance holding the collection of
+        relationships for this package."""
+        if not hasattr(self, "_rels"):
+            self._rels = Relationships(PACKAGE_URI.baseURI)
+        return self._rels
+
+    @rels.setter
+    def rels(self, new_rels: Relationships):
+        """Set the relationships collection for this package."""
+        self._rels = new_rels
+
+    def drop_rels(self, cmp: Callable[[_Relationship], bool]) -> list[str]:
+        """Drop _Relationship by cmp function, related parts will be ignored when save."""
+        rids = [rid for rid, rel in self.rels.items() if cmp(rel)]
+        for rid in rids:
+            del self.rels[rid]
+        return rids
+
+    def save(self, pkg_file: str | IO[bytes]):
+        """Save this package to `pkg_file`.
+
+        `pkg_file` can be either a file-path or a file-like object.
+        """
+        for part in self.parts:
+            part.before_marshal()
+        PackageWriter.write(pkg_file, self.rels, self.parts)
+
+    @property
+    def _core_properties_part(self) -> CorePropertiesPart:
+        """|CorePropertiesPart| object related to this package.
+
+        Creates a default core properties part if one is not present (not common).
+        """
+        try:
+            return cast(CorePropertiesPart, self.part_related_by(RT.CORE_PROPERTIES))
+        except KeyError:
+            core_properties_part = CorePropertiesPart.default(self)
+            self.relate_to(core_properties_part, RT.CORE_PROPERTIES)
+            return core_properties_part
+
+    @property
+    def _custom_properties_part(self) -> CustomPropertiesPart:
+        """|CustomPropertiesPart| object related to this package.
+
+        Creates a default custom properties part if one is not present.
+        """
+        try:
+            return cast(CustomPropertiesPart, self.part_related_by(RT.CUSTOM_PROPERTIES))
+        except KeyError:
+            custom_properties_part = CustomPropertiesPart.default(self)
+            self.relate_to(custom_properties_part, RT.CUSTOM_PROPERTIES)
+            return custom_properties_part
+
+
+class Unmarshaller:
+    """Hosts static methods for unmarshalling a package from a |PackageReader|."""
+
+    @staticmethod
+    def unmarshal(pkg_reader, package, part_factory):
+        """Construct graph of parts and realized relationships based on the contents of
+        `pkg_reader`, delegating construction of each part to `part_factory`.
+
+        Package relationships are added to `pkg`.
+        """
+        parts = Unmarshaller._unmarshal_parts(pkg_reader, package, part_factory)
+        Unmarshaller._unmarshal_relationships(pkg_reader, package, parts)
+        for part in parts.values():
+            part.after_unmarshal()
+        package.after_unmarshal()
+
+    @staticmethod
+    def _unmarshal_parts(pkg_reader, package, part_factory):
+        """Return a dictionary of |Part| instances unmarshalled from `pkg_reader`, keyed
+        by partname.
+
+        Side-effect is that each part in `pkg_reader` is constructed using
+        `part_factory`.
+        """
+        parts = {}
+        for partname, content_type, reltype, blob in pkg_reader.iter_sparts():
+            parts[partname] = part_factory(partname, content_type, reltype, blob, package)
+        return parts
+
+    @staticmethod
+    def _unmarshal_relationships(pkg_reader, package, parts):
+        """Add a relationship to the source object corresponding to each of the
+        relationships in `pkg_reader` with its target_part set to the actual target part
+        in `parts`."""
+        for source_uri, srel in pkg_reader.iter_srels():
+            source = package if source_uri == "/" else parts[source_uri]
+            target = srel.target_ref if srel.is_external else parts[srel.target_partname]
+            source.load_rel(srel.reltype, target, srel.rId, srel.is_external)

docx/opc/packuri.py

@@ -0,0 +1,109 @@
+"""Provides the PackURI value type.
+
+Also some useful known pack URI strings such as PACKAGE_URI.
+"""
+
+from __future__ import annotations
+
+import posixpath
+import re
+
+
+class PackURI(str):
+    """Provides access to pack URI components such as the baseURI and the filename slice.
+
+    Behaves as |str| otherwise.
+    """
+
+    _filename_re = re.compile("([a-zA-Z]+)([1-9][0-9]*)?")
+
+    def __new__(cls, pack_uri_str: str):
+        if pack_uri_str[0] != "/":
+            tmpl = "PackURI must begin with slash, got '%s'"
+            raise ValueError(tmpl % pack_uri_str)
+        return str.__new__(cls, pack_uri_str)
+
+    @staticmethod
+    def from_rel_ref(baseURI: str, relative_ref: str) -> PackURI:
+        """The absolute PackURI formed by translating `relative_ref` onto `baseURI`."""
+        joined_uri = posixpath.join(baseURI, relative_ref)
+        abs_uri = posixpath.abspath(joined_uri)
+        return PackURI(abs_uri)
+
+    @property
+    def baseURI(self) -> str:
+        """The base URI of this pack URI, the directory portion, roughly speaking.
+
+        E.g. ``'/ppt/slides'`` for ``'/ppt/slides/slide1.xml'``. For the package pseudo-
+        partname '/', baseURI is '/'.
+        """
+        return posixpath.split(self)[0]
+
+    @property
+    def ext(self) -> str:
+        """The extension portion of this pack URI, e.g. ``'xml'`` for ``'/word/document.xml'``.
+
+        Note the period is not included.
+        """
+        # raw_ext is either empty string or starts with period, e.g. '.xml'
+        raw_ext = posixpath.splitext(self)[1]
+        return raw_ext[1:] if raw_ext.startswith(".") else raw_ext
+
+    @property
+    def filename(self):
+        """The "filename" portion of this pack URI, e.g. ``'slide1.xml'`` for
+        ``'/ppt/slides/slide1.xml'``.
+
+        For the package pseudo-partname '/', filename is ''.
+        """
+        return posixpath.split(self)[1]
+
+    @property
+    def idx(self):
+        """Return partname index as integer for tuple partname or None for singleton
+        partname, e.g. ``21`` for ``'/ppt/slides/slide21.xml'`` and |None| for
+        ``'/ppt/presentation.xml'``."""
+        filename = self.filename
+        if not filename:
+            return None
+        name_part = posixpath.splitext(filename)[0]  # filename w/ext removed
+        match = self._filename_re.match(name_part)
+        if match is None:
+            return None
+        if match.group(2):
+            return int(match.group(2))
+        return None
+
+    @property
+    def membername(self):
+        """The pack URI with the leading slash stripped off, the form used as the Zip
+        file membername for the package item.
+
+        Returns '' for the package pseudo-partname '/'.
+        """
+        return self[1:]
+
+    def relative_ref(self, baseURI: str):
+        """Return string containing relative reference to package item from `baseURI`.
+
+        E.g. PackURI('/ppt/slideLayouts/slideLayout1.xml') would return
+        '../slideLayouts/slideLayout1.xml' for baseURI '/ppt/slides'.
+        """
+        # workaround for posixpath bug in 2.6, doesn't generate correct
+        # relative path when `start` (second) parameter is root ('/')
+        return self[1:] if baseURI == "/" else posixpath.relpath(self, baseURI)
+
+    @property
+    def rels_uri(self):
+        """The pack URI of the .rels part corresponding to the current pack URI.
+
+        Only produces sensible output if the pack URI is a partname or the package
+        pseudo-partname '/'.
+        """
+        rels_filename = "%s.rels" % self.filename
+        rels_uri_str = posixpath.join(self.baseURI, "_rels", rels_filename)
+        return PackURI(rels_uri_str)
+
+
+PACKAGE_URI = PackURI("/")
+CONTENT_TYPES_URI = PackURI("/[Content_Types].xml")