refactor: reorganize table module and enhance angle type handling

Author: ya7010

src/tppt/pptx/converter.py

@@ -1,6 +1,14 @@
 """Type definitions for pptx wrapper."""
 
-from typing import Protocol, Self, TypeVar, assert_never, overload, runtime_checkable
+from typing import (
+    Protocol,
+    Self,
+    TypeAlias,
+    TypeVar,
+    assert_never,
+    overload,
+    runtime_checkable,
+)
 
 from pptx.dml.color import RGBColor as PptxRGBColor
 from pptx.util import Cm as PptxCm
@@ -10,6 +18,7 @@
 from pptx.util import Mm as PptxMm
 from pptx.util import Pt as PptxPt
 
+from tppt.types._angle import Angle, Degrees, LiteralAngle
 from tppt.types._color import Color, LiteralColor, to_color
 from tppt.types._length import (
     CentiMeters,
@@ -107,3 +116,38 @@ def to_tppt_color(color: PptxRGBColor | None) -> Color | None: ...
 
 def to_tppt_color(color: PptxRGBColor | None) -> Color | None:
     return Color(*color) if color else None
+
+
+PptxAngle: TypeAlias = float
+
+
+@overload
+def to_pptx_angle(angle: Angle | LiteralAngle) -> PptxAngle: ...
+
+
+@overload
+def to_pptx_angle(angle: Angle | LiteralAngle | None) -> PptxAngle | None: ...
+
+
+def to_pptx_angle(angle: Angle | LiteralAngle | None) -> PptxAngle | None:
+    match angle:
+        case Degrees():
+            return angle._value
+        case tuple():
+            return angle[0]
+        case None:
+            return None
+        case _:
+            assert_never(angle)
+
+
+@overload
+def to_tppt_angle(angle: PptxAngle) -> Angle: ...
+
+
+@overload
+def to_tppt_angle(angle: PptxAngle | None) -> Angle | None: ...
+
+
+def to_tppt_angle(angle: PptxAngle | None) -> Angle | None:
+    return Degrees(angle) if angle else None

src/tppt/pptx/dml/color.py

@@ -1,6 +1,7 @@
 from typing import Self
 
 from pptx.dml.color import ColorFormat as PptxColorFormat
+from pptx.enum.dml import MSO_THEME_COLOR
 
 from tppt.pptx.converter import PptxConvertible, to_pptx_rgb_color, to_tppt_color
 from tppt.types import Color, LiteralColor
@@ -10,6 +11,19 @@ class ColorFormat(PptxConvertible[PptxColorFormat]):
     def __init__(self, pptx_obj: PptxColorFormat) -> None:
         self._pptx = pptx_obj
 
+    @property
+    def brightness(self) -> float:
+        """
+        Read/write float value between -1.0 and 1.0 indicating the brightness
+        adjustment for this color, e.g. -0.25 is 25% darker and 0.4 is 40%
+        lighter. 0 means no brightness adjustment.
+        """
+        return self._pptx.brightness
+
+    @brightness.setter
+    def brightness(self, value: float) -> None:
+        self._pptx.brightness = value
+
     @property
     def rgb(self) -> Color | None:
         return to_tppt_color(self._pptx.rgb)
@@ -18,6 +32,22 @@ def rgb(self) -> Color | None:
     def rgb(self, color: Color | LiteralColor):
         self._pptx.rgb = to_pptx_rgb_color(color)
 
+    @property
+    def theme_color(self) -> MSO_THEME_COLOR:
+        """Theme color value of this color.
+
+        Value is a member of :ref:`MsoThemeColorIndex`, e.g.
+        ``MSO_THEME_COLOR.ACCENT_1``. Raises AttributeError on access if the
+        color is not type ``MSO_COLOR_TYPE.SCHEME``. Assigning a member of
+        :ref:`MsoThemeColorIndex` causes the color's type to change to
+        ``MSO_COLOR_TYPE.SCHEME``.
+        """
+        return self._pptx.theme_color
+
+    @theme_color.setter
+    def theme_color(self, value: MSO_THEME_COLOR) -> None:
+        self._pptx.theme_color = value
+
     def to_pptx(self) -> PptxColorFormat:
         return self._pptx
 

src/tppt/pptx/dml/fill.py

@@ -0,0 +1,205 @@
+from typing import Self, cast
+
+from pptx.dml.fill import FillFormat as PptxFillFormat
+from pptx.dml.fill import _GradFill as PptxGradFill
+from pptx.dml.fill import _GradientStop as PptxGradientStop
+from pptx.dml.fill import _GradientStops as PptxGradientStops
+from pptx.dml.fill import _NoFill as PptxNoFill
+from pptx.dml.fill import _PattFill as PptxPattFill
+from pptx.dml.fill import _SolidFill as PptxSolidFill
+from pptx.enum.dml import MSO_PATTERN_TYPE
+
+from tppt.pptx.converter import PptxConvertible, to_pptx_angle, to_tppt_angle
+from tppt.pptx.dml.color import ColorFormat
+from tppt.types._angle import Angle
+
+
+class FillFormat(PptxConvertible[PptxFillFormat]):
+    """Fill format."""
+
+    def __init__(self, pptx_obj: PptxFillFormat) -> None:
+        self._pptx = pptx_obj
+
+    @property
+    def fore_color(self) -> ColorFormat:
+        """Fore color."""
+        return ColorFormat(self._pptx.fore_color)
+
+    @property
+    def back_color(self) -> ColorFormat:
+        """Back color."""
+        return ColorFormat(self._pptx.back_color)
+
+    @property
+    def pattern(self) -> MSO_PATTERN_TYPE:
+        """Pattern."""
+        return self._pptx.pattern
+
+    @pattern.setter
+    def pattern(self, value: MSO_PATTERN_TYPE) -> None:
+        self._pptx.pattern = value
+
+    def patterned(self) -> "PattFill":
+        """Set the fill type to patterned."""
+        self._pptx.patterned()
+        return PattFill(cast(PptxPattFill, self._pptx._fill))
+
+    def background(self) -> "NoFill":
+        """Set the fill type to noFill, i.e. transparent."""
+        self._pptx.background()
+        return NoFill(cast(PptxNoFill, self._pptx._fill))
+
+    def solid(self) -> "SolidFill":
+        """Set the fill type to solid."""
+        self._pptx.solid()
+        return SolidFill(cast(PptxSolidFill, self._pptx._fill))
+
+    def gradient(self) -> "GradFill":
+        """Sets the fill type to gradient."""
+        self._pptx.gradient()
+        return GradFill(cast(PptxGradFill, self._pptx._fill))
+
+    def to_pptx(self) -> PptxFillFormat:
+        """Convert to pptx fill format."""
+        return self._pptx
+
+    @classmethod
+    def from_pptx(cls, pptx_obj: PptxFillFormat) -> Self:
+        """Create from pptx fill format."""
+        return cls(pptx_obj)
+
+
+class NoFill(PptxConvertible[PptxNoFill]):
+    """No fill."""
+
+    def __init__(self, pptx_obj: PptxNoFill) -> None:
+        self._pptx = pptx_obj
+
+    def to_pptx(self) -> PptxNoFill:
+        """Convert to pptx no fill."""
+        return self._pptx
+
+    @classmethod
+    def from_pptx(cls, pptx_obj: PptxNoFill) -> Self:
+        """Create from pptx no fill."""
+        return cls(pptx_obj)
+
+
+class PattFill(PptxConvertible[PptxPattFill]):
+    """Pattern fill."""
+
+    def __init__(self, pptx_obj: PptxPattFill) -> None:
+        self._pptx = pptx_obj
+
+    def to_pptx(self) -> PptxPattFill:
+        """Convert to pptx pattern fill."""
+        return self._pptx
+
+    @classmethod
+    def from_pptx(cls, pptx_obj: PptxPattFill) -> Self:
+        """Create from pptx pattern fill."""
+        return cls(pptx_obj)
+
+
+class SolidFill(PptxConvertible[PptxSolidFill]):
+    """Solid fill."""
+
+    def __init__(self, pptx_obj: PptxSolidFill) -> None:
+        self._pptx = pptx_obj
+
+    def to_pptx(self) -> PptxSolidFill:
+        """Convert to pptx solid fill."""
+        return self._pptx
+
+    @classmethod
+    def from_pptx(cls, pptx_obj: PptxSolidFill) -> Self:
+        """Create from pptx solid fill."""
+        return cls(pptx_obj)
+
+
+class GradFill(PptxConvertible[PptxGradFill]):
+    """Gradient fill."""
+
+    def __init__(self, pptx_obj: PptxGradFill) -> None:
+        self._pptx = pptx_obj
+
+    @property
+    def gradient_angle(self) -> Angle | None:
+        """Angle in float degrees of line of a linear gradient."""
+        return to_tppt_angle(cast(float | None, self._pptx.gradient_angle))
+
+    @gradient_angle.setter
+    def gradient_angle(self, value: Angle) -> None:
+        self._pptx.gradient_angle = to_pptx_angle(value)
+
+    @property
+    def gradient_stops(self) -> "GradientStops":
+        """Gradient stops."""
+        return GradientStops(self._pptx.gradient_stops)
+
+    def to_pptx(self) -> PptxGradFill:
+        """Convert to pptx gradient fill."""
+        return self._pptx
+
+    @classmethod
+    def from_pptx(cls, pptx_obj: PptxGradFill) -> Self:
+        """Create from pptx gradient fill."""
+        return cls(pptx_obj)
+
+
+class GradientStops(PptxConvertible[PptxGradientStops]):
+    """Gradient stops."""
+
+    def __init__(self, pptx_obj: PptxGradientStops) -> None:
+        self._pptx = pptx_obj
+
+    def __getitem__(self, idx: int) -> "GradientStop":
+        return GradientStop(self._pptx[idx])
+
+    def __len__(self) -> int:
+        return len(self._pptx)
+
+    def to_pptx(self) -> PptxGradientStops:
+        """Convert to pptx gradient stops."""
+        return self._pptx
+
+    @classmethod
+    def from_pptx(cls, pptx_obj: PptxGradientStops) -> Self:
+        """Create from pptx gradient stops."""
+        return cls(pptx_obj)
+
+
+class GradientStop(PptxConvertible[PptxGradientStop]):
+    """Gradient stop."""
+
+    def __init__(self, pptx_obj: PptxGradientStop) -> None:
+        self._pptx = pptx_obj
+
+    @property
+    def color(self) -> ColorFormat:
+        """Color."""
+        return ColorFormat(self._pptx.color)
+
+    @property
+    def position(self) -> float:
+        """Location of stop in gradient path as float between 0.0 and 1.0.
+
+        The value represents a percentage, where 0.0 (0%) represents the
+        start of the path and 1.0 (100%) represents the end of the path. For
+        a linear gradient, these would represent opposing extents of the
+        filled area.
+        """
+        return self._pptx.position
+
+    @position.setter
+    def position(self, value: float) -> None:
+        self._pptx.position = value
+
+    def to_pptx(self) -> PptxGradientStop:
+        """Convert to pptx gradient stop."""
+        return self._pptx
+
+    @classmethod
+    def from_pptx(cls, pptx_obj: PptxGradientStop) -> Self:
+        """Create from pptx gradient stop."""
+        return cls(pptx_obj)

src/tppt/pptx/slide.py

@@ -11,10 +11,10 @@
 from .placeholder import SlidePlaceholder
 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 .slide_layout import SlideLayout
 from .snotes_slide import NotesSlide
+from .table.table import DataFrame, Table, TableData, TableProps, dataframe2list
 
 if TYPE_CHECKING:
     pass
@@ -88,7 +88,7 @@ def __init__(
         placeholder_registry: Callable[[Slide], None],
     ) -> None:
         self._slide_layout = slide_layout
-        self._shape_registry: list[Callable[[Slide], Shape[Any]]] = []
+        self._shape_registry: list[Callable[[Slide], Any]] = []
         self._placeholder_registry = placeholder_registry
 
     @overload
@@ -218,14 +218,16 @@ def table(
 
         def _register(slide: Slide) -> Table:
             table_obj = Table(
-                slide.to_pptx().shapes.add_table(
+                slide.to_pptx()
+                .shapes.add_table(
                     rows,
                     cols,
                     to_pptx_length(table_data["left"]),
                     to_pptx_length(table_data["top"]),
                     to_pptx_length(table_data["width"]),
                     to_pptx_length(table_data["height"]),
-                ),
+                )
+                .table,
                 table_data,
             )
 

src/tppt/pptx/table/__init__.py

@@ -0,0 +1,2 @@
+from .table import Table as Table
+from .table import TableCellStyle as TableCellStyle