feat: introduce _Placeholder class and update TpptSlideLayout to use placeholders for field definitions

Author: ya7010

src/tppt/slide_layout.py

@@ -1,12 +1,114 @@
 import datetime
-from typing import TYPE_CHECKING, Any, Self, overload
+from inspect import isclass
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    ClassVar,
+    Self,
+    TypeVar,
+    dataclass_transform,
+    get_args,
+    get_origin,
+    get_type_hints,
+    overload,
+)
+
+from tppt.types import FilePath
 
 if TYPE_CHECKING:
     from tppt._pptx.slide import SlideBuilder
 
-
-class TpptSlideLayout:
-    """Base class for all slide layouts."""
+_AnyType = TypeVar("_AnyType")
+
+
+class _Placeholder:
+    def __init__(self, description: str = ""):
+        self.description = description
+        self.value = None
+
+    def __repr__(self) -> str:
+        return f"Placeholder({self.description!r})"
+
+    @classmethod
+    def __class_getitem__(cls, item: Any) -> Any:
+        return Annotated[item, cls()]
+
+
+Placeholder = Annotated[_AnyType, _Placeholder]
+
+
+class TpptSlideLayoutMeta(type):
+    """TpptSlideLayoutのメタクラス
+
+    プレースホルダーとして注釈されたフィールドを追跡します。
+    """
+
+    def __new__(
+        mcs, name: str, bases: tuple[type, ...], namespace: dict[str, Any]
+    ) -> type:
+        cls = super().__new__(mcs, name, bases, namespace)
+
+        # プレースホルダーフィールドを収集
+        annotations = get_type_hints(cls, include_extras=True)
+        placeholders = {}
+
+        for field_name, field_type in annotations.items():
+            # Annotatedフィールドを検索
+            if get_origin(field_type) is Annotated:
+                args = get_args(field_type)
+                # メタデータのチェック
+                metadata_args = args[1:]
+
+                # Placeholderとして直接マークされたフィールドを検索
+                if any(
+                    arg is _Placeholder
+                    or (isclass(arg) and arg.__name__ == "_Placeholder")
+                    for arg in metadata_args
+                ):
+                    placeholders[field_name] = args[0]  # 実際の型
+                    continue
+
+                # ネストされたAnnotatedのチェック (Placeholder[T]パターン)
+                # Placeholder[T] = Annotated[T, _Placeholder]のパターンを検出
+                base_type = args[0]
+                if get_origin(base_type) is Annotated:
+                    nested_args = get_args(base_type)
+                    if any(
+                        arg is _Placeholder
+                        or (isclass(arg) and arg.__name__ == "_Placeholder")
+                        for arg in nested_args[1:]
+                    ):
+                        placeholders[field_name] = nested_args[0]  # 実際の型
+                        continue
+
+        # プレースホルダー情報をクラスに保存
+        setattr(cls, "__placeholders__", placeholders)
+        return cls
+
+
+@dataclass_transform(
+    eq_default=True,
+    order_default=False,
+    field_specifiers=(),
+)
+class TpptSlideLayout(metaclass=TpptSlideLayoutMeta):
+    """スライドレイアウトのベースクラス"""
+
+    __placeholders__: ClassVar[dict[str, Any]] = {}
+
+    def __init__(self, **kwargs) -> None:
+        # すべてのフィールドに値を設定
+        for field_name, field_value in kwargs.items():
+            if field_name in self.__class__.__placeholders__:
+                # プレースホルダーフィールドの場合
+                setattr(self, field_name, field_value)
+            elif field_name in self.__class__.__annotations__:
+                setattr(self, field_name, field_value)
+            else:
+                raise TypeError(
+                    f"'{self.__class__.__name__}' got an unexpected keyword argument '{field_name}'"
+                )
 
     @overload
     def __get__(self, instance: None, objtype: type[Any]) -> type[Self]: ...
@@ -30,228 +132,107 @@ def builder(self) -> "SlideBuilder":
 class DefaultMasterSlide(TpptSlideLayout):
     """Default master slide layout."""
 
-    def __init__(
-        self,
-        *,
-        title: str,
-        text: str,
-        date: datetime.date | None = None,
-        footer: str | None = None,
-        slide_number: bool = True,
-    ) -> None:
-        self.title = title
-        self.text = text
-        self.date = date
-        self.footer = footer
-        self.slide_number = slide_number
+    title: Placeholder[str]
+    text: Placeholder[str]
+    date: Placeholder[datetime.date | None] = None
+    footer: Placeholder[str | None] = None
 
 
 class DefaultTitleSlide(TpptSlideLayout):
     """Title slide layout."""
 
-    def __init__(
-        self,
-        *,
-        title: str,
-        subtitle: str | None = None,
-        date: datetime.date | None = None,
-        footer: str | None = None,
-        slide_number: bool = True,
-    ) -> None:
-        self.title = title
-        self.subtitle = subtitle
-        self.date = date
-        self.footer = footer
-        self.slide_number = slide_number
+    title: Placeholder[str]
+    subtitle: Placeholder[str | None] = None
+    date: Placeholder[datetime.date | None] = None
+    footer: Placeholder[str | None] = None
 
 
 class DefaultTitleAndContentSlide(TpptSlideLayout):
     """Title and content slide layout."""
 
-    def __init__(
-        self,
-        *,
-        title: str,
-        content: str | None = None,
-        date: datetime.date | None = None,
-        footer: str | None = None,
-        slide_number: bool = True,
-    ) -> None:
-        self.title = title
-        self.content = content
-        self.date = date
-        self.footer = footer
-        self.slide_number = slide_number
+    title: Placeholder[str]
+    content: Placeholder[str]
+    date: Placeholder[datetime.date | None] = None
+    footer: Placeholder[str | None] = None
 
 
 class DefaultSectionHeaderSlide(TpptSlideLayout):
     """Section header slide layout."""
 
-    def __init__(
-        self,
-        *,
-        title: str,
-        text: str | None = None,
-        date: datetime.date | None = None,
-        footer: str | None = None,
-        slide_number: bool = True,
-    ) -> None:
-        self.title = title
-        self.text = text
-        self.date = date
-        self.footer = footer
-        self.slide_number = slide_number
+    title: Placeholder[str]
+    text: Placeholder[str]
+    date: Placeholder[datetime.date | None] = None
+    footer: Placeholder[str | None] = None
 
 
 class DefaultTwoContentSlide(TpptSlideLayout):
     """Two content slide layout."""
 
-    def __init__(
-        self,
-        *,
-        title: str,
-        left_content: str | None = None,
-        right_content: str | None = None,
-        date: datetime.date | None = None,
-        footer: str | None = None,
-        slide_number: bool = True,
-    ) -> None:
-        self.title = title
-        self.left_content = left_content
-        self.right_content = right_content
-        self.date = date
-        self.footer = footer
-        self.slide_number = slide_number
+    title: Placeholder[str]
+    left_content: Placeholder[str]
+    right_content: Placeholder[str]
+    date: Placeholder[datetime.date | None] = None
+    footer: Placeholder[str | None] = None
 
 
 class DefaultComparisonSlide(TpptSlideLayout):
     """Comparison slide layout."""
 
-    def __init__(
-        self,
-        *,
-        title: str,
-        left_title: str | None = None,
-        left_content: str | None = None,
-        right_title: str | None = None,
-        right_content: str | None = None,
-        date: datetime.date | None = None,
-        footer: str | None = None,
-        slide_number: bool = True,
-    ) -> None:
-        self.title = title
-        self.left_title = left_title
-        self.left_content = left_content
-        self.right_title = right_title
-        self.right_content = right_content
-        self.date = date
-        self.footer = footer
-        self.slide_number = slide_number
+    title: Placeholder[str]
+    left_title: Placeholder[str]
+    left_content: Placeholder[str]
+    right_title: Placeholder[str]
+    right_content: Placeholder[str]
+    date: Placeholder[datetime.date | None] = None
+    footer: Placeholder[str | None] = None
 
 
 class DefaultTitleOnlySlide(TpptSlideLayout):
     """Title only slide layout."""
 
-    def __init__(
-        self,
-        *,
-        title: str,
-        date: datetime.date | None = None,
-        footer: str | None = None,
-        slide_number: bool = True,
-    ) -> None:
-        self.title = title
-        self.date = date
-        self.footer = footer
-        self.slide_number = slide_number
+    title: Placeholder[str]
+    date: Placeholder[datetime.date | None] = None
+    footer: Placeholder[str | None] = None
 
 
 class DefaultBlankSlide(TpptSlideLayout):
     """Blank slide layout."""
 
-    def __init__(
-        self,
-        *,
-        date: datetime.date | None = None,
-        footer: str | None = None,
-        slide_number: bool = True,
-    ) -> None:
-        self.date = date
-        self.footer = footer
-        self.slide_number = slide_number
+    date: Placeholder[datetime.date | None] = None
+    footer: Placeholder[str | None] = None
 
 
 class DefaultContentWithCaptionSlide(TpptSlideLayout):
     """Content with caption slide layout."""
 
-    def __init__(
-        self,
-        *,
-        title: str,
-        content: str | None = None,
-        date: datetime.date | None = None,
-        footer: str | None = None,
-        slide_number: bool = True,
-    ) -> None:
-        self.title = title
-        self.content = content
-        self.date = date
-        self.footer = footer
-        self.slide_number = slide_number
+    title: Placeholder[str]
+    content: Placeholder[str]
+    date: Placeholder[datetime.date | None] = None
+    footer: Placeholder[str | None] = None
 
 
 class DefaultPictureWithCaptionSlide(TpptSlideLayout):
     """Picture with caption slide layout."""
 
-    def __init__(
-        self,
-        *,
-        title: str,
-        picture_path: str | None = None,
-        date: datetime.date | None = None,
-        footer: str | None = None,
-        slide_number: bool = True,
-    ) -> None:
-        self.title = title
-        self.picture_path = picture_path
-        self.date = date
-        self.footer = footer
-        self.slide_number = slide_number
+    title: Placeholder[str]
+    picture_path: Placeholder[FilePath]
+    date: Placeholder[datetime.date | None] = None
+    footer: Placeholder[str | None] = None
 
 
 class DefaultTitleAndVerticalTextSlide(TpptSlideLayout):
     """Title and vertical text slide layout."""
 
-    def __init__(
-        self,
-        *,
-        title: str,
-        vertical_text: str | None = None,
-        date: datetime.date | None = None,
-        footer: str | None = None,
-        slide_number: bool = True,
-    ) -> None:
-        self.title = title
-        self.vertical_text = vertical_text
-        self.date = date
-        self.footer = footer
-        self.slide_number = slide_number
+    title: Placeholder[str]
+    vertical_text: Placeholder[str]
+    date: Placeholder[datetime.date | None] = None
+    footer: Placeholder[str | None] = None
 
 
 class DefaultVerticalTitleAndTextSlide(TpptSlideLayout):
     """Vertical title and text slide layout."""
 
-    def __init__(
-        self,
-        *,
-        vertical_title: str,
-        text: str | None = None,
-        date: datetime.date | None = None,
-        footer: str | None = None,
-        slide_number: bool = True,
-    ) -> None:
-        self.vertical_title = vertical_title
-        self.text = text
-        self.date = date
-        self.footer = footer
-        self.slide_number = slide_number
+    vertical_title: Placeholder[str]
+    text: Placeholder[str]
+    date: Placeholder[datetime.date | None]
+    footer: Placeholder[str | None]