WordprocessingML supports a variety of paragraph formatting attributes to control layout characteristics such as justification, indentation, line spacing, space before and after, and widow/orphan control.
In Word, each paragraph has an alignment attribute that specifies how to justify the lines of the paragraph when the paragraph is laid out on the page. Common values are left, right, centered, and justified.
Getting and setting paragraph alignment:
>>> paragraph = body.add_paragraph()
>>> paragraph.alignment
None
>>> paragraph.alignment = WD_ALIGN_PARAGRAPH.RIGHT
>>> paragraph.alignment
RIGHT (2)
>>> paragraph.alignment = None
>>> paragraph.alignment
None
If the <w:jc> element is not present on a paragraph, the alignment value for that paragraph is inherited from its style hierarchy. If the element is present, its value overrides any inherited value. From the API, a value of None on the Paragraph.alignment property corresponds to no <w:jc> element being present. If None is assigned to Paragraph.alignment, the <w:jc> element is removed.
Spacing between subsequent paragraphs is controlled by the paragraph spacing attributes. Spacing can be applied either before the paragraph, after it, or both. The concept is similar to that of padding or margin in CSS. WordprocessingML supports paragraph spacing specified as either a length value or as a multiple of the line height; however only a length value is supported via the Word UI. Inter-paragraph spacing “overlaps”, such that the rendered spacing between two paragraphs is the maximum of the space after the first paragraph and the space before the second.
Getting and setting paragraph spacing:
>>> paragraph_format = document.styles['Normal'].paragraph_format
>>> paragraph_format.space_before
None
>>> paragraph_format.space_before = Pt(12)
>>> paragraph_format.space_before.pt
12.0
Line spacing can be specified either as a specific length or as a multiple of the line height (font size). Line spacing is specified by the combination of values in w:spacing/@w:line and w:spacing/@w:lineRule. The ParagraphFormat.line_spacing property determines which method to use based on whether the assigned value is an instance of Length.
Getting and setting line spacing:
>>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule
(None, None)
>>> paragraph_format.line_spacing = Pt(18)
>>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule
(228600, WD_LINE_SPACING.EXACTLY (4))
>>> paragraph_format.line_spacing = 1
>>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule
(152400, WD_LINE_SPACING.SINGLE (0))
>>> paragraph_format.line_spacing = 0.9
>>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule
(137160, WD_LINE_SPACING.MULTIPLE (5))
14 points:
<w:pPr>
<w:spacing w:line="280"/>
</w:pPr>
double-spaced:
<w:pPr>
<w:spacing w:line="480" w:lineRule="exact"/>
</w:pPr>
Paragraph indentation is specified using the w:pPr/w:ind element. Left, right, first line, and hanging indent can be specified. Indentation can be specified as a length or in hundredths of a character width. Only length is supported by python-docx. Both first line indent and hanging indent are specified using the ParagraphFormat.first_line_indent property. Assigning a positive value produces an indented first line. A negative value produces a hanging indent.
Getting and setting indentation:
>>> paragraph_format.left_indent
None
>>> paragraph_format.right_indent
None
>>> paragraph_format.first_line_indent
None
>>> paragraph_format.left_indent = Pt(36)
>>> paragraph_format.left_indent.pt
36.0
>>> paragraph_format.right_indent = Inches(0.25)
>>> paragraph_format.right_indent.pt
18.0
>>> paragraph_format.first_line_indent = Pt(-18)
>>> paragraph_format.first_line_indent.pt
-18.0
1 inch left, 0.5 inch (additional) first line, 0.5 inch right:
<w:pPr>
<w:ind w:start="1440" w:end="720" w:firstLine="720"/>
</w:pPr>
0.5 inch left, 0.5 inch hanging indent:
<w:pPr>
<w:ind w:start="720" w:hanging="720"/>
</w:pPr>
There are a handful of page placement properties that control such things as keeping the lines of a paragraph together on the same page, keeing a paragraph (such as a heading) on the same page as the subsequent paragraph, and placing the paragraph at the top of a new page. Each of these are tri-state boolean properties where None indicates “inherit”.
Getting and setting indentation:
>>> paragraph_format.keep_with_next
None
>>> paragraph_format.keep_together
None
>>> paragraph_format.page_break_before
None
>>> paragraph_format.widow_control
None
>>> paragraph_format.keep_with_next = True
>>> paragraph_format.keep_with_next
True
>>> paragraph_format.keep_together = False
>>> paragraph_format.keep_together
False
>>> paragraph_format.page_break_before = True
>>> paragraph_format.widow_control = None
keep with next, keep together, no page break before, and widow/orphan control:
<w:pPr>
<w:keepNext/>
<w:keepLines/>
<w:pageBreakBefore w:val="0"/>
<w:widowControl/>
</w:pPr>
A paragraph with inherited alignment:
<w:p>
<w:r>
<w:t>Inherited paragraph alignment.</w:t>
</w:r>
</w:p>
A right-aligned paragraph:
<w:p>
<w:pPr>
<w:jc w:val="right"/>
</w:pPr>
<w:r>
<w:t>Right-aligned paragraph.</w:t>
</w:r>
</w:p>
<xsd:complexType name="CT_PPr"> <!-- denormalized -->
<xsd:sequence>
<xsd:element name="pStyle" type="CT_String" minOccurs="0"/>
<xsd:element name="keepNext" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="keepLines" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="pageBreakBefore" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="framePr" type="CT_FramePr" minOccurs="0"/>
<xsd:element name="widowControl" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="numPr" type="CT_NumPr" minOccurs="0"/>
<xsd:element name="suppressLineNumbers" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="pBdr" type="CT_PBdr" minOccurs="0"/>
<xsd:element name="shd" type="CT_Shd" minOccurs="0"/>
<xsd:element name="tabs" type="CT_Tabs" minOccurs="0"/>
<xsd:element name="suppressAutoHyphens" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="kinsoku" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="wordWrap" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="overflowPunct" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="topLinePunct" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="autoSpaceDE" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="autoSpaceDN" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="bidi" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="adjustRightInd" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="snapToGrid" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="spacing" type="CT_Spacing" minOccurs="0"/>
<xsd:element name="ind" type="CT_Ind" minOccurs="0"/>
<xsd:element name="contextualSpacing" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="mirrorIndents" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="suppressOverlap" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="jc" type="CT_Jc" minOccurs="0"/>
<xsd:element name="textDirection" type="CT_TextDirection" minOccurs="0"/>
<xsd:element name="textAlignment" type="CT_TextAlignment" minOccurs="0"/>
<xsd:element name="textboxTightWrap" type="CT_TextboxTightWrap" minOccurs="0"/>
<xsd:element name="outlineLvl" type="CT_DecimalNumber" minOccurs="0"/>
<xsd:element name="divId" type="CT_DecimalNumber" minOccurs="0"/>
<xsd:element name="cnfStyle" type="CT_Cnf" minOccurs="0"/>
<xsd:element name="rPr" type="CT_ParaRPr" minOccurs="0"/>
<xsd:element name="sectPr" type="CT_SectPr" minOccurs="0"/>
<xsd:element name="pPrChange" type="CT_PPrChange" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="CT_FramePr">
<xsd:attribute name="dropCap" type="ST_DropCap"/>
<xsd:attribute name="lines" type="ST_DecimalNumber"/>
<xsd:attribute name="w" type="s:ST_TwipsMeasure"/>
<xsd:attribute name="h" type="s:ST_TwipsMeasure"/>
<xsd:attribute name="vSpace" type="s:ST_TwipsMeasure"/>
<xsd:attribute name="hSpace" type="s:ST_TwipsMeasure"/>
<xsd:attribute name="wrap" type="ST_Wrap"/>
<xsd:attribute name="hAnchor" type="ST_HAnchor"/>
<xsd:attribute name="vAnchor" type="ST_VAnchor"/>
<xsd:attribute name="x" type="ST_SignedTwipsMeasure"/>
<xsd:attribute name="xAlign" type="s:ST_XAlign"/>
<xsd:attribute name="y" type="ST_SignedTwipsMeasure"/>
<xsd:attribute name="yAlign" type="s:ST_YAlign"/>
<xsd:attribute name="hRule" type="ST_HeightRule"/>
<xsd:attribute name="anchorLock" type="s:ST_OnOff"/>
</xsd:complexType>
<xsd:complexType name="CT_Ind">
<xsd:attribute name="start" type="ST_SignedTwipsMeasure"/>
<xsd:attribute name="startChars" type="ST_DecimalNumber"/>
<xsd:attribute name="end" type="ST_SignedTwipsMeasure"/>
<xsd:attribute name="endChars" type="ST_DecimalNumber"/>
<xsd:attribute name="left" type="ST_SignedTwipsMeasure"/>
<xsd:attribute name="leftChars" type="ST_DecimalNumber"/>
<xsd:attribute name="right" type="ST_SignedTwipsMeasure"/>
<xsd:attribute name="rightChars" type="ST_DecimalNumber"/>
<xsd:attribute name="hanging" type="s:ST_TwipsMeasure"/>
<xsd:attribute name="hangingChars" type="ST_DecimalNumber"/>
<xsd:attribute name="firstLine" type="s:ST_TwipsMeasure"/>
<xsd:attribute name="firstLineChars" type="ST_DecimalNumber"/>
</xsd:complexType>
<xsd:complexType name="CT_Jc">
<xsd:attribute name="val" type="ST_Jc" use="required"/>
</xsd:complexType>
<xsd:complexType name="CT_OnOff">
<xsd:attribute name="val" type="s:ST_OnOff"/>
</xsd:complexType>
<xsd:complexType name="CT_Spacing">
<xsd:attribute name="before" type="s:ST_TwipsMeasure"/>
<xsd:attribute name="beforeLines" type="ST_DecimalNumber"/>
<xsd:attribute name="beforeAutospacing" type="s:ST_OnOff"/>
<xsd:attribute name="after" type="s:ST_TwipsMeasure"/>
<xsd:attribute name="afterLines" type="ST_DecimalNumber"/>
<xsd:attribute name="afterAutospacing" type="s:ST_OnOff"/>
<xsd:attribute name="line" type="ST_SignedTwipsMeasure"/>
<xsd:attribute name="lineRule" type="ST_LineSpacingRule"/>
</xsd:complexType>
<xsd:complexType name="CT_String">
<xsd:attribute name="val" type="s:ST_String" use="required"/>
</xsd:complexType>
<xsd:complexType name="CT_Tabs">
<xsd:sequence>
<xsd:element name="tab" type="CT_TabStop" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<!-- simple types -->
<xsd:simpleType name="ST_Jc">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="start"/>
<xsd:enumeration value="center"/>
<xsd:enumeration value="end"/>
<xsd:enumeration value="both"/>
<xsd:enumeration value="mediumKashida"/>
<xsd:enumeration value="distribute"/>
<xsd:enumeration value="numTab"/>
<xsd:enumeration value="highKashida"/>
<xsd:enumeration value="lowKashida"/>
<xsd:enumeration value="thaiDistribute"/>
<xsd:enumeration value="left"/>
<xsd:enumeration value="right"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ST_LineSpacingRule">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="auto"/> <!-- default -->
<xsd:enumeration value="exact"/>
<xsd:enumeration value="atLeast"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ST_OnOff">
<xsd:union memberTypes="xsd:boolean ST_OnOff1"/>
</xsd:simpleType>
<xsd:simpleType name="ST_OnOff1">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="on"/>
<xsd:enumeration value="off"/>
</xsd:restriction>
</xsd:simpleType>