refactor: introduce TextFrame, Paragraph, and Run classes with builder support for improved text handling

Author: ya7010

src/tppt/pptx/shape/text.py

@@ -4,6 +4,7 @@
 from pptx.shapes.autoshape import Shape as PptxShape
 
 from tppt.pptx.converter import to_pptx_color, to_pptx_length
+from tppt.pptx.text.text_frame import TextFrame
 from tppt.types._color import Color, LiteralColor
 from tppt.types._length import Length, LiteralLength
 
@@ -69,6 +70,9 @@ def __init__(self, pptx_obj: PptxShape, data: TextData | None = None, /) -> None
 
         self._pptx = pptx_obj
 
+    def text_frame(self) -> TextFrame:
+        return TextFrame(self._pptx.text_frame)
+
     def to_pptx(self) -> PptxShape:
         """Convert to pptx shape."""
         return self._pptx

src/tppt/pptx/text/__init__.py

@@ -0,0 +1,41 @@
+from typing import Callable, Self
+
+from pptx.text.text import _Paragraph as PptxParagraph
+
+from tppt.pptx.converter import PptxConvertible
+from tppt.pptx.text.run import Run, RunBuilder
+
+
+class Paragraph(PptxConvertible[PptxParagraph]):
+    def __init__(self, pptx_obj: PptxParagraph) -> None:
+        self._pptx = pptx_obj
+
+    def builder(self) -> "ParagraphBuilder":
+        return ParagraphBuilder(self._pptx)
+
+    def to_pptx(self) -> PptxParagraph:
+        return self._pptx
+
+    @classmethod
+    def from_pptx(cls, pptx_obj: PptxParagraph) -> Self:
+        return cls(pptx_obj)
+
+
+class ParagraphBuilder:
+    def __init__(self, pptx_obj: PptxParagraph) -> None:
+        self._pptx = pptx_obj
+
+    def text(self, text: str) -> "ParagraphBuilder":
+        self._pptx.text = text
+
+        return self
+
+    def run(self, callable: Callable[[Run], Run | RunBuilder]) -> "ParagraphBuilder":
+        run = callable(Run(self._pptx.add_run()))
+        if isinstance(run, RunBuilder):
+            run._build()
+
+        return self
+
+    def _build(self) -> Paragraph:
+        return Paragraph(self._pptx)

src/tppt/pptx/text/paragraph.py

@@ -0,0 +1,28 @@
+from typing import Self
+
+from pptx.text.text import _Run as PptxRun
+
+from tppt.pptx.converter import PptxConvertible
+
+
+class Run(PptxConvertible[PptxRun]):
+    def __init__(self, pptx_obj: PptxRun) -> None:
+        self._pptx = pptx_obj
+
+    def builder(self) -> "RunBuilder":
+        return RunBuilder(self._pptx)
+
+    def to_pptx(self) -> PptxRun:
+        return self._pptx
+
+    @classmethod
+    def from_pptx(cls, pptx_obj: PptxRun) -> Self:
+        return cls(pptx_obj)
+
+
+class RunBuilder:
+    def __init__(self, pptx_obj: PptxRun) -> None:
+        self._pptx = pptx_obj
+
+    def _build(self) -> Run:
+        return Run(self._pptx)

src/tppt/pptx/text/run.py

@@ -0,0 +1,38 @@
+from typing import Callable, Self
+
+from pptx.text.text import TextFrame as PptxTextFrame
+
+from tppt.pptx.converter import PptxConvertible
+from tppt.pptx.text.paragraph import Paragraph, ParagraphBuilder
+
+
+class TextFrame(PptxConvertible[PptxTextFrame]):
+    def __init__(self, pptx_obj: PptxTextFrame) -> None:
+        self._pptx = pptx_obj
+
+    def builder(self) -> "TextFrameBuilder":
+        return TextFrameBuilder(self._pptx)
+
+    def to_pptx(self) -> PptxTextFrame:
+        return self._pptx
+
+    @classmethod
+    def from_pptx(cls, pptx_obj: PptxTextFrame) -> Self:
+        return cls(pptx_obj)
+
+
+class TextFrameBuilder:
+    def __init__(self, pptx_obj: PptxTextFrame) -> None:
+        self._pptx = pptx_obj
+
+    def paragraph(
+        self, callable: Callable[[Paragraph], Paragraph | ParagraphBuilder]
+    ) -> "TextFrameBuilder":
+        paragraph = callable(Paragraph(self._pptx.add_paragraph()))
+        if isinstance(paragraph, ParagraphBuilder):
+            paragraph._build()
+
+        return self
+
+    def _build(self) -> TextFrame:
+        return TextFrame(self._pptx)