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

docx/opc/part.py

@@ -0,0 +1,267 @@
+# pyright: reportImportCycles=false
+
+"""Open Packaging Convention (OPC) objects related to package parts."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable, Type, cast
+
+from docx.opc.oxml import serialize_part_xml
+from docx.opc.packuri import PackURI
+from docx.opc.rel import Relationships, _Relationship
+from docx.opc.shared import cls_method_fn
+from docx.oxml.parser import parse_xml
+from docx.shared import lazyproperty
+
+if TYPE_CHECKING:
+    from docx.oxml.xmlchemy import BaseOxmlElement
+    from docx.package import Package
+
+
+class Part:
+    """Base class for package parts.
+
+    Provides common properties and methods, but intended to be subclassed in client code
+    to implement specific part behaviors.
+    """
+
+    def __init__(
+        self,
+        partname: PackURI,
+        content_type: str,
+        blob: bytes | None = None,
+        package: Package | None = None,
+    ):
+        super(Part, self).__init__()
+        self._partname = partname
+        self._content_type = content_type
+        self._blob = blob
+        self._package = package
+
+    def after_unmarshal(self):
+        """Entry point for post-unmarshaling processing, for example to parse the part
+        XML.
+
+        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
+
+    def before_marshal(self):
+        """Entry point for pre-serialization processing, for example to finalize part
+        naming if necessary.
+
+        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 blob(self) -> bytes:
+        """Contents of this package part as a sequence of bytes.
+
+        May be text or binary. Intended to be overridden by subclasses. Default behavior
+        is to return load blob.
+        """
+        return self._blob or b""
+
+    @property
+    def content_type(self):
+        """Content type of this part."""
+        return self._content_type
+
+    def drop_rel(self, rId: str):
+        """Remove the relationship identified by `rId` if its reference count is less
+        than 2.
+
+        Relationships with a reference count of 0 are implicit relationships.
+        """
+        if self._rel_ref_count(rId) < 2:
+            del self.rels[rId]
+
+    def drop_rels(self, cmp: Callable[[_Relationship], bool]) -> list[str]:
+        rids = [rid for rid, rel in self.rels.items() if cmp(rel)]
+        for rid in rids:
+            del self.rels[rid]
+        return rids
+
+    @classmethod
+    def load(cls, partname: PackURI, content_type: str, blob: bytes, package: Package):
+        return cls(partname, content_type, blob, package)
+
+    def load_rel(self, reltype: str, target: Part | str, rId: str, is_external: bool = False):
+        """Return newly added |_Relationship| instance of `reltype`.
+
+        The new relationship relates the `target` part to this part 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 a part when manipulating a part.
+        """
+        return self.rels.add_relationship(reltype, target, rId, is_external)
+
+    @property
+    def package(self):
+        """|OpcPackage| instance this part belongs to."""
+        return self._package
+
+    @property
+    def partname(self):
+        """|PackURI| instance holding partname of this part, e.g.
+        '/ppt/slides/slide1.xml'."""
+        return self._partname
+
+    @partname.setter
+    def partname(self, partname: str):
+        if not isinstance(partname, PackURI):
+            tmpl = "partname must be instance of PackURI, got '%s'"
+            raise TypeError(tmpl % type(partname).__name__)
+        self._partname = partname
+
+    def __eq__(self, other: object) -> bool:
+        return type(self) == type(other) and self.partname == other.partname
+
+    def part_related_by(self, reltype: str) -> Part:
+        """Return part to which this part has a relationship of `reltype`.
+
+        Raises |KeyError| if no such relationship is found and |ValueError| if more than
+        one such relationship is found. Provides ability to resolve implicitly related
+        part, such as Slide -> SlideLayout.
+        """
+        return self.rels.part_with_reltype(reltype)
+
+    def relate_to(self, target: Part | str, reltype: str, is_external: bool = False) -> str:
+        """Return rId key of relationship of `reltype` to `target`.
+
+        The returned `rId` is from an existing relationship if there is one, otherwise a
+        new relationship is created.
+        """
+        if is_external:
+            return self.rels.get_or_add_ext_rel(reltype, cast(str, target))
+        else:
+            rel = self.rels.get_or_add(reltype, cast(Part, target))
+            return rel.rId
+
+    @property
+    def related_parts(self):
+        """Dictionary mapping related parts by rId, so child objects can resolve
+        explicit relationships present in the part XML, e.g. sldIdLst to a specific
+        |Slide| instance."""
+        return self.rels.related_parts
+
+    @lazyproperty
+    def rels(self):
+        """|Relationships| instance holding the relationships for this part."""
+        # -- prevent breakage in `python-docx-template` by retaining legacy `._rels` attribute --
+        self._rels = Relationships(self._partname.baseURI)
+        return self._rels
+
+    def target_ref(self, rId: str) -> str:
+        """Return URL contained in target ref of relationship identified by `rId`."""
+        rel = self.rels[rId]
+        return rel.target_ref
+
+    def _rel_ref_count(self, rId: str) -> int:
+        """Return the count of references in this part to the relationship identified by `rId`.
+
+        Only an XML part can contain references, so this is 0 for `Part`.
+        """
+        return 0
+
+
+class PartFactory:
+    """Provides a way for client code to specify a subclass of |Part| to be constructed
+    by |Unmarshaller| based on its content type and/or a custom callable.
+
+    Setting ``PartFactory.part_class_selector`` to a callable object will cause that
+    object to be called with the parameters ``content_type, reltype``, once for each
+    part in the package. If the callable returns an object, it is used as the class for
+    that part. If it returns |None|, part class selection falls back to the content type
+    map defined in ``PartFactory.part_type_for``. If no class is returned from either of
+    these, the class contained in ``PartFactory.default_part_type`` is used to construct
+    the part, which is by default ``opc.package.Part``.
+    """
+
+    part_class_selector: Callable[[str, str], Type[Part] | None] | None
+    part_type_for: dict[str, Type[Part]] = {}
+    default_part_type = Part
+
+    def __new__(
+        cls,
+        partname: PackURI,
+        content_type: str,
+        reltype: str,
+        blob: bytes,
+        package: Package,
+    ):
+        PartClass: Type[Part] | None = None
+        if cls.part_class_selector is not None:
+            part_class_selector = cls_method_fn(cls, "part_class_selector")
+            PartClass = part_class_selector(content_type, reltype)
+        if PartClass is None:
+            PartClass = cls._part_cls_for(content_type)
+        return PartClass.load(partname, content_type, blob, package)
+
+    @classmethod
+    def _part_cls_for(cls, content_type: str):
+        """Return the custom part class registered for `content_type`, or the default
+        part class if no custom class is registered for `content_type`."""
+        if content_type in cls.part_type_for:
+            return cls.part_type_for[content_type]
+        return cls.default_part_type
+
+
+class XmlPart(Part):
+    """Base class for package parts containing an XML payload, which is most of them.
+
+    Provides additional methods to the |Part| base class that take care of parsing and
+    reserializing the XML payload and managing relationships to other parts.
+    """
+
+    def __init__(
+        self, partname: PackURI, content_type: str, element: BaseOxmlElement, package: Package
+    ):
+        super(XmlPart, self).__init__(partname, content_type, package=package)
+        self._element = element
+
+    @property
+    def blob(self):
+        return serialize_part_xml(self._element)
+
+    @property
+    def element(self):
+        """The root XML element of this XML part."""
+        return self._element
+
+    @element.setter
+    def element(self, e: BaseOxmlElement):
+        self._element = e
+
+    @classmethod
+    def load(cls, partname: PackURI, content_type: str, blob: bytes, package: Package):
+        element = parse_xml(blob)
+        return cls(partname, content_type, element, package)
+
+    @property
+    def part(self):
+        """Part of the parent protocol, "children" of the document will not know the
+        part that contains them so must ask their parent object.
+
+        That chain of delegation ends here for child objects.
+        """
+        return self
+
+    def _rel_ref_count(self, rId: str) -> int:
+        """Return the number of XML attributes referencing `rId` in this part."""
+        element = getattr(self, "_element", None)
+        if element is None:
+            return 0
+
+        count = 0
+        for child in element.iter():
+            for value in child.attrib.values():
+                if value == rId:
+                    count += 1
+        return count

docx/opc/parts/coreprops.py

@@ -0,0 +1,48 @@
+"""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 docx.opc.constants import CONTENT_TYPE as CT
+from docx.opc.coreprops import CoreProperties
+from docx.opc.packuri import PackURI
+from docx.opc.part import XmlPart
+from docx.oxml.coreprops import CT_CoreProperties
+
+if TYPE_CHECKING:
+    from docx.opc.package import OpcPackage
+
+
+class CorePropertiesPart(XmlPart):
+    """Corresponds to part named ``/docProps/core.xml``.
+
+    The "core" is short for "Dublin Core" and contains document metadata relatively common across
+    documents of all types, not just DOCX.
+    """
+
+    @classmethod
+    def default(cls, package: OpcPackage):
+        """Return a new |CorePropertiesPart| object initialized with default values for
+        its base properties."""
+        core_properties_part = cls._new(package)
+        core_properties = core_properties_part.core_properties
+        core_properties.title = "Word Document"
+        core_properties.last_modified_by = "python-docx"
+        core_properties.revision = 1
+        core_properties.modified = dt.datetime.now(dt.timezone.utc)
+        return core_properties_part
+
+    @property
+    def core_properties(self):
+        """A |CoreProperties| object providing read/write access to the core properties
+        contained in this core properties part."""
+        return CoreProperties(self.element)
+
+    @classmethod
+    def _new(cls, package: OpcPackage) -> CorePropertiesPart:
+        partname = PackURI("/docProps/core.xml")
+        content_type = CT.OPC_CORE_PROPERTIES
+        coreProperties = CT_CoreProperties.new()
+        return CorePropertiesPart(partname, content_type, coreProperties, package)

docx/opc/parts/customprops.py

@@ -0,0 +1,61 @@
+"""
+Custom properties part, corresponds to ``/docProps/custom.xml`` part in package.
+"""
+from lxml import etree
+
+from ...oxml.customprops import CT_CustomProperties
+from ..constants import CONTENT_TYPE as CT
+from ..customprops import CustomProperties
+from ..packuri import PackURI
+from ..part import XmlPart
+
+# configure XML parser
+parser_lookup = etree.ElementDefaultClassLookup(element=CT_CustomProperties)
+ct_parser = etree.XMLParser(remove_blank_text=True)
+ct_parser.set_element_class_lookup(parser_lookup)
+
+
+def ct_parse_xml(xml):
+    """
+    Return root lxml element obtained by parsing XML character string in
+    *xml*, which can be either a Python 2.x string or unicode. The custom
+    parser is used, so custom element classes are produced for elements in
+    *xml* that have them.
+    """
+    return etree.fromstring(xml, ct_parser)
+
+
+class CustomPropertiesPart(XmlPart):
+    """
+    Corresponds to part named ``/docProps/custom.xml``, containing the custom
+    document properties for this document package.
+    """
+
+    @classmethod
+    def default(cls, package):
+        """
+        Return a new |CustomPropertiesPart| object initialized with default
+        values for its base properties.
+        """
+        custom_properties_part = cls._new(package)
+        custom_properties = custom_properties_part.custom_properties
+        return custom_properties_part
+
+    @property
+    def custom_properties(self):
+        """
+        A |CustomProperties| object providing read/write access to the custom
+        properties contained in this custom properties part.
+        """
+        return CustomProperties(self.element)
+
+    @classmethod
+    def load(cls, partname, content_type, blob, package):
+        element = ct_parse_xml(blob)
+        return cls(partname, content_type, element, package)
+
+    @classmethod
+    def _new(cls, package):
+        partname = PackURI("/docProps/custom.xml")
+        content_type = CT.OPC_CUSTOM_PROPERTIES
+        return CustomPropertiesPart(partname, content_type, CT_CustomProperties.new(), package)

docx/opc/phys_pkg.py

@@ -0,0 +1,119 @@
+"""Provides a general interface to a `physical` OPC package, such as a zip file."""
+
+import os
+from zipfile import ZIP_DEFLATED, ZipFile, is_zipfile
+
+from docx.opc.exceptions import PackageNotFoundError
+from docx.opc.packuri import CONTENT_TYPES_URI
+
+
+class PhysPkgReader:
+    """Factory for physical package reader objects."""
+
+    def __new__(cls, pkg_file):
+        # if `pkg_file` is a string, treat it as a path
+        if isinstance(pkg_file, str):
+            if os.path.isdir(pkg_file):
+                reader_cls = _DirPkgReader
+            elif is_zipfile(pkg_file):
+                reader_cls = _ZipPkgReader
+            else:
+                raise PackageNotFoundError("Package not found at '%s'" % pkg_file)
+        else:  # assume it's a stream and pass it to Zip reader to sort out
+            reader_cls = _ZipPkgReader
+
+        return super(PhysPkgReader, cls).__new__(reader_cls)
+
+
+class PhysPkgWriter:
+    """Factory for physical package writer objects."""
+
+    def __new__(cls, pkg_file):
+        return super(PhysPkgWriter, cls).__new__(_ZipPkgWriter)
+
+
+class _DirPkgReader(PhysPkgReader):
+    """Implements |PhysPkgReader| interface for an OPC package extracted into a
+    directory."""
+
+    def __init__(self, path):
+        """`path` is the path to a directory containing an expanded package."""
+        super(_DirPkgReader, self).__init__()
+        self._path = os.path.abspath(path)
+
+    def blob_for(self, pack_uri):
+        """Return contents of file corresponding to `pack_uri` in package directory."""
+        path = os.path.join(self._path, pack_uri.membername)
+        with open(path, "rb") as f:
+            blob = f.read()
+        return blob
+
+    def close(self):
+        """Provides interface consistency with |ZipFileSystem|, but does nothing, a
+        directory file system doesn't need closing."""
+        pass
+
+    @property
+    def content_types_xml(self):
+        """Return the `[Content_Types].xml` blob from the package."""
+        return self.blob_for(CONTENT_TYPES_URI)
+
+    def rels_xml_for(self, source_uri):
+        """Return rels item XML for source with `source_uri`, or None if the item has no
+        rels item."""
+        try:
+            rels_xml = self.blob_for(source_uri.rels_uri)
+        except IOError:
+            rels_xml = None
+        return rels_xml
+
+
+class _ZipPkgReader(PhysPkgReader):
+    """Implements |PhysPkgReader| interface for a zip file OPC package."""
+
+    def __init__(self, pkg_file):
+        super(_ZipPkgReader, self).__init__()
+        self._zipf = ZipFile(pkg_file, "r")
+
+    def blob_for(self, pack_uri):
+        """Return blob corresponding to `pack_uri`.
+
+        Raises |ValueError| if no matching member is present in zip archive.
+        """
+        return self._zipf.read(pack_uri.membername)
+
+    def close(self):
+        """Close the zip archive, releasing any resources it is using."""
+        self._zipf.close()
+
+    @property
+    def content_types_xml(self):
+        """Return the `[Content_Types].xml` blob from the zip package."""
+        return self.blob_for(CONTENT_TYPES_URI)
+
+    def rels_xml_for(self, source_uri):
+        """Return rels item XML for source with `source_uri` or None if no rels item is
+        present."""
+        try:
+            rels_xml = self.blob_for(source_uri.rels_uri)
+        except KeyError:
+            rels_xml = None
+        return rels_xml
+
+
+class _ZipPkgWriter(PhysPkgWriter):
+    """Implements |PhysPkgWriter| interface for a zip file OPC package."""
+
+    def __init__(self, pkg_file):
+        super(_ZipPkgWriter, self).__init__()
+        self._zipf = ZipFile(pkg_file, "w", compression=ZIP_DEFLATED)
+
+    def close(self):
+        """Close the zip archive, flushing any pending physical writes and releasing any
+        resources it's using."""
+        self._zipf.close()
+
+    def write(self, pack_uri, blob):
+        """Write `blob` to this zip package with the membername corresponding to
+        `pack_uri`."""
+        self._zipf.writestr(pack_uri.membername, blob)