Refactor URL upload handling in clients

- Replaced `_normalize_url_inputs` utility with `UploadURLs`
  Pydantic model for validation and normalization.
- Simplified input processing in `create_from_urls`.
- Updated tests to reflect new URL validation logic and error messages.

Author: datalogics-kam

src/pdfrest/client.py

@@ -27,6 +27,8 @@
 
 __all__ = ("AsyncPdfRestClient", "PdfRestClient")
 
+from .models._internal import UploadURLs
+
 DEFAULT_BASE_URL = "https://api.pdfrest.com"
 API_KEY_ENV_VAR = "PDFREST_API_KEY"
 API_KEY_HEADER_NAME = "Api-Key"
@@ -195,26 +197,6 @@ def _normalize_path_inputs(
     return items
 
 
-def _normalize_url_inputs(urls: UrlInput) -> list[str]:
-    if isinstance(urls, Sequence) and not isinstance(urls, (str, bytes, bytearray)):
-        sequence_urls: Sequence[UrlValue] = urls
-        items = list(sequence_urls)
-    else:
-        single_url: UrlValue = urls
-        items = [single_url]
-    if not items:
-        msg = "At least one URL must be provided."
-        raise ValueError(msg)
-    normalized: list[str] = []
-    for item in items:
-        parsed = URL(str(item))
-        if parsed.scheme not in {"http", "https"}:
-            msg = "URL uploads require http or https scheme."
-            raise ValueError(msg)
-        normalized.append(str(parsed))
-    return normalized
-
-
 def _resolve_file_id(file_ref: PdfRestFile | str) -> str:
     return file_ref.id if isinstance(file_ref, PdfRestFile) else str(file_ref)
 
@@ -797,11 +779,11 @@ def create_from_paths(self, file_paths: FilePathInput) -> list[PdfRestFile]:
     def create_from_urls(self, urls: UrlInput) -> list[PdfRestFile]:
         """Upload one or more files by providing remote URLs."""
 
-        normalized_urls = _normalize_url_inputs(urls)
+        normalized_urls = UploadURLs.model_validate({"url": urls})  # pyright: ignore[reportPrivateUsage]
         request = self._client.prepare_request(
             "POST",
             "/upload",
-            json_body={"url": normalized_urls},
+            json_body=normalized_urls.model_dump(mode="json"),
         )
         payload = self._client.send_request(request)
         file_ids = _extract_uploaded_file_ids(payload)
@@ -918,11 +900,11 @@ async def create_from_paths(self, file_paths: FilePathInput) -> list[PdfRestFile
     async def create_from_urls(self, urls: UrlInput) -> list[PdfRestFile]:
         """Upload one or more files by providing remote URLs."""
 
-        normalized_urls = _normalize_url_inputs(urls)
+        normalized_urls = UploadURLs.model_validate({"url": urls})
         request = self._client.prepare_request(
             "POST",
             "/upload",
-            json_body={"url": normalized_urls},
+            json_body=normalized_urls.model_dump(mode="json"),
         )
         payload = await self._client.send_request(request)
         file_ids = _extract_uploaded_file_ids(payload)

src/pdfrest/models/_internal.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from pydantic import (
+    BaseModel,
+    BeforeValidator,
+    Field,
+    HttpUrl,
+)
+
+
+def _ensure_list(value: Any) -> Any:
+    if value is None:
+        return None
+    if not isinstance(value, list):
+        return [value]
+    return value
+
+
+def _list_of_strings(value: list[Any]) -> list[str]:
+    return [str(e) for e in value]
+
+
+class UploadURLs(BaseModel):
+    url: Annotated[
+        list[HttpUrl] | HttpUrl,
+        Field(min_length=1),
+        BeforeValidator(_list_of_strings),
+        BeforeValidator(_ensure_list),
+    ]

tests/test_files.py

@@ -547,9 +547,7 @@ async def test_stream_iter_lines(
 async def test_async_files_create_from_urls_invalid_scheme() -> None:
     transport = httpx.MockTransport(lambda request: httpx.Response(400))
     async with AsyncPdfRestClient(api_key=VALID_API_KEY, transport=transport) as client:
-        with pytest.raises(
-            ValueError, match=r"URL uploads require http or https scheme\."
-        ):
+        with pytest.raises(ValueError, match=r"URL scheme should be 'http' or 'https'"):
             await client.files.create_from_urls("ftp://example.com/file.pdf")
 
 
@@ -569,7 +567,10 @@ def test_files_create_rejects_empty_input() -> None:
             ValueError, match=r"At least one file path must be provided\."
         ):
             client.files.create_from_paths([])
-        with pytest.raises(ValueError, match=r"At least one URL must be provided\."):
+        with pytest.raises(
+            ValueError,
+            match=r"Value should have at least 1 item after validation, not 0",
+        ):
             client.files.create_from_urls([])