watermark-pdf: Remediate text color

- `client.py`: Merge rgb and cmyk into one, `text_color`
- `client.py`: Remove `Sequence[int]` from type
- `_internal.py`: Assign the text color value to the appropriate payload field

Assisted-by: Codex

Author: datalogics-cgreen

src/pdfrest/client.py

@@ -3628,8 +3628,7 @@ def watermark_pdf_with_text(
         output: str | None = None,
         font: str | None = None,
         text_size: int = 72,
-        text_color_rgb: PdfRGBColor | Sequence[int] | None = None,
-        text_color_cmyk: PdfCMYKColor | Sequence[int] | None = None,
+        text_color: PdfRGBColor | PdfCMYKColor = (0, 0, 0),
         opacity: float = 0.5,
         horizontal_alignment: WatermarkHorizontalAlignment = "center",
         vertical_alignment: WatermarkVerticalAlignment = "center",
@@ -3651,8 +3650,7 @@ def watermark_pdf_with_text(
             "output": output,
             "font": font,
             "text_size": text_size,
-            "text_color_rgb": text_color_rgb,
-            "text_color_cmyk": text_color_cmyk,
+            "text_color": text_color,
             "opacity": opacity,
             "horizontal_alignment": horizontal_alignment,
             "vertical_alignment": vertical_alignment,
@@ -5527,8 +5525,7 @@ async def watermark_pdf_with_text(
         output: str | None = None,
         font: str | None = None,
         text_size: int = 72,
-        text_color_rgb: PdfRGBColor | Sequence[int] | None = None,
-        text_color_cmyk: PdfCMYKColor | Sequence[int] | None = None,
+        text_color: PdfRGBColor | PdfCMYKColor = (0, 0, 0),
         opacity: float = 0.5,
         horizontal_alignment: WatermarkHorizontalAlignment = "center",
         vertical_alignment: WatermarkVerticalAlignment = "center",
@@ -5550,8 +5547,7 @@ async def watermark_pdf_with_text(
             "output": output,
             "font": font,
             "text_size": text_size,
-            "text_color_rgb": text_color_rgb,
-            "text_color_cmyk": text_color_cmyk,
+            "text_color": text_color,
             "opacity": opacity,
             "horizontal_alignment": horizontal_alignment,
             "vertical_alignment": vertical_alignment,

src/pdfrest/models/_internal.py

@@ -938,6 +938,10 @@ class ExtractImagesPayload(BaseModel):
 
 RgbChannel = Annotated[int, Field(ge=0, le=255)]
 CmykChannel = Annotated[int, Field(ge=0, le=100)]
+WatermarkTextColor = (
+    tuple[RgbChannel, RgbChannel, RgbChannel]
+    | tuple[CmykChannel, CmykChannel, CmykChannel, CmykChannel]
+)
 
 
 class PdfLiteralRedactionModel(BaseModel):
@@ -1669,25 +1673,33 @@ class PdfTextWatermarkPayload(_BasePdfWatermarkPayload):
         int,
         Field(serialization_alias="text_size", ge=5, le=100, default=72),
     ] = 72
-    text_color_rgb: Annotated[
-        tuple[RgbChannel, RgbChannel, RgbChannel] | None,
-        Field(serialization_alias="text_color_rgb", default=None),
-        BeforeValidator(_split_comma_string),
-        PlainSerializer(_serialize_as_comma_separated_string),
-    ] = None
-    text_color_cmyk: Annotated[
-        tuple[CmykChannel, CmykChannel, CmykChannel, CmykChannel] | None,
-        Field(serialization_alias="text_color_cmyk", default=None),
+    text_color: Annotated[
+        WatermarkTextColor,
+        Field(
+            default=(0, 0, 0),
+        ),
         BeforeValidator(_split_comma_string),
-        PlainSerializer(_serialize_as_comma_separated_string),
-    ] = None
+    ] = (0, 0, 0)
 
-    @model_validator(mode="after")
-    def _validate_text_colors(self) -> PdfTextWatermarkPayload:
-        if self.text_color_rgb is not None and self.text_color_cmyk is not None:
-            msg = "Specify only one of text_color_rgb or text_color_cmyk."
-            raise ValueError(msg)
-        return self
+    @model_serializer(mode="wrap")
+    def _serialize_text_color(
+        self, handler: Callable[[PdfTextWatermarkPayload], dict[str, Any]]
+    ) -> dict[str, Any]:
+        payload = handler(self)
+        text_color = cast(
+            list[Any] | tuple[int, ...],
+            payload.pop("text_color", self.text_color),
+        )
+        serialized_color = list(text_color)
+        if len(text_color) == 3:
+            payload["text_color_rgb"] = _serialize_as_comma_separated_string(
+                serialized_color
+            )
+        else:
+            payload["text_color_cmyk"] = _serialize_as_comma_separated_string(
+                serialized_color
+            )
+        return payload
 
 
 class PdfImageWatermarkPayload(_BasePdfWatermarkPayload):

tests/test_watermark_pdf.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import json
-import re
 
 import httpx
 import pytest
@@ -29,7 +28,7 @@ def test_watermark_pdf_with_text(monkeypatch: pytest.MonkeyPatch) -> None:
             "files": [input_file],
             "watermark_text": "Confidential",
             "text_size": 72,
-            "text_color_rgb": (255, 0, 0),
+            "text_color": (255, 0, 0),
             "opacity": 0.5,
             "horizontal_alignment": "center",
             "vertical_alignment": "center",
@@ -75,7 +74,7 @@ def handler(request: httpx.Request) -> httpx.Response:
         response = client.watermark_pdf_with_text(
             input_file,
             watermark_text="Confidential",
-            text_color_rgb=(255, 0, 0),
+            text_color=(255, 0, 0),
             pages=["1", "3-5"],
             output="watermarked",
         )
@@ -174,6 +173,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["watermark_text"] == "Draft"
             assert payload["text_color_cmyk"] == "0,0,0,50"
+            assert "text_color_rgb" not in payload
             assert payload["opacity"] == 0.25
             assert payload["output"] == "custom"
             assert payload["debug"] == "yes"
@@ -205,7 +205,7 @@ def handler(request: httpx.Request) -> httpx.Response:
         response = client.watermark_pdf_with_text(
             input_file,
             watermark_text="Draft",
-            text_color_cmyk=(0, 0, 0, 50),
+            text_color=(0, 0, 0, 50),
             opacity=0.25,
             output="custom",
             extra_query={"trace": "true"},
@@ -226,7 +226,7 @@ def handler(request: httpx.Request) -> httpx.Response:
         assert timeout_value == pytest.approx(0.31)
 
 
-def test_watermark_pdf_with_text_validation_color_choice(
+def test_watermark_pdf_with_text_validation_rejects_invalid_text_color(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     monkeypatch.delenv("PDFREST_API_KEY", raising=False)
@@ -240,14 +240,13 @@ def test_watermark_pdf_with_text_validation_color_choice(
         ) as client,
         pytest.raises(
             ValidationError,
-            match=re.escape("Specify only one of text_color_rgb or text_color_cmyk."),
+            match=r"text_color",
         ),
     ):
         client.watermark_pdf_with_text(
             input_file,
             watermark_text="Confidential",
-            text_color_rgb=(0, 0, 0),
-            text_color_cmyk=(0, 0, 0, 0),
+            text_color=(0, 0),
         )
 
 
@@ -334,6 +333,7 @@ async def test_async_watermark_pdf_with_text(monkeypatch: pytest.MonkeyPatch) ->
             "files": [input_file],
             "watermark_text": "Async",
             "text_size": 72,
+            "text_color": (0, 0, 0),
             "opacity": 0.6,
             "horizontal_alignment": "center",
             "vertical_alignment": "center",