tbl: add _Cell.add_paragraph()

Steve Canny · Steve Canny · commit 56a5af9fe265 · 2014-07-18T00:04:18.000-07:00
* use super() rather than direct inheritance to allow custom docstring
diff --git a/docx/table.py b/docx/table.py
@@ -100,6 +100,20 @@ def __init__(self, tc, parent):
         super(_Cell, self).__init__(tc, parent)
         self._tc = tc
 
+    def add_paragraph(self, text='', style=None):
+        """
+        Return a paragraph newly added to the end of the content in this
+        cell. If present, *text* is added to the paragraph in a single run.
+        If specified, the paragraph style *style* is applied. If *style* is
+        not specified or is |None|, the result is as though the 'Normal'
+        style was applied. Note that the formatting of text in a cell can be
+        influenced by the table style. *text* can contain tab (``\\t``)
+        characters, which are converted to the appropriate XML form for
+        a tab. *text* can also include newline (``\\n``) or carriage return
+        (``\\r``) characters, each of which is converted to a line break.
+        """
+        return super(_Cell, self).add_paragraph(text, style)
+
     @property
     def paragraphs(self):
         """
diff --git a/tests/test_table.py b/tests/test_table.py
@@ -151,6 +151,12 @@ def table(self):
 
 class Describe_Cell(object):
 
+    def it_can_add_a_paragraph(self, add_paragraph_fixture):
+        cell, expected_xml = add_paragraph_fixture
+        p = cell.add_paragraph()
+        assert cell._tc.xml == expected_xml
+        assert isinstance(p, Paragraph)
+
     def it_provides_access_to_the_paragraphs_it_contains(
             self, paragraphs_fixture):
         cell = paragraphs_fixture
@@ -181,6 +187,17 @@ def it_can_change_its_width(self, width_set_fixture):
 
     # fixtures -------------------------------------------------------
 
+    @pytest.fixture(params=[
+        ('w:tc',       'w:tc/w:p'),
+        ('w:tc/w:p',   'w:tc/(w:p, w:p)'),
+        ('w:tc/w:tbl', 'w:tc/(w:tbl, w:p)'),
+    ])
+    def add_paragraph_fixture(self, request):
+        tc_cxml, after_tc_cxml = request.param
+        cell = _Cell(element(tc_cxml), None)
+        expected_xml = xml(after_tc_cxml)
+        return cell, expected_xml
+
     @pytest.fixture
     def paragraphs_fixture(self):
         return _Cell(element('w:tc/(w:p, w:p)'), None)
