Add Blank PDF methods

datalogics-cgreen · datalogics-cgreen · commit b01cb78b730f · 2026-01-12T17:00:57.000-06:00
- Add `blank_pdf()` sync and async methods
- Ensure compatibility with Blank PDF response:
  - Allow PdfRestRawFileResponse.input_id to default empty so missing inputId doesn’t fail validation
  - When normalizing file responses, fall back to raw ids (outputId) when inputId is absent for blank-pdf
  - Document blank-pdf handling to keep response construction working without server-provided input ids
diff --git a/src/pdfrest/client.py b/src/pdfrest/client.py
@@ -81,6 +81,7 @@
     GifPdfRestPayload,
     JpegPdfRestPayload,
     OcrPdfPayload,
+    PdfBlankPayload,
     PdfCompressPayload,
     PdfConvertColorsPayload,
     PdfFlattenAnnotationsPayload,
@@ -120,7 +121,9 @@
     PdfColorProfile,
     PdfInfoQuery,
     PdfMergeInput,
+    PdfPageOrientation,
     PdfPageSelection,
+    PdfPageSize,
     PdfRedactionInstruction,
     PdfRGBColor,
     PdfXType,
@@ -1031,8 +1034,9 @@ def _post_file_operation(
             for file_id in output_ids
         ]
 
+        input_ids = raw_response.input_id or (raw_response.ids or [])
         response_payload: dict[str, Any] = {
-            "input_id": [str(file_id) for file_id in raw_response.input_id],
+            "input_id": [str(file_id) for file_id in input_ids],
             "output_file": [
                 file.model_dump(mode="json", by_alias=True) for file in output_files
             ],
@@ -1306,8 +1310,9 @@ async def throttled_fetch_file_info(file_id: str) -> PdfRestFile:
                 )
             )
 
+        input_ids = raw_response.input_id or (raw_response.ids or [])
         response_payload: dict[str, Any] = {
-            "input_id": [str(file_id) for file_id in raw_response.input_id],
+            "input_id": [str(file_id) for file_id in input_ids],
             "output_file": [
                 file.model_dump(mode="json", by_alias=True) for file in output_files
             ],
@@ -2753,6 +2758,45 @@ def convert_colors(
             timeout=timeout,
         )
 
+    def blank_pdf(
+        self,
+        *,
+        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,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Create a blank PDF with the specified size, count, and orientation."""
+
+        payload: dict[str, Any] = {
+            "page_size": page_size,
+            "page_count": page_count,
+        }
+        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
+
+        return self._post_file_operation(
+            endpoint="/blank-pdf",
+            payload=payload,
+            payload_model=PdfBlankPayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     def flatten_transparencies(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],
@@ -3854,6 +3898,45 @@ async def convert_colors(
             timeout=timeout,
         )
 
+    async def blank_pdf(
+        self,
+        *,
+        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,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Asynchronously create a blank PDF with the specified size."""
+
+        payload: dict[str, Any] = {
+            "page_size": page_size,
+            "page_count": page_count,
+        }
+        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
+
+        return await self._post_file_operation(
+            endpoint="/blank-pdf",
+            payload=payload,
+            payload_model=PdfBlankPayload,
+            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,8 @@
     PdfAType,
     PdfColorProfile,
     PdfInfoQuery,
+    PdfPageOrientation,
+    PdfPageSize,
     PdfXType,
     SummaryFormat,
     SummaryOutputFormat,
@@ -1113,6 +1115,57 @@ class PdfFlattenLayersPayload(BaseModel):
     ] = None
 
 
+class PdfBlankPayload(BaseModel):
+    """Adapt caller options into a pdfRest-ready blank PDF request payload."""
+
+    page_size: Annotated[
+        PdfPageSize,
+        Field(serialization_alias="page_size"),
+    ]
+    page_count: Annotated[
+        int,
+        Field(serialization_alias="page_count", ge=1, le=1000),
+    ]
+    page_orientation: Annotated[
+        PdfPageOrientation | None,
+        Field(serialization_alias="page_orientation", default=None),
+    ] = None
+    custom_height: Annotated[
+        float | None,
+        Field(serialization_alias="custom_height", gt=0, default=None),
+    ] = None
+    custom_width: Annotated[
+        float | None,
+        Field(serialization_alias="custom_width", gt=0, 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_page_configuration(self) -> PdfBlankPayload:
+        is_custom = self.page_size == "custom"
+        has_custom_height = self.custom_height is not None
+        has_custom_width = self.custom_width is not None
+        if is_custom:
+            if not (has_custom_height and has_custom_width):
+                msg = "custom_height and custom_width are required when page_size is 'custom'."
+                raise ValueError(msg)
+            if self.page_orientation is not None:
+                msg = "page_orientation must be omitted when page_size is 'custom'."
+                raise ValueError(msg)
+        else:
+            if self.page_orientation is None:
+                msg = "page_orientation is required when page_size is not 'custom'."
+                raise ValueError(msg)
+            if has_custom_height or has_custom_width:
+                msg = "custom_height and custom_width can only be provided when page_size is 'custom'."
+                raise ValueError(msg)
+        return self
+
+
 class PdfConvertColorsPayload(BaseModel):
     """Adapt caller options into a pdfRest-ready convert-colors request payload."""
 
@@ -1226,7 +1279,11 @@ class PdfRestRawFileResponse(BaseModel):
 
     input_id: Annotated[
         list[PdfRestFileID],
-        Field(alias="inputId", description="The id of the input file"),
+        Field(
+            alias="inputId",
+            description="The id of the input file",
+            default_factory=list,
+        ),
         BeforeValidator(_ensure_list),
     ]
     output_urls: Annotated[
diff --git a/src/pdfrest/types/__init__.py b/src/pdfrest/types/__init__.py
@@ -14,7 +14,9 @@
     PdfInfoQuery,
     PdfMergeInput,
     PdfMergeSource,
+    PdfPageOrientation,
     PdfPageSelection,
+    PdfPageSize,
     PdfRedactionInstruction,
     PdfRedactionPreset,
     PdfRedactionType,
@@ -42,7 +44,9 @@
     "PdfInfoQuery",
     "PdfMergeInput",
     "PdfMergeSource",
+    "PdfPageOrientation",
     "PdfPageSelection",
+    "PdfPageSize",
     "PdfRGBColor",
     "PdfRedactionInstruction",
     "PdfRedactionPreset",
diff --git a/src/pdfrest/types/public.py b/src/pdfrest/types/public.py
@@ -26,7 +26,9 @@
     "PdfInfoQuery",
     "PdfMergeInput",
     "PdfMergeSource",
+    "PdfPageOrientation",
     "PdfPageSelection",
+    "PdfPageSize",
     "PdfRGBColor",
     "PdfRedactionInstruction",
     "PdfRedactionPreset",
@@ -159,3 +161,6 @@ class PdfMergeSource(TypedDict, total=False):
     "acrobat9-cmyk",
     "custom",
 ]
+
+PdfPageSize = Literal["letter", "legal", "ledger", "A3", "A4", "A5", "custom"]
+PdfPageOrientation = Literal["portrait", "landscape"]
diff --git a/tests/live/test_live_blank_pdf.py b/tests/live/test_live_blank_pdf.py
@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import pytest
+
+from pdfrest import AsyncPdfRestClient, PdfRestApiError, PdfRestClient
+
+
+@pytest.mark.parametrize(
+    "output_name",
+    [
+        pytest.param(None, id="default-output"),
+        pytest.param("blank-doc", id="custom-output"),
+    ],
+)
+def test_live_blank_pdf_success(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    output_name: str | None,
+) -> None:
+    kwargs: dict[str, str | int] = {
+        "page_size": "letter",
+        "page_count": 1,
+        "page_orientation": "portrait",
+    }
+    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.blank_pdf(**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
+    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_blank_pdf_success(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+) -> None:
+    async with AsyncPdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        response = await client.blank_pdf(
+            page_size="A4",
+            page_count=2,
+            page_orientation="landscape",
+            output="async-blank",
+        )
+
+    assert response.output_files
+    output_file = response.output_file
+    assert output_file.name.startswith("async-blank")
+    assert output_file.type == "application/pdf"
+    assert output_file.size > 0
+    assert response.warning is None
+
+
+def test_live_blank_pdf_invalid_request(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+) -> None:
+    with (
+        PdfRestClient(
+            api_key=pdfrest_api_key,
+            base_url=pdfrest_live_base_url,
+        ) as client,
+        pytest.raises(PdfRestApiError, match=r"(?i)(page|size)"),
+    ):
+        client.blank_pdf(
+            page_size="letter",
+            page_count=1,
+            page_orientation="portrait",
+            extra_body={"page_size": "not-a-size"},
+        )
+
+
+@pytest.mark.asyncio
+async def test_live_async_blank_pdf_invalid_request(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+) -> None:
+    async with AsyncPdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        with pytest.raises(PdfRestApiError, match=r"(?i)(page|size)"):
+            await client.blank_pdf(
+                page_size="letter",
+                page_count=1,
+                page_orientation="portrait",
+                extra_body={"page_size": "bad-size"},
+            )
diff --git a/tests/test_blank_pdf.py b/tests/test_blank_pdf.py
