sect: add Document.add_section()

Steve Canny · Steve Canny · commit a665ad154558 · 2014-06-22T14:10:37.000-07:00
Also, reorder fixtures a bit in test_api.py.
diff --git a/docx/api.py b/docx/api.py
@@ -10,6 +10,7 @@
 
 import os
 
+from docx.enum.section import WD_SECTION
 from docx.enum.text import WD_BREAK
 from docx.opc.constants import CONTENT_TYPE as CT, RELATIONSHIP_TYPE as RT
 from docx.package import Package
@@ -100,6 +101,13 @@ def add_picture(self, image_path_or_stream, width=None, height=None):
 
         return picture
 
+    def add_section(self, start_type=WD_SECTION.NEW_PAGE):
+        """
+        Return a |Section| object representing a new section added at the end
+        of the document.
+        """
+        return self._document_part.add_section(start_type)
+
     def add_table(self, rows, cols, style='LightShading-Accent1'):
         """
         Add a table having row and column counts of *rows* and *cols*
diff --git a/docx/parts/document.py b/docx/parts/document.py
@@ -10,6 +10,7 @@
 
 from collections import Sequence
 
+from ..enum.section import WD_SECTION
 from ..opc.constants import RELATIONSHIP_TYPE as RT
 from ..opc.oxml import serialize_part_xml
 from ..opc.package import Part
@@ -37,6 +38,13 @@ def add_paragraph(self):
         """
         return self.body.add_paragraph()
 
+    def add_section(self, start_type=WD_SECTION.NEW_PAGE):
+        """
+        Return a |Section| object representing a new section added at the end
+        of the document.
+        """
+        raise NotImplementedError
+
     def add_table(self, rows, cols):
         """
         Return a table having *rows* rows and *cols* columns, newly appended
diff --git a/tests/test_api.py b/tests/test_api.py
@@ -17,6 +17,7 @@
 from docx.parts.document import DocumentPart, InlineShapes
 from docx.parts.numbering import NumberingPart
 from docx.parts.styles import StylesPart
+from docx.section import Section
 from docx.table import Table
 from docx.text import Paragraph, Run
 
@@ -96,6 +97,14 @@ def it_can_add_a_picture(self, add_picture_fixture):
         assert picture.height == expected_height
         assert picture is picture_
 
+    def it_can_add_a_section(self, add_section_fixture):
+        document, start_type_, section_ = add_section_fixture
+        section = document.add_section(start_type_)
+        document._document_part.add_section.assert_called_once_with(
+            start_type_
+        )
+        assert section is section_
+
     def it_can_add_a_table(self, add_table_fixture):
         document, rows, cols, style, document_part_, expected_style, table_ = (
             add_table_fixture
@@ -200,6 +209,10 @@ def add_picture_fixture(
             expected_width, expected_height, picture_
         )
 
+    @pytest.fixture
+    def add_section_fixture(self, document, start_type_, section_):
+        return document, start_type_, section_
+
     @pytest.fixture
     def add_styled_paragraph_fixture(self, document, p_):
         style = 'foobaresque'
@@ -269,11 +282,13 @@ def document(self, open_):
         return Document()
 
     @pytest.fixture
-    def document_part_(self, request, p_, paragraphs_, table_, tables_):
+    def document_part_(
+            self, request, p_, paragraphs_, section_, table_, tables_):
         document_part_ = instance_mock(
             request, DocumentPart, content_type=CT.WML_DOCUMENT_MAIN
         )
         document_part_.add_paragraph.return_value = p_
+        document_part_.add_section.return_value = section_
         document_part_.add_table.return_value = table_
         document_part_.paragraphs = paragraphs_
         document_part_.tables = tables_
@@ -336,6 +351,14 @@ def paragraphs_(self, request):
     def r_(self, request):
         return instance_mock(request, Run)
 
+    @pytest.fixture
+    def section_(self, request):
+        return instance_mock(request, Section)
+
+    @pytest.fixture
+    def start_type_(self, request):
+        return instance_mock(request, int)
+
     @pytest.fixture
     def StylesPart_(self, request, styles_part_):
         StylesPart_ = class_mock(request, 'docx.api.StylesPart')
