Add support for multi-format graphic conversions (sync & async)

- Implemented methods to convert PDF files to BMP, GIF, JPEG, PNG, and
  TIFF formats in both synchronous and asynchronous clients.
- Centralized `convert_to_graphic` method for reusable logic across all
  conversion methods.
- Added payload models for each graphic format to ensure parameter
  validation and API compatibility.
- Extended tests to verify conversion logic, including live integration
  tests for color models, resolution bounds, and smoothing options.

Assisted-by: Codex

Author: datalogics-kam

src/pdfrest/client.py

@@ -3,7 +3,7 @@
 import re
 from collections.abc import Callable
 from pathlib import PurePath
-from typing import Annotated, Any, Literal
+from typing import Annotated, Any, Generic, Literal, TypeVar
 
 from pydantic import (
     AfterValidator,
@@ -178,7 +178,10 @@ class UploadURLs(BaseModel):
     ]
 
 
-class ConvertToGraphic(BaseModel):
+ColorModelT = TypeVar("ColorModelT", bound=str)
+
+
+class BasePdfRestGraphicPayload(BaseModel, Generic[ColorModelT]):
     files: Annotated[
         list[PdfRestFile],
         Field(
@@ -207,7 +210,7 @@ class ConvertToGraphic(BaseModel):
         PlainSerializer(_serialize_as_comma_separated_string),
     ]
     resolution: Annotated[int, Field(ge=12, le=2400, default=300)]
-    color_model: Annotated[Literal["rgb", "rgba", "gray"], Field(default="rgb")]
+    color_model: Annotated[ColorModelT, Field(default=...)]
     smoothing: Annotated[
         list[Literal["none", "all", "text", "line", "image"]],
         Field(default="none"),
@@ -217,6 +220,41 @@ class ConvertToGraphic(BaseModel):
     ]
 
 
+class PngPdfRestPayload(BasePdfRestGraphicPayload[Literal["rgb", "rgba", "gray"]]):
+    """Adapt caller options into a pdfRest-ready PNG request payload."""
+
+    color_model: Annotated[Literal["rgb", "rgba", "gray"], Field(default="rgb")]
+
+
+class BmpPdfRestPayload(BasePdfRestGraphicPayload[Literal["rgb", "gray"]]):
+    """Adapt caller options into a pdfRest-ready BMP request payload."""
+
+    color_model: Annotated[Literal["rgb", "gray"], Field(default="rgb")]
+
+
+class GifPdfRestPayload(BasePdfRestGraphicPayload[Literal["rgb", "gray"]]):
+    """Adapt caller options into a pdfRest-ready GIF request payload."""
+
+    color_model: Annotated[Literal["rgb", "gray"], Field(default="rgb")]
+
+
+class JpegPdfRestPayload(BasePdfRestGraphicPayload[Literal["rgb", "cmyk", "gray"]]):
+    """Adapt caller options into a pdfRest-ready JPEG request payload."""
+
+    color_model: Annotated[Literal["rgb", "cmyk", "gray"], Field(default="rgb")]
+    jpeg_quality: Annotated[int, Field(ge=1, le=100, default=75)]
+
+
+class TiffPdfRestPayload(
+    BasePdfRestGraphicPayload[Literal["rgb", "rgba", "cmyk", "lab", "gray"]]
+):
+    """Adapt caller options into a pdfRest-ready TIFF request payload."""
+
+    color_model: Annotated[
+        Literal["rgb", "rgba", "cmyk", "lab", "gray"], Field(default="rgb")
+    ]
+
+
 class PdfRestRawUploadedFile(BaseModel):
     """The response sent by /upload is a list of these. /unzip returns files like this
     with outputUrl"""

src/pdfrest/models/_internal.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import datetime, timezone
+from typing import Any
+
+from pdfrest.models import PdfRestFile
+
+VALID_API_KEY = "12345678-1234-1234-1234-123456789abc"
+ASYNC_API_KEY = "fedcba98-7654-3210-fedc-ba9876543210"
+
+
+def build_file_info_payload(file_id: str, name: str, mime_type: str) -> dict[str, Any]:
+    return {
+        "id": file_id,
+        "name": name,
+        "url": f"https://api.pdfrest.com/resource/{file_id}",
+        "type": mime_type,
+        "size": 256,
+        "modified": datetime(2024, 1, 1, tzinfo=timezone.utc)
+        .isoformat()
+        .replace("+00:00", "Z"),
+        "scheduledDeletionTimeUtc": None,
+    }
+
+
+def make_pdf_file(file_id: str, name: str = "example.pdf") -> PdfRestFile:
+    return PdfRestFile.model_validate(
+        {
+            "id": file_id,
+            "name": name,
+            "url": f"https://api.pdfrest.com/resource/{file_id}",
+            "type": "application/pdf",
+            "size": 1024,
+            "modified": datetime(2024, 1, 1, tzinfo=timezone.utc)
+            .isoformat()
+            .replace("+00:00", "Z"),
+            "scheduledDeletionTimeUtc": None,
+        }
+    )
+
+
+def assert_conversion_payload(
+    payload: dict[str, Any],
+    expected: dict[str, Any],
+    *,
+    allowed_extras: Iterable[str] | None = None,
+) -> None:
+    for key, value in expected.items():
+        assert payload[key] == value
+    extra_keys = set(payload) - set(expected)
+    permitted = {"color_model", "resolution"}
+    if allowed_extras is not None:
+        permitted.update(allowed_extras)
+    assert extra_keys <= permitted
+    if "resolution" not in expected and "resolution" in payload:
+        assert payload["resolution"] == 300
+    if "color_model" not in expected and "color_model" in payload:
+        assert payload["color_model"] == "rgb"

tests/graphics_test_helpers.py

@@ -0,0 +1 @@
+# Package for live integration tests.

tests/live/__init__.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any, NamedTuple, get_args
+
+import pytest
+
+from pdfrest import PdfRestApiError, PdfRestClient
+from pdfrest.models._internal import (
+    BasePdfRestGraphicPayload,
+    BmpPdfRestPayload,
+    GifPdfRestPayload,
+    JpegPdfRestPayload,
+    PngPdfRestPayload,
+    TiffPdfRestPayload,
+)
+
+from ..resources import get_test_resource_path
+
+
+class _GraphicEndpointSpec(NamedTuple):
+    method_name: str
+    payload_model: type[BasePdfRestGraphicPayload[Any]]
+
+
+PAYLOAD_MODELS: dict[str, _GraphicEndpointSpec] = {
+    "png": _GraphicEndpointSpec("convert_to_png", PngPdfRestPayload),
+    "bmp": _GraphicEndpointSpec("convert_to_bmp", BmpPdfRestPayload),
+    "gif": _GraphicEndpointSpec("convert_to_gif", GifPdfRestPayload),
+    "jpeg": _GraphicEndpointSpec("convert_to_jpeg", JpegPdfRestPayload),
+    "tiff": _GraphicEndpointSpec("convert_to_tiff", TiffPdfRestPayload),
+}
+
+
+def _enumerate_color_models(
+    payload_model: type[BasePdfRestGraphicPayload[Any]],
+) -> Iterable[str]:
+    field = payload_model.model_fields["color_model"]
+    return get_args(field.annotation) or ()
+
+
+def _resolution_bounds(
+    payload_model: type[BasePdfRestGraphicPayload[Any]],
+) -> tuple[int, int]:
+    field = payload_model.model_fields["resolution"]
+    ge = field.metadata[0].ge if field.metadata else 12
+    le = field.metadata[1].le if len(field.metadata) > 1 else 2400
+    return int(ge), int(le)
+
+
+def _valid_color_cases() -> list[Any]:
+    cases = []
+    for label, spec in PAYLOAD_MODELS.items():
+        for color_model in _enumerate_color_models(spec.payload_model):
+            cases.append(
+                pytest.param(label, spec, color_model, id=f"{label}-{color_model}")
+            )
+    return cases
+
+
+def _invalid_color_cases() -> list[Any]:
+    cases = []
+    candidates = ("lab", "rgba", "cmyk", "xyz", "ultraviolet", "infrared-spectrum")
+    for label, spec in PAYLOAD_MODELS.items():
+        allowed = set(_enumerate_color_models(spec.payload_model))
+        seen: set[str] = set()
+        for value in (*candidates, "not-a-color-model"):
+            if value in allowed or value in seen:
+                continue
+            seen.add(value)
+            cases.append(pytest.param(label, spec, value, id=f"{label}-{value}"))
+    return cases
+
+
+_SMOOTHING_VALUES: tuple[str, ...] = ("none", "all", "text", "line", "image")
+
+
+def _valid_smoothing_cases() -> list[Any]:
+    cases = []
+    for label, spec in PAYLOAD_MODELS.items():
+        for smoothing in _SMOOTHING_VALUES:
+            cases.append(
+                pytest.param(label, spec, smoothing, id=f"{label}-{smoothing}")
+            )
+    return cases
+
+
+def _invalid_smoothing_cases() -> list[Any]:
+    cases = []
+    invalid_inputs: tuple[Any, ...] = (
+        "quantum",
+        "super-smooth",
+        ["line", "hyperreal"],
+    )
+    for label, spec in PAYLOAD_MODELS.items():
+        for candidate in invalid_inputs:
+            case_id = (
+                f"{label}-{'-'.join(candidate)}"
+                if isinstance(candidate, list)
+                else f"{label}-{candidate}"
+            )
+            cases.append(pytest.param(label, spec, candidate, id=case_id))
+    return cases
+
+
+@pytest.mark.parametrize(
+    ("_endpoint_label", "spec", "color_model"),
+    _valid_color_cases(),
+)
+def test_live_graphic_valid_color_models(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    _endpoint_label: str,
+    spec: _GraphicEndpointSpec,
+    color_model: str,
+) -> None:
+    if TYPE_CHECKING:
+        return
+
+    resource = get_test_resource_path("report.pdf")
+    payload_model = spec.payload_model
+    resolution = _resolution_bounds(payload_model)[0]
+    with PdfRestClient(
+        api_key=pdfrest_api_key, base_url=pdfrest_live_base_url
+    ) as client:
+        uploaded = client.files.create_from_paths([resource])[0]
+        client_method = getattr(client, spec.method_name)
+        response = client_method(
+            uploaded,
+            color_model=color_model,
+            resolution=resolution,
+        )
+        assert response.output_files
+
+
+@pytest.mark.parametrize(
+    ("_endpoint_label", "spec", "invalid_color"),
+    _invalid_color_cases(),
+)
+def test_live_graphic_invalid_color_model(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    _endpoint_label: str,
+    spec: _GraphicEndpointSpec,
+    invalid_color: str,
+) -> None:
+    payload_model = spec.payload_model
+
+    resource = get_test_resource_path("report.pdf")
+    with PdfRestClient(
+        api_key=pdfrest_api_key, base_url=pdfrest_live_base_url
+    ) as client:
+        uploaded = client.files.create_from_paths([resource])[0]
+        client_method = getattr(client, spec.method_name)
+        resolution = _resolution_bounds(payload_model)[0]
+        with pytest.raises(PdfRestApiError):
+            client_method(
+                uploaded,
+                resolution=resolution,
+                extra_body={"color_model": invalid_color},
+            )
+
+
+@pytest.mark.parametrize(
+    ("_endpoint_label", "spec"),
+    PAYLOAD_MODELS.items(),
+    ids=list(PAYLOAD_MODELS),
+)
+def test_live_graphic_resolution_bounds(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    _endpoint_label: str,
+    spec: _GraphicEndpointSpec,
+) -> None:
+    payload_model = spec.payload_model
+    min_res, max_res = _resolution_bounds(payload_model)
+    resource = get_test_resource_path("report.pdf")
+
+    with PdfRestClient(
+        api_key=pdfrest_api_key, base_url=pdfrest_live_base_url
+    ) as client:
+        uploaded = client.files.create_from_paths([resource])[0]
+        client_method = getattr(client, spec.method_name)
+
+        response_min = client_method(
+            uploaded,
+            resolution=min_res,
+        )
+        assert response_min.output_files
+
+        response_max = client_method(
+            uploaded,
+            resolution=max_res,
+        )
+        assert response_max.output_files
+
+        with pytest.raises(PdfRestApiError):
+            client_method(
+                uploaded,
+                resolution=min_res,
+                extra_body={"resolution": min_res - 1},
+            )
+
+        with pytest.raises(PdfRestApiError):
+            client_method(
+                uploaded,
+                resolution=max_res,
+                extra_body={"resolution": max_res + 1},
+            )
+
+
+@pytest.mark.parametrize(
+    ("_endpoint_label", "spec", "smoothing_value"),
+    _valid_smoothing_cases(),
+)
+def test_live_graphic_valid_smoothing(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    _endpoint_label: str,
+    spec: _GraphicEndpointSpec,
+    smoothing_value: str,
+) -> None:
+    if TYPE_CHECKING:
+        return
+
+    resource = get_test_resource_path("report.pdf")
+    with PdfRestClient(
+        api_key=pdfrest_api_key, base_url=pdfrest_live_base_url
+    ) as client:
+        uploaded = client.files.create_from_paths([resource])[0]
+        client_method = getattr(client, spec.method_name)
+        response = client_method(
+            uploaded,
+            smoothing=smoothing_value,
+        )
+        assert response.output_files
+
+
+@pytest.mark.parametrize(
+    ("_endpoint_label", "spec", "invalid_smoothing"),
+    _invalid_smoothing_cases(),
+)
+def test_live_graphic_invalid_smoothing(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    _endpoint_label: str,
+    spec: _GraphicEndpointSpec,
+    invalid_smoothing: Any,
+) -> None:
+    resource = get_test_resource_path("report.pdf")
+    with PdfRestClient(
+        api_key=pdfrest_api_key, base_url=pdfrest_live_base_url
+    ) as client:
+        uploaded = client.files.create_from_paths([resource])[0]
+        client_method = getattr(client, spec.method_name)
+        with pytest.raises(PdfRestApiError):
+            client_method(
+                uploaded,
+                smoothing="none",
+                extra_body={"smoothing": invalid_smoothing},
+            )