parfmt: add ParagraphFormat.space_before getter

Steve Canny · Steve Canny · commit 4497b1047baf · 2015-02-08T00:01:43.000-08:00
* refactor CT_PPr oxml declarations to use _tag_seq
* remove now-obsolete CT_PPr._insert_pStyle() method
diff --git a/docx/oxml/__init__.py b/docx/oxml/__init__.py
@@ -136,11 +136,12 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 register_element_cls('w:tr',        CT_Row)
 register_element_cls('w:vMerge',    CT_VMerge)
 
-from .text.paragraph import CT_Jc, CT_P, CT_PPr
-register_element_cls('w:jc',     CT_Jc)
-register_element_cls('w:p',      CT_P)
-register_element_cls('w:pPr',    CT_PPr)
-register_element_cls('w:pStyle', CT_String)
+from .text.paragraph import CT_Jc, CT_P, CT_PPr, CT_Spacing
+register_element_cls('w:jc',      CT_Jc)
+register_element_cls('w:p',       CT_P)
+register_element_cls('w:pPr',     CT_PPr)
+register_element_cls('w:pStyle',  CT_String)
+register_element_cls('w:spacing', CT_Spacing)
 
 from .text.run import (
     CT_Br, CT_Fonts, CT_HpsMeasure, CT_R, CT_RPr, CT_Text, CT_Underline,
diff --git a/docx/oxml/text/paragraph.py b/docx/oxml/text/paragraph.py
@@ -6,8 +6,10 @@
 
 from ...enum.text import WD_ALIGN_PARAGRAPH
 from ..ns import qn
+from ..simpletypes import ST_TwipsMeasure
 from ..xmlchemy import (
-    BaseOxmlElement, OxmlElement, RequiredAttribute, ZeroOrMore, ZeroOrOne
+    BaseOxmlElement, OptionalAttribute, OxmlElement, RequiredAttribute,
+    ZeroOrMore, ZeroOrOne
 )
 
 
@@ -92,7 +94,7 @@ class CT_PPr(BaseOxmlElement):
     """
     ``<w:pPr>`` element, containing the properties for a paragraph.
     """
-    __child_sequence__ = (
+    _tag_seq = (
         'w:pStyle', 'w:keepNext', 'w:keepLines', 'w:pageBreakBefore',
         'w:framePr', 'w:widowControl', 'w:numPr', 'w:suppressLineNumbers',
         'w:pBdr', 'w:shd', 'w:tabs', 'w:suppressAutoHyphens', 'w:kinsoku',
@@ -103,14 +105,12 @@ class CT_PPr(BaseOxmlElement):
         'w:textboxTightWrap', 'w:outlineLvl', 'w:divId', 'w:cnfStyle',
         'w:rPr', 'w:sectPr', 'w:pPrChange'
     )
-    pStyle = ZeroOrOne('w:pStyle')
-    numPr = ZeroOrOne('w:numPr', successors=__child_sequence__[7:])
-    jc = ZeroOrOne('w:jc', successors=__child_sequence__[27:])
-    sectPr = ZeroOrOne('w:sectPr', successors=('w:pPrChange',))
-
-    def _insert_pStyle(self, pStyle):
-        self.insert(0, pStyle)
-        return pStyle
+    pStyle = ZeroOrOne('w:pStyle', successors=_tag_seq[1:])
+    numPr = ZeroOrOne('w:numPr', successors=_tag_seq[7:])
+    spacing = ZeroOrOne('w:spacing', successors=_tag_seq[22:])
+    jc = ZeroOrOne('w:jc', successors=_tag_seq[27:])
+    sectPr = ZeroOrOne('w:sectPr', successors=_tag_seq[35:])
+    del _tag_seq
 
     @property
     def jc_val(self):
@@ -129,6 +129,16 @@ def jc_val(self, value):
             return
         self.get_or_add_jc().val = value
 
+    @property
+    def spacing_before(self):
+        """
+        The value of `w:spacing@w:before` or |None| if not present.
+        """
+        spacing = self.spacing
+        if spacing is None:
+            return None
+        return spacing.before
+
     @property
     def style(self):
         """
@@ -152,3 +162,11 @@ def style(self, style):
             return
         pStyle = self.get_or_add_pStyle()
         pStyle.val = style
+
+
+class CT_Spacing(BaseOxmlElement):
+    """
+    ``<w:spacing>`` element, specifying paragraph spacing attributes such as
+    space before and line spacing.
+    """
+    before = OptionalAttribute('w:before', ST_TwipsMeasure)
diff --git a/docx/text/paragraph.py b/docx/text/paragraph.py
@@ -154,3 +154,18 @@ def alignment(self):
     def alignment(self, value):
         pPr = self._element.get_or_add_pPr()
         pPr.jc_val = value
+
+    @property
+    def space_before(self):
+        """
+        |Length| value specifying the spacing to appear between this
+        paragraph and the prior paragraph. |None| indicates this value is
+        inherited from the style hierarchy. |Length| objects provide
+        convenience properties, such as :attr:`~.Length.pt` and
+        :attr:`~.Length.cm`, that allow easy conversion to various length
+        units.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return pPr.spacing_before
diff --git a/tests/text/test_paragraph.py b/tests/text/test_paragraph.py
@@ -13,6 +13,7 @@
 from docx.oxml.text.paragraph import CT_P
 from docx.oxml.text.run import CT_R
 from docx.parts.document import DocumentPart
+from docx.shared import Pt
 from docx.text.paragraph import Paragraph, ParagraphFormat
 from docx.text.run import Run
 
@@ -296,6 +297,10 @@ def it_can_change_its_alignment_value(self, alignment_set_fixture):
         paragraph_format.alignment = value
         assert paragraph_format._element.xml == expected_xml
 
+    def it_knows_its_space_before(self, space_before_get_fixture):
+        paragraph_format, expected_value = space_before_get_fixture
+        assert paragraph_format.space_before == expected_value
+
     # fixtures -------------------------------------------------------
 
     @pytest.fixture(params=[
@@ -325,3 +330,14 @@ def alignment_set_fixture(self, request):
         paragraph_format = ParagraphFormat(element(p_cxml))
         expected_xml = xml(expected_cxml)
         return paragraph_format, value, expected_xml
+
+    @pytest.fixture(params=[
+        ('w:p',                               None),
+        ('w:p/w:pPr',                         None),
+        ('w:p/w:pPr/w:spacing',               None),
+        ('w:p/w:pPr/w:spacing{w:before=240}', Pt(12)),
+    ])
+    def space_before_get_fixture(self, request):
+        p_cxml, expected_value = request.param
+        paragraph_format = ParagraphFormat(element(p_cxml))
+        return paragraph_format, expected_value
