doc: refactor _Body.add_paragraph()

Steve Canny · Steve Canny · commit 235e2f1571ba · 2014-07-17T22:21:54.000-07:00
* Migrate (text=‘’, style=None) interface for add_paragraph() down to
actual implementation so it can be shared when extracted to
BlockItemContainer.
* Combine unit tests for add_paragraph() in test_api.py
diff --git a/docx/api.py b/docx/api.py
@@ -69,12 +69,7 @@ def add_paragraph(self, text='', style=None):
         return (``\\r``) characters, each of which is converted to a line
         break.
         """
-        paragraph = self._document_part.add_paragraph()
-        if text:
-            paragraph.add_run(text)
-        if style is not None:
-            paragraph.style = style
-        return paragraph
+        return self._document_part.add_paragraph(text, style)
 
     def add_picture(self, image_path_or_stream, width=None, height=None):
         """
diff --git a/docx/parts/document.py b/docx/parts/document.py
@@ -24,11 +24,11 @@ class DocumentPart(XmlPart):
     """
     Main document part of a WordprocessingML (WML) package, aka a .docx file.
     """
-    def add_paragraph(self):
+    def add_paragraph(self, text='', style=None):
         """
         Return a paragraph newly added to the end of body content.
         """
-        return self.body.add_paragraph()
+        return self.body.add_paragraph(text, style)
 
     def add_section(self, start_type=WD_SECTION.NEW_PAGE):
         """
@@ -122,12 +122,20 @@ def __init__(self, body_elm, parent):
         super(_Body, self).__init__(parent)
         self._body = body_elm
 
-    def add_paragraph(self):
+    def add_paragraph(self, text='', style=None):
         """
-        Return a paragraph newly added to the end of body content.
+        Return a paragraph newly added to the end of body content, having
+        *text* in a single run if present, and having paragraph style
+        *style*. If *style* is |None|, no paragraph style is applied, which
+        has the same effect as applying the 'Normal' style.
         """
         p = self._body.add_p()
-        return Paragraph(p, self)
+        paragraph = Paragraph(p, self)
+        if text:
+            paragraph.add_run(text)
+        if style is not None:
+            paragraph.style = style
+        return paragraph
 
     def add_table(self, rows, cols):
         """
diff --git a/tests/parts/test_document.py b/tests/parts/test_document.py
@@ -66,7 +66,7 @@ def it_provides_access_to_the_inline_shapes_in_the_document(
     def it_can_add_a_paragraph(self, add_paragraph_fixture):
         document_part, body_, p_ = add_paragraph_fixture
         p = document_part.add_paragraph()
-        body_.add_paragraph.assert_called_once_with()
+        body_.add_paragraph.assert_called_once_with('', None)
         assert p is p_
 
     def it_can_add_a_section(self, add_section_fixture):
diff --git a/tests/test_api.py b/tests/test_api.py
@@ -66,22 +66,14 @@ def it_should_raise_on_heading_level_out_of_range(self, document):
         with pytest.raises(ValueError):
             document.add_heading(level=10)
 
-    def it_can_add_an_empty_paragraph(self, add_empty_paragraph_fixture):
-        document, document_part_, paragraph_ = add_empty_paragraph_fixture
-        paragraph = document.add_paragraph()
-        document_part_.add_paragraph.assert_called_once_with()
+    def it_can_add_a_paragraph(self, add_paragraph_fixture):
+        document, document_part_, text, style, paragraph_ = (
+            add_paragraph_fixture
+        )
+        paragraph = document.add_paragraph(text, style)
+        document_part_.add_paragraph.assert_called_once_with(text, style)
         assert paragraph is paragraph_
 
-    def it_can_add_a_paragraph_of_text(self, add_text_paragraph_fixture):
-        document, text = add_text_paragraph_fixture
-        paragraph = document.add_paragraph(text)
-        paragraph.add_run.assert_called_once_with(text)
-
-    def it_can_add_a_styled_paragraph(self, add_styled_paragraph_fixture):
-        document, style = add_styled_paragraph_fixture
-        paragraph = document.add_paragraph(style=style)
-        assert paragraph.style == style
-
     def it_can_add_a_page_break(self, add_page_break_fixture):
         document, document_part_, paragraph_, run_ = add_page_break_fixture
         paragraph = document.add_page_break()
@@ -177,10 +169,15 @@ def it_creates_styles_part_on_first_access_if_not_present(
 
     # fixtures -------------------------------------------------------
 
-    @pytest.fixture
-    def add_empty_paragraph_fixture(
-            self, document, document_part_, paragraph_):
-        return document, document_part_, paragraph_
+    @pytest.fixture(params=[
+        ('',         None),
+        ('',         'Heading1'),
+        ('foo\rbar', 'BodyText'),
+    ])
+    def add_paragraph_fixture(
+            self, request, document, document_part_, paragraph_):
+        text, style = request.param
+        return document, document_part_, text, style, paragraph_
 
     @pytest.fixture(params=[0, 1, 2, 5, 9])
     def add_heading_fixture(
@@ -208,11 +205,6 @@ def add_picture_fixture(self, request, run_, picture_):
     def add_section_fixture(self, document, start_type_, section_):
         return document, start_type_, section_
 
-    @pytest.fixture
-    def add_styled_paragraph_fixture(self, document):
-        style = 'foobaresque'
-        return document, style
-
     @pytest.fixture(params=[None, 'LightShading-Accent1', 'foobar'])
     def add_table_fixture(self, request, document, document_part_, table_):
         rows, cols = 4, 2
@@ -222,11 +214,6 @@ def add_table_fixture(self, request, document, document_part_, table_):
             table_
         )
 
-    @pytest.fixture
-    def add_text_paragraph_fixture(self, document):
-        text = 'foobar\rbarfoo'
-        return document, text
-
     @pytest.fixture
     def init_fixture(self, docx_, open_):
         return docx_, open_
