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

docx/package.py

@@ -0,0 +1,119 @@
+"""WordprocessingML Package class and related objects."""
+
+from __future__ import annotations
+
+from typing import IO, TYPE_CHECKING, cast
+
+from docx.image.image import Image
+from docx.opc.constants import RELATIONSHIP_TYPE as RT
+from docx.opc.package import OpcPackage
+from docx.opc.packuri import PackURI
+from docx.parts.image import ImagePart
+from docx.shared import lazyproperty
+
+if TYPE_CHECKING:
+    from docx.opc.customprops import CustomProperties
+
+
+class Package(OpcPackage):
+    """Customizations specific to a WordprocessingML package."""
+
+    def after_unmarshal(self):
+        """Called by loading code after all parts and relationships have been loaded.
+
+        This method affords the opportunity for any required post-processing.
+        """
+        self._gather_image_parts()
+
+    @property
+    def custom_properties(self) -> CustomProperties:
+        """|CustomProperties| object providing read/write access to the custom
+        properties for this document."""
+        return super().custom_properties
+
+    def get_or_add_image_part(self, image_descriptor: str | IO[bytes]) -> ImagePart:
+        """Return |ImagePart| containing image specified by `image_descriptor`.
+
+        The image-part is newly created if a matching one is not already present in the
+        collection.
+        """
+        return self.image_parts.get_or_add_image_part(image_descriptor)
+
+    @lazyproperty
+    def image_parts(self) -> ImageParts:
+        """|ImageParts| collection object for this package."""
+        return ImageParts()
+
+    def _gather_image_parts(self):
+        """Load the image part collection with all the image parts in package."""
+        for rel in self.iter_rels():
+            if rel.is_external:
+                continue
+            if rel.reltype != RT.IMAGE:
+                continue
+            if rel.target_part in self.image_parts:
+                continue
+            self.image_parts.append(cast("ImagePart", rel.target_part))
+
+
+class ImageParts:
+    """Collection of |ImagePart| objects corresponding to images in the package."""
+
+    def __init__(self):
+        self._image_parts: list[ImagePart] = []
+
+    def __contains__(self, item: object):
+        return self._image_parts.__contains__(item)
+
+    def __iter__(self):
+        return self._image_parts.__iter__()
+
+    def __len__(self):
+        return self._image_parts.__len__()
+
+    def append(self, item: ImagePart):
+        self._image_parts.append(item)
+
+    def get_or_add_image_part(self, image_descriptor: str | IO[bytes]) -> ImagePart:
+        """Return |ImagePart| object containing image identified by `image_descriptor`.
+
+        The image-part is newly created if a matching one is not present in the
+        collection.
+        """
+        image = Image.from_file(image_descriptor)
+        matching_image_part = self._get_by_sha1(image.sha1)
+        if matching_image_part is not None:
+            return matching_image_part
+        return self._add_image_part(image)
+
+    def _add_image_part(self, image: Image):
+        """Return |ImagePart| instance newly created from `image` and appended to the collection."""
+        partname = self._next_image_partname(image.ext)
+        image_part = ImagePart.from_image(image, partname)
+        self.append(image_part)
+        return image_part
+
+    def _get_by_sha1(self, sha1: str) -> ImagePart | None:
+        """Return the image part in this collection having a SHA1 hash matching `sha1`,
+        or |None| if not found."""
+        for image_part in self._image_parts:
+            if image_part.sha1 == sha1:
+                return image_part
+        return None
+
+    def _next_image_partname(self, ext: str) -> PackURI:
+        """The next available image partname, starting from ``/word/media/image1.{ext}``
+        where unused numbers are reused.
+
+        The partname is unique by number, without regard to the extension. `ext` does
+        not include the leading period.
+        """
+
+        def image_partname(n: int) -> PackURI:
+            return PackURI("/word/media/image%d.%s" % (n, ext))
+
+        used_numbers = [image_part.partname.idx for image_part in self]
+        for n in range(1, len(self) + 1):
+            if n not in used_numbers:
+                return image_partname(n)
+        return image_partname(len(self) + 1)

docx/parts/comments.py

@@ -0,0 +1,51 @@
+"""Contains comments added to the document."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, cast
+
+from typing_extensions import Self
+
+from docx.comments import Comments
+from docx.opc.constants import CONTENT_TYPE as CT
+from docx.opc.packuri import PackURI
+from docx.oxml.comments import CT_Comments
+from docx.oxml.parser import parse_xml
+from docx.package import Package
+from docx.parts.story import StoryPart
+
+if TYPE_CHECKING:
+    from docx.oxml.comments import CT_Comments
+    from docx.package import Package
+
+
+class CommentsPart(StoryPart):
+    """Container part for comments added to the document."""
+
+    def __init__(
+        self, partname: PackURI, content_type: str, element: CT_Comments, package: Package
+    ):
+        super().__init__(partname, content_type, element, package)
+        self._comments = element
+
+    @property
+    def comments(self) -> Comments:
+        """A |Comments| proxy object for the `w:comments` root element of this part."""
+        return Comments(self._comments, self)
+
+    @classmethod
+    def default(cls, package: Package) -> Self:
+        """A newly created comments part, containing a default empty `w:comments` element."""
+        partname = PackURI("/word/comments.xml")
+        content_type = CT.WML_COMMENTS
+        element = cast("CT_Comments", parse_xml(cls._default_comments_xml()))
+        return cls(partname, content_type, element, package)
+
+    @classmethod
+    def _default_comments_xml(cls) -> bytes:
+        """A byte-string containing XML for a default comments part."""
+        path = os.path.join(os.path.split(__file__)[0], "..", "templates", "default-comments.xml")
+        with open(path, "rb") as f:
+            xml_bytes = f.read()
+        return xml_bytes

docx/parts/customxml.py

@@ -0,0 +1,67 @@
+"""
+|CustomXmlPart| and closely related objects
+"""
+from lxml import etree
+from lxml.etree import fromstring
+
+from docx.opc.package import OpcPackage
+from docx.opc.packuri import PackURI
+from docx.opc.part import XmlPart
+
+
+class CustomXmlPart(XmlPart):
+    """
+    Proxy for the /customXml/*.xml part containing custom items definitions
+    """
+
+    @classmethod
+    def default(
+        cls,
+        file_name: str,
+        content_type: str,
+        xml: str,
+        package: OpcPackage,
+    ) -> "CustomXmlPart":
+        """
+        Create a default xml file in /customXml/*file_name*.xml
+        with default content *xml* and type *content_type*
+        """
+        return cls(
+            PackURI(f"/customXml/{file_name}.xml"),
+            content_type,
+            fromstring(xml),
+            package,
+        )
+
+    @property
+    def tag(self) -> str:
+        """
+        Return the root element tag name.
+        """
+        return self.element.tag
+
+    @property
+    def attrib(self) -> dict:
+        """
+        Return the root element attributes.
+        """
+        return self.element.attrib
+
+    @property
+    def items(self) -> list[etree._Element]:
+        """
+        Return all children belong to root element.
+        """
+        return self.element.getchildren()
+
+    def add_item(self, tag: str, text: str = "", **attrib):
+        """
+        Add a child element to root.
+        """
+        etree.SubElement(self.element, tag, **attrib).text = text
+
+    def delete_item(self, item_element: etree._Element):
+        """
+        Delete a item element. other nodes index may change after deletion.
+        """
+        self.element.remove(item_element)

docx/parts/document.py

@@ -0,0 +1,193 @@
+"""|DocumentPart| and closely related objects."""
+
+from __future__ import annotations
+
+from typing import IO, TYPE_CHECKING, cast
+
+from docx.document import Document
+from docx.opc.constants import CONTENT_TYPE as CT
+from docx.opc.constants import RELATIONSHIP_TYPE as RT
+from docx.parts.comments import CommentsPart
+from docx.parts.customxml import CustomXmlPart
+from docx.parts.hdrftr import FooterPart, HeaderPart
+from docx.parts.numbering import NumberingPart
+from docx.parts.settings import SettingsPart
+from docx.parts.story import StoryPart
+from docx.parts.styles import StylesPart
+from docx.shape import InlineShapes
+from docx.shared import lazyproperty
+
+if TYPE_CHECKING:
+    from docx.comments import Comments
+    from docx.enum.style import WD_STYLE_TYPE
+    from docx.opc.coreprops import CoreProperties
+    from docx.opc.customprops import CustomProperties
+    from docx.settings import Settings
+    from docx.styles.style import BaseStyle
+
+
+class DocumentPart(StoryPart):
+    """Main document part of a WordprocessingML (WML) package, aka a .docx file.
+
+    Acts as broker to other parts such as image, core properties, and style parts. It
+    also acts as a convenient delegate when a mid-document object needs a service
+    involving a remote ancestor. The `Parented.part` property inherited by many content
+    objects provides access to this part object for that purpose.
+    """
+
+    def add_custom_xml_part(
+        self, xml: str, file_name: str = "item1", content_type: str = CT.XML
+    ) -> CustomXmlPart:
+        """Add a file in /customXml/*file_name*.xml with default content *xml*."""
+        part = CustomXmlPart.default(file_name, content_type, xml, self.package)
+        return self.rels.get_or_add(RT.CUSTOM_XML, part).target_part
+
+    def add_footer_part(self):
+        """Return (footer_part, rId) pair for newly-created footer part."""
+        footer_part = FooterPart.new(self.package)
+        rId = self.relate_to(footer_part, RT.FOOTER)
+        return footer_part, rId
+
+    def add_header_part(self):
+        """Return (header_part, rId) pair for newly-created header part."""
+        header_part = HeaderPart.new(self.package)
+        rId = self.relate_to(header_part, RT.HEADER)
+        return header_part, rId
+
+    @property
+    def comments(self) -> Comments:
+        """|Comments| object providing access to the comments added to this document."""
+        return self._comments_part.comments
+
+    @property
+    def core_properties(self) -> CoreProperties:
+        """A |CoreProperties| object providing read/write access to the core properties
+        of this document."""
+        return self.package.core_properties
+
+    @property
+    def custom_properties(self) -> CustomProperties:
+        """A |CustomProperties| object providing read/write access to the custom
+        properties of this document."""
+        return self.package.custom_properties
+
+    @property
+    def custom_xml_parts(self) -> list[CustomXmlPart]:
+        """A list of |CustomXmlPart| objects for this document."""
+        try:
+            return self.rels.parts_with_reltype(RT.CUSTOM_XML)
+        except KeyError:
+            return []
+
+    @property
+    def document(self):
+        """A |Document| object providing access to the content of this document."""
+        return Document(self._element, self)
+
+    def drop_header_part(self, rId: str) -> None:
+        """Remove related header part identified by `rId`."""
+        self.drop_rel(rId)
+
+    def footer_part(self, rId: str):
+        """Return |FooterPart| related by `rId`."""
+        return self.related_parts[rId]
+
+    def get_style(self, style_id: str | None, style_type: WD_STYLE_TYPE) -> BaseStyle:
+        """Return the style in this document matching `style_id`.
+
+        Returns the default style for `style_type` if `style_id` is |None| or does not
+        match a defined style of `style_type`.
+        """
+        return self.styles.get_by_id(style_id, style_type)
+
+    def get_style_id(self, style_or_name, style_type):
+        """Return the style_id (|str|) of the style of `style_type` matching
+        `style_or_name`.
+
+        Returns |None| if the style resolves to the default style for `style_type` or if
+        `style_or_name` is itself |None|. Raises if `style_or_name` is a style of the
+        wrong type or names a style not present in the document.
+        """
+        return self.styles.get_style_id(style_or_name, style_type)
+
+    def header_part(self, rId: str):
+        """Return |HeaderPart| related by `rId`."""
+        return self.related_parts[rId]
+
+    @lazyproperty
+    def inline_shapes(self):
+        """The |InlineShapes| instance containing the inline shapes in the document."""
+        return InlineShapes(self._element.body, self)
+
+    @lazyproperty
+    def numbering_part(self) -> NumberingPart:
+        """A |NumberingPart| object providing access to the numbering definitions for this document.
+
+        Creates an empty numbering part if one is not present.
+        """
+        try:
+            return cast(NumberingPart, self.part_related_by(RT.NUMBERING))
+        except KeyError:
+            numbering_part = NumberingPart.default(self.package)
+            self.relate_to(numbering_part, RT.NUMBERING)
+            return numbering_part
+
+    def save(self, path_or_stream: str | IO[bytes]):
+        """Save this document to `path_or_stream`, which can be either a path to a
+        filesystem location (a string) or a file-like object."""
+        self.package.save(path_or_stream)
+
+    @property
+    def settings(self) -> Settings:
+        """A |Settings| object providing access to the settings in the settings part of
+        this document."""
+        return self._settings_part.settings
+
+    @property
+    def styles(self):
+        """A |Styles| object providing access to the styles in the styles part of this
+        document."""
+        return self._styles_part.styles
+
+    @property
+    def _comments_part(self) -> CommentsPart:
+        """A |CommentsPart| object providing access to the comments added to this document.
+
+        Creates a default comments part if one is not present.
+        """
+        try:
+            return cast(CommentsPart, self.part_related_by(RT.COMMENTS))
+        except KeyError:
+            assert self.package is not None
+            comments_part = CommentsPart.default(self.package)
+            self.relate_to(comments_part, RT.COMMENTS)
+            return comments_part
+
+    @property
+    def _settings_part(self) -> SettingsPart:
+        """A |SettingsPart| object providing access to the document-level settings for
+        this document.
+
+        Creates a default settings part if one is not present.
+        """
+        try:
+            return cast(SettingsPart, self.part_related_by(RT.SETTINGS))
+        except KeyError:
+            settings_part = SettingsPart.default(self.package)
+            self.relate_to(settings_part, RT.SETTINGS)
+            return settings_part
+
+    @property
+    def _styles_part(self) -> StylesPart:
+        """Instance of |StylesPart| for this document.
+
+        Creates an empty styles part if one is not present.
+        """
+        try:
+            return cast(StylesPart, self.part_related_by(RT.STYLES))
+        except KeyError:
+            package = self.package
+            assert package is not None
+            styles_part = StylesPart.default(package)
+            self.relate_to(styles_part, RT.STYLES)
+            return styles_part

docx/parts/hdrftr.py

@@ -0,0 +1,53 @@
+"""Header and footer part objects."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from docx.opc.constants import CONTENT_TYPE as CT
+from docx.oxml.parser import parse_xml
+from docx.parts.story import StoryPart
+
+if TYPE_CHECKING:
+    from docx.package import Package
+
+
+class FooterPart(StoryPart):
+    """Definition of a section footer."""
+
+    @classmethod
+    def new(cls, package: Package):
+        """Return newly created footer part."""
+        partname = package.next_partname("/word/footer%d.xml")
+        content_type = CT.WML_FOOTER
+        element = parse_xml(cls._default_footer_xml())
+        return cls(partname, content_type, element, package)
+
+    @classmethod
+    def _default_footer_xml(cls):
+        """Return bytes containing XML for a default footer part."""
+        path = os.path.join(os.path.split(__file__)[0], "..", "templates", "default-footer.xml")
+        with open(path, "rb") as f:
+            xml_bytes = f.read()
+        return xml_bytes
+
+
+class HeaderPart(StoryPart):
+    """Definition of a section header."""
+
+    @classmethod
+    def new(cls, package: Package):
+        """Return newly created header part."""
+        partname = package.next_partname("/word/header%d.xml")
+        content_type = CT.WML_HEADER
+        element = parse_xml(cls._default_header_xml())
+        return cls(partname, content_type, element, package)
+
+    @classmethod
+    def _default_header_xml(cls):
+        """Return bytes containing XML for a default header part."""
+        path = os.path.join(os.path.split(__file__)[0], "..", "templates", "default-header.xml")
+        with open(path, "rb") as f:
+            xml_bytes = f.read()
+        return xml_bytes

docx/parts/image.py

@@ -0,0 +1,80 @@
+"""The proxy class for an image part, and related objects."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import TYPE_CHECKING
+
+from docx.image.image import Image
+from docx.opc.part import Part
+from docx.shared import Emu, Inches
+
+if TYPE_CHECKING:
+    from docx.opc.package import OpcPackage
+    from docx.opc.packuri import PackURI
+
+
+class ImagePart(Part):
+    """An image part.
+
+    Corresponds to the target part of a relationship with type RELATIONSHIP_TYPE.IMAGE.
+    """
+
+    def __init__(
+        self, partname: PackURI, content_type: str, blob: bytes, image: Image | None = None
+    ):
+        super(ImagePart, self).__init__(partname, content_type, blob)
+        self._image = image
+
+    @property
+    def default_cx(self):
+        """Native width of this image, calculated from its width in pixels and
+        horizontal dots per inch (dpi)."""
+        px_width = self.image.px_width
+        horz_dpi = self.image.horz_dpi
+        width_in_inches = px_width / horz_dpi
+        return Inches(width_in_inches)
+
+    @property
+    def default_cy(self):
+        """Native height of this image, calculated from its height in pixels and
+        vertical dots per inch (dpi)."""
+        px_height = self.image.px_height
+        horz_dpi = self.image.horz_dpi
+        height_in_emu = int(round(914400 * px_height / horz_dpi))
+        return Emu(height_in_emu)
+
+    @property
+    def filename(self):
+        """Filename from which this image part was originally created.
+
+        A generic name, e.g. 'image.png', is substituted if no name is available, for
+        example when the image was loaded from an unnamed stream. In that case a default
+        extension is applied based on the detected MIME type of the image.
+        """
+        if self._image is not None:
+            return self._image.filename
+        return "image.%s" % self.partname.ext
+
+    @classmethod
+    def from_image(cls, image: Image, partname: PackURI):
+        """Return an |ImagePart| instance newly created from `image` and assigned
+        `partname`."""
+        return ImagePart(partname, image.content_type, image.blob, image)
+
+    @property
+    def image(self) -> Image:
+        if self._image is None:
+            self._image = Image.from_blob(self.blob)
+        return self._image
+
+    @classmethod
+    def load(cls, partname: PackURI, content_type: str, blob: bytes, package: OpcPackage):
+        """Called by ``docx.opc.package.PartFactory`` to load an image part from a
+        package being opened by ``Document(...)`` call."""
+        return cls(partname, content_type, blob)
+
+    @property
+    def sha1(self):
+        """SHA1 hash digest of the blob of this image part."""
+        return hashlib.sha1(self.blob).hexdigest()

docx/parts/numbering.py

@@ -0,0 +1,51 @@
+"""|NumberingPart| and closely related objects."""
+
+import os
+
+from ..opc.constants import CONTENT_TYPE as CT
+from ..opc.packuri import PackURI
+from ..opc.part import XmlPart
+from ..oxml import parse_xml
+from ..shared import lazyproperty
+
+
+class NumberingPart(XmlPart):
+    """Proxy for the numbering.xml part containing numbering definitions for a document
+    or glossary."""
+
+    @classmethod
+    def default(cls, package):
+        """Return newly created empty numbering part, containing only the root ``<w:numbering>``
+        element."""
+        partname = PackURI("/word/numbering.xml")
+        content_type = CT.WML_NUMBERING
+        element = parse_xml(cls._default_numbering_xml())
+        return cls(partname, content_type, element, package)
+
+    @classmethod
+    def _default_numbering_xml(cls):
+        """Return a bytestream containing XML for a default numbering part."""
+        path = os.path.join(
+            os.path.split(__file__)[0], "..", "templates", "default-numbering.xml"
+        )
+        with open(path, "rb") as f:
+            xml_bytes = f.read()
+        return xml_bytes
+
+    @lazyproperty
+    def numbering_definitions(self):
+        """The |_NumberingDefinitions| instance containing the numbering definitions
+        (<w:num> element proxies) for this numbering part."""
+        return _NumberingDefinitions(self._element)
+
+
+class _NumberingDefinitions:
+    """Collection of |_NumberingDefinition| instances corresponding to the ``<w:num>``
+    elements in a numbering part."""
+
+    def __init__(self, numbering_elm):
+        super(_NumberingDefinitions, self).__init__()
+        self._numbering = numbering_elm
+
+    def __len__(self):
+        return len(self._numbering.num_lst)

docx/parts/settings.py

@@ -0,0 +1,50 @@
+"""|SettingsPart| and closely related objects."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, cast
+
+from docx.opc.constants import CONTENT_TYPE as CT
+from docx.opc.packuri import PackURI
+from docx.opc.part import XmlPart
+from docx.oxml.parser import parse_xml
+from docx.settings import Settings
+
+if TYPE_CHECKING:
+    from docx.oxml.settings import CT_Settings
+    from docx.package import Package
+
+
+class SettingsPart(XmlPart):
+    """Document-level settings part of a WordprocessingML (WML) package."""
+
+    def __init__(
+        self, partname: PackURI, content_type: str, element: CT_Settings, package: Package
+    ):
+        super().__init__(partname, content_type, element, package)
+        self._settings = element
+
+    @classmethod
+    def default(cls, package: Package):
+        """Return a newly created settings part, containing a default `w:settings` element tree."""
+        partname = PackURI("/word/settings.xml")
+        content_type = CT.WML_SETTINGS
+        element = cast("CT_Settings", parse_xml(cls._default_settings_xml()))
+        return cls(partname, content_type, element, package)
+
+    @property
+    def settings(self) -> Settings:
+        """A |Settings| proxy object for the `w:settings` element in this part.
+
+        Contains the document-level settings for this document.
+        """
+        return Settings(self._settings)
+
+    @classmethod
+    def _default_settings_xml(cls):
+        """Return a bytestream containing XML for a default settings part."""
+        path = os.path.join(os.path.split(__file__)[0], "..", "templates", "default-settings.xml")
+        with open(path, "rb") as f:
+            xml_bytes = f.read()
+        return xml_bytes