Fix color tuple JSON round-trip in BackgroundLayer (#7)

Author: sjquant

quickthumb/canvas.py

@@ -2747,7 +2747,10 @@ def _download_and_cache_font(self, url: str) -> str:
                 cached_header = f.read(4)
             if any(cached_header.startswith(magic) for magic in self._VALID_FONT_MAGIC):
                 return cache_path
-            os.remove(cache_path)  # stale invalid cache — re-download
+            try:
+                os.remove(cache_path)  # stale invalid cache — re-download
+            except OSError:
+                pass  # non-fatal: proceed to re-download; write will overwrite or fail cleanly
 
         try:
             with urlopen(url) as response:

quickthumb/models.py

@@ -344,11 +344,18 @@ def validate_color(cls, v: str | tuple | None) -> str | tuple | None:
             return v
 
         # HexColor validation already applied to str, just validate tuple
-        if isinstance(v, tuple) and len(v) not in (3, 4):
-            raise ValueError(f"invalid color tuple: {v}")
+        if isinstance(v, tuple):
+            if len(v) not in (3, 4) or not all(isinstance(c, int) and 0 <= c <= 255 for c in v):
+                raise ValueError(f"invalid color tuple: {v}")
 
         return v
 
+    @field_serializer("color")
+    def serialize_color(self, v: str | tuple | None) -> str | None:
+        if v is None or isinstance(v, str):
+            return v
+        return "#" + "".join(f"{c:02X}" for c in v)
+
 
 class TextLayer(QuickThumbModel):
     type: Literal["text"]

specs/TASKS.md

@@ -76,7 +76,7 @@
 
 ### P3 — Lower Priority
 
-- [TODO] Fix color tuple JSON round-trip: `BackgroundLayer.color` accepts RGB tuples but they break `to_json()` / `from_json()`
+- [DONE] Fix color tuple JSON round-trip: `BackgroundLayer.color` accepts RGB tuples but they break `to_json()` / `from_json()`
 - [TODO] Font metadata reading: use `fonttools` to read font weight/style from file metadata instead of relying on filename parsing
 - [TODO] Split `canvas.py` (currently 2466 lines) into smaller modules before it becomes a maintenance burden
 

tests/test_background_layers.py

@@ -213,8 +213,12 @@ def test_should_add_radial_gradient_background_with_custom_center(self):
         assert gradient.center == (0.3, 0.7)
 
     def test_should_serialize_background_layer_to_json(self):
-        """Test that canvas with background layers can be serialized to JSON"""
-        # Given: Canvas with multiple background layers
+        """Test that canvas with background layers can be serialized to JSON.
+
+        Includes a tuple-color layer to verify that RGB/RGBA tuples are serialized as
+        hex strings (not JSON arrays) so the output is spec-compliant and round-trippable.
+        """
+        # Given: Canvas with multiple background layers, including a tuple color
         import json
 
         from quickthumb import BlendMode, Canvas, Filter, LinearGradient
@@ -224,9 +228,12 @@ def test_should_serialize_background_layer_to_json(self):
             Canvas(1920, 1080)
             .background(color="#2c3e50", effects=[Filter(blur=5, brightness=0.8)])
             .background(gradient=gradient, opacity=0.5, blend_mode=BlendMode.MULTIPLY)
+            .background(color=(255, 87, 51))
+            .background(color=(255, 87, 51, 200))
         )
 
-        # When/Then: Serialized JSON matches full expected structure
+        # When/Then: Serialized JSON matches full expected structure;
+        # tuple colors appear as hex strings, not arrays.
         assert json.loads(canvas.to_json()) == snapshot(
             {
                 "width": 1920,
@@ -264,10 +271,36 @@ def test_should_serialize_background_layer_to_json(self):
                         "fit": None,
                         "effects": [],
                     },
+                    {
+                        "type": "background",
+                        "color": "#FF5733",
+                        "gradient": None,
+                        "image": None,
+                        "opacity": 1.0,
+                        "blend_mode": None,
+                        "fit": None,
+                        "effects": [],
+                    },
+                    {
+                        "type": "background",
+                        "color": "#FF5733C8",
+                        "gradient": None,
+                        "image": None,
+                        "opacity": 1.0,
+                        "blend_mode": None,
+                        "fit": None,
+                        "effects": [],
+                    },
                 ],
             }
         )
 
+        # Round-trip: after from_json the tuple-color layers come back as hex strings,
+        # confirming the serializer normalises them correctly.
+        roundtrip = Canvas.from_json(canvas.to_json())
+        assert roundtrip.layers[2].color == "#FF5733"
+        assert roundtrip.layers[3].color == "#FF5733C8"
+
     def test_should_deserialize_background_layer_from_json(self):
         """Test that canvas with background layers can be deserialized from JSON"""
         # Given: JSON string with background layers
@@ -374,18 +407,23 @@ def test_should_accept_8_character_hex_color(self):
         assert isinstance(layer, BackgroundLayer)
         assert layer.color == "#FF5733C8"
 
-    def test_should_raise_error_for_invalid_tuple_color_length(self):
-        """Should raise ValidationError for tuple colors with invalid length"""
-        # Given: Canvas
+    @pytest.mark.parametrize(
+        "color",
+        [
+            (255, 87),  # too short
+            (255, 87, 51, 0, 0),  # too long
+            (256, 87, 51),  # channel > 255
+            (-1, 87, 51),  # channel < 0
+            (255, 87, 51, 256),  # alpha > 255
+        ],
+    )
+    def test_should_raise_error_for_invalid_tuple_color(self, color):
+        """ValidationError for tuple colors with wrong length or out-of-range channel values"""
         from quickthumb import Canvas
         from quickthumb.errors import ValidationError
 
-        canvas = Canvas(200, 150)
-
-        # When: Adding background with invalid tuple color (wrong length)
-        # Then: Should raise ValidationError
         with pytest.raises(ValidationError, match="invalid color tuple"):
-            canvas.background(color=(255, 87))
+            Canvas(200, 150).background(color=color)
 
     def test_should_raise_error_for_invalid_fit_mode(self):
         """Test that invalid fit mode raises ValidationError"""
@@ -453,7 +491,9 @@ def test_should_add_grain_effect_to_background_layer(self):
                 "intensity": 0.12,
                 "monochrome": True,
                 "blend_mode": "overlay",
-                "opacity": 1.0, 'seed': None}
+                "opacity": 1.0,
+                "seed": None,
+            }
         )
         roundtrip = Canvas.from_json(json.dumps(data))
         assert roundtrip.layers[0].effects[0] == Grain(intensity=0.12)