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

docx/parts/story.py

@@ -0,0 +1,113 @@
+"""|StoryPart| and related objects."""
+
+from __future__ import annotations
+
+from typing import IO, TYPE_CHECKING, Tuple, cast
+
+from docx.opc.constants import RELATIONSHIP_TYPE as RT
+from docx.opc.part import XmlPart
+from docx.oxml.shape import CT_Anchor, CT_Inline
+from docx.shared import Length, lazyproperty
+
+if TYPE_CHECKING:
+    from docx.enum.style import WD_STYLE_TYPE
+    from docx.image.image import Image
+    from docx.parts.document import DocumentPart
+    from docx.styles.style import BaseStyle
+
+
+class StoryPart(XmlPart):
+    """Base class for story parts.
+
+    A story part is one that can contain textual content, such as the document-part and
+    header or footer parts. These all share content behaviors like `.paragraphs`,
+    `.add_paragraph()`, `.add_table()` etc.
+    """
+
+    def get_or_add_image(self, image_descriptor: str | IO[bytes]) -> Tuple[str, Image]:
+        """Return (rId, image) pair for image identified by `image_descriptor`.
+
+        `rId` is the str key (often like "rId7") for the relationship between this story
+        part and the image part, reused if already present, newly created if not.
+        `image` is an |Image| instance providing access to the properties of the image,
+        such as dimensions and image type.
+        """
+        package = self._package
+        assert package is not None
+        image_part = package.get_or_add_image_part(image_descriptor)
+        rId = self.relate_to(image_part, RT.IMAGE)
+        return rId, image_part.image
+
+    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._document_part.get_style(style_id, style_type)
+
+    def get_style_id(
+        self, style_or_name: BaseStyle | str | None, style_type: WD_STYLE_TYPE
+    ) -> str | None:
+        """Return str style_id for `style_or_name` of `style_type`.
+
+        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._document_part.get_style_id(style_or_name, style_type)
+
+    def new_pic_inline(
+        self,
+        image_descriptor: str | IO[bytes],
+        width: int | Length | None = None,
+        height: int | Length | None = None,
+    ) -> CT_Inline:
+        """Return a newly-created `w:inline` element.
+
+        The element contains the image specified by `image_descriptor` and is scaled
+        based on the values of `width` and `height`.
+        """
+        rId, image = self.get_or_add_image(image_descriptor)
+        cx, cy = image.scaled_dimensions(width, height)
+        shape_id, filename = self.next_id, image.filename
+        return CT_Inline.new_pic_inline(shape_id, rId, filename, cx, cy)
+
+    def new_pic_anchor(
+        self,
+        image_descriptor: str | IO[bytes],
+        width: int | Length | None = None,
+        height: int | Length | None = None,
+        pos_x: int | Length = 0,
+        pos_y: int | Length = 0,
+    ):
+        """Return a newly-created `w:anchor` element.
+
+        The element contains the image specified by `image_descriptor` and is scaled
+        based on the values of `width` and `height`.
+        """
+        rId, image = self.get_or_add_image(image_descriptor)
+        cx, cy = image.scaled_dimensions(width, height)
+        shape_id, filename = self.next_id, image.filename
+        return CT_Anchor.new_pic_anchor(shape_id, rId, filename, cx, cy, pos_x, pos_y)
+
+    @property
+    def next_id(self) -> int:
+        """Next available positive integer id value in this story XML document.
+
+        The value is determined by incrementing the maximum existing id value. Gaps in
+        the existing id sequence are not filled. The id attribute value is unique in the
+        document, without regard to the element type it appears on.
+        """
+        id_str_lst = self._element.xpath("//@id")
+        used_ids = [int(id_str) for id_str in id_str_lst if id_str.isdigit()]
+        if not used_ids:
+            return 1
+        return max(used_ids) + 1
+
+    @lazyproperty
+    def _document_part(self) -> DocumentPart:
+        """|DocumentPart| object for this package."""
+        package = self.package
+        assert package is not None
+        return cast("DocumentPart", package.main_document_part)

docx/parts/styles.py

@@ -0,0 +1,42 @@
+"""Provides StylesPart and related objects."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+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.styles.styles import Styles
+
+if TYPE_CHECKING:
+    from docx.opc.package import OpcPackage
+
+
+class StylesPart(XmlPart):
+    """Proxy for the styles.xml part containing style definitions for a document or
+    glossary."""
+
+    @classmethod
+    def default(cls, package: OpcPackage) -> StylesPart:
+        """Return a newly created styles part, containing a default set of elements."""
+        partname = PackURI("/word/styles.xml")
+        content_type = CT.WML_STYLES
+        element = parse_xml(cls._default_styles_xml())
+        return cls(partname, content_type, element, package)
+
+    @property
+    def styles(self):
+        """The |_Styles| instance containing the styles (<w:style> element proxies) for
+        this styles part."""
+        return Styles(self.element)
+
+    @classmethod
+    def _default_styles_xml(cls):
+        """Return a bytestream containing XML for a default styles part."""
+        path = os.path.join(os.path.split(__file__)[0], "..", "templates", "default-styles.xml")
+        with open(path, "rb") as f:
+            xml_bytes = f.read()
+        return xml_bytes

docx/section.py

@@ -0,0 +1,479 @@
+"""The |Section| object and related proxy classes."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterator, List, Sequence, overload
+
+from docx.blkcntnr import BlockItemContainer
+from docx.enum.section import WD_HEADER_FOOTER
+from docx.oxml.text.paragraph import CT_P
+from docx.parts.hdrftr import FooterPart, HeaderPart
+from docx.shared import lazyproperty
+from docx.table import Table
+from docx.text.paragraph import Paragraph
+
+if TYPE_CHECKING:
+    from docx.enum.section import WD_ORIENTATION, WD_SECTION_START
+    from docx.oxml.document import CT_Document
+    from docx.oxml.section import CT_SectPr
+    from docx.parts.document import DocumentPart
+    from docx.parts.story import StoryPart
+    from docx.shared import Length
+
+
+class Section:
+    """Document section, providing access to section and page setup settings.
+
+    Also provides access to headers and footers.
+    """
+
+    def __init__(self, sectPr: CT_SectPr, document_part: DocumentPart):
+        super(Section, self).__init__()
+        self._sectPr = sectPr
+        self._document_part = document_part
+
+    @property
+    def bottom_margin(self) -> Length | None:
+        """Read/write. Bottom margin for pages in this section, in EMU.
+
+        `None` when no bottom margin has been specified. Assigning |None| removes any
+        bottom-margin setting.
+        """
+        return self._sectPr.bottom_margin
+
+    @bottom_margin.setter
+    def bottom_margin(self, value: int | Length | None):
+        self._sectPr.bottom_margin = value
+
+    @property
+    def different_first_page_header_footer(self) -> bool:
+        """True if this section displays a distinct first-page header and footer.
+
+        Read/write. The definition of the first-page header and footer are accessed
+        using :attr:`.first_page_header` and :attr:`.first_page_footer` respectively.
+        """
+        return self._sectPr.titlePg_val
+
+    @different_first_page_header_footer.setter
+    def different_first_page_header_footer(self, value: bool):
+        self._sectPr.titlePg_val = value
+
+    @property
+    def even_page_footer(self) -> _Footer:
+        """|_Footer| object defining footer content for even pages.
+
+        The content of this footer definition is ignored unless the document setting
+        :attr:`~.Settings.odd_and_even_pages_header_footer` is set True.
+        """
+        return _Footer(self._sectPr, self._document_part, WD_HEADER_FOOTER.EVEN_PAGE)
+
+    @property
+    def even_page_header(self) -> _Header:
+        """|_Header| object defining header content for even pages.
+
+        The content of this header definition is ignored unless the document setting
+        :attr:`~.Settings.odd_and_even_pages_header_footer` is set True.
+        """
+        return _Header(self._sectPr, self._document_part, WD_HEADER_FOOTER.EVEN_PAGE)
+
+    @property
+    def first_page_footer(self) -> _Footer:
+        """|_Footer| object defining footer content for the first page of this section.
+
+        The content of this footer definition is ignored unless the property
+        :attr:`.different_first_page_header_footer` is set True.
+        """
+        return _Footer(self._sectPr, self._document_part, WD_HEADER_FOOTER.FIRST_PAGE)
+
+    @property
+    def first_page_header(self) -> _Header:
+        """|_Header| object defining header content for the first page of this section.
+
+        The content of this header definition is ignored unless the property
+        :attr:`.different_first_page_header_footer` is set True.
+        """
+        return _Header(self._sectPr, self._document_part, WD_HEADER_FOOTER.FIRST_PAGE)
+
+    @lazyproperty
+    def footer(self) -> _Footer:
+        """|_Footer| object representing default page footer for this section.
+
+        The default footer is used for odd-numbered pages when separate odd/even footers
+        are enabled. It is used for both odd and even-numbered pages otherwise.
+        """
+        return _Footer(self._sectPr, self._document_part, WD_HEADER_FOOTER.PRIMARY)
+
+    @property
+    def footer_distance(self) -> Length | None:
+        """Distance from bottom edge of page to bottom edge of the footer.
+
+        Read/write. |None| if no setting is present in the XML.
+        """
+        return self._sectPr.footer
+
+    @footer_distance.setter
+    def footer_distance(self, value: int | Length | None):
+        self._sectPr.footer = value
+
+    @property
+    def gutter(self) -> Length | None:
+        """|Length| object representing page gutter size in English Metric Units.
+
+        Read/write. The page gutter is extra spacing added to the `inner` margin to
+        ensure even margins after page binding. Generally only used in book-bound
+        documents with double-sided and facing pages.
+
+        This setting applies to all pages in this section.
+
+        """
+        return self._sectPr.gutter
+
+    @gutter.setter
+    def gutter(self, value: int | Length | None):
+        self._sectPr.gutter = value
+
+    @lazyproperty
+    def header(self) -> _Header:
+        """|_Header| object representing default page header for this section.
+
+        The default header is used for odd-numbered pages when separate odd/even headers
+        are enabled. It is used for both odd and even-numbered pages otherwise.
+        """
+        return _Header(self._sectPr, self._document_part, WD_HEADER_FOOTER.PRIMARY)
+
+    @property
+    def header_distance(self) -> Length | None:
+        """Distance from top edge of page to top edge of header.
+
+        Read/write. |None| if no setting is present in the XML. Assigning |None| causes
+        default value to be used.
+        """
+        return self._sectPr.header
+
+    @header_distance.setter
+    def header_distance(self, value: int | Length | None):
+        self._sectPr.header = value
+
+    def iter_inner_content(self) -> Iterator[Paragraph | Table]:
+        """Generate each Paragraph or Table object in this `section`.
+
+        Items appear in document order.
+        """
+        for element in self._sectPr.iter_inner_content():
+            yield (Paragraph(element, self) if isinstance(element, CT_P) else Table(element, self))
+
+    @property
+    def left_margin(self) -> Length | None:
+        """|Length| object representing the left margin for all pages in this section in
+        English Metric Units."""
+        return self._sectPr.left_margin
+
+    @left_margin.setter
+    def left_margin(self, value: int | Length | None):
+        self._sectPr.left_margin = value
+
+    @property
+    def orientation(self) -> WD_ORIENTATION:
+        """:ref:`WdOrientation` member specifying page orientation for this section.
+
+        One of ``WD_ORIENT.PORTRAIT`` or ``WD_ORIENT.LANDSCAPE``.
+        """
+        return self._sectPr.orientation
+
+    @orientation.setter
+    def orientation(self, value: WD_ORIENTATION | None):
+        self._sectPr.orientation = value
+
+    @property
+    def page_height(self) -> Length | None:
+        """Total page height used for this section.
+
+        This value is inclusive of all edge spacing values such as margins.
+
+        Page orientation is taken into account, so for example, its expected value
+        would be ``Inches(8.5)`` for letter-sized paper when orientation is landscape.
+        """
+        return self._sectPr.page_height
+
+    @page_height.setter
+    def page_height(self, value: Length | None):
+        self._sectPr.page_height = value
+
+    @property
+    def page_width(self) -> Length | None:
+        """Total page width used for this section.
+
+        This value is like "paper size" and includes all edge spacing values such as
+        margins.
+
+        Page orientation is taken into account, so for example, its expected value
+        would be ``Inches(11)`` for letter-sized paper when orientation is landscape.
+        """
+        return self._sectPr.page_width
+
+    @page_width.setter
+    def page_width(self, value: Length | None):
+        self._sectPr.page_width = value
+
+    @property
+    def part(self) -> StoryPart:
+        return self._document_part
+
+    @property
+    def right_margin(self) -> Length | None:
+        """|Length| object representing the right margin for all pages in this section
+        in English Metric Units."""
+        return self._sectPr.right_margin
+
+    @right_margin.setter
+    def right_margin(self, value: Length | None):
+        self._sectPr.right_margin = value
+
+    @property
+    def start_type(self) -> WD_SECTION_START:
+        """Type of page-break (if any) inserted at the start of this section.
+
+        For exmple, ``WD_SECTION_START.ODD_PAGE`` if the section should begin on the
+        next odd page, possibly inserting two page-breaks instead of one.
+        """
+        return self._sectPr.start_type
+
+    @start_type.setter
+    def start_type(self, value: WD_SECTION_START | None):
+        self._sectPr.start_type = value
+
+    @property
+    def top_margin(self) -> Length | None:
+        """|Length| object representing the top margin for all pages in this section in
+        English Metric Units."""
+        return self._sectPr.top_margin
+
+    @top_margin.setter
+    def top_margin(self, value: Length | None):
+        self._sectPr.top_margin = value
+
+
+class Sections(Sequence[Section]):
+    """Sequence of |Section| objects corresponding to the sections in the document.
+
+    Supports ``len()``, iteration, and indexed access.
+    """
+
+    def __init__(self, document_elm: CT_Document, document_part: DocumentPart):
+        super(Sections, self).__init__()
+        self._document_elm = document_elm
+        self._document_part = document_part
+
+    @overload
+    def __getitem__(self, key: int) -> Section: ...
+
+    @overload
+    def __getitem__(self, key: slice) -> List[Section]: ...
+
+    def __getitem__(self, key: int | slice) -> Section | List[Section]:
+        if isinstance(key, slice):
+            return [
+                Section(sectPr, self._document_part)
+                for sectPr in self._document_elm.sectPr_lst[key]
+            ]
+        return Section(self._document_elm.sectPr_lst[key], self._document_part)
+
+    def __iter__(self) -> Iterator[Section]:
+        for sectPr in self._document_elm.sectPr_lst:
+            yield Section(sectPr, self._document_part)
+
+    def __len__(self) -> int:
+        return len(self._document_elm.sectPr_lst)
+
+
+class _BaseHeaderFooter(BlockItemContainer):
+    """Base class for header and footer classes."""
+
+    def __init__(
+        self,
+        sectPr: CT_SectPr,
+        document_part: DocumentPart,
+        header_footer_index: WD_HEADER_FOOTER,
+    ):
+        self._sectPr = sectPr
+        self._document_part = document_part
+        self._hdrftr_index = header_footer_index
+
+    @property
+    def is_linked_to_previous(self) -> bool:
+        """``True`` if this header/footer uses the definition from the prior section.
+
+        ``False`` if this header/footer has an explicit definition.
+
+        Assigning ``True`` to this property removes the header/footer definition for
+        this section, causing it to "inherit" the corresponding definition of the prior
+        section. Assigning ``False`` causes a new, empty definition to be added for this
+        section, but only if no definition is already present.
+        """
+        # ---absence of a header/footer part indicates "linked" behavior---
+        return not self._has_definition
+
+    @is_linked_to_previous.setter
+    def is_linked_to_previous(self, value: bool) -> None:
+        new_state = bool(value)
+        # ---do nothing when value is not being changed---
+        if new_state == self.is_linked_to_previous:
+            return
+        if new_state is True:
+            self._drop_definition()
+        else:
+            self._add_definition()
+
+    @property
+    def part(self) -> HeaderPart | FooterPart:
+        """The |HeaderPart| or |FooterPart| for this header/footer.
+
+        This overrides `BlockItemContainer.part` and is required to support image
+        insertion and perhaps other content like hyperlinks.
+        """
+        # ---should not appear in documentation;
+        # ---not an interface property, even though public
+        return self._get_or_add_definition()
+
+    def _add_definition(self) -> HeaderPart | FooterPart:
+        """Return newly-added header/footer part."""
+        raise NotImplementedError("must be implemented by each subclass")
+
+    @property
+    def _definition(self) -> HeaderPart | FooterPart:
+        """|HeaderPart| or |FooterPart| object containing header/footer content."""
+        raise NotImplementedError("must be implemented by each subclass")
+
+    def _drop_definition(self) -> None:
+        """Remove header/footer part containing the definition of this header/footer."""
+        raise NotImplementedError("must be implemented by each subclass")
+
+    @property
+    def _element(self):
+        """`w:hdr` or `w:ftr` element, root of header/footer part."""
+        return self._get_or_add_definition().element
+
+    def _get_or_add_definition(self) -> HeaderPart | FooterPart:
+        """Return HeaderPart or FooterPart object for this section.
+
+        If this header/footer inherits its content, the part for the prior header/footer
+        is returned; this process continue recursively until a definition is found. If
+        the definition cannot be inherited (because the header/footer belongs to the
+        first section), a new definition is added for that first section and then
+        returned.
+        """
+        # ---note this method is called recursively to access inherited definitions---
+        # ---case-1: definition is not inherited---
+        if self._has_definition:
+            return self._definition
+        # ---case-2: definition is inherited and belongs to second-or-later section---
+        prior_headerfooter = self._prior_headerfooter
+        if prior_headerfooter:
+            return prior_headerfooter._get_or_add_definition()
+        # ---case-3: definition is inherited, but belongs to first section---
+        return self._add_definition()
+
+    @property
+    def _has_definition(self) -> bool:
+        """True if this header/footer has a related part containing its definition."""
+        raise NotImplementedError("must be implemented by each subclass")
+
+    @property
+    def _prior_headerfooter(self) -> _Header | _Footer | None:
+        """|_Header| or |_Footer| proxy on prior sectPr element.
+
+        Returns None if this is first section.
+        """
+        raise NotImplementedError("must be implemented by each subclass")
+
+
+class _Footer(_BaseHeaderFooter):
+    """Page footer, used for all three types (default, even-page, and first-page).
+
+    Note that, like a document or table cell, a footer must contain a minimum of one
+    paragraph and a new or otherwise "empty" footer contains a single empty paragraph.
+    This first paragraph can be accessed as `footer.paragraphs[0]` for purposes of
+    adding content to it. Using :meth:`add_paragraph()` by itself to add content will
+    leave an empty paragraph above the newly added one.
+    """
+
+    def _add_definition(self) -> FooterPart:
+        """Return newly-added footer part."""
+        footer_part, rId = self._document_part.add_footer_part()
+        self._sectPr.add_footerReference(self._hdrftr_index, rId)
+        return footer_part
+
+    @property
+    def _definition(self):
+        """|FooterPart| object containing content of this footer."""
+        footerReference = self._sectPr.get_footerReference(self._hdrftr_index)
+        # -- currently this is never called when `._has_definition` evaluates False --
+        assert footerReference is not None
+        return self._document_part.footer_part(footerReference.rId)
+
+    def _drop_definition(self):
+        """Remove footer definition (footer part) associated with this section."""
+        rId = self._sectPr.remove_footerReference(self._hdrftr_index)
+        self._document_part.drop_rel(rId)
+
+    @property
+    def _has_definition(self) -> bool:
+        """True if a footer is defined for this section."""
+        footerReference = self._sectPr.get_footerReference(self._hdrftr_index)
+        return footerReference is not None
+
+    @property
+    def _prior_headerfooter(self):
+        """|_Footer| proxy on prior sectPr element or None if this is first section."""
+        preceding_sectPr = self._sectPr.preceding_sectPr
+        return (
+            None
+            if preceding_sectPr is None
+            else _Footer(preceding_sectPr, self._document_part, self._hdrftr_index)
+        )
+
+
+class _Header(_BaseHeaderFooter):
+    """Page header, used for all three types (default, even-page, and first-page).
+
+    Note that, like a document or table cell, a header must contain a minimum of one
+    paragraph and a new or otherwise "empty" header contains a single empty paragraph.
+    This first paragraph can be accessed as `header.paragraphs[0]` for purposes of
+    adding content to it. Using :meth:`add_paragraph()` by itself to add content will
+    leave an empty paragraph above the newly added one.
+    """
+
+    def _add_definition(self):
+        """Return newly-added header part."""
+        header_part, rId = self._document_part.add_header_part()
+        self._sectPr.add_headerReference(self._hdrftr_index, rId)
+        return header_part
+
+    @property
+    def _definition(self):
+        """|HeaderPart| object containing content of this header."""
+        headerReference = self._sectPr.get_headerReference(self._hdrftr_index)
+        # -- currently this is never called when `._has_definition` evaluates False --
+        assert headerReference is not None
+        return self._document_part.header_part(headerReference.rId)
+
+    def _drop_definition(self):
+        """Remove header definition associated with this section."""
+        rId = self._sectPr.remove_headerReference(self._hdrftr_index)
+        self._document_part.drop_header_part(rId)
+
+    @property
+    def _has_definition(self) -> bool:
+        """True if a header is explicitly defined for this section."""
+        headerReference = self._sectPr.get_headerReference(self._hdrftr_index)
+        return headerReference is not None
+
+    @property
+    def _prior_headerfooter(self):
+        """|_Header| proxy on prior sectPr element or None if this is first section."""
+        preceding_sectPr = self._sectPr.preceding_sectPr
+        return (
+            None
+            if preceding_sectPr is None
+            else _Header(preceding_sectPr, self._document_part, self._hdrftr_index)
+        )

docx/settings.py

@@ -0,0 +1,35 @@
+"""Settings object, providing access to document-level settings."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from docx.shared import ElementProxy
+
+if TYPE_CHECKING:
+    import docx.types as t
+    from docx.oxml.settings import CT_Settings
+    from docx.oxml.xmlchemy import BaseOxmlElement
+
+
+class Settings(ElementProxy):
+    """Provides access to document-level settings for a document.
+
+    Accessed using the :attr:`.Document.settings` property.
+    """
+
+    def __init__(self, element: BaseOxmlElement, parent: t.ProvidesXmlPart | None = None):
+        super().__init__(element, parent)
+        self._settings = cast("CT_Settings", element)
+
+    @property
+    def odd_and_even_pages_header_footer(self) -> bool:
+        """True if this document has distinct odd and even page headers and footers.
+
+        Read/write.
+        """
+        return self._settings.evenAndOddHeaders_val
+
+    @odd_and_even_pages_header_footer.setter
+    def odd_and_even_pages_header_footer(self, value: bool):
+        self._settings.evenAndOddHeaders_val = value