refactor: add functional_text utility and enhance formatted_text example with new text styling options

Author: ya7010

examples/formatted_text.py

@@ -9,27 +9,74 @@
 
 
 def main():
-    def formatted_text(text: tppt.pptx.shape.text.Text) -> tppt.pptx.shape.text.Text:
+    def formatted_text(text: tppt.pptx.shape.text.Text, /) -> tppt.pptx.shape.text.Text:
         run = text.text_frame().add_paragraph().add_run()
         run.text = "Hello, world!"
         font = run.font
-        font.color.rgb = "#0000FF"
+        font.color.rgb = "#00FFFF"
         font.italic = True
 
         return text
 
+    def functional_text(
+        text_obj: tppt.pptx.shape.text.Text,
+        /,
+        *,
+        text: str,
+        bold: bool = False,
+        italic: bool = False,
+        color: tppt.types.Color | tppt.types.LiteralColor | None = None,
+    ) -> tppt.pptx.shape.text.Text:
+        run = text_obj.text_frame().add_paragraph().add_run()
+        run.text = text
+        font = run.font
+
+        if color is not None:
+            font.color.rgb = color
+        if bold:
+            font.bold = True
+        if italic:
+            font.italic = True
+
+        return text_obj
+
     """Run the example."""
     # Create a presentation using the builder pattern
     presentation = (
         tppt.Presentation.builder()
         .slide(
             lambda slide: slide.BlankLayout()
             .builder()
+            .text(
+                # Pattern build-in options
+                "This is a text",
+                left=(50, "pt"),
+                top=(50, "pt"),
+                width=(400, "pt"),
+                height=(50, "pt"),
+                bold=True,
+                italic=True,
+                color="#0000FF",
+            )
             .text(
                 # Pattern custom function
                 formatted_text,
                 left=(50, "pt"),
-                top=(50, "pt"),
+                top=(100, "pt"),
+                width=(400, "pt"),
+                height=(50, "pt"),
+            )
+            .text(
+                # Pattern use partial apply function
+                tppt.apply(
+                    functional_text,
+                    text="Hello, world!",
+                    bold=True,
+                    italic=True,
+                    color="#00FF00",
+                ),
+                left=(50, "pt"),
+                top=(150, "pt"),
                 width=(400, "pt"),
                 height=(50, "pt"),
             )

src/tppt/__init__.py

@@ -1,11 +1,39 @@
 """Typed Python PowerPoint Tool"""
 
+from typing import Callable, Concatenate, ParamSpec, TypeVar
+
 from tppt.pptx.presentation import Presentation
 from tppt.template.slide_layout import Placeholder, SlideLayout
 from tppt.template.slide_master import Layout, SlideMaster, slide_master
 
 from . import types as types
 
+T = TypeVar("T")
+P = ParamSpec("P")
+
+
+def apply(
+    func: Callable[Concatenate[T, P], T], *args: P.args, **kwargs: P.kwargs
+) -> Callable[[T], T]:
+    """
+    Partially applies the given function `func` with arguments `args` and keyword arguments `kwargs`,
+    returning a new function that takes only the first argument.
+
+    Args:
+        func: A function that takes a first argument of type `T` and variable arguments `P`, returning `T`
+        *args: Variable positional arguments to partially apply to `func`
+        **kwargs: Variable keyword arguments to partially apply to `func`
+
+    Returns:
+        A function that takes a single argument `x` and calls `func(x, *args, **kwargs)`
+    """
+
+    def wrapper(x: T) -> T:
+        return func(x, *args, **kwargs)
+
+    return wrapper
+
+
 __all__ = [
     "Presentation",
     "SlideLayout",
@@ -14,4 +42,5 @@
     "SlideMaster",
     "Layout",
     "slide_master",
+    "apply",
 ]