para: add Paragraph.clear()

Steve Canny · Steve Canny · commit 70f0605fea2a · 2014-06-26T16:33:47.000-07:00
diff --git a/docx/oxml/text.py b/docx/oxml/text.py
@@ -40,6 +40,15 @@ def add_p_before(self):
         self.addprevious(new_p)
         return new_p
 
+    def clear_content(self):
+        """
+        Remove all child elements, except the ``<w:pPr>`` element if present.
+        """
+        for child in self[:]:
+            if child.tag == qn('w:pPr'):
+                continue
+            self.remove(child)
+
     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
@@ -75,6 +75,14 @@ def add_run(self, text=None, style=None):
             run.style = style
         return run
 
+    def clear(self):
+        """
+        Return this same paragraph after removing all its content.
+        Paragraph-level formatting, such as style, is preserved.
+        """
+        self._p.clear_content()
+        return self
+
     def insert_paragraph_before(self, text=None, style=None):
         """
         Return a newly created paragraph, inserted directly before this
diff --git a/features/par-clear-paragraph.feature b/features/par-clear-paragraph.feature
@@ -4,7 +4,6 @@ Feature: Clear paragraph content
   I need a way to remove the content of a paragraph
 
 
-  @wip
   Scenario: Clear paragraph content
     Given a paragraph with content and formatting
      When I clear the paragraph content
diff --git a/tests/test_text.py b/tests/test_text.py
@@ -73,6 +73,13 @@ def it_can_insert_a_paragraph_before_itself(self, insert_before_fixture):
         assert new_paragraph.style == style
         assert body.xml == expected_xml
 
+    def it_can_remove_its_content_while_preserving_formatting(
+            self, clear_fixture):
+        paragraph, expected_xml = clear_fixture
+        _paragraph = paragraph.clear()
+        assert paragraph._p.xml == expected_xml
+        assert _paragraph is paragraph
+
     # fixtures -------------------------------------------------------
 
     @pytest.fixture(params=[
@@ -90,6 +97,24 @@ 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 clear_fixture(self, request):
+        """
+        After XML should be before XML with content removed. So snapshot XML
+        after adding formatting but before adding content to get after XML.
+        """
+        style, text = ('Heading1', 'foo\tbar')
+        p = OxmlElement('w:p')
+        # expected_xml -----------------
+        if style is not None:
+            p.style = style
+        expected_xml = p.xml
+        # paragraph --------------------
+        paragraph = Paragraph(p)
+        if text is not None:
+            paragraph.add_run(text)
+        return paragraph, expected_xml
+
     @pytest.fixture
     def insert_before_fixture(self):
         text, style = 'foobar', 'Heading1'
