Initial commit (Clean history)

path/to/venv/lib/python3.12/site-packages/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)
+        )