hdr: add Section.header

eupharis · eupharis · commit 35984408d1c4 · 2016-05-05T09:47:40.000-07:00
diff --git a/docx/header.py b/docx/header.py
@@ -7,13 +7,13 @@
 from __future__ import (
     absolute_import, division, print_function, unicode_literals
 )
-
 from .shared import ElementProxy
 
 
 class Header(ElementProxy):
     """
-    The default page header of a section.
+    Proxy for ``<w:hdr>`` element in this section, having primarily a
+    container role.
     """
 
     __slots__ = ()
diff --git a/docx/section.py b/docx/section.py
@@ -7,6 +7,8 @@
 from __future__ import absolute_import, print_function, unicode_literals
 
 from collections import Sequence
+from .shared import lazyproperty
+from .header import Header
 
 
 class Sections(Sequence):
@@ -37,6 +39,7 @@ class Section(object):
     """
     Document section, providing access to section and page setup settings.
     """
+
     def __init__(self, sectPr):
         super(Section, self).__init__()
         self._sectPr = sectPr
@@ -80,6 +83,16 @@ def gutter(self):
     def gutter(self, value):
         self._sectPr.gutter = value
 
+    @lazyproperty
+    def header(self):
+        """
+        Return the |Header| object representing the default header for this
+        section. A |Header| object is always returned, whether such a header is
+        present or not. The header itself is added, updated, or removed using the
+        returned object.
+        """
+        return Header(self._sectPr)
+
     @property
     def header_distance(self):
         """
diff --git a/tests/test_section.py b/tests/test_section.py
@@ -11,8 +11,10 @@
 from docx.enum.section import WD_ORIENT, WD_SECTION
 from docx.section import Section, Sections
 from docx.shared import Inches
+from docx.header import Header
 
 from .unitutil.cxml import element, xml
+from .unitutil.mock import instance_mock, class_mock
 
 
 class DescribeSections(object):
@@ -61,6 +63,12 @@ def document_elm(self):
 
 class DescribeSection(object):
 
+    def it_provides_access_to_its_header(self, header_fixture):
+        section, Header_, sectPr, header_ = header_fixture
+        header = section.header
+        Header_.assert_called_once_with(sectPr)
+        assert header is header_
+
     def it_knows_its_start_type(self, start_type_get_fixture):
         section, expected_start_type = start_type_get_fixture
         assert section.start_type is expected_start_type
@@ -111,6 +119,12 @@ def it_can_change_its_page_margins(self, margins_set_fixture):
 
     # fixtures -------------------------------------------------------
 
+    @pytest.fixture
+    def header_fixture(self, Header_, header_):
+        sectPr = element('w:sectPr')
+        section = Section(sectPr)
+        return section, Header_, sectPr, header_
+
     @pytest.fixture(params=[
         ('w:sectPr/w:pgMar{w:left=120}',   'left_margin',      76200),
         ('w:sectPr/w:pgMar{w:right=240}',  'right_margin',    152400),
@@ -247,3 +261,16 @@ def start_type_set_fixture(self, request):
         section = Section(element(initial_cxml))
         expected_xml = xml(expected_cxml)
         return section, new_start_type, expected_xml
+
+    # fixture components ---------------------------------------------
+
+    @pytest.fixture
+    def header_(self, request):
+        return instance_mock(request, Header)
+
+    @pytest.fixture
+    def Header_(self, request, header_):
+        return class_mock(
+            request, 'docx.section.Header',
+            return_value=header_
+        )
