sect: add Section.start_type getter

Steve Canny · Steve Canny · commit c6ec277722f0 · 2014-06-20T01:49:13.000-07:00
Added InvalidXmlError to docx.exceptions, caused a circular import
error when trying to get it into enum from xmlchemy.
diff --git a/docs/dev/analysis/features/sections.rst b/docs/dev/analysis/features/sections.rst
@@ -130,6 +130,7 @@ Inserting a section break (next page) produces this XML::
     <w:p>
       <w:pPr>
         <w:sectPr>
+          <w:type w:val="oddPage"/>
           <w:pgSz w:w="12240" w:h="15840"/>
           <w:pgMar w:top="1440" w:right="1800" w:bottom="1440" w:left="1800" w:header="720" w:footer="720" w:gutter="0"/>
           <w:cols w:space="720"/>
diff --git a/docx/enum/base.py b/docx/enum/base.py
@@ -9,6 +9,8 @@
 import sys
 import textwrap
 
+from ..exceptions import InvalidXmlError
+
 
 def alias(*aliases):
     """
@@ -184,6 +186,10 @@ def from_xml(cls, xml_val):
         Return the enumeration member corresponding to the XML value
         *xml_val*.
         """
+        if xml_val not in cls._xml_to_member:
+            raise InvalidXmlError(
+                "attribute value '%s' not valid for this type" % xml_val
+            )
         return cls._xml_to_member[xml_val]
 
     @classmethod
diff --git a/docx/exceptions.py b/docx/exceptions.py
@@ -8,4 +8,13 @@
 
 
 class PythonDocxError(Exception):
-    """Generic error class."""
+    """
+    Generic error class.
+    """
+
+
+class InvalidXmlError(PythonDocxError):
+    """
+    Raised when invalid XML is encountered, such as on attempt to access a
+    missing required child element
+    """
diff --git a/docx/oxml/__init__.py b/docx/oxml/__init__.py
@@ -107,6 +107,10 @@ 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_SectPr, CT_SectType
+register_element_cls('w:sectPr', CT_SectPr)
+register_element_cls('w:type',   CT_SectType)
+
 from docx.oxml.table import (
     CT_Row, CT_Tbl, CT_TblGrid, CT_TblGridCol, CT_TblPr, CT_Tc
 )
diff --git a/docx/oxml/section.py b/docx/oxml/section.py
@@ -0,0 +1,34 @@
+# encoding: utf-8
+
+"""
+Section-related custom element classes.
+"""
+
+from ..enum.section import WD_SECTION_START
+from .xmlchemy import BaseOxmlElement, OptionalAttribute, ZeroOrOne
+
+
+class CT_SectPr(BaseOxmlElement):
+    """
+    ``<w:sectPr>`` element, the container element for section properties.
+    """
+    type = ZeroOrOne('w:type')
+
+    @property
+    def start_type(self):
+        """
+        The member of the ``WD_SECTION_START`` enumeration corresponding to
+        the value of the ``val`` attribute of the ``<w:type>`` child element,
+        or ``WD_SECTION_START.NEW_PAGE`` if not present.
+        """
+        type = self.type
+        if type is None or type.val is None:
+            return WD_SECTION_START.NEW_PAGE
+        return type.val
+
+
+class CT_SectType(BaseOxmlElement):
+    """
+    ``<w:sectType>`` element, defining the section start type.
+    """
+    val = OptionalAttribute('w:val', WD_SECTION_START)
diff --git a/docx/section.py b/docx/section.py
@@ -14,3 +14,12 @@ class Section(object):
     def __init__(self, sectPr):
         super(Section, self).__init__()
         self._sectPr = sectPr
+
+    @property
+    def start_type(self):
+        """
+        The member of the ``WD_SECTION`` enumeration corresponding to the
+        initial break behavior of this section, e.g. ``WD_SECTION.ODD_PAGE``
+        if the section should begin on the next odd page.
+        """
+        return self._sectPr.start_type
diff --git a/features/sct-section-props.feature b/features/sct-section-props.feature
@@ -4,7 +4,6 @@ Feature: Access and change section properties
   I need a way to get and set the properties of a section
 
 
-  @wip
   Scenario Outline: Get section start type
     Given a section having start type <start-type>
      Then the reported section start type is <start-type>
diff --git a/tests/oxml/unitdata/section.py b/tests/oxml/unitdata/section.py
@@ -0,0 +1,27 @@
+# encoding: utf-8
+
+"""
+Test data builders for section-related XML elements
+"""
+
+from ...unitdata import BaseBuilder
+
+
+class CT_SectPrBuilder(BaseBuilder):
+    __tag__ = 'w:sectPr'
+    __nspfxs__ = ('w',)
+    __attrs__ = ()
+
+
+class CT_SectTypeBuilder(BaseBuilder):
+    __tag__ = 'w:type'
+    __nspfxs__ = ('w',)
+    __attrs__ = ('w:val',)
+
+
+def a_sectPr():
+    return CT_SectPrBuilder()
+
+
+def a_type():
+    return CT_SectTypeBuilder()
diff --git a/tests/test_section.py b/tests/test_section.py
@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+"""
+Test suite for the docx.section module
+"""
+
+from __future__ import absolute_import, print_function, unicode_literals
+
+import pytest
+
+from docx.enum.section import WD_SECTION
+from docx.section import Section
+
+from .oxml.unitdata.section import a_sectPr, a_type
+
+
+class DescribeSection(object):
+
+    def it_knows_its_start_type(self, start_type_fixture):
+        section, expected_start_type = start_type_fixture
+        assert section.start_type is expected_start_type
+
+    # fixtures -------------------------------------------------------
+
+    @pytest.fixture(params=[
+        (None,         WD_SECTION.NEW_PAGE),
+        ('continuous', WD_SECTION.CONTINUOUS),
+        ('nextPage',   WD_SECTION.NEW_PAGE),
+        ('oddPage',    WD_SECTION.ODD_PAGE),
+        ('evenPage',   WD_SECTION.EVEN_PAGE),
+        ('nextColumn', WD_SECTION.NEW_COLUMN),
+    ])
+    def start_type_fixture(self, request):
+        type_val, expected_start_type = request.param
+        sectPr_bldr = a_sectPr().with_nsdecls()
+        if type_val is not None:
+            sectPr_bldr.with_child(a_type().with_val(type_val))
+        sectPr = sectPr_bldr.element
+        section = Section(sectPr)
+        return section, expected_start_type
