section

section

Section-related custom element classes.

CT_PageBorders

Bases: _CT_BordersBase

w:pgBorders element, the border drawn around the pages of a section.

Only four edges, unlike w:pBdr. The three attributes have no CT_Border counterpart and belong to the container: where the border is measured from, which pages it appears on, and whether it is drawn in front of or behind the page content.

The schema gives the top and bottom edges the CT_TopPageBorder and CT_BottomPageBorder types, which add attributes naming a decorative border image. Those are not modelled; the edges arrive as CT_Border like every other edge tag, which covers the line style, colour, width and spacing that make up an ordinary page border.

CT_HdrFtr

Bases: BaseOxmlElement

w:hdr and w:ftr, the root element for header and footer part respectively.

inner_content_elements property

inner_content_elements: List[CT_P | CT_Tbl]

Generate all w:p and w:tbl elements in this header or footer.

Elements appear in document order. Content inside a w:sdt (content control) wrapper is included; content shaded by nesting in a w:ins or other wrapper is not.

CT_HdrFtrRef

Bases: BaseOxmlElement

w:headerReference and w:footerReference elements.

CT_Column

Bases: BaseOxmlElement

w:col element, one column of an unequal-width multi-column layout.

CT_Columns

Bases: BaseOxmlElement

w:cols element, the multi-column layout of a section.

w:col children appear only when the columns are of unequal width; the common equal-width case is described entirely by the attributes here.

clear_cols

clear_cols() -> None

Remove all w:col children, restoring equal-width columns.

Source code in src/docx/oxml/section.py

def clear_cols(self) -> None:
    """Remove all `w:col` children, restoring equal-width columns."""
    for col in self.col_lst:
        self.remove(col)

CT_PageMar

Bases: BaseOxmlElement

<w:pgMar> element, defining page margins.

CT_PageSz

Bases: BaseOxmlElement

<w:pgSz> element, defining page dimensions and orientation.

CT_SectPr

Bases: BaseOxmlElement

w:sectPr element, the container element for section properties.

bidi_val property writable

bidi_val: bool | None

Value of ./w:bidi/@w:val, or None if the element is absent.

textDirection_val property writable

textDirection_val: WD_TEXT_DIRECTION | None

Value of ./w:textDirection/@w:val, or None if the element is absent.

bottom_margin property writable

bottom_margin: Length | None

Value of the w:bottom attr of <w:pgMar> child element, as Length.

None when either the element or the attribute is not present.

footer property writable

footer: Length | None

Distance from bottom edge of page to bottom edge of the footer.

This is the value of the w:footer attribute in the w:pgMar child element, as a Length object, or None if either the element or the attribute is not present.

gutter property writable

gutter: Length | None

The value of the w:gutter attribute in the <w:pgMar> child element, as a Length object, or None if either the element or the attribute is not present.

header property writable

header: Length | None

Distance from top edge of page to top edge of header.

This value comes from the w:header attribute on the w:pgMar child element. None if either the element or the attribute is not present.

left_margin property writable

left_margin: Length | None

The value of the w:left attribute in the <w:pgMar> child element, as a Length object, or None if either the element or the attribute is not present.

orientation property writable

orientation: WD_ORIENTATION

WD_ORIENTATION member indicating page-orientation for this section.

This is the value of the orient attribute on the w:pgSz child, or WD_ORIENTATION.PORTRAIT if not present.

page_height property writable

page_height: Length | None

Value in EMU of the h attribute of the w:pgSz child element.

None if not present.

page_width property writable

page_width: Length | None

Value in EMU of the w attribute of the <w:pgSz> child element.

None if not present.

preceding_sectPr property

preceding_sectPr: CT_SectPr | None

SectPr immediately preceding this one or None if this is the first.

right_margin property writable

right_margin: Length | None

The value of the w:right attribute in the <w:pgMar> child element, as a Length object, or None if either the element or the attribute is not present.

start_type property writable

start_type: WD_SECTION_START

The member of the WD_SECTION_START enumeration corresponding to the value of the val attribute of the <w:type> child element, or WD_SECTION_START.NEW_PAGE if not present.

titlePg_val property writable

titlePg_val: bool

Value of w:titlePg/@val or False if ./w:titlePg is not present.

top_margin property writable

top_margin: Length | None

The value of the w:top attribute in the <w:pgMar> child element, as a Length object, or None if either the element or the attribute is not present.

add_footerReference

add_footerReference(
    type_: WD_HEADER_FOOTER, rId: str
) -> CT_HdrFtrRef

Return newly added CT_HdrFtrRef element of type_ with rId.

The element tag is w:footerReference.

Source code in src/docx/oxml/section.py

def add_footerReference(self, type_: WD_HEADER_FOOTER, rId: str) -> CT_HdrFtrRef:
    """Return newly added CT_HdrFtrRef element of `type_` with `rId`.

    The element tag is `w:footerReference`.
    """
    footerReference = self._add_footerReference()
    footerReference.type_ = type_
    footerReference.rId = rId
    return footerReference

add_headerReference

add_headerReference(
    type_: WD_HEADER_FOOTER, rId: str
) -> CT_HdrFtrRef

Return newly added CT_HdrFtrRef element of type_ with rId.

The element tag is w:headerReference.

Source code in src/docx/oxml/section.py

def add_headerReference(self, type_: WD_HEADER_FOOTER, rId: str) -> CT_HdrFtrRef:
    """Return newly added CT_HdrFtrRef element of `type_` with `rId`.

    The element tag is `w:headerReference`.
    """
    headerReference = self._add_headerReference()
    headerReference.type_ = type_
    headerReference.rId = rId
    return headerReference

clone

clone() -> CT_SectPr

Return an exact duplicate of this <w:sectPr> element tree suitable for use in adding a section break.

All rsid* attributes are removed from the root <w:sectPr> element.

Source code in src/docx/oxml/section.py

def clone(self) -> CT_SectPr:
    """Return an exact duplicate of this ``<w:sectPr>`` element tree suitable for
    use in adding a section break.

    All rsid* attributes are removed from the root ``<w:sectPr>`` element.
    """
    cloned_sectPr = deepcopy(self)
    cloned_sectPr.attrib.clear()
    return cloned_sectPr

get_footerReference

get_footerReference(
    type_: WD_HEADER_FOOTER,
) -> CT_HdrFtrRef | None

Return footerReference element of type_ or None if not present.

Source code in src/docx/oxml/section.py

def get_footerReference(self, type_: WD_HEADER_FOOTER) -> CT_HdrFtrRef | None:
    """Return footerReference element of `type_` or None if not present."""
    path = "./w:footerReference[@w:type='%s']" % WD_HEADER_FOOTER.to_xml(type_)
    footerReferences = self.xpath(path)
    if not footerReferences:
        return None
    return footerReferences[0]

get_headerReference

get_headerReference(
    type_: WD_HEADER_FOOTER,
) -> CT_HdrFtrRef | None

Return headerReference element of type_ or None if not present.

Source code in src/docx/oxml/section.py

def get_headerReference(self, type_: WD_HEADER_FOOTER) -> CT_HdrFtrRef | None:
    """Return headerReference element of `type_` or None if not present."""
    matching_headerReferences = self.xpath(
        "./w:headerReference[@w:type='%s']" % WD_HEADER_FOOTER.to_xml(type_)
    )
    if len(matching_headerReferences) == 0:
        return None
    return matching_headerReferences[0]

iter_inner_content

iter_inner_content() -> Iterator[CT_P | CT_Tbl]

Generate all w:p and w:tbl elements in this section.

Elements appear in document order. Elements shaded by nesting in a w:ins or other "wrapper" element will not be included.

Source code in src/docx/oxml/section.py

def iter_inner_content(self) -> Iterator[CT_P | CT_Tbl]:
    """Generate all `w:p` and `w:tbl` elements in this section.

    Elements appear in document order. Elements shaded by nesting in a `w:ins` or
    other "wrapper" element will not be included.
    """
    return _SectBlockElementIterator.iter_sect_block_elements(self)

remove_footerReference

remove_footerReference(type_: WD_HEADER_FOOTER) -> str

Return rId of w:footerReference child of type_ after removing it.

Source code in src/docx/oxml/section.py

def remove_footerReference(self, type_: WD_HEADER_FOOTER) -> str:
    """Return rId of w:footerReference child of `type_` after removing it."""
    footerReference = self.get_footerReference(type_)
    if footerReference is None:
        # -- should never happen, but to satisfy type-check and just in case --
        raise ValueError("CT_SectPr has no footer reference")
    rId = footerReference.rId
    self.remove(footerReference)
    return rId

remove_headerReference

remove_headerReference(type_: WD_HEADER_FOOTER)

Return rId of w:headerReference child of type_ after removing it.

Source code in src/docx/oxml/section.py

def remove_headerReference(self, type_: WD_HEADER_FOOTER):
    """Return rId of w:headerReference child of `type_` after removing it."""
    headerReference = self.get_headerReference(type_)
    if headerReference is None:
        # -- should never happen, but to satisfy type-check and just in case --
        raise ValueError("CT_SectPr has no header reference")
    rId = headerReference.rId
    self.remove(headerReference)
    return rId

CT_SectType

Bases: BaseOxmlElement

<w:sectType> element, defining the section start type.

_SectBlockElementIterator

_SectBlockElementIterator(sectPr: CT_SectPr)

Generates the block-item XML elements in a section.

A block-item element is a CT_P (paragraph) or a CT_Tbl (table).

Source code in src/docx/oxml/section.py

def __init__(self, sectPr: CT_SectPr):
    self._sectPr = sectPr

iter_sect_block_elements classmethod

iter_sect_block_elements(
    sectPr: CT_SectPr,
) -> Iterator[BlockElement]

Generate each CT_P or CT_Tbl element within extents governed by sectPr.

Source code in src/docx/oxml/section.py

@classmethod
def iter_sect_block_elements(cls, sectPr: CT_SectPr) -> Iterator[BlockElement]:
    """Generate each CT_P or CT_Tbl element within extents governed by `sectPr`."""
    return cls(sectPr)._iter_sect_block_elements()