oxml: add .inner_content_elements props

Author: scanny

src/docx/oxml/document.py

@@ -77,3 +77,12 @@ def clear_content(self):
  """
  for content_elm in self.xpath("./*[not(self::w:sectPr)]"):
  self.remove(content_elm)
+
+ @property
+ def inner_content_elements(self) -> List[CT_P | CT_Tbl]:
+ """Generate all `w:p` and `w:tbl` elements in this document-body.
+
+ Elements appear in document order. Elements shaded by nesting in a `w:ins` or
+ other "wrapper" element will not be included.
+ """
+ return self.xpath("./w:p | ./w:tbl")

src/docx/oxml/section.py

@@ -38,6 +38,15 @@ class CT_HdrFtr(BaseOxmlElement):
  p = ZeroOrMore("w:p", successors=())
  tbl = ZeroOrMore("w:tbl", successors=())
 
+ @property
+ def inner_content_elements(self) -> List[CT_P | CT_Tbl]:
+ """Generate all `w:p` and `w:tbl` elements in this header or footer.
+
+ Elements appear in document order. Elements shaded by nesting in a `w:ins` or
+ other "wrapper" element will not be included.
+ """
+ return self.xpath("./w:p | ./w:tbl")
+
 
 class CT_HdrFtrRef(BaseOxmlElement):
  """`w:headerReference` and `w:footerReference` elements."""

src/docx/oxml/table.py

@@ -415,6 +415,15 @@ def grid_span(self, value):
  tcPr = self.get_or_add_tcPr()
  tcPr.grid_span = value
 
+ @property
+ def inner_content_elements(self) -> List[CT_P | CT_Tbl]:
+ """Generate all `w:p` and `w:tbl` elements in this document-body.
+
+ Elements appear in document order. Elements shaded by nesting in a `w:ins` or
+ other "wrapper" element will not be included.
+ """
+ return self.xpath("./w:p | ./w:tbl")
+
  def iter_block_items(self):
  """Generate a reference to each of the block-level content elements in this
  cell, in the order they appear."""

tests/oxml/test_document.py

@@ -0,0 +1,19 @@
+"""Unit-test suite for `docx.oxml.document` module."""
+
+from __future__ import annotations
+
+from typing import cast
+
+from docx.oxml.document import CT_Body
+from docx.oxml.table import CT_Tbl
+from docx.oxml.text.paragraph import CT_P
+
+from ..unitutil.cxml import element
+
+
+class DescribeCT_Body:
+ """Unit-test suite for selected units of `docx.oxml.document.CT_Body`."""
+
+ def it_knows_its_inner_content_block_item_elements(self):
+ body = cast(CT_Body, element("w:body/(w:tbl, w:p,w:p)"))
+ assert [type(e) for e in body.inner_content_elements] == [CT_Tbl, CT_P, CT_P]

tests/oxml/test_section.py

@@ -0,0 +1,19 @@
+"""Unit-test suite for `docx.oxml.section` module."""
+
+from __future__ import annotations
+
+from typing import cast
+
+from docx.oxml.section import CT_HdrFtr
+from docx.oxml.table import CT_Tbl
+from docx.oxml.text.paragraph import CT_P
+
+from ..unitutil.cxml import element
+
+
+class DescribeCT_HdrFtr:
+ """Unit-test suite for selected units of `docx.oxml.section.CT_HdrFtr`."""
+
+ def it_knows_its_inner_content_block_item_elements(self):
+ hdr = cast(CT_HdrFtr, element("w:hdr/(w:tbl,w:tbl,w:p)"))
+ assert [type(e) for e in hdr.inner_content_elements] == [CT_Tbl, CT_Tbl, CT_P]

tests/oxml/test_table.py

@@ -2,11 +2,14 @@
 
 from __future__ import annotations
 
+from typing import cast
+
 import pytest
 
 from docx.exceptions import InvalidSpanError
 from docx.oxml.parser import parse_xml
-from docx.oxml.table import CT_Row, CT_Tc
+from docx.oxml.table import CT_Row, CT_Tbl, CT_Tc
+from docx.oxml.text.paragraph import CT_P
 
 from ..unitutil.cxml import element, xml
 from ..unitutil.file import snippet_seq
@@ -102,6 +105,10 @@ def it_can_extend_its_horz_span_to_help_merge(
  ]
  assert tc.vMerge == vMerge
 
+ def it_knows_its_inner_content_block_item_elements(self):
+ tc = cast(CT_Tc, element("w:tc/(w:p,w:tbl,w:p)"))
+ assert [type(e) for e in tc.inner_content_elements] == [CT_P, CT_Tbl, CT_P]
+
  def it_can_swallow_the_next_tc_help_merge(self, swallow_fixture):
  tc, grid_width, top_tc, tr, expected_xml = swallow_fixture
  tc._swallow_next_tc(grid_width, top_tc)