hdr: add _Header._get_or_add_header_part()

Author: scanny

docx/section.py

@@ -276,10 +276,28 @@ def _get_or_add_header_part(self):
         created for the first section and returned.
         """
         # ---note this method is called recursively to access inherited headers---
-        raise NotImplementedError
+        # ---case-1: header does not inherit---
+        if self._has_header_part:
+            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_header_part()
+        # ---case-3: header inherits, but is first header---
+        return self._add_header_part()
 
     @property
     def _has_header_part(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."""
+        raise NotImplementedError
+
+    @property
+    def _prior_header(self):
+        """|_Header| proxy on prior sectPr element or None if this is first section."""
+        raise NotImplementedError

tests/test_section.py

@@ -422,6 +422,47 @@ def it_provides_access_to_the_hdr_element_to_help(
         _get_or_add_header_part_.assert_called_once_with(header)
         assert hdr_elm is hdr
 
+    def it_gets_the_header_part_when_it_has_one(
+        self, _has_header_part_prop_, _header_part_prop_, header_part_
+    ):
+        _has_header_part_prop_.return_value = True
+        _header_part_prop_.return_value = header_part_
+        header = _Header(None, None)
+
+        header_part = header._get_or_add_header_part()
+
+        assert header_part is header_part_
+
+    def but_it_gets_the_prior_header_part_when_it_is_linked(
+        self, _has_header_part_prop_, _prior_header_prop_, prior_header_, header_part_
+    ):
+        _has_header_part_prop_.return_value = False
+        _prior_header_prop_.return_value = prior_header_
+        prior_header_._get_or_add_header_part.return_value = header_part_
+        header = _Header(None, None)
+
+        header_part = header._get_or_add_header_part()
+
+        prior_header_._get_or_add_header_part.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_header_part_prop_,
+        _prior_header_prop_,
+        _add_header_part_,
+        header_part_
+    ):
+        _has_header_part_prop_.return_value = False
+        _prior_header_prop_.return_value = None
+        _add_header_part_.return_value = header_part_
+        header = _Header(None, None)
+
+        header_part = header._get_or_add_header_part()
+
+        _add_header_part_.assert_called_once_with(header)
+        assert header_part is header_part_
+
     def it_knows_when_it_has_a_header_part_to_help(self, has_header_part_fixture):
         sectPr, expected_value = has_header_part_fixture
         header = _Header(sectPr, None)
@@ -484,3 +525,15 @@ def _has_header_part_prop_(self, request):
     @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")