Section objects

Provides access to section properties such as margins and page orientation.

Sections objects

class docx.section.Sections(document_elm, document_part)

Sequence of Section objects corresponding to the sections in the document.

Supports len(), iteration, and indexed access.

Section objects

class docx.section.Section(sectPr, document_part)

Document section, providing access to section and page setup settings.

Also provides access to headers and footers.

property bottom_margin

Length object representing the bottom margin for all pages in this section in English Metric Units.

property different_first_page_header_footer

True if this section displays a distinct first-page header and footer.

Read/write. The definition of the first-page header and footer are accessed using first_page_header and first_page_footer respectively.

property even_page_footer

_Footer object defining footer content for even pages.

The content of this footer definition is ignored unless the document setting odd_and_even_pages_header_footer is set True.

property even_page_header

_Header object defining header content for even pages.

The content of this header definition is ignored unless the document setting odd_and_even_pages_header_footer is set True.

property first_page_footer

_Footer object defining footer content for the first page of this section.

The content of this footer definition is ignored unless the property different_first_page_header_footer is set True.

property first_page_header

_Header object defining header content for the first page of this section.

The content of this header definition is ignored unless the property different_first_page_header_footer is set True.

property footer

_Footer object representing default page footer for this section.

The default footer is used for odd-numbered pages when separate odd/even footers are enabled. It is used for both odd and even-numbered pages otherwise.

property footer_distance

Length object representing the distance from the bottom edge of the page to the bottom edge of the footer. None if no setting is present in the XML.

property gutter

Length object representing the page gutter size in English Metric Units for all pages in this section. The page gutter is extra spacing added to the inner margin to ensure even margins after page binding.

property header

_Header object representing default page header for this section.

The default header is used for odd-numbered pages when separate odd/even headers are enabled. It is used for both odd and even-numbered pages otherwise.

property header_distance

Length object representing the distance from the top edge of the page to the top edge of the header. None if no setting is present in the XML.

property left_margin

Length object representing the left margin for all pages in this section in English Metric Units.

property orientation

Member of the WD_ORIENTATION enumeration specifying the page orientation for this section, one of WD_ORIENT.PORTRAIT or WD_ORIENT.LANDSCAPE.

property page_height

Total page height used for this section, inclusive of all edge spacing values such as margins. Page orientation is taken into account, so for example, its expected value would be Inches(8.5) for letter-sized paper when orientation is landscape.

property page_width

Total page width used for this section, inclusive of all edge spacing values such as margins. Page orientation is taken into account, so for example, its expected value would be Inches(11) for letter-sized paper when orientation is landscape.

property right_margin

Length object representing the right margin for all pages in this section in English Metric Units.

property start_type

The member of the WD_SECTION_START enumeration corresponding to the initial break behavior of this section, e.g. WD_SECTION.ODD_PAGE if the section should begin on the next odd page.

property top_margin

Length object representing the top margin for all pages in this section in English Metric Units.

_Header and _Footer objects

class docx.section._Header

Page header, used for all three types (default, even-page, and first-page).

Note that, like a document or table cell, a header must contain a minimum of one paragraph and a new or otherwise “empty” header contains a single empty paragraph. This first paragraph can be accessed as header.paragraphs[0] for purposes of adding content to it. Using add_paragraph() by itself to add content will leave an empty paragraph above the newly added one.

add_paragraph(text='', style=None)

Return a paragraph newly added to the end of the content in this container, having text in a single run if present, and having paragraph style style. If style is None, no paragraph style is applied, which has the same effect as applying the ‘Normal’ style.

add_table(rows, cols, width)

Return a table of width having rows rows and cols columns, newly appended to the content in this container. width is evenly distributed between the table columns.

property is_linked_to_previous

True if this header/footer uses the definition from the prior section.

False if this header/footer has an explicit definition.

Assigning True to this property removes the header/footer definition for this section, causing it to “inherit” the corresponding definition of the prior section. Assigning False causes a new, empty definition to be added for this section, but only if no definition is already present.

property paragraphs

A list containing the paragraphs in this container, in document order. Read-only.

property tables

A list containing the tables in this container, in document order. Read-only.

class docx.section._Footer

Page footer, used for all three types (default, even-page, and first-page).

Note that, like a document or table cell, a footer must contain a minimum of one paragraph and a new or otherwise “empty” footer contains a single empty paragraph. This first paragraph can be accessed as footer.paragraphs[0] for purposes of adding content to it. Using add_paragraph() by itself to add content will leave an empty paragraph above the newly added one.

add_paragraph(text='', style=None)

Return a paragraph newly added to the end of the content in this container, having text in a single run if present, and having paragraph style style. If style is None, no paragraph style is applied, which has the same effect as applying the ‘Normal’ style.

add_table(rows, cols, width)

Return a table of width having rows rows and cols columns, newly appended to the content in this container. width is evenly distributed between the table columns.

property is_linked_to_previous

True if this header/footer uses the definition from the prior section.

False if this header/footer has an explicit definition.

Assigning True to this property removes the header/footer definition for this section, causing it to “inherit” the corresponding definition of the prior section. Assigning False causes a new, empty definition to be added for this section, but only if no definition is already present.

property paragraphs

A list containing the paragraphs in this container, in document order. Read-only.

property tables

A list containing the tables in this container, in document order. Read-only.