paragraph

paragraph

Custom element classes related to paragraphs (CT_P).

CT_P

Bases: BaseOxmlElement

<w:p> element, containing the properties and text for a paragraph.

alignment property writable

alignment: WD_PARAGRAPH_ALIGNMENT | None

The value of the <w:jc> grandchild element or None if not present.

inner_content_elements property

inner_content_elements: List[CT_R | CT_Hyperlink]

Run and hyperlink children of the w:p element, in document order.

A run-level w:sdt (content control) is looked through, so the runs it wraps appear here in its place.

lastRenderedPageBreaks property

lastRenderedPageBreaks: List[CT_LastRenderedPageBreak]

All w:lastRenderedPageBreak descendants of this paragraph.

Rendered page-breaks commonly occur in a run but can also occur in a run inside a hyperlink. This returns both.

style property writable

style: str | None

String contained in w:val attribute of ./w:pPr/w:pStyle grandchild.

None if not present.

text property

text

The textual content of this paragraph.

Inner-content child elements like w:r and w:hyperlink are translated to their text equivalent, including those wrapped in a run-level w:sdt.

assert_deletable

assert_deletable() -> None

Raise ValueError if removing this paragraph would invalidate the document.

A w:tc must contain at least one block-level element, so the last paragraph of a table cell cannot simply be removed.

Source code in src/docx/oxml/text/paragraph.py

def assert_deletable(self) -> None:
    """Raise |ValueError| if removing this paragraph would invalidate the document.

    A `w:tc` must contain at least one block-level element, so the last paragraph of
    a table cell cannot simply be removed.
    """
    parent = self.getparent()
    if parent is None or parent.tag != qn("w:tc"):
        return
    block_items = parent.xpath("./w:p | ./w:tbl | ./w:sdt")
    if len(block_items) < 2:
        raise ValueError(
            "cannot delete the only block-level element in a table cell; a w:tc"
            " must contain at least one, and Word will not open a document whose"
            " cell is empty. Assign `cell.text = ''` to clear the cell instead."
        )

add_bookmark_around_content

add_bookmark_around_content(
    id: int, name: str
) -> CT_BookmarkStart

Wrap the inner content of this paragraph in a bookmark named name.

The w:bookmarkStart goes after w:pPr and before the first run; the w:bookmarkEnd goes at the end of the paragraph.

Source code in src/docx/oxml/text/paragraph.py

def add_bookmark_around_content(self, id: int, name: str) -> CT_BookmarkStart:
    """Wrap the inner content of this paragraph in a bookmark named `name`.

    The `w:bookmarkStart` goes after `w:pPr` and before the first run; the
    `w:bookmarkEnd` goes at the end of the paragraph.
    """
    bookmarkStart = cast("CT_BookmarkStart", OxmlElement("w:bookmarkStart"))
    bookmarkStart.id = id
    bookmarkStart.name = name
    pPr = self.pPr
    if pPr is None:
        self.insert(0, bookmarkStart)
    else:
        pPr.addnext(bookmarkStart)

    bookmarkEnd = cast("CT_BookmarkEnd", OxmlElement("w:bookmarkEnd"))
    bookmarkEnd.id = id
    self.append(bookmarkEnd)
    return bookmarkStart

add_p_before

add_p_before() -> CT_P

Return a new <w:p> element inserted directly prior to this one.

Source code in src/docx/oxml/text/paragraph.py

def add_p_before(self) -> CT_P:
    """Return a new `<w:p>` element inserted directly prior to this one."""
    new_p = cast(CT_P, OxmlElement("w:p"))
    self.addprevious(new_p)
    return new_p

clear_content

clear_content()

Remove all child elements, except the <w:pPr> element if present.

Source code in src/docx/oxml/text/paragraph.py

def clear_content(self):
    """Remove all child elements, except the `<w:pPr>` element if present."""
    for child in self.xpath("./*[not(self::w:pPr)]"):
        self.remove(child)

set_sectPr

set_sectPr(sectPr: CT_SectPr)

Unconditionally replace or add sectPr as grandchild in correct sequence.

Source code in src/docx/oxml/text/paragraph.py

def set_sectPr(self, sectPr: CT_SectPr):
    """Unconditionally replace or add `sectPr` as grandchild in correct sequence."""
    pPr = self.get_or_add_pPr()
    pPr._remove_sectPr()
    pPr._insert_sectPr(sectPr)