blank-pdf: Consolidate page size parameters

Page size can be either a `str` literal or custom dimensions

Assisted-by: Codex

Author: datalogics-cgreen

src/pdfrest/client.py

@@ -3079,8 +3079,6 @@ def blank_pdf(
         page_size: PdfPageSize,
         page_count: int,
         page_orientation: PdfPageOrientation | None = None,
-        custom_height: float | None = None,
-        custom_width: float | None = None,
         output: str | None = None,
         extra_query: Query | None = None,
         extra_headers: AnyMapping | None = None,
@@ -3095,10 +3093,6 @@ def blank_pdf(
         }
         if page_orientation is not None:
             payload["page_orientation"] = page_orientation
-        if custom_height is not None:
-            payload["custom_height"] = custom_height
-        if custom_width is not None:
-            payload["custom_width"] = custom_width
         if output is not None:
             payload["output"] = output
 
@@ -4498,8 +4492,6 @@ async def blank_pdf(
         page_size: PdfPageSize,
         page_count: int,
         page_orientation: PdfPageOrientation | None = None,
-        custom_height: float | None = None,
-        custom_width: float | None = None,
         output: str | None = None,
         extra_query: Query | None = None,
         extra_headers: AnyMapping | None = None,
@@ -4514,10 +4506,6 @@ async def blank_pdf(
         }
         if page_orientation is not None:
             payload["page_orientation"] = page_orientation
-        if custom_height is not None:
-            payload["custom_height"] = custom_height
-        if custom_width is not None:
-            payload["custom_width"] = custom_width
         if output is not None:
             payload["output"] = output
 

src/pdfrest/models/_internal.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
 import re
-from collections.abc import Callable, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from pathlib import PurePath
-from typing import Annotated, Any, Generic, Literal, TypeVar
+from typing import Annotated, Any, Generic, Literal, TypeVar, cast
 
 from langcodes import tag_is_valid
 from pydantic import (
@@ -1347,7 +1347,7 @@ class PdfBlankPayload(BaseModel):
     """Adapt caller options into a pdfRest-ready blank PDF request payload."""
 
     page_size: Annotated[
-        PdfPageSize,
+        PdfPageSize | Literal["custom"],
         Field(serialization_alias="page_size"),
     ]
     page_count: Annotated[
@@ -1372,6 +1372,33 @@ class PdfBlankPayload(BaseModel):
         AfterValidator(_validate_output_prefix),
     ] = None
 
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_custom_page_size(cls, data: Any) -> Any:
+        if not isinstance(data, Mapping):
+            return data
+
+        request_data = cast(Mapping[str, Any], data)
+        page_size = request_data.get("page_size")
+        if not isinstance(page_size, Sequence) or isinstance(
+            page_size, (str, bytes, bytearray)
+        ):
+            return request_data
+
+        custom_dimensions = list(page_size)
+        if len(custom_dimensions) != 2:
+            msg = (
+                "Custom page sizes must contain exactly two values: "
+                "custom_height and custom_width."
+            )
+            raise ValueError(msg)
+
+        normalized_data: dict[str, Any] = dict(request_data)
+        normalized_data["page_size"] = "custom"
+        normalized_data["custom_height"] = custom_dimensions[0]
+        normalized_data["custom_width"] = custom_dimensions[1]
+        return normalized_data
+
     @model_validator(mode="after")
     def _validate_page_configuration(self) -> PdfBlankPayload:
         is_custom = self.page_size == "custom"

src/pdfrest/types/public.py

@@ -199,5 +199,7 @@ class PdfMergeSource(TypedDict, total=False):
 ALL_PDF_RESTRICTIONS: tuple[PdfRestriction, ...] = cast(
     tuple[PdfRestriction, ...], get_args(PdfRestriction)
 )
-PdfPageSize = Literal["letter", "legal", "ledger", "A3", "A4", "A5", "custom"]
+PdfPageSize = (
+    Literal["letter", "legal", "ledger", "A3", "A4", "A5"] | tuple[float, float]
+)
 PdfPageOrientation = Literal["portrait", "landscape"]

tests/live/test_live_blank_pdf.py

@@ -8,86 +8,66 @@
     pytest.param(
         "letter",
         "portrait",
-        None,
-        None,
         "blank-letter",
         id="letter-portrait",
     ),
     pytest.param(
         "legal",
         "landscape",
-        None,
-        None,
         "blank-legal",
         id="legal-landscape",
     ),
     pytest.param(
         "ledger",
         "portrait",
-        None,
-        None,
         "blank-ledger",
         id="ledger-portrait",
     ),
     pytest.param(
         "A3",
         "landscape",
-        None,
-        None,
         "blank-a3",
         id="a3-landscape",
     ),
     pytest.param(
         "A4",
         "portrait",
-        None,
-        None,
         "blank-a4",
         id="a4-portrait",
     ),
     pytest.param(
         "A5",
         "landscape",
-        None,
-        None,
         "blank-a5",
         id="a5-landscape",
     ),
     pytest.param(
-        "custom",
+        (792.0, 612.0),
         None,
-        792.0,
-        612.0,
         "blank-custom",
         id="custom-dimensions",
     ),
 ]
 
 
 @pytest.mark.parametrize(
-    ("page_size", "page_orientation", "custom_height", "custom_width", "output_name"),
+    ("page_size", "page_orientation", "output_name"),
     BLANK_PDF_LITERAL_CASES,
 )
 def test_live_blank_pdf_success(
     pdfrest_api_key: str,
     pdfrest_live_base_url: str,
-    page_size: str,
+    page_size: str | tuple[float, float],
     page_orientation: str | None,
-    custom_height: float | None,
-    custom_width: float | None,
     output_name: str,
 ) -> None:
-    kwargs: dict[str, str | int | float] = {
+    kwargs: dict[str, str | int | float | tuple[float, float]] = {
         "page_size": page_size,
         "page_count": 1,
         "output": output_name,
     }
     if page_orientation is not None:
         kwargs["page_orientation"] = page_orientation
-    if custom_height is not None:
-        kwargs["custom_height"] = custom_height
-    if custom_width is not None:
-        kwargs["custom_width"] = custom_width
 
     with PdfRestClient(
         api_key=pdfrest_api_key,
@@ -105,29 +85,23 @@ def test_live_blank_pdf_success(
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    ("page_size", "page_orientation", "custom_height", "custom_width", "output_name"),
+    ("page_size", "page_orientation", "output_name"),
     BLANK_PDF_LITERAL_CASES,
 )
 async def test_live_async_blank_pdf_success(
     pdfrest_api_key: str,
     pdfrest_live_base_url: str,
-    page_size: str,
+    page_size: str | tuple[float, float],
     page_orientation: str | None,
-    custom_height: float | None,
-    custom_width: float | None,
     output_name: str,
 ) -> None:
-    kwargs: dict[str, str | int | float] = {
+    kwargs: dict[str, str | int | float | tuple[float, float]] = {
         "page_size": page_size,
         "page_count": 2,
         "output": output_name,
     }
     if page_orientation is not None:
         kwargs["page_orientation"] = page_orientation
-    if custom_height is not None:
-        kwargs["custom_height"] = custom_height
-    if custom_width is not None:
-        kwargs["custom_width"] = custom_width
 
     async with AsyncPdfRestClient(
         api_key=pdfrest_api_key,

tests/test_blank_pdf.py

@@ -297,18 +297,17 @@ async def test_async_blank_pdf_page_count_boundaries_validation(
 
 
 @pytest.mark.parametrize(
-    ("custom_height", "custom_width", "match"),
+    ("page_size", "match"),
     [
-        pytest.param(0.0, 10.0, "greater than 0", id="height-zero"),
-        pytest.param(-1.0, 10.0, "greater than 0", id="height-negative"),
-        pytest.param(10.0, 0.0, "greater than 0", id="width-zero"),
-        pytest.param(10.0, -1.0, "greater than 0", id="width-negative"),
+        pytest.param((0.0, 10.0), "greater than 0", id="height-zero"),
+        pytest.param((-1.0, 10.0), "greater than 0", id="height-negative"),
+        pytest.param((10.0, 0.0), "greater than 0", id="width-zero"),
+        pytest.param((10.0, -1.0), "greater than 0", id="width-negative"),
     ],
 )
 def test_blank_pdf_custom_dimensions_validation(
     monkeypatch: pytest.MonkeyPatch,
-    custom_height: float,
-    custom_width: float,
+    page_size: tuple[float, float],
     match: str,
 ) -> None:
     monkeypatch.delenv("PDFREST_API_KEY", raising=False)
@@ -319,27 +318,24 @@ def test_blank_pdf_custom_dimensions_validation(
         pytest.raises(ValidationError, match=match),
     ):
         client.blank_pdf(
-            page_size="custom",
+            page_size=page_size,
             page_count=1,
-            custom_height=custom_height,
-            custom_width=custom_width,
         )
 
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    ("custom_height", "custom_width", "match"),
+    ("page_size", "match"),
     [
-        pytest.param(0.0, 10.0, "greater than 0", id="height-zero"),
-        pytest.param(-1.0, 10.0, "greater than 0", id="height-negative"),
-        pytest.param(10.0, 0.0, "greater than 0", id="width-zero"),
-        pytest.param(10.0, -1.0, "greater than 0", id="width-negative"),
+        pytest.param((0.0, 10.0), "greater than 0", id="height-zero"),
+        pytest.param((-1.0, 10.0), "greater than 0", id="height-negative"),
+        pytest.param((10.0, 0.0), "greater than 0", id="width-zero"),
+        pytest.param((10.0, -1.0), "greater than 0", id="width-negative"),
     ],
 )
 async def test_async_blank_pdf_custom_dimensions_validation(
     monkeypatch: pytest.MonkeyPatch,
-    custom_height: float,
-    custom_width: float,
+    page_size: tuple[float, float],
     match: str,
 ) -> None:
     monkeypatch.delenv("PDFREST_API_KEY", raising=False)
@@ -348,10 +344,8 @@ async def test_async_blank_pdf_custom_dimensions_validation(
     async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
         with pytest.raises(ValidationError, match=match):
             await client.blank_pdf(
-                page_size="custom",
+                page_size=page_size,
                 page_count=1,
-                custom_height=custom_height,
-                custom_width=custom_width,
             )
 
 
@@ -458,10 +452,8 @@ def handler(request: httpx.Request) -> httpx.Response:
     transport = httpx.MockTransport(handler)
     with PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client:
         response = client.blank_pdf(
-            page_size="custom",
+            page_size=(792, 612),
             page_count=3,
-            custom_height=792,
-            custom_width=612,
             output="custom",
             extra_query={"trace": "true"},
             extra_headers={"X-Debug": "sync"},
@@ -581,10 +573,8 @@ def handler(request: httpx.Request) -> httpx.Response:
     transport = httpx.MockTransport(handler)
     async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
         response = await client.blank_pdf(
-            page_size="custom",
+            page_size=(100, 50),
             page_count=1,
-            custom_height=100,
-            custom_width=50,
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"debug": "yes"},
@@ -615,33 +605,18 @@ def test_blank_pdf_validation(monkeypatch: pytest.MonkeyPatch) -> None:
 
     with (
         PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client,
-        pytest.raises(ValueError, match="custom_height and custom_width are required"),
+        pytest.raises(ValueError, match="Custom page sizes must contain exactly two"),
     ):
-        client.blank_pdf(page_size="custom", page_count=1, custom_height=50)
-
-    with (
-        PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client,
-        pytest.raises(
-            ValueError, match="custom_height and custom_width can only be provided"
-        ),
-    ):
-        client.blank_pdf(
-            page_size="A3",
-            page_count=1,
-            page_orientation="portrait",
-            custom_width=10,
-        )
+        client.blank_pdf(page_size=(50,), page_count=1)
 
     with (
         PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client,
         pytest.raises(ValueError, match="page_orientation must be omitted"),
     ):
         client.blank_pdf(
-            page_size="custom",
+            page_size=(10, 10),
             page_count=1,
             page_orientation="portrait",
-            custom_width=10,
-            custom_height=10,
         )
 
     with (