para: add Paragraph.insert_paragraph_before()

Steve Canny · Steve Canny · commit 65db85311e9d · 2014-06-24T21:53:48.000-07:00
diff --git a/docx/oxml/text.py b/docx/oxml/text.py
@@ -9,7 +9,7 @@
 from .ns import qn
 from .simpletypes import ST_BrClear, ST_BrType
 from .xmlchemy import (
-    BaseOxmlElement, OptionalAttribute, ZeroOrMore, ZeroOrOne
+    BaseOxmlElement, OptionalAttribute, OxmlElement, ZeroOrMore, ZeroOrOne
 )
 
 
@@ -32,6 +32,14 @@ def _insert_pPr(self, pPr):
         self.insert(0, pPr)
         return pPr
 
+    def add_p_before(self):
+        """
+        Return a new ``<w:p>`` element inserted directly prior to this one.
+        """
+        new_p = OxmlElement('w:p')
+        self.addprevious(new_p)
+        return new_p
+
     def set_sectPr(self, sectPr):
         """
         Unconditionally replace or add *sectPr* as a grandchild in the
diff --git a/docx/text.py b/docx/text.py
@@ -71,6 +71,20 @@ def add_run(self, text=None, style=None):
             run.style = style
         return run
 
+    def insert_paragraph_before(self, text=None, style=None):
+        """
+        Return a newly created paragraph, inserted directly before this
+        paragraph, and having its text set to *text* and style set to
+        *style*.
+        """
+        p = self._p.add_p_before()
+        paragraph = Paragraph(p)
+        if text:
+            paragraph.add_run(text)
+        if style is not None:
+            paragraph.style = style
+        return paragraph
+
     @property
     def runs(self):
         """
diff --git a/features/par-insert-paragraph.feature b/features/par-insert-paragraph.feature
@@ -4,7 +4,6 @@ Feature: Insert a paragraph before or after a paragraph
   I need a way to insert a paragraph relative to another paragraph
 
 
-  @wip
   Scenario: Add a new paragraph above an existing paragraph
     Given a document containing three paragraphs
      When I insert a paragraph above the second paragraph
diff --git a/tests/test_text.py b/tests/test_text.py
@@ -9,16 +9,18 @@
 )
 
 from docx.enum.text import WD_BREAK, WD_UNDERLINE
+from docx.oxml.ns import qn
 from docx.oxml.text import CT_P, CT_R
 from docx.text import Paragraph, Run
 
 import pytest
 
+from .oxml.parts.unitdata.document import a_body
 from .oxml.unitdata.text import (
-    a_b, a_bCs, a_br, a_caps, a_cs, a_dstrike, a_p, a_shadow, a_smallCaps,
-    a_snapToGrid, a_specVanish, a_strike, a_t, a_u, a_vanish, a_webHidden,
-    an_emboss, an_i, an_iCs, an_imprint, an_oMath, a_noProof, an_outline,
-    an_r, an_rPr, an_rStyle, an_rtl
+    a_b, a_bCs, a_br, a_caps, a_cs, a_dstrike, a_p, a_pPr, a_pStyle,
+    a_shadow, a_smallCaps, a_snapToGrid, a_specVanish, a_strike, a_t, a_u,
+    a_vanish, a_webHidden, an_emboss, an_i, an_iCs, an_imprint, an_oMath,
+    a_noProof, an_outline, an_r, an_rPr, an_rStyle, an_rtl
 )
 from .unitutil import call, class_mock, instance_mock, Mock
 
@@ -62,6 +64,14 @@ def it_knows_the_text_it_contains(self, text_prop_fixture):
         p, expected_text = text_prop_fixture
         assert p.text == expected_text
 
+    def it_can_insert_a_paragraph_before_itself(self, insert_before_fixture):
+        paragraph, text, style, body, expected_xml = insert_before_fixture
+        new_paragraph = paragraph.insert_paragraph_before(text, style)
+        assert isinstance(new_paragraph, Paragraph)
+        assert new_paragraph.text == text
+        assert new_paragraph.style == style
+        assert body.xml == expected_xml
+
     # fixtures -------------------------------------------------------
 
     @pytest.fixture(params=[
@@ -79,6 +89,26 @@ def add_run_fixture(self, request, paragraph):
         expected_xml = a_p().with_nsdecls().with_child(r_bldr).xml()
         return paragraph, text, style, expected_xml
 
+    @pytest.fixture
+    def insert_before_fixture(self):
+        text, style = 'foobar', 'Heading1'
+        body = (
+            a_body().with_nsdecls().with_child(
+                a_p())
+        ).element
+        p = body.find(qn('w:p'))
+        paragraph = Paragraph(p)
+        expected_xml = (
+            a_body().with_nsdecls().with_child(
+                a_p().with_child(
+                    a_pPr().with_child(
+                        a_pStyle().with_val(style))).with_child(
+                    an_r().with_child(
+                        a_t().with_text(text)))).with_child(
+                a_p())
+        ).xml()
+        return paragraph, text, style, body, expected_xml
+
     # fixture components ---------------------------------------------
 
     @pytest.fixture
