txt: add Run.add_break()

Steve Canny · Steve Canny · commit e386299e5f30 · 2013-12-31T17:45:58.000-08:00
Along the way:

* refactor existing DescribeRun test methods
* refactor CT_Text.new()
* remove leftover print statements in test_package.py
diff --git a/docx/enum/text.py b/docx/enum/text.py
@@ -0,0 +1,27 @@
+# encoding: utf-8
+
+"""
+Enumerations related to text in WordprocessingML files
+"""
+
+from __future__ import absolute_import, print_function, unicode_literals
+
+
+class WD_BREAK_TYPE(object):
+    """
+    Corresponds to WdBreakType enumeration
+    http://msdn.microsoft.com/en-us/library/office/ff195905.aspx
+    """
+    COLUMN = 8
+    LINE = 6
+    LINE_CLEAR_LEFT = 9
+    LINE_CLEAR_RIGHT = 10
+    LINE_CLEAR_ALL = 11  # added for consistency, not in MS version
+    PAGE = 7
+    SECTION_CONTINUOUS = 3
+    SECTION_EVEN_PAGE = 4
+    SECTION_NEXT_PAGE = 2
+    SECTION_ODD_PAGE = 5
+    TEXT_WRAPPING = 11
+
+WD_BREAK = WD_BREAK_TYPE
diff --git a/docx/oxml/__init__.py b/docx/oxml/__init__.py
@@ -45,7 +45,8 @@ class ValidationError(Exception):
 register_custom_element_class('w:tc', CT_Tc)
 register_custom_element_class('w:tr', CT_Row)
 
-from docx.oxml.text import CT_P, CT_PPr, CT_R, CT_Text
+from docx.oxml.text import CT_Br, CT_P, CT_PPr, CT_R, CT_Text
+register_custom_element_class('w:br', CT_Br)
 register_custom_element_class('w:p', CT_P)
 register_custom_element_class('w:pPr', CT_PPr)
 register_custom_element_class('w:pStyle', CT_String)
diff --git a/docx/oxml/text.py b/docx/oxml/text.py
@@ -10,6 +10,34 @@
 )
 
 
+class CT_Br(OxmlBaseElement):
+    """
+    ``<w:br>`` element, indicating a line, page, or column break in a run.
+    """
+    @classmethod
+    def new(cls):
+        """
+        Return a new ``<w:br>`` element.
+        """
+        return OxmlElement('w:br')
+
+    @property
+    def clear(self):
+        self.get(qn('w:clear'))
+
+    @clear.setter
+    def clear(self, clear_str):
+        self.set(qn('w:clear'), clear_str)
+
+    @property
+    def type(self):
+        self.get(qn('w:type'))
+
+    @type.setter
+    def type(self, type_str):
+        self.set(qn('w:type'), type_str)
+
+
 class CT_P(OxmlBaseElement):
     """
     ``<w:p>`` element, containing the properties and text for a paragraph.
@@ -155,6 +183,14 @@ class CT_R(OxmlBaseElement):
     """
     ``<w:r>`` element, containing the properties and text for a run.
     """
+    def add_br(self):
+        """
+        Return a newly appended CT_Br (<w:br>) child element.
+        """
+        br = CT_Br.new()
+        self.append(br)
+        return br
+
     def add_drawing(self, inline_or_anchor):
         """
         Return a newly appended ``CT_Drawing`` (``<w:drawing>``) child
@@ -192,10 +228,11 @@ class CT_Text(OxmlBaseElement):
     """
     ``<w:t>`` element, containing a sequence of characters within a run.
     """
-    @staticmethod
-    def new(text):
+    @classmethod
+    def new(cls, text):
         """
         Return a new ``<w:t>`` element.
         """
-        xml = '<w:t %s>%s</w:t>' % (nsdecls('w'), text)
-        return oxml_fromstring(xml)
+        t = OxmlElement('w:t')
+        t.text = text
+        return t
diff --git a/docx/text.py b/docx/text.py
@@ -4,6 +4,10 @@
 Text-related proxy types for python-docx, such as Paragraph and Run.
 """
 
+from __future__ import absolute_import, print_function, unicode_literals
+
+from docx.enum.text import WD_BREAK
+
 
 class Paragraph(object):
     """
@@ -49,6 +53,24 @@ def __init__(self, r_elm):
         super(Run, self).__init__()
         self._r = r_elm
 
+    def add_break(self, break_type=WD_BREAK.LINE):
+        """
+        Add a break element of *break_type* to this run.
+        """
+        type_, clear = {
+            WD_BREAK.LINE:             (None,           None),
+            WD_BREAK.PAGE:             ('page',         None),
+            WD_BREAK.COLUMN:           ('column',       None),
+            WD_BREAK.LINE_CLEAR_LEFT:  ('textWrapping', 'left'),
+            WD_BREAK.LINE_CLEAR_RIGHT: ('textWrapping', 'right'),
+            WD_BREAK.LINE_CLEAR_ALL:   ('textWrapping', 'all'),
+        }[break_type]
+        br = self._r.add_br()
+        if type_ is not None:
+            br.type = type_
+        if clear is not None:
+            br.clear = clear
+
     def add_text(self, text):
         """
         Add a text element to this run.
diff --git a/features/steps/text.py b/features/steps/text.py
@@ -9,6 +9,8 @@
 from behave import given, then, when
 
 from docx import Document
+from docx.enum.text import WD_BREAK
+from docx.oxml.shared import qn
 
 
 # given ===================================================
@@ -21,22 +23,30 @@ def given_a_run(context):
 
 # when ====================================================
 
+@when('I add a column break')
+def when_add_column_break(context):
+    run = context.run
+    run.add_break(WD_BREAK.COLUMN)
+
+
 @when('I add a line break')
 def when_add_line_break(context):
     run = context.run
     run.add_break()
 
 
+@when('I add a page break')
+def when_add_page_break(context):
+    run = context.run
+    run.add_break(WD_BREAK.PAGE)
+
+
 # then =====================================================
 
-@then('the last item in the run is a break')
-def then_last_item_in_run_is_a_break(context):
-    run = context.run
-    context.last_child = run._r[-1]
-    expected_tag = (
-        '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}br'
-    )
-    assert context.last_child.tag == expected_tag
+@then('it is a column break')
+def then_type_is_column_break(context):
+    attrib = context.last_child.attrib
+    assert attrib == {qn('w:type'): 'column'}
 
 
 @then('it is a line break')
@@ -48,10 +58,14 @@ def then_type_is_line_break(context):
 @then('it is a page break')
 def then_type_is_page_break(context):
     attrib = context.last_child.attrib
-    assert attrib == {'type': 'page'}
+    assert attrib == {qn('w:type'): 'page'}
 
 
-@then('it is a column break')
-def then_type_is_column_break(context):
-    attrib = context.last_child.attrib
-    assert attrib == {'type': 'column'}
+@then('the last item in the run is a break')
+def then_last_item_in_run_is_a_break(context):
+    run = context.run
+    context.last_child = run._r[-1]
+    expected_tag = (
+        '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}br'
+    )
+    assert context.last_child.tag == expected_tag
diff --git a/features/txt-add-break.feature b/features/txt-add-break.feature
@@ -3,21 +3,18 @@ Feature: Add a line, page, or column break
   As an python-docx developer
   I need the ability to add a line, page, or column break
 
-  @wip
   Scenario: Add a line break
     Given a run
      When I add a line break
      Then the last item in the run is a break
       And it is a line break
 
-  @wip
   Scenario: Add a page break
     Given a run
      When I add a page break
      Then the last item in the run is a break
       And it is a page break
 
-  @wip
   Scenario: Add a column break
     Given a run
      When I add a column break
diff --git a/tests/oxml/unitdata/text.py b/tests/oxml/unitdata/text.py
@@ -8,6 +8,12 @@
 from .shared import CT_StringBuilder
 
 
+class CT_BrBuilder(BaseBuilder):
+    __tag__ = 'w:br'
+    __nspfxs__ = ('w',)
+    __attrs__ = ('w:type', 'w:clear')
+
+
 class CT_PBuilder(BaseBuilder):
     __tag__ = 'w:p'
     __nspfxs__ = ('w',)
@@ -38,6 +44,10 @@ class CT_TextBuilder(BaseBuilder):
     __attrs__ = ()
 
 
+def a_br():
+    return CT_BrBuilder()
+
+
 def a_p():
     return CT_PBuilder()
 
diff --git a/tests/test_package.py b/tests/test_package.py
@@ -46,8 +46,6 @@ def it_knows_the_next_available_image_partname(
             self, next_partname_fixture):
         image_parts, ext, expected_partname = next_partname_fixture
         assert image_parts._next_image_partname(ext) == expected_partname
-        print('\n%s' % image_parts._next_image_partname(ext))
-        print(expected_partname)
 
     def it_can_really_add_a_new_image_part(
             self, really_add_image_part_fixture):
diff --git a/tests/test_text.py b/tests/test_text.py
@@ -4,13 +4,17 @@
 Test suite for the docx.text module
 """
 
+from __future__ import absolute_import, print_function, unicode_literals
+
+from docx.enum.text import WD_BREAK
 from docx.oxml.text import CT_P
 from docx.text import Paragraph, Run
 
 import pytest
 
 from mock import call, create_autospec, Mock
 
+from .oxml.unitdata.text import a_br, a_t, an_r
 from .unitutil import class_mock
 
 
@@ -68,27 +72,68 @@ def it_can_set_its_paragraph_style(self):
 
 class DescribeRun(object):
 
+    def it_can_add_text(self, add_text_fixture):
+        run, text_str, expected_xml, Text_ = add_text_fixture
+        _text = run.add_text(text_str)
+        assert run._r.xml == expected_xml
+        assert _text is Text_.return_value
+
+    def it_can_add_a_break(self, add_break_fixture):
+        run, break_type, expected_xml = add_break_fixture
+        run.add_break(break_type)
+        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
+
+    # fixtures -------------------------------------------------------
+
+    @pytest.fixture(params=[
+        'line', 'page', 'column', 'clr_lt', 'clr_rt', 'clr_all'
+    ])
+    def add_break_fixture(self, request, run):
+        type_, clear, break_type = {
+            'line':    (None,           None,    WD_BREAK.LINE),
+            'page':    ('page',         None,    WD_BREAK.PAGE),
+            'column':  ('column',       None,    WD_BREAK.COLUMN),
+            'clr_lt':  ('textWrapping', 'left',  WD_BREAK.LINE_CLEAR_LEFT),
+            'clr_rt':  ('textWrapping', 'right', WD_BREAK.LINE_CLEAR_RIGHT),
+            'clr_all': ('textWrapping', 'all',   WD_BREAK.LINE_CLEAR_ALL),
+        }[request.param]
+        # expected_xml -----------------
+        br_bldr = a_br()
+        if type_ is not None:
+            br_bldr.with_type(type_)
+        if clear is not None:
+            br_bldr.with_clear(clear)
+        expected_xml = an_r().with_nsdecls().with_child(br_bldr).xml()
+        return run, break_type, expected_xml
+
+    @pytest.fixture
+    def add_text_fixture(self, run, Text_):
+        text_str = 'foobar'
+        expected_xml = (
+            an_r().with_nsdecls().with_child(
+                a_t().with_text(text_str))
+        ).xml()
+        return run, text_str, expected_xml, Text_
+
+    @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')
 
-    def it_can_add_text_to_itself(self, Text_):
-        # mockery ----------------------
-        r_elm = Mock(name='r_elm')
-        r_elm.add_t.return_value = t_elm = Mock(name='t_elm')
-        text = Mock(name='text')
-        r = Run(r_elm)
-        # exercise ---------------------
-        t = r.add_text(text)
-        # verify -----------------------
-        r_elm.add_t.assert_called_once_with(text)
-        Text_.assert_called_once_with(t_elm)
-        assert t is Text_.return_value
-
-    def it_has_a_composite_of_the_text_it_contains(self):
-        # mockery ----------------------
-        t1, t2 = (Mock(name='t1', text='foo'), Mock(name='t2', text='bar'))
-        r_elm = Mock(name='r_elm', t_lst=[t1, t2])
-        r = Run(r_elm)
-        # verify -----------------------
-        assert r.text == 'foobar'
+    @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'
