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

docx/opc/coreprops.py

@@ -0,0 +1,142 @@
+"""Provides CoreProperties, Dublin-Core attributes of the document.
+
+These are broadly-standardized attributes like author, last-modified, etc.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import TYPE_CHECKING
+
+from docx.oxml.coreprops import CT_CoreProperties
+
+if TYPE_CHECKING:
+    from docx.oxml.coreprops import CT_CoreProperties
+
+
+class CoreProperties:
+    """Corresponds to part named ``/docProps/core.xml``, containing the core document
+    properties for this document package."""
+
+    def __init__(self, element: CT_CoreProperties):
+        self._element = element
+
+    @property
+    def author(self):
+        return self._element.author_text
+
+    @author.setter
+    def author(self, value: str):
+        self._element.author_text = value
+
+    @property
+    def category(self):
+        return self._element.category_text
+
+    @category.setter
+    def category(self, value: str):
+        self._element.category_text = value
+
+    @property
+    def comments(self):
+        return self._element.comments_text
+
+    @comments.setter
+    def comments(self, value: str):
+        self._element.comments_text = value
+
+    @property
+    def content_status(self):
+        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):
+        return self._element.identifier_text
+
+    @identifier.setter
+    def identifier(self, value: str):
+        self._element.identifier_text = value
+
+    @property
+    def keywords(self):
+        return self._element.keywords_text
+
+    @keywords.setter
+    def keywords(self, value: str):
+        self._element.keywords_text = value
+
+    @property
+    def language(self):
+        return self._element.language_text
+
+    @language.setter
+    def language(self, value: str):
+        self._element.language_text = value
+
+    @property
+    def last_modified_by(self):
+        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):
+        return self._element.subject_text
+
+    @subject.setter
+    def subject(self, value: str):
+        self._element.subject_text = value
+
+    @property
+    def title(self):
+        return self._element.title_text
+
+    @title.setter
+    def title(self, value: str):
+        self._element.title_text = value
+
+    @property
+    def version(self):
+        return self._element.version_text
+
+    @version.setter
+    def version(self, value: str):
+        self._element.version_text = value

docx/opc/exceptions.py

@@ -0,0 +1,12 @@
+"""Exceptions specific to python-opc.
+
+The base exception class is OpcError.
+"""
+
+
+class OpcError(Exception):
+    """Base error class for python-opc."""
+
+
+class PackageNotFoundError(OpcError):
+    """Raised when a package cannot be found at the specified path."""

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,219 @@
+"""Objects that implement reading and writing OPC packages."""
+
+from __future__ import annotations
+
+from typing import IO, TYPE_CHECKING, 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.pkgreader import PackageReader
+from docx.opc.pkgwriter import PackageWriter
+from docx.opc.rel import Relationships
+from docx.shared import lazyproperty
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from docx.opc.coreprops import CoreProperties
+    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
+
+    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
+
+    @lazyproperty
+    def rels(self):
+        """Return a reference to the |Relationships| instance holding the collection of
+        relationships for this package."""
+        return Relationships(PACKAGE_URI.baseURI)
+
+    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
+
+
+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)