sect: add Section margin getters

Steve Canny · Steve Canny · commit 445d5d28df38 · 2014-06-21T02:26:52.000-07:00
diff --git a/docx/oxml/__init__.py b/docx/oxml/__init__.py
@@ -107,7 +107,8 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 register_element_cls('w:style',  CT_Style)
 register_element_cls('w:styles', CT_Styles)
 
-from docx.oxml.section import CT_PageSz, CT_SectPr, CT_SectType
+from docx.oxml.section import CT_PageMar, CT_PageSz, CT_SectPr, CT_SectType
+register_element_cls('w:pgMar',  CT_PageMar)
 register_element_cls('w:pgSz',   CT_PageSz)
 register_element_cls('w:sectPr', CT_SectPr)
 register_element_cls('w:type',   CT_SectType)
diff --git a/docx/oxml/section.py b/docx/oxml/section.py
@@ -5,10 +5,23 @@
 """
 
 from ..enum.section import WD_ORIENTATION, WD_SECTION_START
-from .simpletypes import ST_TwipsMeasure
+from .simpletypes import ST_SignedTwipsMeasure, ST_TwipsMeasure
 from .xmlchemy import BaseOxmlElement, OptionalAttribute, ZeroOrOne
 
 
+class CT_PageMar(BaseOxmlElement):
+    """
+    ``<w:pgMar>`` element, defining page margins.
+    """
+    top = OptionalAttribute('w:top', ST_SignedTwipsMeasure)
+    right = OptionalAttribute('w:right', ST_TwipsMeasure)
+    bottom = OptionalAttribute('w:bottom', ST_SignedTwipsMeasure)
+    left = OptionalAttribute('w:left', ST_TwipsMeasure)
+    header = OptionalAttribute('w:header', ST_TwipsMeasure)
+    footer = OptionalAttribute('w:footer', ST_TwipsMeasure)
+    gutter = OptionalAttribute('w:gutter', ST_TwipsMeasure)
+
+
 class CT_PageSz(BaseOxmlElement):
     """
     ``<w:pgSz>`` element, defining page dimensions and orientation.
@@ -37,6 +50,81 @@ class CT_SectPr(BaseOxmlElement):
     pgSz = ZeroOrOne('w:pgSz', successors=(
         __child_sequence__[__child_sequence__.index('w:pgSz')+1:]
     ))
+    pgMar = ZeroOrOne('w:pgMar', successors=(
+        __child_sequence__[__child_sequence__.index('w:pgMar')+1:]
+    ))
+
+    @property
+    def bottom_margin(self):
+        """
+        The value of the ``w:bottom`` attribute in the ``<w:pgMar>`` child
+        element, as a |Length| object, or |None| if either the element or the
+        attribute is not present.
+        """
+        pgMar = self.pgMar
+        if pgMar is None:
+            return None
+        return pgMar.bottom
+
+    @property
+    def footer(self):
+        """
+        The value of the ``w:footer`` attribute in the ``<w:pgMar>`` child
+        element, as a |Length| object, or |None| if either the element or the
+        attribute is not present.
+        """
+        pgMar = self.pgMar
+        if pgMar is None:
+            return None
+        return pgMar.footer
+
+    @property
+    def gutter(self):
+        """
+        The value of the ``w:gutter`` attribute in the ``<w:pgMar>`` child
+        element, as a |Length| object, or |None| if either the element or the
+        attribute is not present.
+        """
+        pgMar = self.pgMar
+        if pgMar is None:
+            return None
+        return pgMar.gutter
+
+    @property
+    def header(self):
+        """
+        The value of the ``w:header`` attribute in the ``<w:pgMar>`` child
+        element, as a |Length| object, or |None| if either the element or the
+        attribute is not present.
+        """
+        pgMar = self.pgMar
+        if pgMar is None:
+            return None
+        return pgMar.header
+
+    @property
+    def left_margin(self):
+        """
+        The value of the ``w:left`` attribute in the ``<w:pgMar>`` child
+        element, as a |Length| object, or |None| if either the element or the
+        attribute is not present.
+        """
+        pgMar = self.pgMar
+        if pgMar is None:
+            return None
+        return pgMar.left
+
+    @property
+    def right_margin(self):
+        """
+        The value of the ``w:right`` attribute in the ``<w:pgMar>`` child
+        element, as a |Length| object, or |None| if either the element or the
+        attribute is not present.
+        """
+        pgMar = self.pgMar
+        if pgMar is None:
+            return None
+        return pgMar.right
 
     @property
     def orientation(self):
@@ -107,6 +195,18 @@ def start_type(self, value):
         type = self.get_or_add_type()
         type.val = value
 
+    @property
+    def top_margin(self):
+        """
+        The value of the ``w:top`` attribute in the ``<w:pgMar>`` child
+        element, as a |Length| object, or |None| if either the element or the
+        attribute is not present.
+        """
+        pgMar = self.pgMar
+        if pgMar is None:
+            return None
+        return pgMar.top
+
 
 class CT_SectType(BaseOxmlElement):
     """
diff --git a/docx/oxml/simpletypes.py b/docx/oxml/simpletypes.py
@@ -234,6 +234,21 @@ class ST_RelationshipId(XsdString):
     pass
 
 
+class ST_SignedTwipsMeasure(XsdInt):
+
+    @classmethod
+    def convert_from_xml(cls, str_value):
+        if 'i' in str_value or 'm' in str_value or 'p' in str_value:
+            return ST_UniversalMeasure.convert_from_xml(str_value)
+        return Twips(int(str_value))
+
+    @classmethod
+    def convert_to_xml(cls, value):
+        emu = Emu(value)
+        twips = emu.twips
+        return str(twips)
+
+
 class ST_String(XsdString):
     pass
 
diff --git a/docx/section.py b/docx/section.py
@@ -15,6 +15,50 @@ def __init__(self, sectPr):
         super(Section, self).__init__()
         self._sectPr = sectPr
 
+    @property
+    def bottom_margin(self):
+        """
+        |Length| object representing the bottom margin for all pages in this
+        section in English Metric Units.
+        """
+        return self._sectPr.bottom_margin
+
+    @property
+    def footer_distance(self):
+        """
+        |Length| object representing the distance from the bottom edge of the
+        page to the bottom edge of the footer. |None| if no setting is present
+        in the XML.
+        """
+        return self._sectPr.footer
+
+    @property
+    def gutter(self):
+        """
+        |Length| object representing the page gutter size in English Metric
+        Units for all pages in this section. The page gutter is extra spacing
+        added to the *inner* margin to ensure even margins after page
+        binding.
+        """
+        return self._sectPr.gutter
+
+    @property
+    def header_distance(self):
+        """
+        |Length| object representing the distance from the top edge of the
+        page to the top edge of the header. |None| if no setting is present
+        in the XML.
+        """
+        return self._sectPr.header
+
+    @property
+    def left_margin(self):
+        """
+        |Length| object representing the left margin for all pages in this
+        section in English Metric Units.
+        """
+        return self._sectPr.left_margin
+
     @property
     def orientation(self):
         """
@@ -55,6 +99,14 @@ def page_width(self):
     def page_width(self, value):
         self._sectPr.page_width = value
 
+    @property
+    def right_margin(self):
+        """
+        |Length| object representing the right margin for all pages in this
+        section in English Metric Units.
+        """
+        return self._sectPr.right_margin
+
     @property
     def start_type(self):
         """
@@ -67,3 +119,11 @@ def start_type(self):
     @start_type.setter
     def start_type(self, value):
         self._sectPr.start_type = value
+
+    @property
+    def top_margin(self):
+        """
+        |Length| object representing the top margin for all pages in this
+        section in English Metric Units.
+        """
+        return self._sectPr.top_margin
diff --git a/features/sct-section-props.feature b/features/sct-section-props.feature
@@ -65,7 +65,6 @@ Feature: Access and change section properties
       | landscape           | None                 |  WD_ORIENT.PORTRAIT   |
 
 
-  @wip
   Scenario: Get section page margins
     Given a section having known page margins
      Then the reported left margin is 1.0 inches
diff --git a/tests/oxml/unitdata/section.py b/tests/oxml/unitdata/section.py
@@ -7,6 +7,15 @@
 from ...unitdata import BaseBuilder
 
 
+class CT_PageMarBuilder(BaseBuilder):
+    __tag__ = 'w:pgMar'
+    __nspfxs__ = ('w',)
+    __attrs__ = (
+        'w:top', 'w:right', 'w:bottom', 'w:left', 'w:header', 'w:footer',
+        'w:gutter'
+    )
+
+
 class CT_PageSzBuilder(BaseBuilder):
     __tag__ = 'w:pgSz'
     __nspfxs__ = ('w',)
@@ -25,6 +34,10 @@ class CT_SectTypeBuilder(BaseBuilder):
     __attrs__ = ('w:val',)
 
 
+def a_pgMar():
+    return CT_PageMarBuilder()
+
+
 def a_pgSz():
     return CT_PageSzBuilder()
 
diff --git a/tests/test_section.py b/tests/test_section.py
@@ -12,7 +12,7 @@
 from docx.section import Section
 from docx.shared import Inches
 
-from .oxml.unitdata.section import a_pgSz, a_sectPr, a_type
+from .oxml.unitdata.section import a_pgMar, a_pgSz, a_sectPr, a_type
 
 
 class DescribeSection(object):
@@ -52,8 +52,47 @@ def it_can_change_its_orientation(self, orientation_set_fixture):
         section.orientation = new_orientation
         assert section._sectPr.xml == expected_xml
 
+    def it_knows_its_page_margins(self, margins_get_fixture):
+        section, left, right, top, bottom, gutter, header, footer = (
+            margins_get_fixture
+        )
+        assert section.left_margin == left
+        assert section.right_margin == right
+        assert section.top_margin == top
+        assert section.bottom_margin == bottom
+        assert section.gutter == gutter
+        assert section.header_distance == header
+        assert section.footer_distance == footer
+
     # fixtures -------------------------------------------------------
 
+    @pytest.fixture(params=[
+        (True,   720,  720,  720,  720,  720,  720,  720),
+        (True,  None,  360, None,  360, None,  360, None),
+        (False, None, None, None, None, None, None, None),
+    ])
+    def margins_get_fixture(self, request):
+        (has_pgMar_child, left, right, top, bottom, gutter, header,
+         footer) = request.param
+        pgMar_bldr = self.pgMar_bldr(
+            has_pgMar_child, left=left, right=right, top=top, bottom=bottom,
+            gutter=gutter, header=header, footer=footer
+        )
+        sectPr = self.sectPr_bldr(pgMar_bldr).element
+        section = Section(sectPr)
+        expected_left = left * 635 if left else None
+        expected_right = right * 635 if right else None
+        expected_top = top * 635 if top else None
+        expected_bottom = bottom * 635 if bottom else None
+        expected_gutter = gutter * 635 if gutter else None
+        expected_header = header * 635 if header else None
+        expected_footer = footer * 635 if footer else None
+        return (
+            section, expected_left, expected_right, expected_top,
+            expected_bottom, expected_gutter, expected_header,
+            expected_footer
+        )
+
     @pytest.fixture(params=[
         (True,  'landscape', WD_ORIENT.LANDSCAPE),
         (True,  'portrait',  WD_ORIENT.PORTRAIT),
@@ -172,6 +211,28 @@ def start_type_set_fixture(self, request):
 
     # fixture components ---------------------------------------------
 
+    def pgMar_bldr(
+            self, has_pgMar=True, left=None, right=None, top=None,
+            bottom=None, header=None, footer=None, gutter=None):
+        if not has_pgMar:
+            return None
+        pgMar_bldr = a_pgMar()
+        if left is not None:
+            pgMar_bldr.with_left(left)
+        if right is not None:
+            pgMar_bldr.with_right(right)
+        if top is not None:
+            pgMar_bldr.with_top(top)
+        if bottom is not None:
+            pgMar_bldr.with_bottom(bottom)
+        if header is not None:
+            pgMar_bldr.with_header(header)
+        if footer is not None:
+            pgMar_bldr.with_footer(footer)
+        if gutter is not None:
+            pgMar_bldr.with_gutter(gutter)
+        return pgMar_bldr
+
     def pgSz_bldr(self, has_pgSz=True, w=None, h=None, orient=None):
         if not has_pgSz:
             return None
