Skip to content

docx_plus.layout.breaks

Insert a section break at an arbitrary paragraph. python-docx's Document.add_section only appends a new section at the end of the document; this module handles the mid-document case by cloning the trailing <w:sectPr> into the chosen paragraph's pPr and setting <w:type> to the requested start kind.

docx_plus.layout.breaks

Insert a section break at an arbitrary paragraph.

python-docx's :meth:Document.add_section only appends a new section at the end of the document. Inserting a section break mid-document requires moving the existing trailing <w:sectPr>'s properties into the chosen paragraph and writing a fresh <w:type> value to mark the break style. :func:insert_section_break does that in one call.

This module imports only from docx_plus.core and python-docx internals via the section proxy (SPEC §9.1).

SectionStartType module-attribute 

SectionStartType = Literal[
    "nextPage", "continuous", "evenPage", "oddPage", "nextColumn"
]

insert_section_break 

insert_section_break(
    paragraph: Paragraph, *, start_type: SectionStartType = "nextPage"
) -> Section

Insert a section break at paragraph.

The break splits the document so that the chosen paragraph becomes the last paragraph of a new section. Section properties (page size, margins, header/footer references) are copied from the document's trailing <w:sectPr>, then <w:type> is set on the inserted copy so Word knows how the following section starts.

If paragraph already carries a section break, this call replaces it (idempotent re-application is supported, e.g. to switch the break type from nextPage to continuous).

Parameters:

Name Type Description Default
paragraph Paragraph

A python-docx :class:~docx.text.paragraph.Paragraph in the main document body.

 required
start_type SectionStartType

How the following section begins. "nextPage" (default) puts the new section on a fresh page; "continuous" lets it flow on the same page; "evenPage" / "oddPage" page-break to the next even/odd-numbered page; "nextColumn" starts a new column.

 'nextPage'

Returns:

Name Type Description
A Section

class:Section proxy wrapping the new section's
Section

<w:sectPr>. Use it to mutate the new section's properties
Section

(margins, columns, headers).

Raises:

Type Description
ValueError

If paragraph is not parented to <w:body> (e.g. a header/footer paragraph), or if the document has no trailing <w:sectPr> to copy section properties from (reachable on a hand-built document that never had one).
Example

from docx import Document from docx_plus.layout import insert_section_break doc = Document() doc.add_paragraph("intro") p = doc.add_paragraph("split here") doc.add_paragraph("after the break") new_section = insert_section_break(p, start_type="continuous")

Source code in docx_plus/layout/breaks.py 
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def insert_section_break(
    paragraph: Paragraph,
    *,
    start_type: SectionStartType = "nextPage",
) -> Section:
    """Insert a section break at ``paragraph``.

    The break splits the document so that the chosen paragraph becomes
    the last paragraph of a new section. Section properties (page size,
    margins, header/footer references) are copied from the document's
    trailing ``<w:sectPr>``, then ``<w:type>`` is set on the inserted
    copy so Word knows how the *following* section starts.

    If ``paragraph`` already carries a section break, this call replaces
    it (idempotent re-application is supported, e.g. to switch the
    break type from ``nextPage`` to ``continuous``).

    Args:
        paragraph: A python-docx :class:`~docx.text.paragraph.Paragraph`
            in the main document body.
        start_type: How the *following* section begins. ``"nextPage"``
            (default) puts the new section on a fresh page;
            ``"continuous"`` lets it flow on the same page;
            ``"evenPage"`` / ``"oddPage"`` page-break to the next
            even/odd-numbered page; ``"nextColumn"`` starts a new column.

    Returns:
        A :class:`Section` proxy wrapping the new section's
        ``<w:sectPr>``. Use it to mutate the new section's properties
        (margins, columns, headers).

    Raises:
        ValueError: If ``paragraph`` is not parented to ``<w:body>``
            (e.g. a header/footer paragraph), or if the document has no
            trailing ``<w:sectPr>`` to copy section properties from
            (reachable on a hand-built document that never had one).

    Example:
        >>> from docx import Document
        >>> from docx_plus.layout import insert_section_break
        >>> doc = Document()
        >>> doc.add_paragraph("intro")
        >>> p = doc.add_paragraph("split here")
        >>> doc.add_paragraph("after the break")
        >>> new_section = insert_section_break(p, start_type="continuous")
    """
    p_element = paragraph._p
    body = p_element.getparent()
    if body is None or body.tag != qn("w:body"):
        raise ValueError("insert_section_break requires a paragraph in the main document body")

    sentinel = body.find(qn("w:sectPr"))
    if sentinel is None:
        raise ValueError("document has no trailing sectPr to copy properties from")

    new_sect_pr = cast("CT_SectPr", deepcopy(sentinel))
    new_sect_pr.attrib.clear()
    _set_start_type(new_sect_pr, start_type)
    p_element.set_sectPr(new_sect_pr)

    document_part = cast("DocumentPart", paragraph.part)
    return Section(new_sect_pr, document_part)