refactor: replace RGBColor with Color type in color handling

Author: ya7010

examples/formatted_text.py

@@ -24,7 +24,7 @@ def functional_text(
         text: str,
         bold: bool = False,
         italic: bool = False,
-        color: tppt.types.RGBColor | tppt.types.LiteralColor | None = None,
+        color: tppt.types.Color | tppt.types.LiteralColor | None = None,
     ) -> tppt.pptx.Text:
         run = text_obj.text_frame.add_paragraph().add_run()
         run.text = text

src/tppt/exception.py

@@ -1,5 +1,5 @@
 from abc import abstractmethod
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 if TYPE_CHECKING:
     from pptx.slide import SlideLayouts as PptxSlideLayouts
@@ -31,6 +31,17 @@ def message(self) -> str:
         return f"Invalid color format: {self.color}"
 
 
+class ColorInvalidTupleSizeError(TpptException, ValueError):
+    """Color tuple size is invalid."""
+
+    def __init__(self, color: tuple[Any, ...]) -> None:
+        self.color = color
+
+    @property
+    def message(self) -> str:
+        return f"Invalid color tuple size: {self.color}, expected 3(RGB) or 4(RGBA) elements."
+
+
 class SlideLayoutIndexError(TpptException, IndexError):
     """Slide layout index is out of range."""
 
@@ -87,3 +98,17 @@ def __init__(
     @property
     def message(self) -> str:
         return f"Invalid setter type. Expected type: {self.expected_type}, but got: {self.actual_type}."
+
+
+class InvalidColorValueError(TpptException, ValueError):
+    """Invalid color value."""
+
+    def __init__(
+        self, type: Literal["red", "green", "blue", "alpha"], value: int
+    ) -> None:
+        self.type = type
+        self.value = value
+
+    @property
+    def message(self) -> str:
+        return f"Invalid {self.type} value: {self.value}. It must be between 0 and 255."

src/tppt/pptx/converter.py

@@ -19,7 +19,7 @@
 from pptx.util import Pt as PptxPt
 
 from tppt.types._angle import Angle, Degrees, LiteralAngle
-from tppt.types._color import LiteralColor, RGBColor, to_rgb_color
+from tppt.types._color import Color, LiteralColor, to_rgb_color
 from tppt.types._length import (
     CentiMeters,
     EnglishMetricUnits,
@@ -90,32 +90,46 @@ def to_tppt_length(length: PptxLength | None) -> Length | None:
 
 
 @overload
-def to_pptx_rgb_color(color: RGBColor | LiteralColor) -> PptxRGBColor: ...
+def to_pptx_rgb_color(
+    color: Color | LiteralColor,
+) -> tuple[PptxRGBColor, int | None]: ...
 
 
 @overload
-def to_pptx_rgb_color(color: RGBColor | LiteralColor | None) -> PptxRGBColor | None: ...
-
-
-def to_pptx_rgb_color(color: RGBColor | LiteralColor | None) -> PptxRGBColor | None:
+def to_pptx_rgb_color(
+    color: Color | LiteralColor | None,
+) -> tuple[PptxRGBColor, int | None] | None: ...
+
+
+def to_pptx_rgb_color(
+    color: Color | LiteralColor | None,
+) -> (
+    tuple[
+        PptxRGBColor,
+        int | None,
+    ]
+    | None
+):
     if color is None:
         return None
 
     color = to_rgb_color(color)
 
-    return PptxRGBColor(color.r, color.g, color.b)
+    return PptxRGBColor(color.r, color.g, color.b), color.a
 
 
 @overload
-def to_tppt_rgb_color(color: PptxRGBColor) -> RGBColor: ...
+def to_tppt_rgb_color(color: PptxRGBColor, alpha: int | None) -> Color: ...
 
 
 @overload
-def to_tppt_rgb_color(color: PptxRGBColor | None) -> RGBColor | None: ...
+def to_tppt_rgb_color(
+    color: PptxRGBColor | None, alpha: int | None
+) -> Color | None: ...
 
 
-def to_tppt_rgb_color(color: PptxRGBColor | None) -> RGBColor | None:
-    return RGBColor(*color) if color else None
+def to_tppt_rgb_color(color: PptxRGBColor | None, alpha: int | None) -> Color | None:
+    return Color(color[0], color[1], color[2], alpha) if color else None
 
 
 PptxAngle: TypeAlias = float

src/tppt/pptx/dml/color.py

@@ -1,10 +1,11 @@
-from typing import Self
+from typing import Self, cast
 
 from pptx.dml.color import ColorFormat as PptxColorFormat
+from pptx.dml.color import RGBColor as PptxRGBColor
 from pptx.enum.dml import MSO_THEME_COLOR
 
 from tppt.pptx.converter import PptxConvertible, to_pptx_rgb_color, to_tppt_rgb_color
-from tppt.types import LiteralColor, RGBColor
+from tppt.types import Color, LiteralColor
 
 
 class ColorFormat(PptxConvertible[PptxColorFormat]):
@@ -25,12 +26,13 @@ def brightness(self, value: float) -> None:
         self._pptx.brightness = value
 
     @property
-    def rgb(self) -> RGBColor | None:
-        return to_tppt_rgb_color(self._pptx.rgb)
+    def rgb(self) -> Color:
+        return to_tppt_rgb_color(cast(PptxRGBColor, self._pptx.rgb), alpha=None)
 
     @rgb.setter
-    def rgb(self, color: RGBColor | LiteralColor):
-        self._pptx.rgb = to_pptx_rgb_color(color)
+    def rgb(self, color: Color | LiteralColor):
+        pptx_color, _ = to_pptx_rgb_color(color)
+        self._pptx.rgb = pptx_color
 
     @property
     def theme_color(self) -> MSO_THEME_COLOR:

src/tppt/pptx/shape/text.py

@@ -5,7 +5,7 @@
 
 from tppt.pptx.converter import to_pptx_length, to_pptx_rgb_color
 from tppt.pptx.text.text_frame import TextFrame
-from tppt.types._color import LiteralColor, RGBColor
+from tppt.types._color import Color, LiteralColor
 from tppt.types._length import Length, LiteralLength
 
 from . import RangeProps, Shape
@@ -17,7 +17,7 @@ class TextProps(RangeProps):
     size: NotRequired[Length | LiteralLength]
     bold: NotRequired[bool]
     italic: NotRequired[bool]
-    color: NotRequired[RGBColor | LiteralColor]
+    color: NotRequired[Color | LiteralColor]
     margin_bottom: NotRequired[Length | LiteralLength]
     margin_left: NotRequired[Length | LiteralLength]
     vertical_anchor: NotRequired[MSO_ANCHOR]

src/tppt/types/__init__.py

@@ -5,8 +5,8 @@
 
 from tppt.pptx.shape import RangeProps as _RangeProps
 
+from ._color import Color as Color
 from ._color import LiteralColor as LiteralColor
-from ._color import RGBColor as RGBColor
 from ._color import to_rgb_color as to_rgb_color
 from ._length import (
     CentiMeters as CentiMeters,

src/tppt/types/_color.py

@@ -1,51 +1,87 @@
 """Color types for tppt."""
 
-from typing import NamedTuple, TypeAlias, assert_never, overload
+from dataclasses import dataclass
+from typing import TypeAlias, assert_never, overload
 
-from tppt.exception import ColorInvalidFormatError
+from pptx.dml.color import RGBColor as _PptxRGBColor
+from typing_extensions import Annotated, Doc
 
-LiteralColor: TypeAlias = tuple[int, int, int] | str
+from tppt.exception import (
+    ColorInvalidFormatError,
+    ColorInvalidTupleSizeError,
+    InvalidColorValueError,
+)
 
+LiteralRGBColor: TypeAlias = tuple[int, int, int]
+LiteralRGBAColor: TypeAlias = tuple[int, int, int, int]
+LiteralColor: TypeAlias = LiteralRGBColor | LiteralRGBAColor | str
 
-class RGBColor(NamedTuple):
-    r: int
-    g: int
-    b: int
+
+@dataclass
+class Color:
+    r: Annotated[int, Doc("red color value")]
+    g: Annotated[int, Doc("green color value")]
+    b: Annotated[int, Doc("blue color value")]
+    a: Annotated[int | None, Doc("alpha color value")] = None
+
+    def __post_init__(self):
+        if not 0 <= self.r <= 255:
+            raise InvalidColorValueError("red", self.r)
+        if not 0 <= self.g <= 255:
+            raise InvalidColorValueError("green", self.g)
+        if not 0 <= self.b <= 255:
+            raise InvalidColorValueError("blue", self.b)
+        if self.a is not None and not 0 <= self.a <= 255:
+            raise InvalidColorValueError("alpha", self.a)
 
 
 @overload
-def to_rgb_color(color: RGBColor | LiteralColor) -> RGBColor: ...
+def to_rgb_color(color: Color | LiteralColor | _PptxRGBColor) -> Color: ...
 
 
 @overload
-def to_rgb_color(color: RGBColor | LiteralColor | None) -> RGBColor | None: ...
+def to_rgb_color(
+    color: Color | LiteralColor | _PptxRGBColor | None,
+) -> Color | None: ...
 
 
-def to_rgb_color(color: RGBColor | LiteralColor | None) -> RGBColor | None:
+def to_rgb_color(color: Color | LiteralColor | _PptxRGBColor | None) -> Color | None:
     match color:
         case None:
             return None
-        case tuple():
-            return RGBColor(*color)
         case str():
             if not color.startswith("#"):
                 raise ColorInvalidFormatError(color)
 
             match len(color):
-                case 4:
+                case 4 | 5:
                     # Note that #123 is the same as #112233
                     r = int(color[1:2] * 2, 16)
                     g = int(color[2:3] * 2, 16)
                     b = int(color[3:4] * 2, 16)
-                    return RGBColor(r, g, b)
+                    a = int(color[4:5] * 2, 16) if len(color) == 5 else None
+                    return Color(r, g, b, a)
 
-                case 7:
+                case 7 | 9:
                     r = int(color[1:3], 16)
                     g = int(color[3:5], 16)
                     b = int(color[5:7], 16)
-                    return RGBColor(r, g, b)
+                    a = int(color[7:9], 16) if len(color) == 9 else None
+                    return Color(r, g, b, a)
 
                 case _:
                     raise ColorInvalidFormatError(color)
+        case tuple():
+            match color:
+                case tuple() if len(color) == 3:
+                    r, g, b = color
+                    return Color(r, g, b)
+                case tuple() if len(color) == 4:
+                    r, g, b, a = color
+                    return Color(r, g, b, a)
+                case _:
+                    raise ColorInvalidTupleSizeError(color)
+        case Color():
+            return color
         case _:
             assert_never(color)

tests/test_types_color.py

@@ -3,7 +3,7 @@
 import unittest
 
 from tppt.exception import ColorInvalidFormatError
-from tppt.types._color import RGBColor, to_rgb_color
+from tppt.types._color import Color, to_rgb_color
 
 
 class TestColor(unittest.TestCase):
@@ -12,26 +12,23 @@ class TestColor(unittest.TestCase):
     def test_init_with_rgb_hex_short(self):
         """Test initialization with short hex color code (#RGB)."""
         color = to_rgb_color("#123")
-        r, g, b = color
-        assert r == 0x11
-        assert g == 0x22
-        assert b == 0x33
+        assert color.r == 0x11
+        assert color.g == 0x22
+        assert color.b == 0x33
 
     def test_init_with_rgb_hex_long(self):
         """Test initialization with long hex color code (#RRGGBB)."""
         color = to_rgb_color("#123456")
-        r, g, b = color
-        assert r == 0x12
-        assert g == 0x34
-        assert b == 0x56
+        assert color.r == 0x12
+        assert color.g == 0x34
+        assert color.b == 0x56
 
     def test_init_with_rgb_tuple(self):
         """Test initialization with RGB tuple."""
-        color = RGBColor(10, 20, 30)
-        r, g, b = color
-        assert r == 10
-        assert g == 20
-        assert b == 30
+        color = Color(10, 20, 30)
+        assert color.r == 10
+        assert color.g == 20
+        assert color.b == 30
 
     def test_invalid_format_no_hash(self):
         """Test initialization with invalid format (no # prefix)."""
@@ -49,27 +46,24 @@ class TestToColor(unittest.TestCase):
 
     def test_to_color_with_tuple(self):
         """Test to_color with a RGB tuple."""
-        result = to_rgb_color((10, 20, 30))
-        assert isinstance(result, RGBColor)
-        r, g, b = result
-        assert r == 10
-        assert g == 20
-        assert b == 30
+        color = to_rgb_color((10, 20, 30))
+        assert isinstance(color, Color)
+        assert color.r == 10
+        assert color.g == 20
+        assert color.b == 30
 
     def test_to_color_with_str(self):
         """Test to_color with a hex string."""
-        result = to_rgb_color("#123456")
-        assert isinstance(result, RGBColor)
-        r, g, b = result
-        assert r == 0x12
-        assert g == 0x34
-        assert b == 0x56
+        color = to_rgb_color("#123456")
+        assert isinstance(color, Color)
+        assert color.r == 0x12
+        assert color.g == 0x34
+        assert color.b == 0x56
 
     def test_to_color_with_short_hex(self):
         """Test to_color with a short hex string."""
-        result = to_rgb_color("#123")
-        assert isinstance(result, RGBColor)
-        r, g, b = result
-        assert r == 0x11
-        assert g == 0x22
-        assert b == 0x33
+        color = to_rgb_color("#123")
+        assert isinstance(color, Color)
+        assert color.r == 0x11
+        assert color.g == 0x22
+        assert color.b == 0x33