Add Convert Colors in PDF methods

datalogics-cgreen · datalogics-cgreen · commit 197531b89a34 · 2026-01-13T11:06:23.000-06:00
Assisted-by: Codex
diff --git a/src/pdfrest/client.py b/src/pdfrest/client.py
@@ -82,6 +82,7 @@
     JpegPdfRestPayload,
     OcrPdfPayload,
     PdfCompressPayload,
+    PdfConvertColorsPayload,
     PdfFlattenAnnotationsPayload,
     PdfFlattenFormsPayload,
     PdfFlattenTransparenciesPayload,
@@ -116,6 +117,7 @@
     JpegColorModel,
     OcrLanguage,
     PdfAType,
+    PdfColorProfile,
     PdfInfoQuery,
     PdfMergeInput,
     PdfPageSelection,
@@ -2717,6 +2719,41 @@ def compress_pdf(
             timeout=timeout,
         )
 
+    def convert_colors(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        color_profile: PdfColorProfile,
+        profile: PdfRestFile | Sequence[PdfRestFile] | None = None,
+        preserve_black: bool = False,
+        output: str | None = None,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Convert PDF colors using preset or custom ICC profiles."""
+
+        payload: dict[str, Any] = {
+            "files": file,
+            "color_profile": color_profile,
+            "preserve_black": preserve_black,
+        }
+        if profile is not None:
+            payload["profile"] = profile
+        if output is not None:
+            payload["output"] = output
+
+        return self._post_file_operation(
+            endpoint="/pdf-with-converted-colors",
+            payload=payload,
+            payload_model=PdfConvertColorsPayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     def flatten_transparencies(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],
@@ -3759,6 +3796,41 @@ async def compress_pdf(
             timeout=timeout,
         )
 
+    async def convert_colors(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        color_profile: PdfColorProfile,
+        profile: PdfRestFile | Sequence[PdfRestFile] | None = None,
+        preserve_black: bool = False,
+        output: str | None = None,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Asynchronously convert PDF colors using preset or custom ICC profiles."""
+
+        payload: dict[str, Any] = {
+            "files": file,
+            "color_profile": color_profile,
+            "preserve_black": preserve_black,
+        }
+        if profile is not None:
+            payload["profile"] = profile
+        if output is not None:
+            payload["output"] = output
+
+        return await self._post_file_operation(
+            endpoint="/pdf-with-converted-colors",
+            payload=payload,
+            payload_model=PdfConvertColorsPayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     async def flatten_transparencies(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],
diff --git a/src/pdfrest/models/_internal.py b/src/pdfrest/models/_internal.py
@@ -25,6 +25,7 @@
 from ..types import (
     OcrLanguage,
     PdfAType,
+    PdfColorProfile,
     PdfInfoQuery,
     PdfXType,
     SummaryFormat,
@@ -1142,6 +1143,68 @@ class PdfFlattenAnnotationsPayload(BaseModel):
     ] = None
 
 
+class PdfConvertColorsPayload(BaseModel):
+    """Adapt caller options into a pdfRest-ready convert-colors request payload."""
+
+    files: Annotated[
+        list[PdfRestFile],
+        Field(
+            min_length=1,
+            max_length=1,
+            validation_alias=AliasChoices("file", "files"),
+            serialization_alias="id",
+        ),
+        BeforeValidator(_ensure_list),
+        AfterValidator(
+            _allowed_mime_types("application/pdf", error_msg="Must be a PDF file")
+        ),
+        PlainSerializer(_serialize_as_first_file_id),
+    ]
+    color_profile: Annotated[
+        PdfColorProfile,
+        Field(serialization_alias="color_profile"),
+    ]
+    profile: Annotated[
+        list[PdfRestFile] | None,
+        Field(
+            default=None,
+            min_length=1,
+            max_length=1,
+            validation_alias=AliasChoices("profile", "profiles"),
+            serialization_alias="profile_id",
+        ),
+        BeforeValidator(_ensure_list),
+        AfterValidator(
+            _allowed_mime_types(
+                "application/vnd.iccprofile",
+                "application/octet-stream",
+                error_msg="Profile must be an ICC file",
+            )
+        ),
+        PlainSerializer(_serialize_as_first_file_id),
+    ] = None
+    preserve_black: Annotated[
+        bool | None,
+        Field(serialization_alias="preserve_black", default=None),
+    ] = None
+    output: Annotated[
+        str | None,
+        Field(serialization_alias="output", min_length=1, default=None),
+        AfterValidator(_validate_output_prefix),
+    ] = None
+
+    @model_validator(mode="after")
+    def _validate_profile_dependency(self) -> PdfConvertColorsPayload:
+        if self.color_profile == "custom":
+            if not self.profile:
+                msg = "color_profile 'custom' requires a profile to be provided."
+                raise ValueError(msg)
+        elif self.profile:
+            msg = "A profile can only be provided when color_profile is 'custom'."
+            raise ValueError(msg)
+        return self
+
+
 class BmpPdfRestPayload(BasePdfRestGraphicPayload[Literal["rgb", "gray"]]):
     """Adapt caller options into a pdfRest-ready BMP request payload."""
 
diff --git a/src/pdfrest/types/__init__.py b/src/pdfrest/types/__init__.py
@@ -12,6 +12,7 @@
     JpegColorModel,
     OcrLanguage,
     PdfAType,
+    PdfColorProfile,
     PdfInfoQuery,
     PdfMergeInput,
     PdfMergeSource,
@@ -41,6 +42,7 @@
     "JpegColorModel",
     "OcrLanguage",
     "PdfAType",
+    "PdfColorProfile",
     "PdfInfoQuery",
     "PdfMergeInput",
     "PdfMergeSource",
diff --git a/src/pdfrest/types/public.py b/src/pdfrest/types/public.py
@@ -24,6 +24,7 @@
     "JpegColorModel",
     "OcrLanguage",
     "PdfAType",
+    "PdfColorProfile",
     "PdfInfoQuery",
     "PdfMergeInput",
     "PdfMergeSource",
@@ -160,3 +161,20 @@ class PdfMergeSource(TypedDict, total=False):
 ALL_OCR_LANGUAGES: tuple[OcrLanguage, ...] = cast(
     tuple[OcrLanguage, ...], get_args(OcrLanguage)
 )
+PdfColorProfile = Literal[
+    "lab-d50",
+    "srgb",
+    "apple-rgb",
+    "color-match-rgb",
+    "gamma-18",
+    "gamma-22",
+    "dot-gain-10",
+    "dot-gain-15",
+    "dot-gain-20",
+    "dot-gain-25",
+    "dot-gain-30",
+    "monitor-rgb",
+    "acrobat5-cmyk",
+    "acrobat9-cmyk",
+    "custom",
+]
diff --git a/tests/live/test_live_convert_colors.py b/tests/live/test_live_convert_colors.py
@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import pytest
+
+from pdfrest import AsyncPdfRestClient, PdfRestApiError, PdfRestClient
+from pdfrest.models import PdfRestFile
+
+from ..resources import get_test_resource_path
+
+
+@pytest.fixture(scope="module")
+def uploaded_pdf_for_color_conversion(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+) -> PdfRestFile:
+    resource = get_test_resource_path("report.pdf")
+    with PdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        return client.files.create_from_paths([resource])[0]
+
+
+@pytest.mark.parametrize(
+    "output_name",
+    [
+        pytest.param(None, id="default-output"),
+        pytest.param("converted-colors", id="custom-output"),
+    ],
+)
+def test_live_convert_colors_success(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    uploaded_pdf_for_color_conversion: PdfRestFile,
+    output_name: str | None,
+) -> None:
+    kwargs: dict[str, str | bool] = {"color_profile": "srgb"}
+    if output_name is not None:
+        kwargs["output"] = output_name
+
+    with PdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        response = client.convert_colors(uploaded_pdf_for_color_conversion, **kwargs)
+
+    assert response.output_files
+    output_file = response.output_file
+    assert output_file.type == "application/pdf"
+    assert output_file.size > 0
+    assert response.warning is None
+    assert str(response.input_id) == str(uploaded_pdf_for_color_conversion.id)
+    if output_name is not None:
+        assert output_file.name.startswith(output_name)
+    else:
+        assert output_file.name.endswith(".pdf")
+
+
+@pytest.mark.asyncio
+async def test_live_async_convert_colors_success(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    uploaded_pdf_for_color_conversion: PdfRestFile,
+) -> None:
+    async with AsyncPdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        response = await client.convert_colors(
+            uploaded_pdf_for_color_conversion,
+            color_profile="srgb",
+            output="async",
+        )
+
+    assert response.output_files
+    output_file = response.output_file
+    assert output_file.name.startswith("async")
+    assert output_file.type == "application/pdf"
+    assert output_file.size > 0
+    assert response.warning is None
+    assert str(response.input_id) == str(uploaded_pdf_for_color_conversion.id)
+
+
+def test_live_convert_colors_invalid_file_id(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    uploaded_pdf_for_color_conversion: PdfRestFile,
+) -> None:
+    with (
+        PdfRestClient(
+            api_key=pdfrest_api_key,
+            base_url=pdfrest_live_base_url,
+        ) as client,
+        pytest.raises(PdfRestApiError, match=r"(?i)(id|file)"),
+    ):
+        client.convert_colors(
+            uploaded_pdf_for_color_conversion,
+            color_profile="srgb",
+            extra_body={"id": "00000000-0000-0000-0000-000000000000"},
+        )
+
+
+@pytest.mark.asyncio
+async def test_live_async_convert_colors_invalid_file_id(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    uploaded_pdf_for_color_conversion: PdfRestFile,
+) -> None:
+    async with AsyncPdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        with pytest.raises(PdfRestApiError, match=r"(?i)(id|file)"):
+            await client.convert_colors(
+                uploaded_pdf_for_color_conversion,
+                color_profile="srgb",
+                extra_body={"id": "ffffffff-ffff-ffff-ffff-ffffffffffff"},
+            )
diff --git a/tests/test_convert_colors.py b/tests/test_convert_colors.py
