hdr: add _BaseHeaderFooter._get_or_add_definition()

Author: scanny

docx/section.py

@@ -247,6 +247,11 @@ def _add_definition(self):
         """Return newly-added header/footer part."""
         raise NotImplementedError("must be implemented by each subclass")
 
+    @property
+    def _definition(self):
+        """|HeaderPart| or |FooterPart| object containing header/footer content."""
+        raise NotImplementedError("must be implemented by each subclass")
+
     def _drop_definition(self):
         """Remove header/footer part containing the definition of this header/footer."""
         raise NotImplementedError("must be implemented by each subclass")
@@ -260,16 +265,35 @@ def _get_or_add_definition(self):
         """Return HeaderPart or FooterPart object for this section.
 
         If this header/footer inherits its content, the part for the prior header/footer
-        is returned. If the definition cannot be inherited (it belongs to the first
-        section), a new definition is added and then returned.
+        is returned; this process continue recursively until a definition is found. If
+        the definition cannot be inherited (because the header/footer belongs to the
+        first section), a new definition is added for that first section and then
+        returned.
         """
-        raise NotImplementedError
+        # ---note this method is called recursively to access inherited definitions---
+        # ---case-1: definition is not inherited---
+        if self._has_definition:
+            return self._definition
+        # ---case-2: definition is inherited and belongs to second-or-later section---
+        prior_headerfooter = self._prior_headerfooter
+        if prior_headerfooter:
+            return prior_headerfooter._get_or_add_definition()
+        # ---case-3: definition is inherited, but belongs to first section---
+        return self._add_definition()
 
     @property
     def _has_definition(self):
         """True if this header/footer has a related part containing its definition."""
         raise NotImplementedError("must be implemented by each subclass")
 
+    @property
+    def _prior_headerfooter(self):
+        """|_Header| or |_Footer| proxy on prior sectPr element.
+
+        Returns None if this is first section.
+        """
+        raise NotImplementedError("must be implemented by each subclass")
+
 
 class _Footer(_BaseHeaderFooter):
     """Page footer."""
@@ -301,44 +325,25 @@ def _add_definition(self):
         self._sectPr.add_headerReference(WD_HEADER_FOOTER.PRIMARY, rId)
         return header_part
 
+    @property
+    def _definition(self):
+        """|HeaderPart| object containing content of this header."""
+        headerReference = self._sectPr.get_headerReference(WD_HEADER_FOOTER.PRIMARY)
+        return self._document_part.header_part(headerReference.rId)
+
     def _drop_definition(self):
         """Remove header definition associated with this section."""
         rId = self._sectPr.remove_headerReference(WD_HEADER_FOOTER.PRIMARY)
         self._document_part.drop_header_part(rId)
 
-    def _get_or_add_definition(self):
-        """Return |HeaderPart| object for this header.
-
-        If this header inherits its content, the header part for the prior header is
-        returned; this process continue recursively until a header is found. If this
-        header cannot inherit (it belongs to the first section), a new header part is
-        created for the first section and returned.
-        """
-        # ---note this method is called recursively to access inherited headers---
-        # ---case-1: header does not inherit---
-        if self._has_definition:
-            return self._header_part
-        prior_header = self._prior_header
-        # ---case-2: header inherits and belongs to second-or-later section---
-        if prior_header is not None:
-            return prior_header._get_or_add_definition()
-        # ---case-3: header inherits, but is first header---
-        return self._add_definition()
-
     @property
     def _has_definition(self):
         """True if a header is explicitly defined for this section."""
         headerReference = self._sectPr.get_headerReference(WD_HEADER_FOOTER.PRIMARY)
         return False if headerReference is None else True
 
     @property
-    def _header_part(self):
-        """|HeaderPart| object containing content of this header."""
-        headerReference = self._sectPr.get_headerReference(WD_HEADER_FOOTER.PRIMARY)
-        return self._document_part.header_part(headerReference.rId)
-
-    @property
-    def _prior_header(self):
+    def _prior_headerfooter(self):
         """|_Header| proxy on prior sectPr element or None if this is first section."""
         preceding_sectPr = self._sectPr.preceding_sectPr
         return (

tests/test_section.py

@@ -400,6 +400,51 @@ def it_provides_access_to_the_hdr_or_ftr_element_to_help(
         _get_or_add_definition_.assert_called_once_with(header)
         assert hdr_elm is hdr
 
+    def it_gets_the_definition_when_it_has_one(
+        self, _has_definition_prop_, _definition_prop_, header_part_
+    ):
+        _has_definition_prop_.return_value = True
+        _definition_prop_.return_value = header_part_
+        header = _BaseHeaderFooter(None, None)
+
+        header_part = header._get_or_add_definition()
+
+        assert header_part is header_part_
+
+    def but_it_gets_the_prior_definition_when_it_is_linked(
+        self,
+        _has_definition_prop_,
+        _prior_headerfooter_prop_,
+        prior_headerfooter_,
+        header_part_,
+    ):
+        _has_definition_prop_.return_value = False
+        _prior_headerfooter_prop_.return_value = prior_headerfooter_
+        prior_headerfooter_._get_or_add_definition.return_value = header_part_
+        header = _BaseHeaderFooter(None, None)
+
+        header_part = header._get_or_add_definition()
+
+        prior_headerfooter_._get_or_add_definition.assert_called_once_with()
+        assert header_part is header_part_
+
+    def and_it_adds_a_definition_when_it_is_linked_and_the_first_section(
+        self,
+        _has_definition_prop_,
+        _prior_headerfooter_prop_,
+        _add_definition_,
+        header_part_
+    ):
+        _has_definition_prop_.return_value = False
+        _prior_headerfooter_prop_.return_value = None
+        _add_definition_.return_value = header_part_
+        header = _BaseHeaderFooter(None, None)
+
+        header_part = header._get_or_add_definition()
+
+        _add_definition_.assert_called_once_with(header)
+        assert header_part is header_part_
+
     # fixtures -------------------------------------------------------
 
     @pytest.fixture(params=[(False, True), (True, False)])
@@ -425,6 +470,10 @@ def is_linked_set_fixture(self, request):
     def _add_definition_(self, request):
         return method_mock(request, _BaseHeaderFooter, "_add_definition")
 
+    @pytest.fixture
+    def _definition_prop_(self, request):
+        return property_mock(request, _BaseHeaderFooter, "_definition")
+
     @pytest.fixture
     def _drop_definition_(self, request):
         return method_mock(request, _BaseHeaderFooter, "_drop_definition")
@@ -441,6 +490,14 @@ def _has_definition_prop_(self, request):
     def header_part_(self, request):
         return instance_mock(request, HeaderPart)
 
+    @pytest.fixture
+    def prior_headerfooter_(self, request):
+        return instance_mock(request, _BaseHeaderFooter)
+
+    @pytest.fixture
+    def _prior_headerfooter_prop_(self, request):
+        return property_mock(request, _BaseHeaderFooter, "_prior_headerfooter")
+
 
 class Describe_Footer(object):
 
@@ -512,6 +569,18 @@ def it_can_add_a_header_part_to_help(self, document_part_, header_part_):
         )
         assert header_part is header_part_
 
+    def it_provides_access_to_its_header_part_to_help(
+        self, document_part_, header_part_
+    ):
+        sectPr = element("w:sectPr/w:headerReference{w:type=default,r:id=rId8}")
+        document_part_.header_part.return_value = header_part_
+        header = _Header(sectPr, document_part_)
+
+        header_part = header._definition
+
+        document_part_.header_part.assert_called_once_with("rId8")
+        assert header_part is header_part_
+
     def it_can_drop_the_related_header_part_to_help(self, document_part_):
         sectPr = element("w:sectPr{r:a=b}/w:headerReference{w:type=default,r:id=rId42}")
         header = _Header(sectPr, document_part_)
@@ -521,47 +590,6 @@ def it_can_drop_the_related_header_part_to_help(self, document_part_):
         assert sectPr.xml == xml("w:sectPr{r:a=b}")
         document_part_.drop_header_part.assert_called_once_with("rId42")
 
-    def it_gets_the_header_part_when_it_has_one(
-        self, _has_definition_prop_, _header_part_prop_, header_part_
-    ):
-        _has_definition_prop_.return_value = True
-        _header_part_prop_.return_value = header_part_
-        header = _Header(None, None)
-
-        header_part = header._get_or_add_definition()
-
-        assert header_part is header_part_
-
-    def but_it_gets_the_prior_header_part_when_it_is_linked(
-        self, _has_definition_prop_, _prior_header_prop_, prior_header_, header_part_
-    ):
-        _has_definition_prop_.return_value = False
-        _prior_header_prop_.return_value = prior_header_
-        prior_header_._get_or_add_definition.return_value = header_part_
-        header = _Header(None, None)
-
-        header_part = header._get_or_add_definition()
-
-        prior_header_._get_or_add_definition.assert_called_once_with()
-        assert header_part is header_part_
-
-    def and_it_adds_the_header_part_when_it_is_linked_and_the_first_section(
-        self,
-        _has_definition_prop_,
-        _prior_header_prop_,
-        _add_definition_,
-        header_part_
-    ):
-        _has_definition_prop_.return_value = False
-        _prior_header_prop_.return_value = None
-        _add_definition_.return_value = header_part_
-        header = _Header(None, None)
-
-        header_part = header._get_or_add_definition()
-
-        _add_definition_.assert_called_once_with(header)
-        assert header_part is header_part_
-
     def it_knows_when_it_has_a_header_part_to_help(self, has_definition_fixture):
         sectPr, expected_value = has_definition_fixture
         header = _Header(sectPr, None)
@@ -570,18 +598,6 @@ def it_knows_when_it_has_a_header_part_to_help(self, has_definition_fixture):
 
         assert has_definition is expected_value
 
-    def it_provides_access_to_its_header_part_to_help(
-        self, document_part_, header_part_
-    ):
-        sectPr = element("w:sectPr/w:headerReference{w:type=default,r:id=rId8}")
-        document_part_.header_part.return_value = header_part_
-        header = _Header(sectPr, document_part_)
-
-        header_part = header._header_part
-
-        document_part_.header_part.assert_called_once_with("rId8")
-        assert header_part is header_part_
-
     def it_provides_access_to_the_prior_Header_to_help(
         self, request, document_part_, header_
     ):
@@ -591,7 +607,7 @@ def it_provides_access_to_the_prior_Header_to_help(
         # ---mock must occur after construction of "real" header---
         _Header_ = class_mock(request, "docx.section._Header", return_value=header_)
 
-        prior_header = header._prior_header
+        prior_header = header._prior_headerfooter
 
         _Header_.assert_called_once_with(prior_sectPr, document_part_)
         assert prior_header is header_
@@ -601,7 +617,7 @@ def but_it_returns_None_when_its_the_first_header(self):
         sectPr = doc_elm[0]
         header = _Header(sectPr, None)
 
-        prior_header = header._prior_header
+        prior_header = header._prior_headerfooter
 
         assert prior_header is None
 
@@ -619,38 +635,14 @@ def has_definition_fixture(self, request):
 
     # fixture components ---------------------------------------------
 
-    @pytest.fixture
-    def _add_definition_(self, request):
-        return method_mock(request, _Header, "_add_definition")
-
     @pytest.fixture
     def document_part_(self, request):
         return instance_mock(request, DocumentPart)
 
-    @pytest.fixture
-    def _get_or_add_definition_(self, request):
-        return method_mock(request, _Header, "_get_or_add_definition")
-
-    @pytest.fixture
-    def _has_definition_prop_(self, request):
-        return property_mock(request, _Header, "_has_definition")
-
     @pytest.fixture
     def header_(self, request):
         return instance_mock(request, _Header)
 
     @pytest.fixture
     def header_part_(self, request):
         return instance_mock(request, HeaderPart)
-
-    @pytest.fixture
-    def _header_part_prop_(self, request):
-        return property_mock(request, _Header, "_header_part")
-
-    @pytest.fixture
-    def prior_header_(self, request):
-        return instance_mock(request, _Header)
-
-    @pytest.fixture
-    def _prior_header_prop_(self, request):
-        return property_mock(request, _Header, "_prior_header")