blk: add BlockItemContainer.iter_inner_content()

Author: scanny

features/blk-iter-inner-content.feature

@@ -4,25 +4,21 @@ Feature: Iterate paragraphs and tables in document-order
   I need the ability to iterate the inner-content of a block-item-container
 
 
-  @wip
   Scenario: Document.iter_inner_content()
     Given a Document object with paragraphs and tables
      Then document.iter_inner_content() produces the block-items in document order
 
 
-  @wip
   Scenario: Header.iter_inner_content()
     Given a Header object with paragraphs and tables
      Then header.iter_inner_content() produces the block-items in document order
 
 
-  @wip
   Scenario: Footer.iter_inner_content()
     Given a Footer object with paragraphs and tables
      Then footer.iter_inner_content() produces the block-items in document order
 
 
-  @wip
   Scenario: _Cell.iter_inner_content()
     Given a _Cell object with paragraphs and tables
      Then cell.iter_inner_content() produces the block-items in document order

src/docx/blkcntnr.py

@@ -13,6 +13,7 @@
 from typing_extensions import TypeAlias
 
 from docx.oxml.table import CT_Tbl
+from docx.oxml.text.paragraph import CT_P
 from docx.shared import StoryChild
 from docx.text.paragraph import Paragraph
 
@@ -73,7 +74,14 @@ def add_table(self, rows: int, cols: int, width: Length) -> Table:
 
     def iter_inner_content(self) -> Iterator[Paragraph | Table]:
         """Generate each `Paragraph` or `Table` in this container in document order."""
-        raise NotImplementedError
+        from docx.table import Table
+
+        for element in self._element.inner_content_elements:
+            yield (
+                Paragraph(element, self)
+                if isinstance(element, CT_P)
+                else Table(element, self)
+            )
 
     @property
     def paragraphs(self):

tests/test_blkcntnr.py

@@ -2,13 +2,14 @@
 
 import pytest
 
+from docx import Document
 from docx.blkcntnr import BlockItemContainer
 from docx.shared import Inches
 from docx.table import Table
 from docx.text.paragraph import Paragraph
 
 from .unitutil.cxml import element, xml
-from .unitutil.file import snippet_seq
+from .unitutil.file import snippet_seq, test_file
 from .unitutil.mock import call, instance_mock, method_mock
 
 
@@ -34,6 +35,26 @@ def it_can_add_a_table(self, add_table_fixture):
         assert table._element.xml == expected_xml
         assert table._parent is blkcntnr
 
+    def it_can_iterate_its_inner_content(self):
+        document = Document(test_file("blk-inner-content.docx"))
+
+        inner_content = document.iter_inner_content()
+
+        para = next(inner_content)
+        assert isinstance(para, Paragraph)
+        assert para.text == "P1"
+        # --
+        t = next(inner_content)
+        assert isinstance(t, Table)
+        assert t.rows[0].cells[0].text == "T2"
+        # --
+        para = next(inner_content)
+        assert isinstance(para, Paragraph)
+        assert para.text == "P3"
+        # --
+        with pytest.raises(StopIteration):
+            next(inner_content)
+
     def it_provides_access_to_the_paragraphs_it_contains(self, paragraphs_fixture):
         # test len(), iterable, and indexed access
         blkcntnr, expected_count = paragraphs_fixture