Working with Sections¶
Word supports the notion of a section, a division of a document having the same page layout settings, such as margins and page orientation. This is how, for example, a document can contain some pages in portrait layout and others in landscape.
Most Word documents have only the single section that comes by default and further, most of those have no reason to change the default margins or other page layout. But when you do need to change the page layout, you’ll need to understand sections to get it done.
Access to document sections is provided by the
sections property on the
>>> document = Document() >>> sections = document.sections >>> sections <docx.parts.document.Sections object at 0x1deadbeef> >>> len(sections) 3 >>> section = sections >>> section <docx.section.Section object at 0x1deadbeef> >>> for section in sections: ... print(section.start_type) ... NEW_PAGE (2) EVEN_PAGE (3) ODD_PAGE (4)
It’s theoretically possible for a document not to have any explicit sections,
although I’ve yet to see this occur in the wild. If you’re accessing an
unpredictable population of .docx files you may want to provide for that
possibility using a
len() check or
try block to avoid an uncaught
IndexError exception stopping your program.
Adding a new section¶
Document.add_section() method allows a new section to be started at
the end of the document. Paragraphs and tables added after calling this method
will appear in the new section:
>>> current_section = document.sections[-1] # last section in document >>> current_section.start_type NEW_PAGE (2) >>> new_section = document.add_section(WD_SECTION.ODD_PAGE) >>> new_section.start_type ODD_PAGE (4)
Section object has eleven properties that allow page layout settings to
be discovered and specified.
Section start type¶
Section.start_type describes the type of break that precedes the
>>> section.start_type NEW_PAGE (2) >>> section.start_type = WD_SECTION.ODD_PAGE >>> section.start_type ODD_PAGE (4)
start_type are members of the WD_SECTION_START enumeration.
Page dimensions and orientation¶
Three properties on
Section describe page dimensions and orientation.
Together these can be used, for example, to change the orientation of a section
from portrait to landscape:
>>> section.orientation, section.page_width, section.page_height (PORTRAIT (0), 7772400, 10058400) # (Inches(8.5), Inches(11)) >>> new_width, new_height = section.page_height, section.page_width >>> section.orientation = WD_ORIENT.LANDSCAPE >>> section.page_width = new_width >>> section.page_height = new_height >>> section.orientation, section.page_width, section.page_height (LANDSCAPE (1), 10058400, 7772400)
Seven properties on
Section together specify the various edge spacings that
determine where text appears on the page:
>>> from docx.shared import Inches >>> section.left_margin, section.right_margin (1143000, 1143000) # (Inches(1.25), Inches(1.25)) >>> section.top_margin, section.bottom_margin (914400, 914400) # (Inches(1), Inches(1)) >>> section.gutter 0 >>> section.header_distance, section.footer_distance (457200, 457200) # (Inches(0.5), Inches(0.5)) >>> section.left_margin = Inches(1.5) >>> section.right_margin = Inches(1) >>> section.left_margin, section.right_margin (1371600, 914400)