hdr: add _Header.is_linked_to_previous

Author: ondrej-111

docx/section.py

@@ -224,3 +224,22 @@ class _Header(BlockItemContainer):
     def __init__(self, sectPr, document_part):
         self._sectPr = sectPr
         self._document_part = document_part
+
+    @property
+    def is_linked_to_previous(self):
+        """True if this header uses the header definition of the preceding section.
+
+        False if this header has an explicit definition.
+
+        Assigning ``True`` to this property removes any header definition for this
+        section, causing it to "inherit" the header definition of the prior section.
+        Assigning ``False`` causes a new, empty header definition to be added for this
+        section, but only if no existing definition is present.
+        """
+        # ---absence of a header (definition) part indicates "linked" behavior---
+        return not self._has_header_part
+
+    @property
+    def _has_header_part(self):
+        """True if a header is explicitly defined for this section."""
+        raise NotImplementedError

tests/test_section.py

@@ -12,7 +12,7 @@
 from docx.shared import Inches
 
 from .unitutil.cxml import element, xml
-from .unitutil.mock import call, class_mock, instance_mock
+from .unitutil.mock import call, class_mock, instance_mock, property_mock
 
 
 class DescribeSections(object):
@@ -355,3 +355,30 @@ def _Header_(self, request):
     @pytest.fixture
     def header_(self, request):
         return instance_mock(request, _Header)
+
+
+class Describe_Header(object):
+
+    def it_knows_when_its_linked_to_the_previous_header(
+        self, is_linked_fixture, _has_header_part_prop_
+    ):
+        has_header_part, expected_value = is_linked_fixture
+        _has_header_part_prop_.return_value = has_header_part
+        header = _Header(None, None)
+
+        is_linked = header.is_linked_to_previous
+
+        assert is_linked is expected_value
+
+    # fixtures -------------------------------------------------------
+
+    @pytest.fixture(params=[(False, True), (True, False)])
+    def is_linked_fixture(self, request):
+        has_header_part, expected_value = request.param
+        return has_header_part, expected_value
+
+    # fixture components ---------------------------------------------
+
+    @pytest.fixture
+    def _has_header_part_prop_(self, request):
+        return property_mock(request, _Header, "_has_header_part")