client: Rename convert_urls_to_pdf to convert_url_to_pdf

- Updated method name to reflect singular URL input, improving clarity.
- Adjusted parameter from `urls: UrlInput` to `url: UrlValue` to align with
  single URL support.
- Revised docstrings to clarify behavior for single URL input.
- Renamed `ConvertUrlsToPdfPayload` → `ConvertUrlToPdfPayload`.
- Ensured updates in related tests, including test names and payload
  expectations.

Assisted-by: Codex

Author: datalogics-kam

src/pdfrest/client.py

@@ -81,7 +81,7 @@
     ConvertOfficeToPdfPayload,
     ConvertPostscriptToPdfPayload,
     ConvertToMarkdownPayload,
-    ConvertUrlsToPdfPayload,
+    ConvertUrlToPdfPayload,
     DeletePayload,
     ExtractImagesPayload,
     ExtractTextPayload,
@@ -3476,9 +3476,9 @@ def convert_html_to_pdf(
             timeout=timeout,
         )
 
-    def convert_urls_to_pdf(
+    def convert_url_to_pdf(
         self,
-        urls: UrlInput,
+        url: UrlValue,
         *,
         output: str | None = None,
         compression: PdfConversionCompression | None = None,
@@ -3492,10 +3492,10 @@ def convert_urls_to_pdf(
         extra_body: Body | None = None,
         timeout: TimeoutTypes | None = None,
     ) -> PdfRestFileBasedResponse:
-        """Convert HTML content from one or more URLs to PDF."""
+        """Convert HTML content from one URL to PDF."""
 
         payload: dict[str, Any] = {
-            "url": urls,
+            "url": url,
             "output": output,
             "compression": compression,
             "downsample": downsample,
@@ -3509,7 +3509,7 @@ def convert_urls_to_pdf(
         return self._post_file_operation(
             endpoint="/pdf",
             payload=payload,
-            payload_model=ConvertUrlsToPdfPayload,
+            payload_model=ConvertUrlToPdfPayload,
             extra_query=extra_query,
             extra_headers=extra_headers,
             extra_body=extra_body,
@@ -5179,9 +5179,9 @@ async def convert_html_to_pdf(
             timeout=timeout,
         )
 
-    async def convert_urls_to_pdf(
+    async def convert_url_to_pdf(
         self,
-        urls: UrlInput,
+        url: UrlValue,
         *,
         output: str | None = None,
         compression: PdfConversionCompression | None = None,
@@ -5195,10 +5195,10 @@ async def convert_urls_to_pdf(
         extra_body: Body | None = None,
         timeout: TimeoutTypes | None = None,
     ) -> PdfRestFileBasedResponse:
-        """Asynchronously convert HTML content from one or more URLs to PDF."""
+        """Asynchronously convert HTML content from one URL to PDF."""
 
         payload: dict[str, Any] = {
-            "url": urls,
+            "url": url,
             "output": output,
             "compression": compression,
             "downsample": downsample,
@@ -5212,7 +5212,7 @@ async def convert_urls_to_pdf(
         return await self._post_file_operation(
             endpoint="/pdf",
             payload=payload,
-            payload_model=ConvertUrlsToPdfPayload,
+            payload_model=ConvertUrlToPdfPayload,
             extra_query=extra_query,
             extra_headers=extra_headers,
             extra_body=extra_body,

src/pdfrest/models/_internal.py

@@ -793,14 +793,12 @@ class ConvertHtmlToPdfPayload(BaseModel):
     ] = None
 
 
-class ConvertUrlsToPdfPayload(BaseModel):
-    """Adapt caller options into a pdfRest-ready convert-to-pdf payload for URLs."""
+class ConvertUrlToPdfPayload(BaseModel):
+    """Adapt caller options into a pdfRest-ready convert-to-pdf payload for one URL."""
 
     url: Annotated[
-        list[HttpUrl],
-        Field(serialization_alias="url", min_length=1),
-        BeforeValidator(_list_of_strings),
-        BeforeValidator(_ensure_list),
+        HttpUrl,
+        Field(serialization_alias="url"),
     ]
     output: Annotated[
         str | None,

tests/live/test_live_convert_urls_to_pdf.py

@@ -4,34 +4,19 @@
 
 from pdfrest import AsyncPdfRestClient, PdfRestApiError, PdfRestClient
 
-from ..resources import get_test_resource_path
-
-
-@pytest.fixture(scope="module")
-def uploaded_html_url_for_pdf(
-    pdfrest_api_key: str,
-    pdfrest_live_base_url: str,
-) -> str:
-    resource = get_test_resource_path("sample.html")
-    with PdfRestClient(
-        api_key=pdfrest_api_key,
-        base_url=pdfrest_live_base_url,
-    ) as client:
-        uploaded = client.files.create_from_paths([resource])[0]
-        return str(uploaded.url)
+LIVE_HTML_URL = "https://example.com"
 
 
 def test_live_convert_urls_to_pdf_success(
     pdfrest_api_key: str,
     pdfrest_live_base_url: str,
-    uploaded_html_url_for_pdf: str,
 ) -> None:
     with PdfRestClient(
         api_key=pdfrest_api_key,
         base_url=pdfrest_live_base_url,
     ) as client:
-        response = client.convert_urls_to_pdf(
-            [uploaded_html_url_for_pdf],
+        response = client.convert_url_to_pdf(
+            LIVE_HTML_URL,
             output="live-html-url",
             page_size="letter",
             page_margin="8mm",
@@ -52,14 +37,13 @@ def test_live_convert_urls_to_pdf_success(
 async def test_live_async_convert_urls_to_pdf_invalid_page_size(
     pdfrest_api_key: str,
     pdfrest_live_base_url: str,
-    uploaded_html_url_for_pdf: 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|page size"):
-            await client.convert_urls_to_pdf(
-                [uploaded_html_url_for_pdf],
+            await client.convert_url_to_pdf(
+                LIVE_HTML_URL,
                 extra_body={"page_size": "poster"},
             )

tests/test_convert_urls_to_pdf.py

@@ -8,18 +8,18 @@
 
 from pdfrest import AsyncPdfRestClient, PdfRestClient
 from pdfrest.models import PdfRestFileBasedResponse, PdfRestFileID
-from pdfrest.models._internal import ConvertUrlsToPdfPayload
+from pdfrest.models._internal import ConvertUrlToPdfPayload
 
 from .graphics_test_helpers import ASYNC_API_KEY, VALID_API_KEY, build_file_info_payload
 
 
 def test_convert_urls_to_pdf_success(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.delenv("PDFREST_API_KEY", raising=False)
-    urls = ["https://example.com/page"]
+    url = "https://example.com/page"
     output_id = str(PdfRestFileID.generate())
-    payload_dump = ConvertUrlsToPdfPayload.model_validate(
+    payload_dump = ConvertUrlToPdfPayload.model_validate(
         {
-            "url": urls,
+            "url": url,
             "output": "url-out",
             "page_size": "letter",
             "page_margin": "2.5in",
@@ -52,8 +52,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.convert_urls_to_pdf(
-            urls,
+        response = client.convert_url_to_pdf(
+            url,
             output="url-out",
             page_size="letter",
             page_margin="2.5in",
@@ -68,11 +68,11 @@ def handler(request: httpx.Request) -> httpx.Response:
 
 def test_convert_urls_to_pdf_validation_errors() -> None:
     with pytest.raises(ValidationError, match="Input should be a valid URL"):
-        ConvertUrlsToPdfPayload.model_validate({"url": "not-a-url"})
+        ConvertUrlToPdfPayload.model_validate({"url": "not-a-url"})
 
     with pytest.raises(ValidationError, match="page_margin must be a number"):
-        ConvertUrlsToPdfPayload.model_validate(
-            {"url": ["https://example.com"], "page_margin": "mm"}
+        ConvertUrlToPdfPayload.model_validate(
+            {"url": "https://example.com", "page_margin": "mm"}
         )
 
 
@@ -81,7 +81,7 @@ async def test_async_convert_urls_to_pdf_request_customization(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     monkeypatch.delenv("PDFREST_API_KEY", raising=False)
-    urls = ["https://example.com/page", "https://example.com/other"]
+    url = "https://example.com/page"
     output_id = str(PdfRestFileID.generate())
     captured_timeout: dict[str, float | dict[str, float] | None] = {}
 
@@ -91,7 +91,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             assert request.headers["X-Debug"] == "async"
             captured_timeout["value"] = request.extensions.get("timeout")
             payload = json.loads(request.content.decode("utf-8"))
-            assert payload["url"] == urls
+            assert payload["url"] == url
             assert payload["output"] == "async-url"
             assert payload["page_orientation"] == "portrait"
             assert payload["debug"] == "yes"
@@ -116,8 +116,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.convert_urls_to_pdf(
-            urls,
+        response = await client.convert_url_to_pdf(
+            url,
             output="async-url",
             page_orientation="portrait",
             extra_query={"trace": "async"},