parfmt

parfmt

Paragraph-related proxy types.

_ParagraphBorders

_ParagraphBorders(parfmt: ParagraphFormat)

Bases: _Borders

The border edges of a paragraph, paragraph_format.borders.

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

def __init__(self, parfmt: ParagraphFormat):
    super().__init__(CT_PBdr.edges)
    self._parfmt = parfmt

ParagraphFormat

ParagraphFormat(
    element: BaseOxmlElement,
    parent: ProvidesXmlPart | None = None,
)

Bases: ElementProxy

Provides access to paragraph formatting such as justification, indentation, line spacing, space before and after, and widow/orphan control.

Source code in src/docx/shared.py

def __init__(self, element: BaseOxmlElement, parent: t.ProvidesXmlPart | None = None):
    self._element = element
    self._parent = parent

alignment property writable

alignment

A member of the WdParagraphAlignment enumeration specifying the justification setting for this paragraph.

A value of None indicates paragraph alignment is inherited from the style hierarchy.

first_line_indent property writable

first_line_indent

Length value specifying the relative difference in indentation for the first line of the paragraph.

A positive value causes the first line to be indented. A negative value produces a hanging indent. None indicates first line indentation is inherited from the style hierarchy.

bidi property writable

bidi: bool | None

True when this paragraph's base direction is right-to-left.

This is the paragraph's reading direction — which edge the text starts from, where the punctuation lands, which way the indents and the list bullet face. Setting Font.rtl on the runs is not a substitute: the runs render right-to-left inside a paragraph still laid out left-to-right, which is subtly rather than obviously wrong.

None indicates the value is inherited, from the section's own bidi and ultimately from the style hierarchy — it does not mean False.

first_line_indent_chars property writable

first_line_indent_chars: int | None

First-line indent in hundredths of a character, or None when not set.

The character-unit counterpart of first_line_indent. Word's paragraph dialogue offers "2 ch" as the first-line indent unit for a CJK document and writes w:firstLineChars="200", often with no twips companion — on such a document first_line_indent is None although Word plainly shows an indent.

The value is in hundredths, matching the XML: 2 characters reads as 200, not 2.0. These are deliberately not Length values, since a character has no fixed size and nothing on Length could express one.

A negative value means a hanging indent, as for first_line_indent. Assigning clears the twips attributes, because Word prefers the character value where both are present and leaving the two disagreeing changes the layout.

left_indent_chars property writable

left_indent_chars: int | None

Left indent in hundredths of a character, or None when not set.

See first_line_indent_chars for the unit. Assigning clears the twips sibling.

right_indent_chars property writable

right_indent_chars: int | None

Right indent in hundredths of a character, or None when not set.

See first_line_indent_chars for the unit. Assigning clears the twips sibling.

space_after_lines property writable

space_after_lines: int | None

Space after the paragraph in hundredths of a line, or None when not set.

The line-relative counterpart of space_after, in the same hundredths unit as first_line_indent_chars — 50 is half a line. Word writes this for a CJK document alongside, or instead of, the twips value.

space_before_lines property writable

space_before_lines: int | None

Space before the paragraph in hundredths of a line, or None when not set.

See space_after_lines.

text_direction property writable

text_direction: WD_TEXT_DIRECTION | None

Flow direction of the text in this paragraph, or None when inherited.

This is the vertical-writing knob, and a different thing from bidi: it says which way the lines run and whether the glyphs are rotated, not which direction the text reads in.

keep_together property writable

keep_together

True if the paragraph should be kept "in one piece" and not broken across a page boundary when the document is rendered.

None indicates its effective value is inherited from the style hierarchy.

keep_with_next property writable

keep_with_next

True if the paragraph should be kept on the same page as the subsequent paragraph when the document is rendered.

For example, this property could be used to keep a section heading on the same page as its first paragraph. None indicates its effective value is inherited from the style hierarchy.

left_indent property writable

left_indent

Length value specifying the space between the left margin and the left side of the paragraph.

None indicates the left indent value is inherited from the style hierarchy. Use an Inches value object as a convenient way to apply indentation in units of inches.

line_spacing property writable

line_spacing

float or Length value specifying the space between baselines in successive lines of the paragraph.

A value of None indicates line spacing is inherited from the style hierarchy. A float value, e.g. 2.0 or 1.75, indicates spacing is applied in multiples of line heights. A Length value such as Pt(12) indicates spacing is a fixed height. The Pt value class is a convenient way to apply line spacing in units of points. Assigning None resets line spacing to inherit from the style hierarchy.

line_spacing_rule property writable

line_spacing_rule

A member of the WdLineSpacing enumeration indicating how the value of line_spacing should be interpreted.

Assigning any of the WdLineSpacing members SINGLE, DOUBLE, or ONE_POINT_FIVE will cause the value of line_spacing to be updated to produce the corresponding line spacing.

outline_level property writable

outline_level: int | None

Outline level of this paragraph, from 0 (top level) to 9.

The outline level drives the document map that navigation panes and PDF bookmarks are built from. Level 9 is Word's "Body Text", meaning the paragraph is deliberately excluded from the outline; None means no level is set here and the effective value is inherited from the style hierarchy.

Setting this does not change how the paragraph is rendered.

shading_fill property writable

shading_fill

Background shading color applied behind the whole paragraph.

An RGBColor value, the string "auto", or None when no shading is applied. Assigning a hex string such as "FF0000" or "#FF0000" is also accepted.

Use Font.shading_fill to shade individual runs instead.

shading_pattern property writable

shading_pattern: WD_SHADING_PATTERN | None

The pattern drawn over the shading behind the whole paragraph.

A WD_SHADING_PATTERN member, or None when no shading is applied. Word writes |WD_SHADING_PATTERN.CLEAR| for an ordinary background color, which is what .shading_fill produces on its own.

Assigning None removes the shading entirely, the same as assigning None to .shading_fill.

shading_color property writable

shading_color

The foreground color of the shading pattern behind this paragraph.

An RGBColor value, the string "auto", or None. This is the color the .shading_pattern is drawn in; .shading_fill is the color behind it. For the usual |WD_SHADING_PATTERN.CLEAR| pattern nothing is drawn and this has no visible effect.

page_break_before property writable

page_break_before

True if the paragraph should appear at the top of the page following the prior paragraph.

None indicates its effective value is inherited from the style hierarchy.

right_indent property writable

right_indent

Length value specifying the space between the right margin and the right side of the paragraph.

None indicates the right indent value is inherited from the style hierarchy. Use a Cm value object as a convenient way to apply indentation in units of centimeters.

space_after property writable

space_after

Length value specifying the spacing to appear between this paragraph and the subsequent paragraph.

None indicates this value is inherited from the style hierarchy. Length objects provide convenience properties, such as pt and inches, that allow easy conversion to various length units.

space_before property writable

space_before

Length value specifying the spacing to appear between this paragraph and the prior paragraph.

None indicates this value is inherited from the style hierarchy. Length objects provide convenience properties, such as pt and cm, that allow easy conversion to various length units.

widow_control property writable

widow_control

True if the first and last lines in the paragraph remain on the same page as the rest of the paragraph when Word repaginates the document.

None indicates its effective value is inherited from the style hierarchy.

borders

borders() -> _ParagraphBorders

The border edges of this paragraph, as a mapping keyed by edge name:

paragraph.paragraph_format.borders["bottom"].line = WD_LINE_STYLE.SINGLE

A paragraph with only a bottom border and no text is how Word draws a horizontal rule; there is no other way to draw one.

Beyond the four sides, a paragraph admits two edges a table does not. between is the border drawn between consecutive paragraphs that share identical border settings, rather than an edge of any one paragraph, and bar is the vertical bar drawn beside it.

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

@lazyproperty
def borders(self) -> _ParagraphBorders:
    """The border edges of this paragraph, as a mapping keyed by edge name::

        paragraph.paragraph_format.borders["bottom"].line = WD_LINE_STYLE.SINGLE

    A paragraph with only a bottom border and no text is how Word draws a horizontal
    rule; there is no other way to draw one.

    Beyond the four sides, a paragraph admits two edges a table does not. `between`
    is the border drawn *between* consecutive paragraphs that share identical border
    settings, rather than an edge of any one paragraph, and `bar` is the vertical bar
    drawn beside it.
    """
    return _ParagraphBorders(self)

mark_font

mark_font() -> Font

The run properties of the paragraph mark — the ¶ itself.

These are neither the properties of any run in the paragraph nor the paragraph's style: they are the formatting of the mark character, stored in w:pPr/w:rPr:

paragraph.paragraph_format.mark_font.size = Pt(8)

It matters more than it sounds. The mark's font size participates in the line height of the paragraph's last line, so a paragraph whose runs are all 8pt but whose mark is 24pt renders with a tall final line. An empty paragraph has no runs at all, so the mark's properties are the only place its formatting lives — the height of a blank spacer paragraph is not expressible any other way. And assigning Paragraph.text discards the runs and rebuilds them while the mark's properties survive, which can leave a rewritten paragraph looking wrong.

Named mark_font rather than font because "the paragraph's font" reads as the font of the paragraph's text, which this is not.

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

@lazyproperty
def mark_font(self) -> Font:
    """The run properties of the paragraph mark — the ¶ itself.

    These are neither the properties of any run in the paragraph nor the paragraph's
    style: they are the formatting of the mark character, stored in `w:pPr/w:rPr`::

        paragraph.paragraph_format.mark_font.size = Pt(8)

    It matters more than it sounds. The mark's font size participates in the line
    height of the paragraph's last line, so a paragraph whose runs are all 8pt but
    whose mark is 24pt renders with a tall final line. An empty paragraph has no runs
    at all, so the mark's properties are the only place its formatting lives — the
    height of a blank spacer paragraph is not expressible any other way. And
    assigning `Paragraph.text` discards the runs and rebuilds them while the mark's
    properties survive, which can leave a rewritten paragraph looking wrong.

    Named `mark_font` rather than `font` because "the paragraph's font" reads as the
    font of the paragraph's text, which this is not.
    """
    return Font(self._element.get_or_add_pPr())  # pyright: ignore[reportArgumentType]

tab_stops

tab_stops()

TabStops object providing access to the tab stops defined for this paragraph format.

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

@lazyproperty
def tab_stops(self):
    """|TabStops| object providing access to the tab stops defined for this
    paragraph format."""
    pPr = self._element.get_or_add_pPr()
    return TabStops(pPr)