run

run

Custom element classes related to text runs (CT_R).

CT_R

Bases: BaseOxmlElement

<w:r> element, containing the properties and text for a run.

inner_content_items property

inner_content_items: List[
    str | CT_Drawing | CT_LastRenderedPageBreak
]

Text of run, possibly punctuated by w:lastRenderedPageBreak elements.

lastRenderedPageBreaks property

lastRenderedPageBreaks: List[CT_LastRenderedPageBreak]

All w:lastRenderedPageBreaks descendants of this run.

style property writable

style: str | None

String contained in w:val attribute of w:rStyle grandchild.

None if that element is not present.

text property writable

text: str

The textual content of this run.

Inner-content child elements like w:tab are translated to their text equivalent.

add_t

add_t(text: str) -> CT_Text

Return a newly added <w:t> element containing text.

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

def add_t(self, text: str) -> CT_Text:
    """Return a newly added `<w:t>` element containing `text`."""
    t = self._add_t(text=text)
    if len(text.strip()) < len(text):
        t.set(qn("xml:space"), "preserve")
    return t

add_drawing

add_drawing(
    inline_or_anchor: CT_Inline | CT_Anchor,
) -> CT_Drawing

Return newly appended CT_Drawing (w:drawing) child element.

The w:drawing element has inline_or_anchor as its child.

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

def add_drawing(self, inline_or_anchor: CT_Inline | CT_Anchor) -> CT_Drawing:
    """Return newly appended `CT_Drawing` (`w:drawing`) child element.

    The `w:drawing` element has `inline_or_anchor` as its child.
    """
    drawing = self._add_drawing()
    drawing.append(inline_or_anchor)
    return drawing

clear_content

clear_content() -> None

Remove all child elements except a w:rPr element if present.

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

def clear_content(self) -> None:
    """Remove all child elements except a `w:rPr` element if present."""
    # -- remove all run inner-content except a `w:rPr` when present. --
    for e in self.xpath("./*[not(self::w:rPr)]"):
        self.remove(e)

insert_comment_range_end_and_reference_below

insert_comment_range_end_and_reference_below(
    comment_id: int,
) -> None

Insert a w:commentRangeEnd and w:commentReference element after this run.

The w:commentRangeEnd element is the immediate sibling of this w:r and is followed by a w:r containing the w:commentReference element.

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

def insert_comment_range_end_and_reference_below(self, comment_id: int) -> None:
    """Insert a `w:commentRangeEnd` and `w:commentReference` element after this run.

    The `w:commentRangeEnd` element is the immediate sibling of this `w:r` and is followed by
    a `w:r` containing the `w:commentReference` element.
    """
    self.addnext(self._new_comment_reference_run(comment_id))
    self.addnext(OxmlElement("w:commentRangeEnd", attrs={qn("w:id"): str(comment_id)}))

insert_bookmark_start_above

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

Insert a w:bookmarkStart for name immediately before this run.

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

def insert_bookmark_start_above(self, id: int, name: str) -> CT_BookmarkStart:
    """Insert a `w:bookmarkStart` for `name` immediately before this run."""
    bookmarkStart = cast("CT_BookmarkStart", OxmlElement("w:bookmarkStart"))
    bookmarkStart.id = id
    bookmarkStart.name = name
    self.addprevious(bookmarkStart)
    return bookmarkStart

insert_bookmark_end_below

insert_bookmark_end_below(id: int) -> CT_BookmarkEnd

Insert a w:bookmarkEnd for id immediately after this run.

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

def insert_bookmark_end_below(self, id: int) -> CT_BookmarkEnd:
    """Insert a `w:bookmarkEnd` for `id` immediately after this run."""
    bookmarkEnd = cast("CT_BookmarkEnd", OxmlElement("w:bookmarkEnd"))
    bookmarkEnd.id = id
    self.addnext(bookmarkEnd)
    return bookmarkEnd

insert_comment_range_start_above

insert_comment_range_start_above(comment_id: int) -> None

Insert a w:commentRangeStart element with comment_id before this run.

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

def insert_comment_range_start_above(self, comment_id: int) -> None:
    """Insert a `w:commentRangeStart` element with `comment_id` before this run."""
    self.addprevious(OxmlElement("w:commentRangeStart", attrs={qn("w:id"): str(comment_id)}))

CT_Br

Bases: BaseOxmlElement

<w:br> element, indicating a line, page, or column break in a run.

CT_Cr

Bases: BaseOxmlElement

<w:cr> element, representing a carriage-return (0x0D) character within a run.

In Word, this represents a "soft carriage-return" in the sense that it does not end
the paragraph the way pressing Enter (aka. Return) on the keyboard does. Here the
text equivalent is considered to be newline ("

") since in plain-text that's the closest Python equivalent.

NOTE: this complex-type name does not exist in the schema, where `w:tab` maps to
`CT_Empty`. This name was added to give it distinguished behavior. CT_Empty is used
for many elements.

CT_NoBreakHyphen

Bases: BaseOxmlElement

<w:noBreakHyphen> element, a hyphen ineligible for a line-wrap position.

This maps to a plain-text dash ("-").

NOTE: this complex-type name does not exist in the schema, where w:noBreakHyphen maps to CT_Empty. This name was added to give it behavior distinguished from the many other elements represented in the schema by CT_Empty.

CT_PTab

Bases: BaseOxmlElement

<w:ptab> element, representing an absolute-position tab character within a run.

This character advances the rendering position to the specified position regardless of any tab-stops, perhaps for layout of a table-of-contents (TOC) or similar.

CT_Text

Bases: BaseOxmlElement

<w:t> element, containing a sequence of characters within a run.

_RunContentAppender

_RunContentAppender(r: CT_R)

Translates a Python string into run content elements appended in a w:r element.

Contiguous sequences of regular characters are appended in a single `<w:t>` element.
Each tab character ('       ') causes a `<w:tab/>` element to be appended. Likewise a
newline or carriage return character ('

', ' ') causes a <w:cr> element to be appended.

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

def __init__(self, r: CT_R):
    self._r = r
    self._bfr: List[str] = []

append_to_run_from_text classmethod

append_to_run_from_text(r: CT_R, text: str)

Append inner-content elements for text to r element.

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

@classmethod
def append_to_run_from_text(cls, r: CT_R, text: str):
    """Append inner-content elements for `text` to `r` element."""
    appender = cls(r)
    appender.add_text(text)

add_text

add_text(text: str)

Append inner-content elements for text to the w:r element.

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

def add_text(self, text: str):
    """Append inner-content elements for `text` to the `w:r` element."""
    for char in text:
        self.add_char(char)
    self.flush()

add_char

add_char(char: str)

Process next character of input through finite state maching (FSM).

There are two possible states, buffer pending and not pending, but those are hidden behind the .flush() method which must be called at the end of text to ensure any pending <w:t> element is written.

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

def add_char(self, char: str):
    """Process next character of input through finite state maching (FSM).

    There are two possible states, buffer pending and not pending, but those are
    hidden behind the `.flush()` method which must be called at the end of text to
    ensure any pending `<w:t>` element is written.
    """
    if char == "\t":
        self.flush()
        self._r.add_tab()
    elif char in "\r\n":
        self.flush()
        self._r.add_br()
    else:
        self._bfr.append(char)