doc: add Document.add_paragraph()

Steve Canny · Steve Canny · commit 4f983127cb00 · 2015-02-14T16:54:42.000-08:00
diff --git a/docx/document.py b/docx/document.py
@@ -24,6 +24,17 @@ def __init__(self, element, part):
         self._part = part
         self.__body = None
 
+    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*. *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 self._body.add_paragraph(text, style)
+
     @property
     def part(self):
         """
diff --git a/tests/test_document.py b/tests/test_document.py
@@ -12,13 +12,20 @@
 
 from docx.document import _Body, Document
 from docx.parts.document import DocumentPart
+from docx.text.paragraph import Paragraph
 
 from .unitutil.cxml import element
-from .unitutil.mock import class_mock, instance_mock
+from .unitutil.mock import class_mock, instance_mock, property_mock
 
 
 class DescribeDocument(object):
 
+    def it_can_add_a_paragraph(self, add_paragraph_fixture):
+        document, text, style, paragraph_ = add_paragraph_fixture
+        paragraph = document.add_paragraph(text, style)
+        document._body.add_paragraph.assert_called_once_with(text, style)
+        assert paragraph is paragraph_
+
     def it_provides_access_to_the_document_part(self, part_fixture):
         document, part_ = part_fixture
         assert document.part is part_
@@ -31,6 +38,17 @@ def it_provides_access_to_the_document_body(self, body_fixture):
 
     # fixtures -------------------------------------------------------
 
+    @pytest.fixture(params=[
+        ('',         None),
+        ('',         'Heading 1'),
+        ('foo\rbar', 'Body Text'),
+    ])
+    def add_paragraph_fixture(self, request, body_prop_, paragraph_):
+        text, style = request.param
+        document = Document(None, None)
+        body_prop_.return_value.add_paragraph.return_value = paragraph_
+        return document, text, style, paragraph_
+
     @pytest.fixture
     def body_fixture(self, _Body_, body_):
         document_elm = element('w:document/w:body')
@@ -53,6 +71,14 @@ def _Body_(self, request, body_):
     def body_(self, request):
         return instance_mock(request, _Body)
 
+    @pytest.fixture
+    def body_prop_(self, request):
+        return property_mock(request, Document, '_body')
+
     @pytest.fixture
     def document_part_(self, request):
         return instance_mock(request, DocumentPart)
+
+    @pytest.fixture
+    def paragraph_(self, request):
+        return instance_mock(request, Paragraph)
