run: add Run.text getter

Steve Canny · Steve Canny · commit 7beb12487b15 · 2014-06-25T22:14:22.000-07:00
Upgraded to handle more of the run content elements.
diff --git a/docx/oxml/text.py b/docx/oxml/text.py
@@ -125,6 +125,7 @@ class CT_R(BaseOxmlElement):
     rPr = ZeroOrOne('w:rPr')
     t = ZeroOrMore('w:t')
     br = ZeroOrMore('w:br')
+    cr = ZeroOrMore('w:cr')
     tab = ZeroOrMore('w:tab')
     drawing = ZeroOrMore('w:drawing')
 
@@ -178,6 +179,23 @@ def style(self, style):
         rPr = self.get_or_add_rPr()
         rPr.style = style
 
+    @property
+    def text(self):
+        """
+        A string representing the textual content of this run, with content
+        child elements like ``<w:tab/>`` translated to their Python
+        equivalent.
+        """
+        text = ''
+        for child in self:
+            if child.tag == qn('w:t'):
+                text += child.text
+            elif child.tag == qn('w:tab'):
+                text += '\t'
+            elif child.tag in (qn('w:br'), qn('w:cr')):
+                text += '\n'
+        return text
+
     @property
     def underline(self):
         """
diff --git a/docx/text.py b/docx/text.py
@@ -160,7 +160,10 @@ def add_tab(self):
 
     def add_text(self, text):
         """
-        Add a text element to this run.
+        Returns a newly appended |Text| object (corresponding to a new
+        ``<w:t>`` child element) to the run, containing *text*. Compare with
+        the possibly more friendly approach of assigning text to the
+        :attr:`Run.text` property.
         """
         t = self._r.add_t(text)
         return Text(t)
@@ -351,13 +354,22 @@ def style(self, char_style):
     @property
     def text(self):
         """
-        A string formed by concatenating all the <w:t> elements present in
-        this run.
+        String formed by concatenating the text equivalent of each run
+        content child element into a Python string. Each ``<w:t>`` element
+        adds the text characters it contains. A ``<w:tab/>`` element adds
+        a ``\\t`` character. A ``<w:cr/>`` or ``<w:br>`` element each add
+        a ``\\n`` character. Note that a ``<w:br>`` element can indicate
+        a page break or column break as well as a line break. All ``<w:br>``
+        elements translate to a single ``\\n`` character regardless of their
+        type. All other content child elements, such as ``<w:drawing>``, are
+        ignored.
+
+        Assigning text to this property has the reverse effect, translating
+        each ``\\t`` character to a ``<w:tab/>`` element and each ``\\n`` or
+        ``\\r`` character to a ``<w:cr/>`` element. Any existing run content
+        is replaced. Run formatting is preserved.
         """
-        text = ''
-        for t in self._r.t_lst:
-            text += t.text
-        return text
+        return self._r.text
 
     @property
     def underline(self):
@@ -369,8 +381,8 @@ def underline(self):
         property removes any directly-applied underline value. A value of
         |False| indicates a directly-applied setting of no underline,
         overriding any inherited value. A value of |True| indicates single
-        underline. The values from ``WD_UNDERLINE`` are used to specify other
-        outline styles such as double, wavy, and dotted.
+        underline. The values from :ref:`WdUnderline` are used to specify
+        other outline styles such as double, wavy, and dotted.
         """
         return self._r.underline
 
diff --git a/tests/oxml/unitdata/text.py b/tests/oxml/unitdata/text.py
@@ -87,6 +87,10 @@ def a_caps():
     return CT_OnOffBuilder('w:caps')
 
 
+def a_cr():
+    return CT_EmptyBuilder('w:cr')
+
+
 def a_cs():
     return CT_OnOffBuilder('w:cs')
 
diff --git a/tests/test_text.py b/tests/test_text.py
@@ -18,7 +18,7 @@
 
 from .oxml.parts.unitdata.document import a_body
 from .oxml.unitdata.text import (
-    a_b, a_bCs, a_br, a_caps, a_cs, a_dstrike, a_p, a_pPr, a_pStyle,
+    a_b, a_bCs, a_br, a_caps, a_cr, a_cs, a_dstrike, a_p, a_pPr, a_pStyle,
     a_shadow, a_smallCaps, a_snapToGrid, a_specVanish, a_strike, a_t, a_tab,
     a_u, a_vanish, a_webHidden, an_emboss, an_i, an_iCs, an_imprint,
     an_oMath, a_noProof, an_outline, an_r, an_rPr, an_rStyle, an_rtl
@@ -212,17 +212,17 @@ def it_can_add_a_tab(self, add_tab_fixture):
         run.add_tab()
         assert run._r.xml == expected_xml
 
-    def it_knows_the_text_it_contains(self, text_prop_fixture):
-        run, expected_text = text_prop_fixture
-        assert run.text == expected_text
-
     def it_can_remove_its_content_while_preserving_formatting(
             self, clear_fixture):
         run, expected_xml = clear_fixture
         _run = run.clear()
         assert run._r.xml == expected_xml
         assert _run is run
 
+    def it_knows_the_text_it_contains(self, text_get_fixture):
+        run, expected_text = text_get_fixture
+        assert run.text == expected_text
+
     # fixtures -------------------------------------------------------
 
     @pytest.fixture(params=[
@@ -421,15 +421,17 @@ def style_set_fixture(self, request):
         expected_xml = self.r_bldr_with_style(after_style).xml()
         return run, after_style, expected_xml
 
-    @pytest.fixture
-    def text_prop_fixture(self, Text_):
-        r = (
-            an_r().with_nsdecls().with_child(
-                a_t().with_text('foo')).with_child(
-                a_t().with_text('bar'))
-        ).element
-        run = Run(r)
-        return run, 'foobar'
+    @pytest.fixture(params=[
+        (('',),                          ''),
+        (('xfoobar',),                   'foobar'),
+        (('bpage', 'xabc', 'xdef', 't'), '\nabcdef\t'),
+        (('xabc', 't', 'xdef', 'n'),     'abc\tdef\n'),
+    ])
+    def text_get_fixture(self, request):
+        content_children, expected_text = request.param
+        r_bldr = self.r_content_bldr(content_children)
+        run = Run(r_bldr.element)
+        return run, expected_text
 
     @pytest.fixture(params=[
         (None,     None),
@@ -471,11 +473,6 @@ def underline_set_fixture(self, request):
 
     # fixture components ---------------------------------------------
 
-    @pytest.fixture
-    def run(self):
-        r = an_r().with_nsdecls().element
-        return Run(r)
-
     def r_bldr_with_style(self, style):
         rPr_bldr = an_rPr()
         if style is not None:
@@ -490,6 +487,28 @@ def r_bldr_with_underline(self, underline_type):
         r_bldr = an_r().with_nsdecls().with_child(rPr_bldr)
         return r_bldr
 
+    def r_content_bldr(self, elm_codes):
+        """
+        Return a ``<w:r>`` builder having child elements indicated by
+        *elm_codes*.
+        """
+        r_bldr = an_r().with_nsdecls()
+        for e in elm_codes:
+            if e.startswith('x'):
+                r_bldr.with_child(a_t().with_text(e[1:]))
+            elif e == 't':
+                r_bldr.with_child(a_tab())
+            elif e.startswith('b'):
+                r_bldr.with_child(a_br().with_type(e[1:]))
+            elif e == 'n':
+                r_bldr.with_child(a_cr())
+        return r_bldr
+
+    @pytest.fixture
+    def run(self):
+        r = an_r().with_nsdecls().element
+        return Run(r)
+
     @pytest.fixture
     def Text_(self, request):
         return class_mock(request, 'docx.text.Text')
