doc: add Document.add_page_break()

Steve Canny · Steve Canny · commit aaae2e6028e2 · 2015-02-14T17:58:09.000-08:00
diff --git a/docx/document.py b/docx/document.py
@@ -9,6 +9,7 @@
 )
 
 from .blkcntnr import BlockItemContainer
+from .enum.text import WD_BREAK
 from .shared import ElementProxy
 
 
@@ -38,6 +39,15 @@ def add_heading(self, text='', level=1):
         style = 'Title' if level == 0 else 'Heading %d' % level
         return self.add_paragraph(text, style)
 
+    def add_page_break(self):
+        """
+        Return a paragraph newly added to the end of the document and
+        containing only a page break.
+        """
+        paragraph = self.add_paragraph()
+        paragraph.add_run().add_break(WD_BREAK.PAGE)
+        return paragraph
+
     def add_paragraph(self, text='', style=None):
         """
         Return a paragraph newly added to the end of the document, populated
diff --git a/tests/test_document.py b/tests/test_document.py
@@ -11,8 +11,10 @@
 import pytest
 
 from docx.document import _Body, Document
+from docx.enum.text import WD_BREAK
 from docx.parts.document import DocumentPart
 from docx.text.paragraph import Paragraph
+from docx.text.run import Run
 
 from .unitutil.cxml import element
 from .unitutil.mock import (
@@ -35,6 +37,14 @@ def it_raises_on_heading_level_out_of_range(self):
         with pytest.raises(ValueError):
             document.add_heading(level=10)
 
+    def it_can_add_a_page_break(self, add_page_break_fixture):
+        document, paragraph_, run_ = add_page_break_fixture
+        paragraph = document.add_page_break()
+        document.add_paragraph.assert_called_once_with()
+        paragraph_.add_run.assert_called_once_with()
+        run_.add_break.assert_called_once_with(WD_BREAK.PAGE)
+        assert paragraph is paragraph_
+
     def it_can_add_a_paragraph(self, add_paragraph_fixture):
         document, text, style, paragraph_ = add_paragraph_fixture
         paragraph = document.add_paragraph(text, style)
@@ -66,6 +76,13 @@ def add_heading_fixture(self, request, add_paragraph_, paragraph_):
         add_paragraph_.return_value = paragraph_
         return document, text, level, style, paragraph_
 
+    @pytest.fixture
+    def add_page_break_fixture(self, add_paragraph_, paragraph_, run_):
+        document = Document(None, None)
+        add_paragraph_.return_value = paragraph_
+        paragraph_.add_run.return_value = run_
+        return document, paragraph_, run_
+
     @pytest.fixture(params=[
         ('',         None),
         ('',         'Heading 1'),
@@ -114,3 +131,7 @@ def document_part_(self, request):
     @pytest.fixture
     def paragraph_(self, request):
         return instance_mock(request, Paragraph)
+
+    @pytest.fixture
+    def run_(self, request):
+        return instance_mock(request, Run)
