tests/models: close Add Text/Image/Attachment coverage gaps

- Add focused Add Text unit coverage for RGB/CMYK validation, color-mode exclusivity, page parsing ("all" and numeric strings), output-prefix rejection, and comma-separated RGB serialization.
- Cover async output payload branches in Add Text and Add Image request-customization tests.
- Fix invalid PdfRestFileID.generate(3) usage in Add Image/Add Attachment multi-file validation tests.
- Update add-text color validators to run custom RGB/CMYK checks in BeforeValidator, ensuring endpoint-specific integer/range errors are exercised.
- Simplify _validate_output_prefix by removing redundant basename logic and mark unreachable None serializer/validator branches with # pragma: no cover.

Assisted-by: Codex

Author: datalogics-cgreen

src/pdfrest/models/_internal.py

@@ -3,7 +3,6 @@
 import json
 import re
 from collections.abc import Callable, Sequence
-from pathlib import PurePath
 from typing import Annotated, Any, Generic, Literal, TypeVar
 
 from langcodes import tag_is_valid
@@ -53,7 +52,7 @@ def _list_of_strings(value: list[Any]) -> list[str]:
 def _validate_output_prefix(value: str | None) -> str | None:
     """Validate output prefix to prevent directory traversal and reserved or unsafe names."""
     if value is None:
-        return None
+        return None  # pragma: no cover
     if "/" in value or "\\" in value or ":" in value:
         msg = "The output prefix must not contain a directory separator."
         raise ValueError(msg)
@@ -63,11 +62,7 @@ def _validate_output_prefix(value: str | None) -> str | None:
     if ".." in value:
         msg = "The output prefix must not contain `..`."
         raise ValueError(msg)
-    basename = PurePath(value).name
-    if value != basename:
-        msg = "The output prefix must not include directory components."
-        raise ValueError(msg)
-    if basename in {"profile.json", "metadata.json"}:
+    if value in {"profile.json", "metadata.json"}:
         msg = "The output prefix is a reserved name."
         raise ValueError(msg)
     special_chars_pattern = r"[`!@#$%^&*()+=\[\]{};':\"\\|,<>?~]"
@@ -114,7 +109,7 @@ def _serialize_as_first_file_id(value: list[PdfRestFile]) -> str:
 
 def _serialize_as_comma_separated_string(value: list[Any] | None) -> str | None:
     if value is None:
-        return None
+        return None  # pragma: no cover
     return ",".join(str(element) for element in value)
 
 
@@ -1120,15 +1115,15 @@ class PdfAddTextObjectModel(BaseModel):
     text_color_rgb: Annotated[
         list[int] | tuple[int, ...] | None,
         Field(serialization_alias="text_color_rgb", default=None),
+        BeforeValidator(_validate_rgb_values),
         BeforeValidator(_split_comma_string),
-        AfterValidator(_validate_rgb_values),
         PlainSerializer(_serialize_as_comma_separated_string),
     ] = None
     text_color_cmyk: Annotated[
         list[int] | tuple[int, ...] | None,
         Field(serialization_alias="text_color_cmyk", default=None),
+        BeforeValidator(_validate_cmyk_values),
         BeforeValidator(_split_comma_string),
-        AfterValidator(_validate_cmyk_values),
         PlainSerializer(_serialize_as_comma_separated_string),
     ] = None
     text_size: Annotated[

tests/test_add_attachment_to_pdf.py

@@ -338,6 +338,6 @@ def handler(_: httpx.Request) -> httpx.Response:
             make_pdf_file(PdfRestFileID.generate(1)),
             attachment=[
                 make_attachment_file(str(PdfRestFileID.generate(2))),
-                make_attachment_file(str(PdfRestFileID.generate(3)), "more.txt"),
+                make_attachment_file(str(PdfRestFileID.generate()), "more.txt"),
             ],
         )

tests/test_add_image_to_pdf.py

@@ -233,7 +233,7 @@ def handler(_: httpx.Request) -> httpx.Response:
                 make_pdf_file(PdfRestFileID.generate(1)),
                 make_pdf_file(PdfRestFileID.generate(2)),
             ],
-            image=make_image_file(PdfRestFileID.generate(3)),
+            image=make_image_file(PdfRestFileID.generate()),
             x=1,
             y=1,
             page=1,
@@ -257,7 +257,7 @@ def handler(_: httpx.Request) -> httpx.Response:
             make_pdf_file(PdfRestFileID.generate(1)),
             image=[
                 make_image_file(PdfRestFileID.generate(2)),
-                make_image_file(PdfRestFileID.generate(3), name="secondary.png"),
+                make_image_file(PdfRestFileID.generate(), name="secondary.png"),
             ],
             x=1,
             y=1,
@@ -335,6 +335,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["x"] == 15
             assert payload["y"] == 25
+            assert payload["output"] == "async-image-output"
             captured_timeout["value"] = request.extensions.get("timeout")
             return httpx.Response(
                 200,
@@ -363,6 +364,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             x=15,
             y=25,
             page=1,
+            output="async-image-output",
             extra_query={"trace": "true"},
             extra_headers={"X-Test": "async"},
             extra_body={"x": 15},

tests/test_add_text_to_pdf.py

@@ -38,7 +38,7 @@ def make_text_object(**overrides: object) -> dict[str, object]:
 def _serialize_text_object_for_request(
     text_object: dict[str, object],
 ) -> dict[str, object]:
-    serialized = dict(text_object)
+    serialized = {key: value for key, value in text_object.items() if value is not None}
     # PdfAddTextObjectModel defines these fields as floats, so Pydantic serializes
     # integer inputs as 200.0/45.0/etc. Mirror that to keep wire assertions exact.
     for key in ("max_width", "rotation", "text_size", "x", "y"):
@@ -226,6 +226,275 @@ def handler(_: httpx.Request) -> httpx.Response:
         )
 
 
+def test_add_text_to_pdf_rejects_non_integer_rgb_values(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        pytest.fail("Request should not be sent when validation fails.")
+
+    transport = httpx.MockTransport(handler)
+    with (
+        PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client,
+        pytest.raises(
+            ValidationError,
+            match=re.escape("text_color_rgb values must be integers."),
+        ),
+    ):
+        client.add_text_to_pdf(
+            make_pdf_file(PdfRestFileID.generate(1)),
+            text_objects=[make_text_object(text_color_rgb=(0, "invalid", 2))],
+        )
+
+
+def test_add_text_to_pdf_rejects_non_integer_cmyk_values(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        pytest.fail("Request should not be sent when validation fails.")
+
+    transport = httpx.MockTransport(handler)
+    with (
+        PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client,
+        pytest.raises(
+            ValidationError,
+            match=re.escape("text_color_cmyk values must be integers."),
+        ),
+    ):
+        client.add_text_to_pdf(
+            make_pdf_file(PdfRestFileID.generate(1)),
+            text_objects=[
+                make_text_object(text_color_rgb=None, text_color_cmyk=(0, 0, "bad", 0))
+            ],
+        )
+
+
+def test_add_text_to_pdf_rejects_incomplete_cmyk_values(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        pytest.fail("Request should not be sent when validation fails.")
+
+    transport = httpx.MockTransport(handler)
+    with (
+        PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client,
+        pytest.raises(
+            ValidationError,
+            match=re.escape("text_color_cmyk must have exactly 4 values."),
+        ),
+    ):
+        client.add_text_to_pdf(
+            make_pdf_file(PdfRestFileID.generate(1)),
+            text_objects=[
+                make_text_object(text_color_rgb=None, text_color_cmyk=(0, 0, 0))
+            ],
+        )
+
+
+def test_add_text_to_pdf_rejects_non_sequence_rgb_color(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        pytest.fail("Request should not be sent when validation fails.")
+
+    transport = httpx.MockTransport(handler)
+    with (
+        PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client,
+        pytest.raises(
+            ValidationError,
+            match=re.escape("Must be a list, or a comma separated string."),
+        ),
+    ):
+        client.add_text_to_pdf(
+            make_pdf_file(PdfRestFileID.generate(1)),
+            text_objects=[make_text_object(text_color_rgb=123)],
+        )
+
+
+def test_add_text_to_pdf_rejects_incomplete_rgb_values(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        pytest.fail("Request should not be sent when validation fails.")
+
+    transport = httpx.MockTransport(handler)
+    with (
+        PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client,
+        pytest.raises(
+            ValidationError,
+            match=re.escape("text_color_rgb must have exactly 3 values."),
+        ),
+    ):
+        client.add_text_to_pdf(
+            make_pdf_file(PdfRestFileID.generate(1)),
+            text_objects=[make_text_object(text_color_rgb=(1, 2))],
+        )
+
+
+def test_add_text_to_pdf_rejects_multiple_color_modes(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        pytest.fail("Request should not be sent when validation fails.")
+
+    transport = httpx.MockTransport(handler)
+    with (
+        PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client,
+        pytest.raises(
+            ValidationError,
+            match=re.escape("Provide only one of text_color_rgb or text_color_cmyk."),
+        ),
+    ):
+        client.add_text_to_pdf(
+            make_pdf_file(PdfRestFileID.generate(1)),
+            text_objects=[make_text_object(text_color_cmyk=(0, 0, 0, 0))],
+        )
+
+
+def test_add_text_to_pdf_rejects_invalid_page_selector(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        pytest.fail("Request should not be sent when validation fails.")
+
+    transport = httpx.MockTransport(handler)
+    with (
+        PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client,
+        pytest.raises(
+            ValidationError,
+            match=re.escape('page must be a positive integer or "all".'),
+        ),
+    ):
+        client.add_text_to_pdf(
+            make_pdf_file(PdfRestFileID.generate(1)),
+            text_objects=[make_text_object(page="zero")],
+        )
+
+
+def test_add_text_to_pdf_rejects_disallowed_output_prefix(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        pytest.fail("Request should not be sent when validation fails.")
+
+    transport = httpx.MockTransport(handler)
+    with (
+        PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client,
+        pytest.raises(
+            ValidationError,
+            match=re.escape("The output prefix must not contain `..`."),
+        ),
+    ):
+        client.add_text_to_pdf(
+            make_pdf_file(PdfRestFileID.generate(1)),
+            text_objects=[make_text_object()],
+            output="bad..prefix",
+        )
+
+
+def test_add_text_to_pdf_accepts_comma_separated_rgb_string(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+    pdf_file = make_pdf_file(PdfRestFileID.generate(1))
+    output_id = str(PdfRestFileID.generate())
+    text_object = make_text_object(text_color_rgb="10,20,30", text_color_cmyk=None)
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST" and request.url.path == "/pdf-with-added-text":
+            payload = json.loads(request.content.decode("utf-8"))
+            assert payload["text_objects"] == json.dumps(
+                [_serialize_text_object_for_request(text_object)],
+                separators=(",", ":"),
+            )
+            return httpx.Response(
+                200,
+                json={
+                    "inputId": [pdf_file.id],
+                    "outputId": [output_id],
+                },
+            )
+        if request.method == "GET" and request.url.path == f"/resource/{output_id}":
+            return httpx.Response(
+                200,
+                json=build_file_info_payload(
+                    output_id,
+                    "comma-rgb.pdf",
+                    "application/pdf",
+                ),
+            )
+        msg = f"Unexpected request {request.method} {request.url}"
+        raise AssertionError(msg)
+
+    transport = httpx.MockTransport(handler)
+    with PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client:
+        response = client.add_text_to_pdf(
+            pdf_file,
+            text_objects=[text_object],
+        )
+
+    assert response.output_file.name == "comma-rgb.pdf"
+
+
+def test_add_text_to_pdf_accepts_numeric_page_string(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+    pdf_file = make_pdf_file(PdfRestFileID.generate(1))
+    output_id = str(PdfRestFileID.generate())
+    text_object = make_text_object(page="2")
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST" and request.url.path == "/pdf-with-added-text":
+            payload = json.loads(request.content.decode("utf-8"))
+            assert payload["text_objects"] == json.dumps(
+                [_serialize_text_object_for_request(make_text_object(page=2))],
+                separators=(",", ":"),
+            )
+            return httpx.Response(
+                200,
+                json={
+                    "inputId": [pdf_file.id],
+                    "outputId": [output_id],
+                },
+            )
+        if request.method == "GET" and request.url.path == f"/resource/{output_id}":
+            return httpx.Response(
+                200,
+                json=build_file_info_payload(
+                    output_id,
+                    "numeric-page.pdf",
+                    "application/pdf",
+                ),
+            )
+        msg = f"Unexpected request {request.method} {request.url}"
+        raise AssertionError(msg)
+
+    transport = httpx.MockTransport(handler)
+    with PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client:
+        response = client.add_text_to_pdf(
+            pdf_file,
+            text_objects=[text_object],
+        )
+
+    assert response.output_file.name == "numeric-page.pdf"
+
+
 def test_add_text_to_pdf_text_size_bounds(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
@@ -333,6 +602,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             assert request.headers["X-Test"] == "async"
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["text_size"] == 18
+            assert payload["output"] == "async-custom-output"
             assert payload["text_objects"] == json.dumps(
                 [_serialize_text_object_for_request(overridden_text_object)],
                 separators=(",", ":"),
@@ -364,6 +634,7 @@ def handler(request: httpx.Request) -> httpx.Response:
         response = await client.add_text_to_pdf(
             pdf_file,
             text_objects=[make_text_object(text_size=18)],
+            output="async-custom-output",
             extra_query={"trace": "true"},
             extra_headers={"X-Test": "async"},
             extra_body={