run: add Run.iter_inner_content()

Author: scanny

features/run-access-inner-content.feature

@@ -15,7 +15,6 @@ Feature: Access run inner-content including rendered page-breaks
       | two          | True  |
 
 
-  @wip
   Scenario: Run.iter_inner_content() generates the run's text and rendered page-breaks
     Given a run having two rendered page breaks
      Then run.iter_inner_content() generates the run text and rendered page-breaks

src/docx/drawing/__init__.py

@@ -0,0 +1,16 @@
+"""DrawingML-related objects are in this subpackage."""
+
+from __future__ import annotations
+
+from docx import types as t
+from docx.oxml.drawing import CT_Drawing
+from docx.shared import Parented
+
+
+class Drawing(Parented):
+    """Container for a DrawingML object."""
+
+    def __init__(self, drawing: CT_Drawing, parent: t.StoryChild):
+        super().__init__(parent)
+        self._parent = parent
+        self._drawing = self._element = drawing

src/docx/oxml/__init__.py

@@ -5,7 +5,22 @@
 
 from __future__ import annotations
 
+from docx.oxml.drawing import CT_Drawing
 from docx.oxml.parser import register_element_cls
+from docx.oxml.shape import (
+    CT_Blip,
+    CT_BlipFillProperties,
+    CT_GraphicalObject,
+    CT_GraphicalObjectData,
+    CT_Inline,
+    CT_NonVisualDrawingProps,
+    CT_Picture,
+    CT_PictureNonVisual,
+    CT_Point2D,
+    CT_PositiveSize2D,
+    CT_ShapeProperties,
+    CT_Transform2D,
+)
 from docx.oxml.text.pagebreak import CT_LastRenderedPageBreak
 from docx.oxml.text.run import (
     CT_R,
@@ -16,6 +31,25 @@
     CT_Text,
 )
 
+# ---------------------------------------------------------------------------
+# DrawingML-related elements
+
+register_element_cls("a:blip", CT_Blip)
+register_element_cls("a:ext", CT_PositiveSize2D)
+register_element_cls("a:graphic", CT_GraphicalObject)
+register_element_cls("a:graphicData", CT_GraphicalObjectData)
+register_element_cls("a:off", CT_Point2D)
+register_element_cls("a:xfrm", CT_Transform2D)
+register_element_cls("pic:blipFill", CT_BlipFillProperties)
+register_element_cls("pic:cNvPr", CT_NonVisualDrawingProps)
+register_element_cls("pic:nvPicPr", CT_PictureNonVisual)
+register_element_cls("pic:pic", CT_Picture)
+register_element_cls("pic:spPr", CT_ShapeProperties)
+register_element_cls("w:drawing", CT_Drawing)
+register_element_cls("wp:docPr", CT_NonVisualDrawingProps)
+register_element_cls("wp:extent", CT_PositiveSize2D)
+register_element_cls("wp:inline", CT_Inline)
+
 # ---------------------------------------------------------------------------
 # text-related elements
 
@@ -78,36 +112,6 @@
 
 register_element_cls("w:settings", CT_Settings)
 
-from .shape import (  # noqa
-    CT_Blip,
-    CT_BlipFillProperties,
-    CT_GraphicalObject,
-    CT_GraphicalObjectData,
-    CT_Inline,
-    CT_NonVisualDrawingProps,
-    CT_Picture,
-    CT_PictureNonVisual,
-    CT_Point2D,
-    CT_PositiveSize2D,
-    CT_ShapeProperties,
-    CT_Transform2D,
-)
-
-register_element_cls("a:blip", CT_Blip)
-register_element_cls("a:ext", CT_PositiveSize2D)
-register_element_cls("a:graphic", CT_GraphicalObject)
-register_element_cls("a:graphicData", CT_GraphicalObjectData)
-register_element_cls("a:off", CT_Point2D)
-register_element_cls("a:xfrm", CT_Transform2D)
-register_element_cls("pic:blipFill", CT_BlipFillProperties)
-register_element_cls("pic:cNvPr", CT_NonVisualDrawingProps)
-register_element_cls("pic:nvPicPr", CT_PictureNonVisual)
-register_element_cls("pic:pic", CT_Picture)
-register_element_cls("pic:spPr", CT_ShapeProperties)
-register_element_cls("wp:docPr", CT_NonVisualDrawingProps)
-register_element_cls("wp:extent", CT_PositiveSize2D)
-register_element_cls("wp:inline", CT_Inline)
-
 from .styles import CT_LatentStyles, CT_LsdException, CT_Style, CT_Styles  # noqa
 
 register_element_cls("w:basedOn", CT_String)

src/docx/oxml/drawing.py

@@ -0,0 +1,11 @@
+"""Custom element-classes for DrawingML-related elements like `<w:drawing>`.
+
+For legacy reasons, many DrawingML-related elements are in `docx.oxml.shape`. Expect
+those to move over here as we have reason to touch them.
+"""
+
+from docx.oxml.xmlchemy import BaseOxmlElement
+
+
+class CT_Drawing(BaseOxmlElement):
+    """`<w:drawing>` element, containing a DrawingML object like a picture or chart."""

src/docx/oxml/text/run.py

@@ -2,12 +2,14 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Callable, List
+from typing import TYPE_CHECKING, Callable, Iterator, List
 
+from docx.oxml.drawing import CT_Drawing
 from docx.oxml.ns import qn
 from docx.oxml.simpletypes import ST_BrClear, ST_BrType
 from docx.oxml.text.font import CT_RPr
 from docx.oxml.xmlchemy import BaseOxmlElement, OptionalAttribute, ZeroOrMore, ZeroOrOne
+from docx.shared import TextAccumulator
 
 if TYPE_CHECKING:
     from docx.oxml.text.pagebreak import CT_LastRenderedPageBreak
@@ -52,6 +54,35 @@ def clear_content(self):
         for child in content_child_elms:
             self.remove(child)
 
+    @property
+    def inner_content_items(self) -> List[str | CT_Drawing | CT_LastRenderedPageBreak]:
+        """Text of run, possibly punctuated by `w:lastRenderedPageBreak` elements."""
+        from docx.oxml.text.pagebreak import CT_LastRenderedPageBreak
+
+        accum = TextAccumulator()
+
+        def iter_items() -> Iterator[str | CT_Drawing | CT_LastRenderedPageBreak]:
+            for e in self.xpath(
+                "w:br"
+                " | w:cr"
+                " | w:drawing"
+                " | w:lastRenderedPageBreak"
+                " | w:noBreakHyphen"
+                " | w:ptab"
+                " | w:t"
+                " | w:tab"
+            ):
+                if isinstance(e, (CT_Drawing, CT_LastRenderedPageBreak)):
+                    yield from accum.pop()
+                    yield e
+                else:
+                    accum.push(str(e))
+
+            # -- don't forget the "tail" string --
+            yield from accum.pop()
+
+        return list(iter_items())
+
     @property
     def lastRenderedPageBreaks(self) -> List[CT_LastRenderedPageBreak]:
         """All `w:lastRenderedPageBreaks` descendants of this run."""

src/docx/shared.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import functools
-from typing import TYPE_CHECKING, Any, Callable, Generic, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Callable, Generic, Iterator, List, TypeVar, cast
 
 if TYPE_CHECKING:
     from docx.oxml.xmlchemy import BaseOxmlElement
@@ -315,3 +315,32 @@ def __init__(self, parent):
     def part(self):
         """The package part containing this object."""
         return self._parent.part
+
+
+class TextAccumulator:
+    """Accepts `str` fragments and joins them together, in order, on `.pop().
+
+    Handy when text in a stream is broken up arbitrarily and you want to join it back
+    together within certain bounds. The optional `separator` argument determines how
+    the text fragments are punctuated, defaulting to the empty string.
+    """
+
+    def __init__(self, separator: str = ""):
+        self._separator = separator
+        self._texts: List[str] = []
+
+    def push(self, text: str) -> None:
+        """Add a text fragment to the accumulator."""
+        self._texts.append(text)
+
+    def pop(self) -> Iterator[str]:
+        """Generate sero-or-one str from those accumulated.
+
+        Using `yield from accum.pop()` in a generator setting avoids producing an empty
+        string when no text is in the accumulator.
+        """
+        if not self._texts:
+            return
+        text = self._separator.join(self._texts)
+        self._texts.clear()
+        yield text

src/docx/text/pagebreak.py

@@ -0,0 +1,29 @@
+"""Proxy objects related to rendered page-breaks."""
+
+from __future__ import annotations
+
+from docx import types as t
+from docx.oxml.text.pagebreak import CT_LastRenderedPageBreak
+from docx.shared import Parented
+
+
+class RenderedPageBreak(Parented):
+    """A page-break inserted by Word during page-layout for print or display purposes.
+
+    This usually does not correspond to a "hard" page-break inserted by the document
+    author, rather just that Word ran out of room on one page and needed to start
+    another. The position of these can change depending on the printer and page-size, as
+    well as margins, etc. They also will change in response to edits, but not until Word
+    loads and saves the document.
+
+    Note these are never inserted by `python-docx` because it has no rendering function.
+    These are generally only useful for text-extraction of existing documents when
+    `python-docx` is being used solely as a document "reader".
+    """
+
+    def __init__(
+        self, lastRenderedPageBreak: CT_LastRenderedPageBreak, parent: t.StoryChild
+    ):
+        super().__init__(parent)
+        self._element = lastRenderedPageBreak
+        self._lastRenderedPageBreak = lastRenderedPageBreak

src/docx/text/run.py

@@ -2,16 +2,20 @@
 
 from __future__ import annotations
 
-from typing import IO
+from typing import IO, Iterator
 
 from docx import types as t
+from docx.drawing import Drawing
 from docx.enum.style import WD_STYLE_TYPE
 from docx.enum.text import WD_BREAK
+from docx.oxml.drawing import CT_Drawing
+from docx.oxml.text.pagebreak import CT_LastRenderedPageBreak
 from docx.oxml.text.run import CT_R, CT_Text
 from docx.shape import InlineShape
 from docx.shared import Length, Parented
 from docx.styles.style import CharacterStyle
 from docx.text.font import Font
+from docx.text.pagebreak import RenderedPageBreak
 
 
 class Run(Parented):
@@ -135,6 +139,31 @@ def italic(self) -> bool:
     def italic(self, value: bool):
         self.font.italic = value
 
+    def iter_inner_content(self) -> Iterator[str | Drawing | RenderedPageBreak]:
+        """Generate the content-items in this run in the order they appear.
+
+        NOTE: only content-types currently supported by `python-docx` are generated. In
+        this version, that is text and rendered page-breaks. Drawing is included but
+        currently only provides access to its XML element (CT_Drawing) on its
+        `._drawing` attribute. `Drawing` attributes and methods may be expanded in
+        future releases.
+
+        There are a number of element-types that can appear inside a run, but most of
+        those (w:br, w:cr, w:noBreakHyphen, w:t, w:tab) have a clear plain-text
+        equivalent. Any contiguous range of such elements is generated as a single
+        `str`. Rendered page-break and drawing elements are generated individually. Any
+        other elements are ignored.
+        """
+        for item in self._r.inner_content_items:
+            if isinstance(item, str):
+                yield item
+            elif isinstance(item, CT_LastRenderedPageBreak):
+                yield RenderedPageBreak(item, self)
+            elif isinstance(  # pyright: ignore[reportUnnecessaryIsInstance]
+                item, CT_Drawing
+            ):
+                yield Drawing(item, self)
+
     @property
     def style(self) -> CharacterStyle | None:
         """Read/write.

tests/text/test_run.py

@@ -2,14 +2,16 @@
 
 from __future__ import annotations
 
-from typing import cast
+from typing import List, cast
 
 import pytest
 
+from docx import types as t
 from docx.enum.style import WD_STYLE_TYPE
 from docx.enum.text import WD_BREAK, WD_UNDERLINE
 from docx.oxml.text.run import CT_R
 from docx.parts.document import DocumentPart
+from docx.parts.story import StoryPart
 from docx.shape import InlineShape
 from docx.text.font import Font
 from docx.text.run import Run
@@ -19,6 +21,8 @@
 
 
 class DescribeRun(object):
+    """Unit-test suite for `docx.text.run.Run`."""
+
     def it_knows_its_bool_prop_states(self, bool_prop_get_fixture):
         run, prop_name, expected_state = bool_prop_get_fixture
         assert getattr(run, prop_name) == expected_state
@@ -45,6 +49,36 @@ def it_knows_whether_it_contains_a_page_break(
 
         assert run.contains_page_break == expected_value
 
+    @pytest.mark.parametrize(
+        ("r_cxml", "expected"),
+        [
+            # -- no content produces an empty iterator --
+            ("w:r", []),
+            # -- contiguous text content is condensed into a single str --
+            ('w:r/(w:t"foo",w:cr,w:t"bar")', ["str"]),
+            # -- page-breaks are a form of inner-content --
+            (
+                'w:r/(w:t"abc",w:br,w:lastRenderedPageBreak,w:noBreakHyphen,w:t"def")',
+                ["str", "RenderedPageBreak", "str"],
+            ),
+            # -- as are drawings --
+            (
+                'w:r/(w:t"abc", w:lastRenderedPageBreak, w:drawing)',
+                ["str", "RenderedPageBreak", "Drawing"],
+            ),
+        ],
+    )
+    def it_can_iterate_its_inner_content_items(
+        self, r_cxml: str, expected: List[str], fake_parent: t.StoryChild
+    ):
+        r = cast(CT_R, element(r_cxml))
+        run = Run(r, fake_parent)
+
+        inner_content = run.iter_inner_content()
+
+        actual = [type(item).__name__ for item in inner_content]
+        assert actual == expected, f"expected: {expected}, got: {actual}"
+
     def it_knows_its_character_style(self, style_get_fixture):
         run, style_id_, style_ = style_get_fixture
         style = run.style
@@ -244,6 +278,15 @@ def clear_fixture(self, request):
         expected_xml = xml(expected_cxml)
         return run, expected_xml
 
+    @pytest.fixture
+    def fake_parent(self) -> t.StoryChild:
+        class StoryChild:
+            @property
+            def part(self) -> StoryPart:
+                raise NotImplementedError
+
+        return StoryChild()
+
     @pytest.fixture
     def font_fixture(self, Font_, font_):
         run = Run(element("w:r"), None)