parfmt

parfmt

Custom element classes related to paragraph properties (CT_PPr).

CT_Ind

Bases: BaseOxmlElement

<w:ind> element, specifying paragraph indentation.

Two unit systems live side by side here. The w:left, w:right, w:firstLine and w:hanging attributes are absolute twips measures. The *Chars attributes beside them are in hundredths of a character — the unit Word's paragraph dialogue offers for a CJK document — and are not Length values: a character has no fixed size, so there is nothing to convert them to.

w:start and w:end are the newer writing-direction synonyms of w:left and w:right. Word writes them in files saved by recent versions; a document using them reads as unindented if only w:left is consulted.

CT_Jc

Bases: BaseOxmlElement

<w:jc> element, specifying paragraph justification.

CT_TextDirection

Bases: BaseOxmlElement

w:textDirection element, specifying the flow direction of text.

One class serves the w:pPr, w:sectPr and w:tcPr occurrences; the element is identical in all three.

CT_PBdr

Bases: _CT_BordersBase

w:pBdr element, the set of border edges of a paragraph.

Two of the six edges have no table counterpart. w:between is the border drawn between consecutive paragraphs that share identical border settings, rather than an edge of any one paragraph; w:bar is the vertical bar drawn beside the paragraph.

CT_PPr

Bases: BaseOxmlElement

<w:pPr> element, containing the properties for a paragraph.

outlineLvl_val property writable

outlineLvl_val: int | None

Value of ./w:outlineLvl/@w:val, or None if not present.

shd_fill property writable

shd_fill: RGBColor | str | None

Value of ./w:shd/@w:fill, or None when there is none.

None both when there is no w:shd at all and when it carries a pattern but no fill, which is valid — <w:shd w:val="pct25" w:color="FF0000"/> for instance.

shd_val property writable

shd_val: WD_SHADING_PATTERN | None

The w:shd/@w:val shading pattern, or None when no shading is applied.

shd_color property writable

shd_color: RGBColor | str | None

Value of ./w:shd/@w:color, the pattern foreground, or None.

first_line_indent property writable

first_line_indent: Length | None

A Length value calculated from the values of w:ind/@w:firstLine and w:ind/@w:hanging.

Returns None if the w:ind child is not present.

first_line_indent_chars property writable

first_line_indent_chars: int | None

The first-line indent in hundredths of a character, or None if not present.

Derived from w:ind/@w:firstLineChars and @w:hangingChars the way .first_line_indent is derived from their twips counterparts: a negative value means a hanging indent.

ind_left property writable

ind_left: Length | None

The value of w:ind/@w:left or None if not present.

Falls back to @w:start, the writing-direction synonym Word writes in files saved by recent versions.

ind_right property writable

ind_right: Length | None

The value of w:ind/@w:right or None if not present.

Falls back to @w:end, the writing-direction synonym.

ind_left_chars property writable

ind_left_chars: int | None

w:ind/@w:leftChars in hundredths of a character, or None if not present.

Falls back to @w:startChars, its writing-direction synonym.

ind_right_chars property writable

ind_right_chars: int | None

w:ind/@w:rightChars in hundredths of a character, or None if not present.

Falls back to @w:endChars, its writing-direction synonym.

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.

jc_val property writable

jc_val: WD_ALIGN_PARAGRAPH | None

Value of the <w:jc> child element or None if not present.

keepLines_val property writable

keepLines_val

The value of keepLines/@val or None if not present.

keepNext_val property writable

keepNext_val

The value of keepNext/@val or None if not present.

pageBreakBefore_val property writable

pageBreakBefore_val

The value of pageBreakBefore/@val or None if not present.

spacing_after property writable

spacing_after

The value of w:spacing/@w:after or None if not present.

spacing_before property writable

spacing_before

The value of w:spacing/@w:before or None if not present.

spacing_after_lines property writable

spacing_after_lines: int | None

w:spacing/@w:afterLines in hundredths of a line, or None if not present.

spacing_before_lines property writable

spacing_before_lines: int | None

w:spacing/@w:beforeLines in hundredths of a line, or None if not present.

spacing_line property writable

spacing_line

The value of w:spacing/@w:line or None if not present.

spacing_lineRule property writable

spacing_lineRule

The value of w:spacing/@w:lineRule as a member of the WdLineSpacing enumeration.

Only the MULTIPLE, EXACTLY, and AT_LEAST members are used. It is the responsibility of the client to calculate the use of SINGLE, DOUBLE, and MULTIPLE based on the value of w:spacing/@w:line if that behavior is desired.

style property writable

style: str | None

String contained in ./w:pStyle/@val, or None if child is not present.

widowControl_val property writable

widowControl_val

The value of widowControl/@val or None if not present.

CT_Spacing

Bases: BaseOxmlElement

<w:spacing> element, specifying paragraph spacing attributes such as space before and line spacing.

w:beforeLines and w:afterLines are the line-relative counterparts of w:before and w:after, in hundredths of a line. Like the *Chars attributes on w:ind they are not Length values — a line has no fixed height.

CT_TabStop

Bases: BaseOxmlElement

<w:tab> element, representing an individual tab stop.

Overloaded to use for a tab-character in a run, which also uses the w:tab tag but only needs a str method.

CT_TabStops

Bases: BaseOxmlElement

<w:tabs> element, container for a sorted sequence of tab stops.

insert_tab_in_order

insert_tab_in_order(pos, align, leader)

Insert a newly created w:tab child element in pos order.

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

def insert_tab_in_order(self, pos, align, leader):
    """Insert a newly created `w:tab` child element in `pos` order."""
    new_tab = self._new_tab()
    new_tab.pos, new_tab.val, new_tab.leader = pos, align, leader
    for tab in self.tab_lst:
        if new_tab.pos < tab.pos:
            tab.addprevious(new_tab)
            return new_tab
    self.append(new_tab)
    return new_tab