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

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")

docx/opc/part.py

@@ -0,0 +1,247 @@
+# 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
+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]
+
+    @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 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
+
+    @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 count of references in this part's XML to the relationship
+        identified by `rId`."""
+        rIds = cast("list[str]", self._element.xpath("//@r:id"))
+        return len([_rId for _rId in rIds if _rId == rId])

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/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)