parfmt: add ParagraphFormat.line_spacing getter

Steve Canny · Steve Canny · commit c38bf8eb0a67 · 2015-02-08T00:01:43.000-08:00
diff --git a/docx/oxml/text/paragraph.py b/docx/oxml/text/paragraph.py
@@ -4,9 +4,9 @@
 Custom element classes related to paragraphs (CT_P).
 """
 
-from ...enum.text import WD_ALIGN_PARAGRAPH
+from ...enum.text import WD_ALIGN_PARAGRAPH, WD_LINE_SPACING
 from ..ns import qn
-from ..simpletypes import ST_TwipsMeasure
+from ..simpletypes import ST_SignedTwipsMeasure, ST_TwipsMeasure
 from ..xmlchemy import (
     BaseOxmlElement, OptionalAttribute, OxmlElement, RequiredAttribute,
     ZeroOrMore, ZeroOrOne
@@ -161,6 +161,33 @@ def spacing_before(self, value):
             return
         self.get_or_add_spacing().before = value
 
+    @property
+    def spacing_line(self):
+        """
+        The value of `w:spacing/@w:line` or |None| if not present.
+        """
+        spacing = self.spacing
+        if spacing is None:
+            return None
+        return spacing.line
+
+    @property
+    def spacing_lineRule(self):
+        """
+        The value of `w:spacing/@w:lineRule` as a member of the
+        :ref:`WdLineSpacing` enumeration. Only the `MULTIPLE`, `EXACTLY`, and
+        `AT_LEAST` members are used. It is the responsibility of the client
+        to calculate the use of `SINGLE`, `DOUBLE`, and `MULTIPLE` based on
+        the value of `w:spacing/@w:line` if that behavior is desired.
+        """
+        spacing = self.spacing
+        if spacing is None:
+            return None
+        lineRule = spacing.lineRule
+        if lineRule is None and spacing.line is not None:
+            return WD_LINE_SPACING.MULTIPLE
+        return lineRule
+
     @property
     def style(self):
         """
@@ -193,3 +220,5 @@ class CT_Spacing(BaseOxmlElement):
     """
     after = OptionalAttribute('w:after', ST_TwipsMeasure)
     before = OptionalAttribute('w:before', ST_TwipsMeasure)
+    line = OptionalAttribute('w:line', ST_SignedTwipsMeasure)
+    lineRule = OptionalAttribute('w:lineRule', WD_LINE_SPACING)
diff --git a/docx/text/paragraph.py b/docx/text/paragraph.py
@@ -4,11 +4,14 @@
 Paragraph-related proxy types.
 """
 
-from __future__ import absolute_import, print_function, unicode_literals
+from __future__ import (
+    absolute_import, division, print_function, unicode_literals
+)
 
 from ..enum.style import WD_STYLE_TYPE
+from ..enum.text import WD_LINE_SPACING
 from .run import Run
-from ..shared import ElementProxy, Parented
+from ..shared import ElementProxy, Parented, Pt
 
 
 class Paragraph(Parented):
@@ -155,6 +158,23 @@ def alignment(self, value):
         pPr = self._element.get_or_add_pPr()
         pPr.jc_val = value
 
+    @property
+    def line_spacing(self):
+        """
+        |float| or |Length| value specifying the space between baselines in
+        successive lines of the paragraph. A value of |None| indicates line
+        spacing is inherited from the style hierarchy. A float value, e.g.
+        ``2.0`` or ``1.75``, indicates spacing is applied in multiples of
+        line heights. A |Length| value such as ``Pt(12)`` indicates spacing
+        is a fixed height. The |Pt| value class is a convenient way to apply
+        line spacing in units of points. Assigning |None| resets line spacing
+        to inherit from the style hierarchy.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return self._line_spacing(pPr.spacing_line, pPr.spacing_lineRule)
+
     @property
     def space_after(self):
         """
@@ -192,3 +212,18 @@ def space_before(self):
     @space_before.setter
     def space_before(self, value):
         self._element.get_or_add_pPr().spacing_before = value
+
+    @staticmethod
+    def _line_spacing(spacing_line, spacing_lineRule):
+        """
+        Return the line spacing value calculated from the combination of
+        *spacing_line* and *spacing_lineRule*. Returns a |float| number of
+        lines when *spacing_lineRule* is ``WD_LINE_SPACING.MULTIPLE``,
+        otherwise a |Length| object of absolute line height is returned.
+        Returns |None| when *spacing_line* is |None|.
+        """
+        if spacing_line is None:
+            return None
+        if spacing_lineRule == WD_LINE_SPACING.MULTIPLE:
+            return spacing_line / Pt(12)
+        return spacing_line
diff --git a/tests/text/test_paragraph.py b/tests/text/test_paragraph.py
@@ -315,6 +315,10 @@ def it_can_change_its_space_after(self, space_after_set_fixture):
         paragraph_format.space_after = value
         assert paragraph_format._element.xml == expected_xml
 
+    def it_knows_its_line_spacing(self, line_spacing_get_fixture):
+        paragraph_format, expected_value = line_spacing_get_fixture
+        assert paragraph_format.line_spacing == expected_value
+
     # fixtures -------------------------------------------------------
 
     @pytest.fixture(params=[
@@ -345,6 +349,19 @@ def alignment_set_fixture(self, request):
         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:line=420}',                    1.75),
+        ('w:p/w:pPr/w:spacing{w:line=840,w:lineRule=exact}',   Pt(42)),
+        ('w:p/w:pPr/w:spacing{w:line=840,w:lineRule=atLeast}', Pt(42)),
+    ])
+    def line_spacing_get_fixture(self, request):
+        p_cxml, expected_value = request.param
+        paragraph_format = ParagraphFormat(element(p_cxml))
+        return paragraph_format, expected_value
+
     @pytest.fixture(params=[
         ('w:p',                              None),
         ('w:p/w:pPr',                        None),
