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.

bottom_margin

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

left_margin

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

orientation

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

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.

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.

right_margin

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

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.

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=u'', 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.

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.

paragraphs

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

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=u'', 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.

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.

paragraphs

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

tables

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