rfctr: resolve StoryChild conflation

We need one type for the base-class role and a different one for the
parameter-type role. The base-class is concrete, the parameter-type is
abstract.

Introduce `docx.types.ProvidesStoryPart` for the parameter-type role.
Add `ProvidesXmlPart` while we're at it for use by `ElementProxy`, which
probably needs a little more thought too.

Author: scanny

src/docx/drawing/__init__.py

@@ -10,7 +10,7 @@
 class Drawing(Parented):
     """Container for a DrawingML object."""
 
-    def __init__(self, drawing: CT_Drawing, parent: t.StoryChild):
+    def __init__(self, drawing: CT_Drawing, parent: t.ProvidesStoryPart):
         super().__init__(parent)
         self._parent = parent
         self._drawing = self._element = drawing

src/docx/text/hyperlink.py

@@ -23,7 +23,7 @@ class Hyperlink(Parented):
     stored.
     """
 
-    def __init__(self, hyperlink: CT_Hyperlink, parent: t.StoryChild):
+    def __init__(self, hyperlink: CT_Hyperlink, parent: t.ProvidesStoryPart):
         super().__init__(parent)
         self._parent = parent
         self._hyperlink = self._element = hyperlink

src/docx/text/pagebreak.py

@@ -36,7 +36,9 @@ class RenderedPageBreak(Parented):
     """
 
     def __init__(
-        self, lastRenderedPageBreak: CT_LastRenderedPageBreak, parent: t.StoryChild
+        self,
+        lastRenderedPageBreak: CT_LastRenderedPageBreak,
+        parent: t.ProvidesStoryPart,
     ):
         super().__init__(parent)
         self._element = lastRenderedPageBreak

src/docx/text/paragraph.py

@@ -6,6 +6,7 @@
 
 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
@@ -21,7 +22,7 @@
 class Paragraph(StoryChild):
     """Proxy object wrapping a `<w:p>` element."""
 
-    def __init__(self, p: CT_P, parent: StoryChild):
+    def __init__(self, p: CT_P, parent: t.ProvidesStoryPart):
         super(Paragraph, self).__init__(parent)
         self._p = self._element = p
 

src/docx/text/run.py

@@ -4,6 +4,7 @@
 
 from typing import IO, TYPE_CHECKING, Iterator, cast
 
+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
@@ -30,7 +31,7 @@ class Run(StoryChild):
     the style hierarchy.
     """
 
-    def __init__(self, r: CT_R, parent: StoryChild):
+    def __init__(self, r: CT_R, parent: t.ProvidesStoryPart):
         super().__init__(parent)
         self._r = self._element = self.element = r
 

src/docx/types.py

@@ -2,13 +2,17 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from typing_extensions import Protocol
 
-from docx.parts.story import StoryPart
+if TYPE_CHECKING:
+    from docx.opc.part import XmlPart
+    from docx.parts.story import StoryPart
 
 
-class StoryChild(Protocol):
-    """An object that can fulfill the `parent` role in a `Parented` class.
+class ProvidesStoryPart(Protocol):
+    """An object that provides access to the StoryPart.
 
     This type is for objects that have a story part like document or header as their
     root part.
@@ -17,3 +21,16 @@ class StoryChild(Protocol):
     @property
     def part(self) -> StoryPart:
         ...
+
+
+class ProvidesXmlPart(Protocol):
+    """An object that provides access to its XmlPart.
+
+    This type is for objects that need access to their part but it either isn't a
+    StoryPart or they don't care, possibly because they just need access to the package
+    or related parts.
+    """
+
+    @property
+    def part(self) -> XmlPart:
+        ...

tests/conftest.py

@@ -1,16 +1,21 @@
 """pytest fixtures that are shared across test modules."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
 import pytest
 
-from docx import types as t
-from docx.parts.story import StoryPart
+if TYPE_CHECKING:
+    from docx import types as t
+    from docx.parts.story import StoryPart
 
 
 @pytest.fixture
-def fake_parent() -> t.StoryChild:
-    class StoryChild:
+def fake_parent() -> t.ProvidesStoryPart:
+    class ProvidesStoryPart:
         @property
         def part(self) -> StoryPart:
             raise NotImplementedError
 
-    return StoryChild()
+    return ProvidesStoryPart()

tests/text/test_hyperlink.py

@@ -26,7 +26,7 @@ class DescribeHyperlink:
         ],
     )
     def it_knows_the_hyperlink_address(
-        self, hlink_cxml: str, expected_value: str, fake_parent: t.StoryChild
+        self, hlink_cxml: str, expected_value: str, fake_parent: t.ProvidesStoryPart
     ):
         hlink = cast(CT_Hyperlink, element(hlink_cxml))
         hyperlink = Hyperlink(hlink, fake_parent)
@@ -44,7 +44,7 @@ def it_knows_the_hyperlink_address(
         ],
     )
     def it_knows_whether_it_contains_a_page_break(
-        self, hlink_cxml: str, expected_value: bool, fake_parent: t.StoryChild
+        self, hlink_cxml: str, expected_value: bool, fake_parent: t.ProvidesStoryPart
     ):
         hlink = cast(CT_Hyperlink, element(hlink_cxml))
         hyperlink = Hyperlink(hlink, fake_parent)
@@ -59,7 +59,7 @@ def it_knows_whether_it_contains_a_page_break(
         ],
     )
     def it_knows_the_link_fragment_when_there_is_one(
-        self, hlink_cxml: str, expected_value: str, fake_parent: t.StoryChild
+        self, hlink_cxml: str, expected_value: str, fake_parent: t.ProvidesStoryPart
     ):
         hlink = cast(CT_Hyperlink, element(hlink_cxml))
         hyperlink = Hyperlink(hlink, fake_parent)
@@ -78,7 +78,7 @@ def it_knows_the_link_fragment_when_there_is_one(
         ],
     )
     def it_provides_access_to_the_runs_it_contains(
-        self, hlink_cxml: str, count: int, fake_parent: t.StoryChild
+        self, hlink_cxml: str, count: int, fake_parent: t.ProvidesStoryPart
     ):
         hlink = cast(CT_Hyperlink, element(hlink_cxml))
         hyperlink = Hyperlink(hlink, fake_parent)
@@ -100,7 +100,7 @@ def it_provides_access_to_the_runs_it_contains(
         ],
     )
     def it_knows_the_visible_text_of_the_link(
-        self, hlink_cxml: str, expected_text: str, fake_parent: t.StoryChild
+        self, hlink_cxml: str, expected_text: str, fake_parent: t.ProvidesStoryPart
     ):
         hlink = cast(CT_Hyperlink, element(hlink_cxml))
         hyperlink = Hyperlink(hlink, fake_parent)
@@ -122,7 +122,7 @@ def it_knows_the_visible_text_of_the_link(
         ],
     )
     def it_knows_the_full_url_for_web_addresses(
-        self, hlink_cxml: str, expected_value: str, fake_parent: t.StoryChild
+        self, hlink_cxml: str, expected_value: str, fake_parent: t.ProvidesStoryPart
     ):
         hlink = cast(CT_Hyperlink, element(hlink_cxml))
         hyperlink = Hyperlink(hlink, fake_parent)
@@ -132,7 +132,7 @@ def it_knows_the_full_url_for_web_addresses(
     # -- fixtures --------------------------------------------------------------------
 
     @pytest.fixture
-    def fake_parent(self, story_part: Mock, rel: Mock) -> t.StoryChild:
+    def fake_parent(self, story_part: Mock, rel: Mock) -> t.ProvidesStoryPart:
         class StoryChild:
             @property
             def part(self) -> StoryPart:

tests/text/test_pagebreak.py

@@ -17,7 +17,7 @@ class DescribeRenderedPageBreak:
     """Unit-test suite for the docx.text.pagebreak.RenderedPageBreak object."""
 
     def it_raises_on_preceding_fragment_when_page_break_is_not_first_in_paragrah(
-        self, fake_parent: t.StoryChild
+        self, fake_parent: t.ProvidesStoryPart
     ):
         p_cxml = 'w:p/(w:r/(w:t"abc",w:lastRenderedPageBreak,w:lastRenderedPageBreak))'
         p = cast(CT_P, element(p_cxml))
@@ -28,7 +28,7 @@ def it_raises_on_preceding_fragment_when_page_break_is_not_first_in_paragrah(
             page_break.preceding_paragraph_fragment
 
     def it_produces_None_for_preceding_fragment_when_page_break_is_leading(
-        self, fake_parent: t.StoryChild
+        self, fake_parent: t.ProvidesStoryPart
     ):
         """A page-break with no preceding content is "leading"."""
         p_cxml = 'w:p/(w:pPr/w:ind,w:r/(w:lastRenderedPageBreak,w:t"foo",w:t"bar"))'
@@ -41,7 +41,7 @@ def it_produces_None_for_preceding_fragment_when_page_break_is_leading(
         assert preceding_fragment is None
 
     def it_can_split_off_the_preceding_paragraph_content_when_in_a_run(
-        self, fake_parent: t.StoryChild
+        self, fake_parent: t.ProvidesStoryPart
     ):
         p_cxml = (
             "w:p/("
@@ -61,7 +61,7 @@ def it_can_split_off_the_preceding_paragraph_content_when_in_a_run(
         assert preceding_fragment._p.xml == xml(expected_cxml)
 
     def and_it_can_split_off_the_preceding_paragraph_content_when_in_a_hyperlink(
-        self, fake_parent: t.StoryChild
+        self, fake_parent: t.ProvidesStoryPart
     ):
         p_cxml = (
             "w:p/("
@@ -81,7 +81,7 @@ def and_it_can_split_off_the_preceding_paragraph_content_when_in_a_hyperlink(
         assert preceding_fragment._p.xml == xml(expected_cxml)
 
     def it_raises_on_following_fragment_when_page_break_is_not_first_in_paragrah(
-        self, fake_parent: t.StoryChild
+        self, fake_parent: t.ProvidesStoryPart
     ):
         p_cxml = 'w:p/(w:r/(w:lastRenderedPageBreak,w:lastRenderedPageBreak,w:t"abc"))'
         p = cast(CT_P, element(p_cxml))
@@ -92,7 +92,7 @@ def it_raises_on_following_fragment_when_page_break_is_not_first_in_paragrah(
             page_break.following_paragraph_fragment
 
     def it_produces_None_for_following_fragment_when_page_break_is_trailing(
-        self, fake_parent: t.StoryChild
+        self, fake_parent: t.ProvidesStoryPart
     ):
         """A page-break with no following content is "trailing"."""
         p_cxml = 'w:p/(w:pPr/w:ind,w:r/(w:t"foo",w:t"bar",w:lastRenderedPageBreak))'
@@ -105,7 +105,7 @@ def it_produces_None_for_following_fragment_when_page_break_is_trailing(
         assert following_fragment is None
 
     def it_can_split_off_the_following_paragraph_content_when_in_a_run(
-        self, fake_parent: t.StoryChild
+        self, fake_parent: t.ProvidesStoryPart
     ):
         p_cxml = (
             "w:p/("
@@ -125,7 +125,7 @@ def it_can_split_off_the_following_paragraph_content_when_in_a_run(
         assert following_fragment._p.xml == xml(expected_cxml)
 
     def and_it_can_split_off_the_following_paragraph_content_when_in_a_hyperlink(
-        self, fake_parent: t.StoryChild
+        self, fake_parent: t.ProvidesStoryPart
     ):
         p_cxml = (
             "w:p/("

tests/text/test_paragraph.py

@@ -31,7 +31,7 @@ class DescribeParagraph:
         ],
     )
     def it_knows_whether_it_contains_a_page_break(
-        self, p_cxml: str, expected_value: bool, fake_parent: t.StoryChild
+        self, p_cxml: str, expected_value: bool, fake_parent: t.ProvidesStoryPart
     ):
         p = cast(CT_P, element(p_cxml))
         paragraph = Paragraph(p, fake_parent)
@@ -50,7 +50,7 @@ def it_knows_whether_it_contains_a_page_break(
         ],
     )
     def it_provides_access_to_the_hyperlinks_it_contains(
-        self, p_cxml: str, count: int, fake_parent: t.StoryChild
+        self, p_cxml: str, count: int, fake_parent: t.ProvidesStoryPart
     ):
         p = cast(CT_P, element(p_cxml))
         paragraph = Paragraph(p, fake_parent)
@@ -72,7 +72,7 @@ def it_provides_access_to_the_hyperlinks_it_contains(
         ],
     )
     def it_can_iterate_its_inner_content_items(
-        self, p_cxml: str, expected: List[str], fake_parent: t.StoryChild
+        self, p_cxml: str, expected: List[str], fake_parent: t.ProvidesStoryPart
     ):
         p = cast(CT_P, element(p_cxml))
         paragraph = Paragraph(p, fake_parent)
@@ -120,7 +120,7 @@ def it_can_change_its_paragraph_style(self, style_set_fixture):
         ],
     )
     def it_provides_access_to_the_rendered_page_breaks_it_contains(
-        self, p_cxml: str, count: int, fake_parent: t.StoryChild
+        self, p_cxml: str, count: int, fake_parent: t.ProvidesStoryPart
     ):
         p = cast(CT_P, element(p_cxml))
         paragraph = Paragraph(p, fake_parent)