refactor: enhance text and color handling with builder pattern support and new properties

ya7010 · ya7010 · commit d3546e2bc2cf · 2025-04-28T05:00:58.000+09:00
diff --git a/examples/color_text.py b/examples/color_text.py
@@ -0,0 +1,48 @@
+"""Simple example of using tppt."""
+
+from pathlib import Path
+
+import tppt
+
+EXAMPLE_DIR = Path(__file__).parent
+
+
+def main():
+    """Run the example."""
+    # Create a presentation using the builder pattern
+    presentation = (
+        tppt.Presentation.builder()
+        .slide(
+            lambda slide: slide.BlankLayout()
+            .builder()
+            .text(
+                lambda text: text.builder().text_frame(
+                    lambda text_frame: text_frame.builder().paragraph(
+                        lambda paragraph: paragraph.builder().run(
+                            lambda run: run.builder()
+                            .text("Hello, world!")
+                            .font(
+                                lambda font: font.builder().color(
+                                    lambda color: color.builder().rgb("#0000FF")
+                                )
+                            )
+                        )
+                    ),
+                ),
+                left=(50, "pt"),
+                top=(50, "pt"),
+                width=(400, "pt"),
+                height=(50, "pt"),
+            )
+        )
+        .build()
+    )
+
+    # Save the presentation
+    presentation.save(Path(__file__).with_suffix(".pptx"))
+
+    print("Rich Text presentation created successfully!")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/presentation_tree.json b/examples/presentation_tree.json
@@ -7,68 +7,11 @@
   "slides": [
     {
       "slide_id": 256,
-      "slide_layout_name": "Title Slide",
+      "slide_layout_name": "Blank",
       "shapes": [
         {
-          "name": "Title 1",
+          "name": "TextBox 1",
           "shape_id": 2,
-          "shape_type": "PLACEHOLDER (14)",
-          "has_text_frame": true,
-          "has_table": false,
-          "has_chart": false,
-          "width": 612.0,
-          "height": 115.75,
-          "rotation": 0.0,
-          "left": 54.0,
-          "top": 167.75,
-          "placeholder_type": 3,
-          "placeholder_idx": 0,
-          "text_frame": {
-            "text": "Hello, world!",
-            "paragraphs": [
-              {
-                "text": "Hello, world!",
-                "level": 0,
-                "runs": [
-                  {
-                    "text": "Hello, world!",
-                    "font": {
-                      "color": {}
-                    }
-                  }
-                ]
-              }
-            ]
-          }
-        },
-        {
-          "name": "Subtitle 2",
-          "shape_id": 3,
-          "shape_type": "PLACEHOLDER (14)",
-          "has_text_frame": true,
-          "has_table": false,
-          "has_chart": false,
-          "width": 504.0,
-          "height": 138.0,
-          "rotation": 0.0,
-          "left": 108.0,
-          "top": 306.0,
-          "placeholder_type": 4,
-          "placeholder_idx": 1,
-          "text_frame": {
-            "text": "",
-            "paragraphs": [
-              {
-                "text": "",
-                "level": 0,
-                "runs": []
-              }
-            ]
-          }
-        },
-        {
-          "name": "TextBox 3",
-          "shape_id": 4,
           "shape_type": "TEXT_BOX (17)",
           "has_text_frame": true,
           "has_table": false,
@@ -97,65 +40,7 @@
           }
         }
       ],
-      "placeholders": [
-        {
-          "name": "Title 1",
-          "shape_id": 2,
-          "shape_type": "PLACEHOLDER (14)",
-          "has_text_frame": true,
-          "has_table": false,
-          "has_chart": false,
-          "width": 612.0,
-          "height": 115.75,
-          "rotation": 0.0,
-          "left": 54.0,
-          "top": 167.75,
-          "placeholder_type": 3,
-          "placeholder_idx": 0,
-          "text_frame": {
-            "text": "Hello, world!",
-            "paragraphs": [
-              {
-                "text": "Hello, world!",
-                "level": 0,
-                "runs": [
-                  {
-                    "text": "Hello, world!",
-                    "font": {
-                      "color": {}
-                    }
-                  }
-                ]
-              }
-            ]
-          }
-        },
-        {
-          "name": "Subtitle 2",
-          "shape_id": 3,
-          "shape_type": "PLACEHOLDER (14)",
-          "has_text_frame": true,
-          "has_table": false,
-          "has_chart": false,
-          "width": 504.0,
-          "height": 138.0,
-          "rotation": 0.0,
-          "left": 108.0,
-          "top": 306.0,
-          "placeholder_type": 4,
-          "placeholder_idx": 1,
-          "text_frame": {
-            "text": "",
-            "paragraphs": [
-              {
-                "text": "",
-                "level": 0,
-                "runs": []
-              }
-            ]
-          }
-        }
-      ],
+      "placeholders": [],
       "notes_slide": {
         "shapes": [
           {
diff --git a/src/tppt/pptx/dml/color.py b/src/tppt/pptx/dml/color.py
@@ -25,7 +25,7 @@ class ColorFormatBuilder:
     def __init__(self, pptx_obj: PptxColorFormat) -> None:
         self._pptx = pptx_obj
 
-    def color(self, color: Color | LiteralColor) -> Self:
+    def rgb(self, color: Color | LiteralColor) -> Self:
         self._pptx.rgb = to_pptx_rgb_color(color)
 
         return self
diff --git a/src/tppt/pptx/shape/text.py b/src/tppt/pptx/shape/text.py
@@ -1,10 +1,10 @@
-from typing import Literal, NotRequired, Self
+from typing import Callable, Literal, NotRequired, Self
 
 from pptx.enum.text import MSO_ANCHOR, MSO_AUTO_SIZE, PP_ALIGN
 from pptx.shapes.autoshape import Shape as PptxShape
 
 from tppt.pptx.converter import to_pptx_length, to_pptx_rgb_color
-from tppt.pptx.text.text_frame import TextFrame
+from tppt.pptx.text.text_frame import TextFrame, TextFrameBuilder
 from tppt.types._color import Color, LiteralColor
 from tppt.types._length import Length, LiteralLength
 
@@ -70,8 +70,8 @@ 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 builder(self) -> "TextBuilder":
+        return TextBuilder(self._pptx)
 
     def to_pptx(self) -> PptxShape:
         """Convert to pptx shape."""
@@ -81,3 +81,20 @@ def to_pptx(self) -> PptxShape:
     def from_pptx(cls, pptx_obj: PptxShape) -> Self:
         """Create from pptx shape."""
         return cls(pptx_obj)
+
+
+class TextBuilder:
+    def __init__(self, pptx_obj: PptxShape) -> None:
+        self._pptx = pptx_obj
+
+    def text_frame(
+        self, callable: Callable[[TextFrame], TextFrame | TextFrameBuilder]
+    ) -> Self:
+        text_frame = callable(TextFrame(self._pptx.text_frame))
+        if isinstance(text_frame, TextFrameBuilder):
+            text_frame._build()
+
+        return self
+
+    def _build(self) -> Text:
+        return Text(self._pptx)
diff --git a/src/tppt/pptx/slide.py b/src/tppt/pptx/slide.py
@@ -1,18 +1,18 @@
 """Slide wrapper implementation."""
 
 import os
-from typing import IO, TYPE_CHECKING, Any, Callable, Self, Unpack
+from typing import IO, TYPE_CHECKING, Any, Callable, Self, Unpack, overload
 
 from pptx.slide import Slide as PptxSlide
 
 from tppt.types import FilePath
 
 from .converter import PptxConvertible, to_pptx_length
 from .placeholder import SlidePlaceholder
-from .shape import Shape
+from .shape import RangeProps, Shape
 from .shape.picture import Picture, PictureData, PictureProps
 from .shape.table import DataFrame, Table, TableData, TableProps, dataframe2list
-from .shape.text import Text, TextData, TextProps
+from .shape.text import Text, TextBuilder, TextData, TextProps
 from .slide_layout import SlideLayout
 from .snotes_slide import NotesSlide
 
@@ -91,8 +91,27 @@ def __init__(
         self._shape_registry: list[Callable[[Slide], Shape[Any]]] = []
         self._placeholder_registry = placeholder_registry
 
-    def text(self, text: str, **kwargs: Unpack[TextProps]) -> Self:
-        data = TextData(type="text", text=text, **kwargs)
+    @overload
+    def text(self, text: str, **kwargs: Unpack[TextProps]) -> Self: ...
+
+    @overload
+    def text(
+        self, text: Callable[[Text], Text | TextBuilder], **kwargs: Unpack[RangeProps]
+    ) -> Self: ...
+
+    def text(
+        self,
+        text: str | Callable[[Text], Text | TextBuilder],
+        **kwargs: Unpack[TextProps],
+    ) -> Self:
+        data = TextData(
+            type="text",
+            text=text if isinstance(text, str) else "",
+            top=kwargs["top"],
+            left=kwargs["left"],
+            width=kwargs["width"],
+            height=kwargs["height"],
+        )
 
         self._shape_registry.append(
             lambda slide: Text(
diff --git a/src/tppt/pptx/text/font.py b/src/tppt/pptx/text/font.py
@@ -1,19 +1,56 @@
-from typing import Self
+from typing import Callable, Self
 
 from pptx.text.text import Font as PptxFont
 
-from tppt.pptx.converter import PptxConvertible, to_pptx_length
-from tppt.pptx.dml.color import ColorFormat
+from tppt.pptx.converter import PptxConvertible, to_pptx_length, to_tppt_length
+from tppt.pptx.dml.color import ColorFormat, ColorFormatBuilder
 from tppt.types._length import Length, LiteralLength
 
 
 class Font(PptxConvertible[PptxFont]):
     def __init__(self, pptx_obj: PptxFont) -> None:
         self._pptx = pptx_obj
 
-    def color(self) -> ColorFormat:
+    @property
+    def name(self) -> str | None:
+        return self._pptx.name
+
+    @name.setter
+    def name(self, name: str) -> None:
+        self._pptx.name = name
+
+    @property
+    def size(self) -> Length | None:
+        return to_tppt_length(self._pptx.size)
+
+    @size.setter
+    def size(self, size: Length) -> None:
+        self._pptx.size = to_pptx_length(size)
+
+    @property
+    def bold(self) -> bool | None:
+        return self._pptx.bold
+
+    @bold.setter
+    def bold(self, bold: bool) -> None:
+        self._pptx.bold = bold
+
+    @property
+    def italic(self) -> bool | None:
+        return self._pptx.italic
+
+    @italic.setter
+    def italic(self, italic: bool) -> None:
+        self._pptx.italic = italic
+
+    @property
+    def color(self) -> ColorFormat | None:
         return ColorFormat(self._pptx.color)
 
+    @color.setter
+    def color(self, color: ColorFormat) -> None:
+        self._pptx.color = color.to_pptx()
+
     def builder(self) -> "FontBuilder":
         return FontBuilder(self._pptx)
 
@@ -49,5 +86,14 @@ def italic(self, italic: bool) -> Self:
 
         return self
 
+    def color(
+        self, callable: Callable[[ColorFormat], ColorFormat | ColorFormatBuilder]
+    ) -> Self:
+        color = callable(ColorFormat(self._pptx.color))
+        if isinstance(color, ColorFormatBuilder):
+            color._build()
+
+        return self
+
     def _build(self) -> Font:
         return Font(self._pptx)
diff --git a/src/tppt/pptx/text/paragraph.py b/src/tppt/pptx/text/paragraph.py
@@ -10,6 +10,10 @@ class Paragraph(PptxConvertible[PptxParagraph]):
     def __init__(self, pptx_obj: PptxParagraph) -> None:
         self._pptx = pptx_obj
 
+    @property
+    def runs(self) -> list[Run]:
+        return [Run(run) for run in self._pptx.runs]
+
     def builder(self) -> "ParagraphBuilder":
         return ParagraphBuilder(self._pptx)
 
diff --git a/src/tppt/pptx/text/run.py b/src/tppt/pptx/text/run.py
