blank-pdf: Encapsulate custom page dimensions

Assisted-by: Codex

Author: datalogics-cgreen

src/pdfrest/models/_internal.py

@@ -1404,19 +1404,20 @@ def _normalize_custom_page_size(cls, data: Any) -> Any:
 
         normalized_data: dict[str, Any] = dict(cast(Mapping[str, Any], data))
         page_size = normalized_data.get("page_size")
-        if isinstance(page_size, Sequence) and not isinstance(
-            page_size, (str, bytes, bytearray)
-        ):
-            custom_dimensions = list(page_size)
-            if len(custom_dimensions) != 2:
+        if isinstance(page_size, Mapping):
+            custom_page_size = cast(Mapping[str, Any], page_size)
+            if (
+                "custom_height" not in custom_page_size
+                or "custom_width" not in custom_page_size
+            ):
                 msg = (
-                    "Custom page sizes must contain exactly two values: "
-                    "custom_height and custom_width."
+                    "Custom page sizes must include both custom_height and "
+                    "custom_width."
                 )
                 raise ValueError(msg)
             normalized_data["page_size"] = "custom"
-            normalized_data["custom_height"] = custom_dimensions[0]
-            normalized_data["custom_width"] = custom_dimensions[1]
+            normalized_data["custom_height"] = custom_page_size["custom_height"]
+            normalized_data["custom_width"] = custom_page_size["custom_width"]
 
         if (
             normalized_data.get("page_size") is not None

src/pdfrest/types/__init__.py

@@ -15,6 +15,7 @@
     PdfAddTextObject,
     PdfAType,
     PdfCmykColor,
+    PdfCustomPageSize,
     PdfInfoQuery,
     PdfMergeInput,
     PdfMergeSource,
@@ -50,6 +51,7 @@
     "PdfAType",
     "PdfAddTextObject",
     "PdfCmykColor",
+    "PdfCustomPageSize",
     "PdfInfoQuery",
     "PdfMergeInput",
     "PdfMergeSource",

src/pdfrest/types/public.py

@@ -27,6 +27,7 @@
     "PdfAType",
     "PdfAddTextObject",
     "PdfCmykColor",
+    "PdfCustomPageSize",
     "PdfInfoQuery",
     "PdfMergeInput",
     "PdfMergeSource",
@@ -128,6 +129,11 @@ class PdfAddTextObject(TypedDict, total=False):
     is_right_to_left: bool
 
 
+class PdfCustomPageSize(TypedDict):
+    custom_height: Required[float]
+    custom_width: Required[float]
+
+
 PdfPageSelection = str | int | Sequence[str | int]
 
 
@@ -199,7 +205,5 @@ class PdfMergeSource(TypedDict, total=False):
 ALL_PDF_RESTRICTIONS: tuple[PdfRestriction, ...] = cast(
     tuple[PdfRestriction, ...], get_args(PdfRestriction)
 )
-PdfPageSize = (
-    Literal["letter", "legal", "ledger", "A3", "A4", "A5"] | tuple[float, float]
-)
+PdfPageSize = Literal["letter", "legal", "ledger", "A3", "A4", "A5"] | PdfCustomPageSize
 PdfPageOrientation = Literal["portrait", "landscape"]

tests/live/test_live_blank_pdf.py

@@ -3,6 +3,7 @@
 import pytest
 
 from pdfrest import AsyncPdfRestClient, PdfRestApiError, PdfRestClient
+from pdfrest.types import PdfCustomPageSize
 
 BLANK_PDF_LITERAL_CASES = [
     pytest.param(
@@ -42,7 +43,7 @@
         id="a5-landscape",
     ),
     pytest.param(
-        (792.0, 612.0),
+        {"custom_height": 792.0, "custom_width": 612.0},
         None,
         "blank-custom",
         id="custom-dimensions",
@@ -57,11 +58,11 @@
 def test_live_blank_pdf_success(
     pdfrest_api_key: str,
     pdfrest_live_base_url: str,
-    page_size: str | tuple[float, float],
+    page_size: str | PdfCustomPageSize,
     page_orientation: str | None,
     output_name: str,
 ) -> None:
-    kwargs: dict[str, str | int | float | tuple[float, float]] = {
+    kwargs: dict[str, str | int | float | PdfCustomPageSize] = {
         "page_size": page_size,
         "page_count": 1,
         "output": output_name,
@@ -91,11 +92,11 @@ def test_live_blank_pdf_success(
 async def test_live_async_blank_pdf_success(
     pdfrest_api_key: str,
     pdfrest_live_base_url: str,
-    page_size: str | tuple[float, float],
+    page_size: str | PdfCustomPageSize,
     page_orientation: str | None,
     output_name: str,
 ) -> None:
-    kwargs: dict[str, str | int | float | tuple[float, float]] = {
+    kwargs: dict[str, str | int | float | PdfCustomPageSize] = {
         "page_size": page_size,
         "page_count": 2,
         "output": output_name,

tests/test_blank_pdf.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+from typing import cast
 
 import httpx
 import pytest
@@ -9,6 +10,7 @@
 from pdfrest import AsyncPdfRestClient, PdfRestClient
 from pdfrest.models import PdfRestFileBasedResponse, PdfRestFileID
 from pdfrest.models._internal import PdfBlankPayload
+from pdfrest.types import PdfCustomPageSize
 
 from .graphics_test_helpers import ASYNC_API_KEY, VALID_API_KEY, build_file_info_payload
 
@@ -384,15 +386,31 @@ async def test_async_blank_pdf_page_count_boundaries_validation(
 @pytest.mark.parametrize(
     ("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(
+            {"custom_height": 0.0, "custom_width": 10.0},
+            "greater than 0",
+            id="height-zero",
+        ),
+        pytest.param(
+            {"custom_height": -1.0, "custom_width": 10.0},
+            "greater than 0",
+            id="height-negative",
+        ),
+        pytest.param(
+            {"custom_height": 10.0, "custom_width": 0.0},
+            "greater than 0",
+            id="width-zero",
+        ),
+        pytest.param(
+            {"custom_height": 10.0, "custom_width": -1.0},
+            "greater than 0",
+            id="width-negative",
+        ),
     ],
 )
 def test_blank_pdf_custom_dimensions_validation(
     monkeypatch: pytest.MonkeyPatch,
-    page_size: tuple[float, float],
+    page_size: PdfCustomPageSize,
     match: str,
 ) -> None:
     monkeypatch.delenv("PDFREST_API_KEY", raising=False)
@@ -412,15 +430,31 @@ def test_blank_pdf_custom_dimensions_validation(
 @pytest.mark.parametrize(
     ("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(
+            {"custom_height": 0.0, "custom_width": 10.0},
+            "greater than 0",
+            id="height-zero",
+        ),
+        pytest.param(
+            {"custom_height": -1.0, "custom_width": 10.0},
+            "greater than 0",
+            id="height-negative",
+        ),
+        pytest.param(
+            {"custom_height": 10.0, "custom_width": 0.0},
+            "greater than 0",
+            id="width-zero",
+        ),
+        pytest.param(
+            {"custom_height": 10.0, "custom_width": -1.0},
+            "greater than 0",
+            id="width-negative",
+        ),
     ],
 )
 async def test_async_blank_pdf_custom_dimensions_validation(
     monkeypatch: pytest.MonkeyPatch,
-    page_size: tuple[float, float],
+    page_size: PdfCustomPageSize,
     match: str,
 ) -> None:
     monkeypatch.delenv("PDFREST_API_KEY", raising=False)
@@ -537,7 +571,7 @@ 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=(792, 612),
+            page_size={"custom_height": 792, "custom_width": 612},
             page_count=3,
             output="custom",
             extra_query={"trace": "true"},
@@ -658,7 +692,7 @@ 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=(100, 50),
+            page_size={"custom_height": 100, "custom_width": 50},
             page_count=1,
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
@@ -684,16 +718,24 @@ 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 page sizes must contain exactly two"),
+        pytest.raises(
+            ValueError, match="must include both custom_height and custom_width"
+        ),
     ):
-        client.blank_pdf(page_size=(50,), page_count=1)
+        client.blank_pdf(
+            page_size=cast(
+                PdfCustomPageSize,
+                cast(object, {"custom_height": 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=(10, 10),
+            page_size={"custom_height": 10, "custom_width": 10},
             page_count=1,
             page_orientation="portrait",
         )