doc: Document.add_section() strips hdr/ftr refs

scanny · scanny · commit 5a310348c1b5 · 2019-01-06T14:26:12.000-08:00
The implementation of `Document.add_section()` "clones" the previously
last `w:sectPr` element to produce the `w:sectPr` for the new section.
This has the effect of duplicating the header and footer references
along with the rIds used to link them to their header or footer part.

There have been no reports that this causes a problem, but in any case
the correct behavior is to add a new section without any header or
footer definitions, such that the new section "inherits" all
header/footer definitions (and header/footer parts are not "reused").

Add code to remove all `w:headerReference` and `w:footerReference`
elements from a "cloned" `w:sectPr` element when adding a section.
diff --git a/docx/oxml/document.py b/docx/oxml/document.py
@@ -33,17 +33,25 @@ class CT_Body(BaseOxmlElement):
     sectPr = ZeroOrOne('w:sectPr', successors=())
 
     def add_section_break(self):
+        """Return `w:sectPr` element for new section added at end of document.
+
+        The last `w:sectPr` becomes the second-to-last, with the new `w:sectPr` being an
+        exact clone of the previous one, except that all header and footer references
+        are removed (and are therefore now "inherited" from the prior section).
+
+        A copy of the previously-last `w:sectPr` will now appear in a new `w:p` at the
+        end of the document. The returned `w:sectPr` is the sentinel `w:sectPr` for the
+        document (and as implemented, *is* the prior sentinel `w:sectPr` with headers
+        and footers removed).
         """
-        Return the current ``<w:sectPr>`` element after adding a clone of it
-        in a new ``<w:p>`` element appended to the block content elements.
-        Note that the "current" ``<w:sectPr>`` will always be the sentinel
-        sectPr in this case since we're always working at the end of the
-        block content.
-        """
+        # ---get the sectPr at file-end, which controls last section (sections[-1])---
         sentinel_sectPr = self.get_or_add_sectPr()
-        cloned_sectPr = sentinel_sectPr.clone()
-        p = self.add_p()
-        p.set_sectPr(cloned_sectPr)
+        # ---add exact copy to new `w:p` element; that is now second-to last section---
+        self.add_p().set_sectPr(sentinel_sectPr.clone())
+        # ---remove any header or footer references from "new" last section---
+        for hdrftr_ref in sentinel_sectPr.xpath("w:headerReference|w:footerReference"):
+            sentinel_sectPr.remove(hdrftr_ref)
+        # ---the sentinel `w:sectPr` now controls the new last section---
         return sentinel_sectPr
 
     def clear_content(self):
diff --git a/features/doc-add-section.feature b/features/doc-add-section.feature
@@ -11,3 +11,14 @@ Feature: Add a document section
       Then the document has two sections
        And the first section is portrait
        And the second section is landscape
+
+
+  Scenario: Document.add_section() adds a section that inherits headers and footers
+    Given a single-section Document object with headers and footers as document
+     When I execute section = document.add_section()
+     Then section.header.is_linked_to_previous is True
+      And section.even_page_header.is_linked_to_previous is True
+      And section.first_page_header.is_linked_to_previous is True
+      And section.footer.is_linked_to_previous is True
+      And section.even_page_footer.is_linked_to_previous is True
+      And section.first_page_footer.is_linked_to_previous is True
diff --git a/features/steps/document.py b/features/steps/document.py
@@ -59,6 +59,11 @@ def given_a_single_section_document_having_portrait_layout(context):
     context.original_dimensions = (section.page_width, section.page_height)
 
 
+@given("a single-section Document object with headers and footers as document")
+def given_a_single_section_Document_object_with_headers_and_footers(context):
+    context.document = Document(test_docx("doc-add-section"))
+
+
 # when ====================================================
 
 @when('I add a 2 x 2 table specifying only row and column count')
@@ -160,6 +165,11 @@ def when_I_change_the_new_section_layout_to_landscape(context):
     section.page_height = new_height
 
 
+@when("I execute section = document.add_section()")
+def when_I_execute_section_eq_document_add_section(context):
+    context.section = context.document.add_section()
+
+
 # then ====================================================
 
 @then('document.inline_shapes is an InlineShapes object')
diff --git a/features/steps/section.py b/features/steps/section.py
@@ -204,6 +204,15 @@ def then_section_header_is_a_Header_object(context):
     assert actual == expected, "section.header is a %s object" % actual
 
 
+@then("section.{propname}.is_linked_to_previous is True")
+def then_section_hdrftr_prop_is_linked_to_previous_is_True(context, propname):
+    actual = getattr(context.section, propname).is_linked_to_previous
+    expected = True
+    assert actual == expected, (
+        "section.%s.is_linked_to_previous is %s" % (propname, actual)
+    )
+
+
 @then('the reported {margin_side} margin is {inches} inches')
 def then_the_reported_margin_is_inches(context, margin_side, inches):
     prop_name = {
diff --git a/features/steps/test_files/doc-add-section.docx b/features/steps/test_files/doc-add-section.docx
