api: add Document.add_paragraph()

Steve Canny · Steve Canny · commit 770db0a085b5 · 2014-01-02T19:52:22.000-08:00
Along the way:

* move DocumentPart.get_or_add_image_part() into proper sort order
diff --git a/docx/api.py b/docx/api.py
@@ -37,6 +37,19 @@ def add_inline_picture(self, image_path_or_stream):
         """
         return self.inline_shapes.add_picture(image_path_or_stream)
 
+    def add_paragraph(self, text='', style=None):
+        """
+        Return a paragraph newly added to the end of the document, populated
+        with *text* and having paragraph style *style*.
+        """
+        p = self._document_part.add_paragraph()
+        if text:
+            r = p.add_run()
+            r.add_text(text)
+        if style is not None:
+            p.style = style
+        return p
+
     @property
     def body(self):
         """
diff --git a/docx/parts/document.py b/docx/parts/document.py
@@ -28,18 +28,11 @@ def __init__(self, partname, content_type, document_elm, package):
         )
         self._element = document_elm
 
-    def get_or_add_image_part(self, image_descriptor):
+    def add_paragraph(self):
         """
-        Return an ``(image_part, rId)`` 2-tuple for the image identified by
-        *image_descriptor*. *image_part* is an |Image| instance corresponding
-        to the image, newly created if no matching image part is found. *rId*
-        is the key for the relationship between this document part and the
-        image part, reused if already present, newly created if not.
+        Return a paragraph newly added to the end of body content.
         """
-        image_parts = self._package.image_parts
-        image_part = image_parts.get_or_add_image_part(image_descriptor)
-        rId = self.relate_to(image_part, RT.IMAGE)
-        return (image_part, rId)
+        raise NotImplementedError
 
     @property
     def blob(self):
@@ -52,6 +45,19 @@ def body(self):
         """
         return _Body(self._element.body)
 
+    def get_or_add_image_part(self, image_descriptor):
+        """
+        Return an ``(image_part, rId)`` 2-tuple for the image identified by
+        *image_descriptor*. *image_part* is an |Image| instance corresponding
+        to the image, newly created if no matching image part is found. *rId*
+        is the key for the relationship between this document part and the
+        image part, reused if already present, newly created if not.
+        """
+        image_parts = self._package.image_parts
+        image_part = image_parts.get_or_add_image_part(image_descriptor)
+        rId = self.relate_to(image_part, RT.IMAGE)
+        return (image_part, rId)
+
     @lazyproperty
     def inline_shapes(self):
         """
diff --git a/tests/test_api.py b/tests/test_api.py
@@ -10,6 +10,7 @@
 from docx.opc.constants import CONTENT_TYPE as CT
 from docx.package import Package
 from docx.parts.document import DocumentPart, InlineShapes
+from docx.text import Paragraph, Run
 
 from .unitutil import class_mock, instance_mock, method_mock, var_mock
 
@@ -39,6 +40,23 @@ def it_should_raise_if_not_a_Word_file(self, Package_, package_, docx_):
         with pytest.raises(ValueError):
             Document._open(docx_)
 
+    def it_can_add_an_empty_paragraph(self, add_empty_paragraph_fixture):
+        document, document_part_, p_ = add_empty_paragraph_fixture
+        p = document.add_paragraph()
+        document_part_.add_paragraph.assert_called_once_with()
+        assert p is p_
+
+    def it_can_add_a_paragraph_of_text(self, add_text_paragraph_fixture):
+        document, text, p_, r_ = add_text_paragraph_fixture
+        p = document.add_paragraph(text)
+        p.add_run.assert_called_once_with()
+        r_.add_text.assert_called_once_with(text)
+
+    def it_can_add_a_styled_paragraph(self, add_styled_paragraph_fixture):
+        document, style, p_ = add_styled_paragraph_fixture
+        p = document.add_paragraph(style=style)
+        assert p.style == style
+
     def it_provides_access_to_the_document_body(self, document):
         body = document.body
         assert body is document._document_part.body
@@ -64,6 +82,10 @@ def it_can_save_the_package(self, save_fixture):
 
     # fixtures -------------------------------------------------------
 
+    @pytest.fixture
+    def add_empty_paragraph_fixture(self, document, document_part_, p_):
+        return document, document_part_, p_
+
     @pytest.fixture
     def add_picture_fixture(self, request, open_, document_part_):
         document = Document()
@@ -73,6 +95,16 @@ def add_picture_fixture(self, request, open_, document_part_):
         picture_shape_ = inline_shapes.add_picture.return_value
         return document, inline_shapes, image_path_, picture_shape_
 
+    @pytest.fixture
+    def add_styled_paragraph_fixture(self, document, p_):
+        style = 'foobaresque'
+        return document, style, p_
+
+    @pytest.fixture
+    def add_text_paragraph_fixture(self, document, p_, r_):
+        text = 'foobar\rbarfoo'
+        return document, text, p_, r_
+
     @pytest.fixture
     def default_docx_(self, request):
         return var_mock(request, 'docx.api._default_docx_path')
@@ -82,10 +114,12 @@ def document(self, open_):
         return Document()
 
     @pytest.fixture
-    def document_part_(self, request):
-        return instance_mock(
+    def document_part_(self, request, p_):
+        document_part_ = instance_mock(
             request, DocumentPart, content_type=CT.WML_DOCUMENT_MAIN
         )
+        document_part_.add_paragraph.return_value = p_
+        return document_part_
 
     @pytest.fixture
     def docx_(self, request):
@@ -106,6 +140,12 @@ def open_(self, request, document_part_, package_):
     def open_fixture(self, docx_, Package_, package_, document_part_):
         return docx_, Package_, package_, document_part_
 
+    @pytest.fixture
+    def p_(self, request, r_):
+        p_ = instance_mock(request, Paragraph)
+        p_.add_run.return_value = r_
+        return p_
+
     @pytest.fixture
     def Package_(self, request, package_):
         Package_ = class_mock(request, 'docx.api.Package')
@@ -118,6 +158,10 @@ def package_(self, request, document_part_):
         package_.main_document = document_part_
         return package_
 
+    @pytest.fixture
+    def r_(self, request):
+        return instance_mock(request, Run)
+
     @pytest.fixture
     def save_fixture(self, request, open_, package_):
         file_ = instance_mock(request, str)
