blk: add Document.iter_inner_content()

scanny · scanny · commit f46751fd9df3 · 2023-11-03T15:04:34.000-07:00
diff --git a/src/docx/blkcntnr.py b/src/docx/blkcntnr.py
@@ -8,7 +8,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Iterator
 
 from typing_extensions import TypeAlias
 
@@ -71,6 +71,10 @@ def add_table(self, rows: int, cols: int, width: Length) -> Table:
         self._element._insert_tbl(tbl)  #  # pyright: ignore[reportPrivateUsage]
         return Table(tbl, self)
 
+    def iter_inner_content(self) -> Iterator[Paragraph | Table]:
+        """Generate each `Paragraph` or `Table` in this container in document order."""
+        raise NotImplementedError
+
     @property
     def paragraphs(self):
         """A list containing the paragraphs in this container, in document order.
diff --git a/src/docx/document.py b/src/docx/document.py
@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-from typing import IO, TYPE_CHECKING, List
+from typing import IO, TYPE_CHECKING, Iterator, List
 
 from docx.blkcntnr import BlockItemContainer
 from docx.enum.section import WD_SECTION
@@ -124,6 +124,10 @@ def inline_shapes(self):
         """
         return self._part.inline_shapes
 
+    def iter_inner_content(self) -> Iterator[Paragraph | Table]:
+        """Generate each `Paragraph` or `Table` in this document in document order."""
+        return self._body.iter_inner_content()
+
     @property
     def paragraphs(self) -> List[Paragraph]:
         """The |Paragraph| instances in the document, in document order.
diff --git a/tests/test_document.py b/tests/test_document.py
@@ -5,12 +5,15 @@
 
 from __future__ import annotations
 
+from typing import cast
+
 import pytest
 
 from docx.document import Document, _Body
 from docx.enum.section import WD_SECTION
 from docx.enum.text import WD_BREAK
 from docx.opc.coreprops import CoreProperties
+from docx.oxml.document import CT_Document
 from docx.parts.document import DocumentPart
 from docx.section import Section, Sections
 from docx.settings import Settings
@@ -22,7 +25,7 @@
 from docx.text.run import Run
 
 from .unitutil.cxml import element, xml
-from .unitutil.mock import class_mock, instance_mock, method_mock, property_mock
+from .unitutil.mock import Mock, class_mock, instance_mock, method_mock, property_mock
 
 
 class DescribeDocument:
@@ -104,6 +107,16 @@ def it_provides_access_to_its_inline_shapes(self, inline_shapes_fixture):
         document, inline_shapes_ = inline_shapes_fixture
         assert document.inline_shapes is inline_shapes_
 
+    def it_can_iterate_the_inner_content_of_the_document(
+        self, body_prop_: Mock, body_: Mock, document_part_: Mock
+    ):
+        document_elm = cast(CT_Document, element("w:document"))
+        body_prop_.return_value = body_
+        body_.iter_inner_content.return_value = iter((1, 2, 3))
+        document = Document(document_elm, document_part_)
+
+        assert list(document.iter_inner_content()) == [1, 2, 3]
+
     def it_provides_access_to_its_paragraphs(self, paragraphs_fixture):
         document, paragraphs_ = paragraphs_fixture
         paragraphs = document.paragraphs
