para: add Paragraph.iter_inner_content()

Author: scanny

features/par-access-inner-content.feature

@@ -27,7 +27,6 @@ Feature: Access paragraph inner-content including hyperlinks
       | three        |   3   |
 
 
-  @wip
   Scenario: Paragraph.iter_inner_content() generates the paragraph's runs and hyperlinks
     Given a paragraph having three hyperlinks
      Then paragraph.iter_inner_content() generates the paragraph runs and hyperlinks

src/docx/oxml/text/paragraph.py

@@ -50,6 +50,11 @@ def clear_content(self):
         for child in self.xpath("./*[not(self::w:pPr)]"):
             self.remove(child)
 
+    @property
+    def inner_content_elements(self) -> List[CT_R | CT_Hyperlink]:
+        """Run and hyperlink children of the `w:p` element, in document order."""
+        return self.xpath("./w:r | ./w:hyperlink")
+
     @property
     def lastRenderedPageBreaks(self) -> List[CT_LastRenderedPageBreak]:
         """All `w:lastRenderedPageBreak` descendants of this paragraph.

src/docx/text/paragraph.py

@@ -2,14 +2,15 @@
 
 from __future__ import annotations
 
-from typing import List
+from typing import Iterator, List
 
 from typing_extensions import Self
 
 from docx import types as t
 from docx.enum.style import WD_STYLE_TYPE
 from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
 from docx.oxml.text.paragraph import CT_P
+from docx.oxml.text.run import CT_R
 from docx.shared import Parented
 from docx.styles.style import CharacterStyle, ParagraphStyle
 from docx.text.hyperlink import Hyperlink
@@ -90,6 +91,21 @@ def insert_paragraph_before(
             paragraph.style = style
         return paragraph
 
+    def iter_inner_content(self) -> Iterator[Run | Hyperlink]:
+        """Generate the runs and hyperlinks in this paragraph, in the order they appear.
+
+        The content in a paragraph consists of both runs and hyperlinks. This method
+        allows accessing each of those separately, in document order, for when the
+        precise position of the hyperlink within the paragraph text is important. Note
+        that a hyperlink itself contains runs.
+        """
+        for r_or_hlink in self._p.inner_content_elements:
+            yield (
+                Run(r_or_hlink, self)
+                if isinstance(r_or_hlink, CT_R)
+                else Hyperlink(r_or_hlink, self)
+            )
+
     @property
     def paragraph_format(self):
         """The |ParagraphFormat| object providing access to the formatting properties

tests/text/test_paragraph.py

@@ -1,6 +1,6 @@
 """Unit test suite for the docx.text.paragraph module."""
 
-from typing import cast
+from typing import List, cast
 
 import pytest
 
@@ -61,6 +61,27 @@ def it_provides_access_to_the_hyperlinks_it_contains(
         expected = ["Hyperlink" for _ in range(count)]
         assert actual == expected, f"expected: {expected}, got: {actual}"
 
+    @pytest.mark.parametrize(
+        ("p_cxml", "expected"),
+        [
+            ("w:p", []),
+            ("w:p/w:r", ["Run"]),
+            ("w:p/w:hyperlink", ["Hyperlink"]),
+            ("w:p/(w:r,w:hyperlink,w:r)", ["Run", "Hyperlink", "Run"]),
+            ("w:p/(w:hyperlink,w:r,w:hyperlink)", ["Hyperlink", "Run", "Hyperlink"]),
+        ],
+    )
+    def it_can_iterate_its_inner_content_items(
+        self, p_cxml: str, expected: List[str], fake_parent: t.StoryChild
+    ):
+        p = cast(CT_P, element(p_cxml))
+        paragraph = Paragraph(p, fake_parent)
+
+        inner_content = paragraph.iter_inner_content()
+
+        actual = [type(item).__name__ for item in inner_content]
+        assert actual == expected, f"expected: {expected}, got: {actual}"
+
     def it_knows_its_paragraph_style(self, style_get_fixture):
         paragraph, style_id_, style_ = style_get_fixture
         style = paragraph.style