hdr: add Section.header

eupharis · eupharis · commit c68f667c495f · 2016-05-02T15:32:50.000-07:00
diff --git a/docx/header.py b/docx/header.py
@@ -8,12 +8,11 @@
     absolute_import, division, print_function, unicode_literals
 )
 
-from .shared import ElementProxy
+from .blkcntnr import BlockItemContainer
 
 
-class Header(ElementProxy):
+class Header(BlockItemContainer):
     """
-    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/oxml/header.py b/docx/oxml/header.py
@@ -0,0 +1,14 @@
+from . import OxmlElement
+from .xmlchemy import BaseOxmlElement, ZeroOrMore
+
+
+class CT_Hdr(BaseOxmlElement):
+    """
+    ``<w:hdr>``, the container element for the header content
+    """
+    p = ZeroOrMore('w:p', successors=())
+
+    @classmethod
+    def new(cls):
+        header_elm = OxmlElement('w:hdr')
+        return header_elm
diff --git a/docx/section.py b/docx/section.py
@@ -7,6 +7,7 @@
 from __future__ import absolute_import, print_function, unicode_literals
 
 from collections import Sequence
+from .header import Header
 
 
 class Sections(Sequence):
@@ -37,10 +38,24 @@ class Section(object):
     """
     Document section, providing access to section and page setup settings.
     """
+    _header = None
+
     def __init__(self, sectPr):
         super(Section, self).__init__()
         self._sectPr = sectPr
 
+    @property
+    def header(self):
+        if not self._header:
+            # here's how I did the header element in my previous implementation:
+            # from .oxml.header import CT_Hdr
+            # header_elm = CT_Hdr.new()
+            # not sure what is appropriate here for this first unit test
+            header_elm = 'pretend element'
+            self._header = Header(header_elm, self)
+
+        return self._header
+
     @property
     def bottom_margin(self):
         """
diff --git a/tests/test_section.py b/tests/test_section.py
@@ -11,8 +11,12 @@
 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 +65,16 @@ def document_elm(self):
 
 class DescribeSection(object):
 
+    def it_provides_access_to_its_header(self, header_fixture):
+        section, Header_, header_ = header_fixture
+        header = section.header
+        Header_.assert_called_once_with('pretend element', section)
+
+        # access header again, dont instantiate with Header_ again, return same header
+        header = section.header
+        assert Header_.call_count == 1
+        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 +125,22 @@ def it_can_change_its_page_margins(self, margins_set_fixture):
 
     # fixtures -------------------------------------------------------
 
+    @pytest.fixture
+    def Header_(self, request, header_):
+        return class_mock(
+            request, 'docx.section.Header',
+            return_value=header_
+        )
+
+    @pytest.fixture
+    def header_(self, request):
+        return instance_mock(request, Header)
+
+    @pytest.fixture
+    def header_fixture(self, Header_, header_):
+        section = Section(element('w:sectPr'))
+        return section, Header_, header_
+
     @pytest.fixture(params=[
         ('w:sectPr/w:pgMar{w:left=120}',   'left_margin',      76200),
         ('w:sectPr/w:pgMar{w:right=240}',  'right_margin',    152400),
