hdr: add _Header._element

Author: scanny

docx/section.py

@@ -262,6 +262,22 @@ def _drop_header_part(self):
         rId = self._sectPr.remove_headerReference(WD_HEADER_FOOTER.PRIMARY)
         self._document_part.drop_header_part(rId)
 
+    @property
+    def _element(self):
+        """`w:hdr` element, root of header part."""
+        return self._get_or_add_header_part().element
+
+    def _get_or_add_header_part(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---
+        raise NotImplementedError
+
     @property
     def _has_header_part(self):
         """True if a header is explicitly defined for this section."""

tests/test_section.py

@@ -409,6 +409,19 @@ 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_provides_access_to_the_hdr_element_to_help(
+        self, _get_or_add_header_part_, header_part_
+    ):
+        hdr = element("w:hdr")
+        _get_or_add_header_part_.return_value = header_part_
+        header_part_.element = hdr
+        header = _Header(None, None)
+
+        hdr_elm = header._element
+
+        _get_or_add_header_part_.assert_called_once_with(header)
+        assert hdr_elm is hdr
+
     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)
@@ -450,15 +463,19 @@ def is_linked_set_fixture(self, request):
 
     @pytest.fixture
     def _add_header_part_(self, request):
-        return method_mock(request, _Header, "_add_header_part", autospec=True)
+        return method_mock(request, _Header, "_add_header_part")
 
     @pytest.fixture
     def document_part_(self, request):
         return instance_mock(request, DocumentPart)
 
     @pytest.fixture
     def _drop_header_part_(self, request):
-        return method_mock(request, _Header, "_drop_header_part", autospec=True)
+        return method_mock(request, _Header, "_drop_header_part")
+
+    @pytest.fixture
+    def _get_or_add_header_part_(self, request):
+        return method_mock(request, _Header, "_get_or_add_header_part")
 
     @pytest.fixture
     def _has_header_part_prop_(self, request):