Word supports page headers and page footers. A page header is text that appears in the top margin area of each page, separated from the main body of text, and usually conveying context information, such as the document title, author, creation date, or the page number. The page headers in a document are the same from page to page, with only small differences in content, such as a changing section title or page number. A page header is also known as a running head.
A page footer is analogous in every way to a page header except that it appears at the bottom of a page. It should not be confused with a footnote, which is not uniform between pages. For brevity’s sake, the term header is often used here to refer to what may be either a header or footer object, trusting the reader to understand its applicability to both object types.
Headers and footers are linked to a section; this allows each section to have a distinct header and/or footer. For example, a landscape section might have a wider header than a portrait section.
Each section object has a .header property providing access to a _Header object for that section:
>>> document = Document()
>>> section = document.sections[0]
>>> header = section.header
>>> header
<docx.section._Header object at 0x...>
A _Header object is always present on Section.header, even when no header is defined for that section. The presence of an actual header definition is indicated by _Header.is_linked_to_previous:
>>> header.is_linked_to_previous
True
A value of True indicates the _Header object contains no header definition and the section will display the same header as the previous section. This “inheritance” behavior is recursive, such that a “linked” header actually gets its definition from the first prior section having a header definition. This “linked” state is indicated as “Same as previous” in the Word UI.
A new document does not have a header (on the single section it contains) and so .is_linked_to_previous is True in that case. Note this case may be a bit counterintuitive in that there is no previous section header to link to. In this “no previous header” case, no header is displayed.
A header can be added to a new document simply by editing the content of the _Header object. A _Header object is a “story” container and its content is edited just like a Document object. Note that like a new document, a new header already contains a single (empty) paragraph:
>>> paragraph = header.paragraphs[0]
>>> paragraph.text = "Title of my document"
Note also that the act of adding content (or even just accessing header.paragraphs) added a header definition and changed the state of .is_linked_to_previous:
>>> header.is_linked_to_previous
False
A header with multiple “zones” is often accomplished using carefully placed tab stops.
The required tab-stops for a center and right-aligned “zone” are part of the Header and Footer styles in Word. If you’re using a custom template rather than the python-docx default, it probably makes sense to define that style in your template.
Inserted tab characters ("\t") are used to separate left, center, and right-aligned header content:
>>> paragraph = header.paragraphs[0]
>>> paragraph.text = "Left Text\tCenter Text\tRight Text"
>>> paragraph.style = document.styles["Header"]
The Header style is automatically applied to a new header, so the third line just above (applying the Header style) is unnecessary in this case, but included here to illustrate the general case.
An unwanted header can be removed by assigning True to its .is_linked_to_previous attribute:
>>> header.is_linked_to_previous = True
>>> header.is_linked_to_previous
True
The content for a header is irreversably deleted when True is assigned to .is_linked_to_previous.
The “just start editing” approach works fine for the simple case, but to make sense of header behaviors in a multi-section document, a few simple concepts will be helpful. Here they are in a nutshell:
An explicit header definition can be given to a section that lacks one by assigning False to its .is_linked_to_previous property:
>>> header.is_linked_to_previous
True
>>> header.is_linked_to_previous = False
>>> header.is_linked_to_previous
False
The newly added header definition contains a single empty paragraph. Note that leaving the header this way is occasionally useful as it effectively “turns-off” a header for that section and those after it until the next section with a defined header.
Assigning False to .is_linked_to_previous on a header that already has a header definition does nothing.
Editing the content of a header edits the content of the source header, taking into account any “inheritance”. So for example, if the section 2 header inherits from section 1 and you edit the section 2 header, you actually change the contents of the section 1 header. A new header definition is not added for section 2 unless you first explicitly assign False to its .is_linked_to_previous property.
Enter search terms or a module, class or function name.