refactor: update color handling to use RGBColor and simplify color conversion logic

Author: ya7010

examples/formatted_text.py

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

examples/simple_example.py

@@ -3,7 +3,6 @@
 from pathlib import Path
 
 import tppt
-from tppt.types import Color
 
 EXAMPLE_DIR = Path(__file__).parent
 
@@ -32,7 +31,7 @@ def main():
                 size=(60, "pt"),
                 bold=True,
                 italic=True,
-                color=Color("#0000FF"),
+                color="#0000FF",
             )
             .text(
                 "Example of using tppt library",  # Subtitle

src/tppt/pptx/converter.py

@@ -10,7 +10,6 @@
     runtime_checkable,
 )
 
-from pptx.dml.color import RGBColor as PptxRGBColor
 from pptx.util import Cm as PptxCm
 from pptx.util import Emu as PptxEmu
 from pptx.util import Inches as PptxInches
@@ -19,7 +18,6 @@
 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,
     EnglishMetricUnits,
@@ -89,35 +87,6 @@ def to_tppt_length(length: PptxLength | None) -> Length | None:
     return to_length((length.emu, "emu")) if length else None
 
 
-@overload
-def to_pptx_rgb_color(color: Color | LiteralColor) -> PptxRGBColor: ...
-
-
-@overload
-def to_pptx_rgb_color(color: Color | LiteralColor | None) -> PptxRGBColor | None: ...
-
-
-def to_pptx_rgb_color(color: Color | LiteralColor | None) -> PptxRGBColor | None:
-    if color is None:
-        return None
-
-    color = to_color(color)
-
-    return PptxRGBColor(color.r, color.g, color.b)
-
-
-@overload
-def to_tppt_color(color: PptxRGBColor) -> Color: ...
-
-
-@overload
-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
 
 

src/tppt/pptx/dml/color.py

@@ -3,8 +3,8 @@
 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
+from tppt.pptx.converter import PptxConvertible
+from tppt.types import LiteralColor, RGBColor, to_color
 
 
 class ColorFormat(PptxConvertible[PptxColorFormat]):
@@ -25,12 +25,12 @@ def brightness(self, value: float) -> None:
         self._pptx.brightness = value
 
     @property
-    def rgb(self) -> Color | None:
-        return to_tppt_color(self._pptx.rgb)
+    def rgb(self) -> RGBColor | None:
+        return self._pptx.rgb
 
     @rgb.setter
-    def rgb(self, color: Color | LiteralColor):
-        self._pptx.rgb = to_pptx_rgb_color(color)
+    def rgb(self, color: RGBColor | LiteralColor):
+        self._pptx.rgb = to_color(color)
 
     @property
     def theme_color(self) -> MSO_THEME_COLOR:

src/tppt/pptx/shape/text.py

@@ -3,9 +3,9 @@
 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.converter import to_pptx_length
 from tppt.pptx.text.text_frame import TextFrame
-from tppt.types._color import Color, LiteralColor
+from tppt.types._color import LiteralColor, RGBColor, to_color
 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[Color | LiteralColor]
+    color: NotRequired[RGBColor | LiteralColor]
     margin_bottom: NotRequired[Length | LiteralLength]
     margin_left: NotRequired[Length | LiteralLength]
     vertical_anchor: NotRequired[MSO_ANCHOR]
@@ -52,7 +52,7 @@ def __init__(self, pptx_obj: PptxShape, data: TextData | None = None, /) -> None
             if (italic := data.get("italic")) is not None:
                 font.italic = italic
             if (color := data.get("color")) is not None:
-                font.color.rgb = to_pptx_rgb_color(color)
+                font.color.rgb = to_color(color)
             if (margin_bottom := data.get("margin_bottom")) is not None:
                 p.space_after = to_pptx_length(margin_bottom)
             if (margin_left := data.get("margin_left")) is not None:

src/tppt/types/__init__.py

@@ -5,8 +5,9 @@
 
 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_color as to_color
 from ._length import (
     CentiMeters as CentiMeters,
 )

src/tppt/types/_color.py

@@ -1,63 +1,48 @@
 """Color types for tppt."""
 
-from typing import TypeAlias, overload
+from typing import TypeAlias, assert_never, overload
+
+from pptx.dml.color import RGBColor as _PptxRGBColor
 
 from tppt.exception import ColorInvalidFormatError
 
 LiteralColor: TypeAlias = tuple[int, int, int] | str
+RGBColor: TypeAlias = _PptxRGBColor
 
 
-class Color:
-    """Represents a color in RGB or by hex code.
+@overload
+def to_color(color: RGBColor | LiteralColor) -> RGBColor: ...
 
-    Examples:
-        >>> Color("#00B")
-        >>> Color("#00BB00")
-        >>> Color(255, 0, 0)
-    """
 
-    @overload
-    def __init__(self, r: str): ...
+@overload
+def to_color(color: RGBColor | LiteralColor | None) -> RGBColor | None: ...
 
-    @overload
-    def __init__(self, r: int, g: int, b: int): ...
 
-    def __init__(self, r: str | int, g: int | None = None, b: int | None = None):
-        """Initialize a Color instance."""
-        if isinstance(r, str):
-            if not r.startswith("#"):
-                raise ColorInvalidFormatError(r)
+def to_color(color: RGBColor | LiteralColor | None) -> RGBColor | None:
+    match color:
+        case None:
+            return None
+        case tuple():
+            return RGBColor(*color)
+        case str():
+            if not color.startswith("#"):
+                raise ColorInvalidFormatError(color)
 
-            match len(r):
+            match len(color):
                 case 4:
                     # Note that #123 is the same as #112233
-                    self.r = int(r[1:2] * 2, 16)
-                    self.g = int(r[2:3] * 2, 16)
-                    self.b = int(r[3:4] * 2, 16)
+                    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)
 
                 case 7:
-                    self.r = int(r[1:3], 16)
-                    self.g = int(r[3:5], 16)
-                    self.b = int(r[5:7], 16)
+                    r = int(color[1:3], 16)
+                    g = int(color[3:5], 16)
+                    b = int(color[5:7], 16)
+                    return RGBColor(r, g, b)
 
                 case _:
-                    raise ColorInvalidFormatError(r)
-
-        else:
-            self.r = r
-            self.g = g  # type: ignore
-            self.b = b  # type: ignore
-
-    def __repr__(self) -> str:
-        """Return string representation."""
-        return f"Color({self.r}, {self.g}, {self.b})"
-
-
-def to_color(color: Color | LiteralColor) -> Color:
-    if isinstance(color, Color):
-        return color
-    else:
-        if isinstance(color, tuple):
-            return Color(*color)
-        else:
-            return Color(color)
+                    raise ColorInvalidFormatError(color)
+        case _:
+            assert_never(color)

tests/test_text.py

@@ -3,7 +3,6 @@
 from pptx.enum.text import MSO_ANCHOR, MSO_AUTO_SIZE, PP_ALIGN
 
 import tppt
-from tppt.types._color import Color
 
 
 def test_text_with_options(output) -> None:
@@ -26,7 +25,7 @@ def test_text_with_options(output) -> None:
                 size=(24, "pt"),
                 bold=True,
                 italic=True,
-                color=Color("#0000FF"),
+                color="#0000FF",
                 margin_bottom=(10, "pt"),
                 margin_left=(10, "pt"),
                 vertical_anchor=MSO_ANCHOR.MIDDLE,

tests/test_types_color.py

@@ -3,78 +3,73 @@
 import unittest
 
 from tppt.exception import ColorInvalidFormatError
-from tppt.types._color import Color, to_color
+from tppt.types._color import RGBColor, to_color
 
 
 class TestColor(unittest.TestCase):
     """Test cases for Color class."""
 
     def test_init_with_rgb_hex_short(self):
         """Test initialization with short hex color code (#RGB)."""
-        color = Color("#123")
-        assert color.r == 0x11
-        assert color.g == 0x22
-        assert color.b == 0x33
+        color = to_color("#123")
+        r, g, b = color
+        assert r == 0x11
+        assert g == 0x22
+        assert b == 0x33
 
     def test_init_with_rgb_hex_long(self):
         """Test initialization with long hex color code (#RRGGBB)."""
-        color = Color("#123456")
-        assert color.r == 0x12
-        assert color.g == 0x34
-        assert color.b == 0x56
+        color = to_color("#123456")
+        r, g, b = color
+        assert r == 0x12
+        assert g == 0x34
+        assert b == 0x56
 
     def test_init_with_rgb_tuple(self):
         """Test initialization with RGB tuple."""
-        color = Color(10, 20, 30)
-        assert color.r == 10
-        assert color.g == 20
-        assert color.b == 30
+        color = RGBColor(10, 20, 30)
+        r, g, b = color
+        assert r == 10
+        assert g == 20
+        assert b == 30
 
     def test_invalid_format_no_hash(self):
         """Test initialization with invalid format (no # prefix)."""
         with self.assertRaises(ColorInvalidFormatError):
-            Color("123456")
+            to_color("123456")
 
     def test_invalid_format_wrong_length(self):
         """Test initialization with invalid format (wrong length)."""
         with self.assertRaises(ColorInvalidFormatError):
-            Color("#12345")  # 6 characters (including #) is invalid
-
-    def test_repr(self):
-        """Test string representation."""
-        color = Color(10, 20, 30)
-        assert repr(color) == "Color(10, 20, 30)"
+            to_color("#12345")  # 6 characters (including #) is invalid
 
 
 class TestToColor(unittest.TestCase):
     """Test cases for to_color function."""
 
-    def test_to_color_with_color_instance(self):
-        """Test to_color with a Color instance."""
-        original = Color(10, 20, 30)
-        result = to_color(original)
-        assert result is original
-
     def test_to_color_with_tuple(self):
         """Test to_color with a RGB tuple."""
         result = to_color((10, 20, 30))
-        assert isinstance(result, Color)
-        assert result.r == 10
-        assert result.g == 20
-        assert result.b == 30
+        assert isinstance(result, RGBColor)
+        r, g, b = result
+        assert r == 10
+        assert g == 20
+        assert b == 30
 
     def test_to_color_with_str(self):
         """Test to_color with a hex string."""
         result = to_color("#123456")
-        assert isinstance(result, Color)
-        assert result.r == 0x12
-        assert result.g == 0x34
-        assert result.b == 0x56
+        assert isinstance(result, RGBColor)
+        r, g, b = result
+        assert r == 0x12
+        assert g == 0x34
+        assert b == 0x56
 
     def test_to_color_with_short_hex(self):
         """Test to_color with a short hex string."""
         result = to_color("#123")
-        assert isinstance(result, Color)
-        assert result.r == 0x11
-        assert result.g == 0x22
-        assert result.b == 0x33
+        assert isinstance(result, RGBColor)
+        r, g, b = result
+        assert r == 0x11
+        assert g == 0x22
+        assert b == 0x33