Enhance file upload functionality in clients and tests

- Simplified `UploadFiles` types and updated handling for single and
  sequence-based file specifications.
- Replaced mapping-based file upload support with streamlined
  normalization logic, because the target field is always "file".
- Introduced `_normalize_path_inputs` for consistent path handling
  in `create_from_paths`.
- Updated file creation flows to use the refined file upload logic.
- Added and extended test cases to cover updated behaviors and edge
  cases.

Assisted-by: Codex

Author: datalogics-kam

src/pdfrest/client.py

@@ -44,12 +44,13 @@
 FileTuple3 = tuple[str | None, FileContent, str | None]
 FileTuple4 = tuple[str | None, FileContent, str | None, Mapping[str, str]]
 FileTypes = FileContent | FileTuple2 | FileTuple3 | FileTuple4
-UploadFiles = Mapping[str, FileTypes] | Sequence[tuple[str, FileTypes]]
+UploadFiles = Sequence[FileTypes] | FileTypes
 
 FilePath = str | PathLike[str]
 FilePathTuple2 = tuple[FilePath, str | None]
 FilePathTuple3 = tuple[FilePath, str | None, Mapping[str, str]]
 FilePathTypes = FilePath | FilePathTuple2 | FilePathTuple3
+FilePathInput = FilePathTypes | Sequence[FilePathTypes]
 NormalizedFileTypes: TypeAlias = FileContent | FileTuple2 | FileTuple3 | FileTuple4
 
 
@@ -128,26 +129,24 @@ def _normalize_file_type(file_value: FileTypes) -> NormalizedFileTypes:
 def _normalize_upload_files(
     files: UploadFiles,
 ) -> list[tuple[str, NormalizedFileTypes]]:
-    is_mapping = isinstance(files, Mapping)
-    if is_mapping:
-        mapping_files = cast(Mapping[str, FileTypes], files)
-        items: list[tuple[str, FileTypes]] = list(mapping_files.items())
+    if isinstance(files, Mapping):
+        msg = "Upload files must be provided as a sequence or a single file specification."
+        raise TypeError(msg)
+
+    if isinstance(files, Sequence) and not isinstance(files, (str, bytes, bytearray)):
+        items = list(files)
     else:
-        sequence_files = cast(Sequence[tuple[str, FileTypes]], files)
-        items = list(sequence_files)
+        # Treat single file specification as a one-element sequence.
+        items = [cast(FileTypes, files)]
+
     if not items:
         msg = "At least one file must be provided."
         raise ValueError(msg)
     normalized_items: list[tuple[str, NormalizedFileTypes]] = []
-    for entry in items:
-        if is_mapping:
-            field_name, file_value = entry
-        else:
-            if not isinstance(entry, tuple) or len(entry) != 2:
-                msg = "Files sequence entries must be (field_name, file_value) tuples."
-                raise TypeError(msg)
-            field_name, file_value = entry
-        normalized_items.append((str(field_name), _normalize_file_type(file_value)))
+    for file_value in items:
+        normalized_items.append(
+            (FILE_UPLOAD_FIELD_NAME, _normalize_file_type(cast(FileTypes, file_value)))
+        )
     return normalized_items
 
 
@@ -175,6 +174,22 @@ def _parse_path_spec(spec: FilePathTypes) -> tuple[Path, str | None, Mapping[str
     return path, None, {}
 
 
+def _normalize_path_inputs(
+    file_paths: FilePathInput,
+) -> list[FilePathTypes]:
+    if isinstance(file_paths, Sequence) and not isinstance(
+        file_paths, (str, bytes, bytearray)
+    ):
+        sequence_paths = cast(Sequence[FilePathTypes], file_paths)
+        items: list[FilePathTypes] = list(sequence_paths)
+    else:
+        items = [cast(FilePathTypes, file_paths)]
+    if not items:
+        msg = "At least one file path must be provided."
+        raise ValueError(msg)
+    return items
+
+
 ClientType = TypeVar("ClientType", httpx.Client, httpx.AsyncClient)
 
 
@@ -621,13 +636,11 @@ def __init__(self, client: _SyncApiClient) -> None:
         self._client = client
 
     def create(self, files: UploadFiles) -> list[PdfRestFile]:
-        """Upload one or more files by content, in the same style accepted by
-        the `files` parameter of `httpx.Client.post`.
+        """Upload one or more files by content.
 
-        Provide either a mapping of field names to file specifications, or a
-        sequence of `(field_name, file_spec)` tuples. File specifications may be
-        raw file-like objects, bytes, str, or the tuple forms documented by
-        httpx.
+        Provide either a single file specification or a sequence of file
+        specifications (each matching the shapes accepted by httpx). Every
+        uploaded part is sent using the field name ``file``.
         """
         normalized_files = _normalize_upload_files(files)
         request = self._client.prepare_request(
@@ -637,42 +650,29 @@ def create(self, files: UploadFiles) -> list[PdfRestFile]:
         file_ids = _extract_uploaded_file_ids(payload)
         return [self._client.fetch_file_info(file_id) for file_id in file_ids]
 
-    def create_from_paths(
-        self, file_paths: Sequence[FilePathTypes]
-    ) -> list[PdfRestFile]:
+    def create_from_paths(self, file_paths: FilePathInput) -> list[PdfRestFile]:
         """Upload one or more files by their path.
 
         Each entry may be a bare path-like object or a tuple of
         `(path, content_type)` / `(path, content_type, headers)` where headers
         mirrors the httpx multipart header mapping. All opened file handles are
         closed once the request completes.
         """
-        if not file_paths:
-            msg = "At least one file path must be provided."
-            raise ValueError(msg)
+        normalized_paths = _normalize_path_inputs(file_paths)
 
         with ExitStack() as stack:
-            upload_entries: list[tuple[str, FileTypes]] = []
-            for spec in file_paths:
+            upload_specs: list[FileTypes] = []
+            for spec in normalized_paths:
                 path, content_type, headers = _parse_path_spec(spec)
                 file_obj = stack.enter_context(path.open("rb"))
                 filename = path.name
                 if headers:
-                    upload_entries.append(
-                        (
-                            FILE_UPLOAD_FIELD_NAME,
-                            (filename, file_obj, content_type, headers),
-                        )
-                    )
+                    upload_specs.append((filename, file_obj, content_type, headers))
                 elif content_type is not None:
-                    upload_entries.append(
-                        (FILE_UPLOAD_FIELD_NAME, (filename, file_obj, content_type))
-                    )
+                    upload_specs.append((filename, file_obj, content_type))
                 else:
-                    upload_entries.append(
-                        (FILE_UPLOAD_FIELD_NAME, (filename, file_obj))
-                    )
-            return self.create(upload_entries)
+                    upload_specs.append((filename, file_obj))
+            return self.create(upload_specs)
 
 
 class _AsyncFilesClient:
@@ -688,13 +688,12 @@ def __init__(
         self._concurrency_limit = concurrency_limit
 
     async def create(self, files: UploadFiles) -> list[PdfRestFile]:
-        """Upload one or more files by content, in the same style accepted by
-        the `files` parameter of `httpx.AsyncClient.post`.
+        """Upload one or more files by content.
 
-        Provide either a mapping of field names to file specifications, or a
-        sequence of `(field_name, file_spec)` tuples. File specifications may be
-        raw file-like objects, bytes, str, or the tuple forms documented by
-        httpx."""
+        Provide either a single file specification or a sequence of file
+        specifications (each matching the shapes accepted by httpx). Every
+        uploaded part is sent using the field name ``file``.
+        """
         normalized_files = _normalize_upload_files(files)
         request = self._client.prepare_request(
             "POST", "/upload", files=normalized_files
@@ -709,42 +708,29 @@ async def fetch(file_id: str) -> PdfRestFile:
 
         return await asyncio.gather(*(fetch(file_id) for file_id in file_ids))
 
-    async def create_from_paths(
-        self, file_paths: Sequence[FilePathTypes]
-    ) -> list[PdfRestFile]:
+    async def create_from_paths(self, file_paths: FilePathInput) -> list[PdfRestFile]:
         """Upload one or more files by their path.
 
         Each entry may be a bare path-like object or a tuple of
         `(path, content_type)` / `(path, content_type, headers)` where headers
         mirrors the httpx multipart header mapping. All opened file handles are
         closed once the request completes.
         """
-        if not file_paths:
-            msg = "At least one file path must be provided."
-            raise ValueError(msg)
+        normalized_paths = _normalize_path_inputs(file_paths)
 
         with ExitStack() as stack:
-            upload_entries: list[tuple[str, FileTypes]] = []
-            for spec in file_paths:
+            upload_specs: list[FileTypes] = []
+            for spec in normalized_paths:
                 path, content_type, headers = _parse_path_spec(spec)
                 file_obj = stack.enter_context(path.open("rb"))
                 filename = path.name
                 if headers:
-                    upload_entries.append(
-                        (
-                            FILE_UPLOAD_FIELD_NAME,
-                            (filename, file_obj, content_type, headers),
-                        )
-                    )
+                    upload_specs.append((filename, file_obj, content_type, headers))
                 elif content_type is not None:
-                    upload_entries.append(
-                        (FILE_UPLOAD_FIELD_NAME, (filename, file_obj, content_type))
-                    )
+                    upload_specs.append((filename, file_obj, content_type))
                 else:
-                    upload_entries.append(
-                        (FILE_UPLOAD_FIELD_NAME, (filename, file_obj))
-                    )
-            return await self.create(upload_entries)
+                    upload_specs.append((filename, file_obj))
+            return await self.create(upload_specs)
 
 
 class PdfRestClient(_SyncApiClient):

tests/test_files.py

@@ -2,7 +2,7 @@
 
 import uuid
 from datetime import datetime, timezone
-from typing import Any
+from typing import Any, cast
 
 import httpx
 import pytest
@@ -76,7 +76,7 @@ def handler(request: httpx.Request) -> httpx.Response:
     report_pdf = get_test_resource_path("report.pdf")
     try:
         with report_pdf.open("rb") as pdf_file:
-            response = client.files.create({"file": ("report.pdf", pdf_file)})
+            response = client.files.create([("report.pdf", pdf_file)])
     finally:
         client.close()
 
@@ -133,6 +133,41 @@ def handler(request: httpx.Request) -> httpx.Response:
         _assert_file_matches_payload(file_repr, payload)
 
 
+def test_files_create_from_paths_single_path() -> None:
+    uploaded_file_id = str(uuid.uuid4())
+    info_payload = _build_file_info_payload(uploaded_file_id, "report.pdf")
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST" and request.url.path == "/upload":
+            body = request.content
+            assert body.count(b'name="file"') == 1
+            assert b'filename="report.pdf"' in body
+            return httpx.Response(
+                200,
+                json={
+                    "files": [
+                        {"name": "report.pdf", "id": uploaded_file_id},
+                    ]
+                },
+            )
+        if request.method == "GET" and request.url.path.startswith("/resource/"):
+            assert request.url.params["format"] == "info"
+            return httpx.Response(200, json=info_payload)
+        msg = f"Unexpected request: {request.method} {request.url}"
+        raise AssertionError(msg)
+
+    transport = httpx.MockTransport(handler)
+    client = PdfRestClient(api_key=VALID_API_KEY, transport=transport)
+    report_pdf = get_test_resource_path("report.pdf")
+    try:
+        response = client.files.create_from_paths(report_pdf)
+    finally:
+        client.close()
+
+    assert len(response) == 1
+    _assert_file_matches_payload(response[0], info_payload)
+
+
 def test_files_create_from_paths_supports_metadata() -> None:
     uploaded_file_id = str(uuid.uuid4())
     info_payload = _build_file_info_payload(uploaded_file_id, "report.pdf")
@@ -183,8 +218,11 @@ def test_files_create_rejects_empty_input() -> None:
         transport=httpx.MockTransport(lambda _: httpx.Response(200)),
     )
     try:
-        with pytest.raises(ValueError, match=r"At least one file must be provided\."):
-            client.files.create({})
+        with pytest.raises(
+            TypeError,
+            match=r"Upload files must be provided as a sequence or a single file specification\.",
+        ):
+            client.files.create(cast(Any, {}))
         with pytest.raises(ValueError, match=r"At least one file must be provided\."):
             client.files.create([])
         with pytest.raises(
@@ -231,8 +269,8 @@ def handler(request: httpx.Request) -> httpx.Response:
         with report_pdf.open("rb") as pdf_file, report_docx.open("rb") as docx_file:
             response = await client.files.create(
                 [
-                    ("file", ("report.pdf", pdf_file)),
-                    ("file", ("report.docx", docx_file)),
+                    ("report.pdf", pdf_file),
+                    ("report.docx", docx_file),
                 ]
             )
 
@@ -288,13 +326,47 @@ def handler(request: httpx.Request) -> httpx.Response:
         _assert_file_matches_payload(file_repr, payload)
 
 
+@pytest.mark.asyncio
+async def test_async_files_create_from_paths_single_path() -> None:
+    uploaded_file_id = str(uuid.uuid4())
+    info_payload = _build_file_info_payload(uploaded_file_id, "report.pdf")
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST" and request.url.path == "/upload":
+            body = request.content
+            assert body.count(b'name="file"') == 1
+            assert b'filename="report.pdf"' in body
+            return httpx.Response(
+                200,
+                json={
+                    "files": [
+                        {"name": "report.pdf", "id": uploaded_file_id},
+                    ]
+                },
+            )
+        if request.method == "GET" and request.url.path.startswith("/resource/"):
+            assert request.url.params["format"] == "info"
+            return httpx.Response(200, json=info_payload)
+        msg = f"Unexpected request: {request.method} {request.url}"
+        raise AssertionError(msg)
+
+    transport = httpx.MockTransport(handler)
+    client = AsyncPdfRestClient(api_key=VALID_API_KEY, transport=transport)
+    report_pdf = get_test_resource_path("report.pdf")
+    async with client:
+        response = await client.files.create_from_paths(report_pdf)
+
+    assert len(response) == 1
+    _assert_file_matches_payload(response[0], info_payload)
+
+
 def test_live_file_create(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:
         report_pdf = get_test_resource_path("report.pdf")
         with report_pdf.open("rb") as pdf_file:
-            response = client.files.create({"file": pdf_file})
+            response = client.files.create([pdf_file])
             assert isinstance(response, list)
             assert len(response) == 1
             file_repr = response[0]
@@ -312,7 +384,7 @@ def test_live_file_create_two_files(
         report_pdf = get_test_resource_path("report.pdf")
         report_docx = get_test_resource_path("report.docx")
         with report_pdf.open("rb") as pdf_file, report_docx.open("rb") as docx_file:
-            response = client.files.create([("file", pdf_file), ("file", docx_file)])
+            response = client.files.create([pdf_file, docx_file])
             assert isinstance(response, list)
             assert len(response) == 2
             names = {file_repr.name for file_repr in response}
@@ -342,7 +414,7 @@ async def test_live_async_file_create(
     report_pdf = get_test_resource_path("report.pdf")
     async with client:
         with report_pdf.open("rb") as pdf_file:
-            response = await client.files.create({"file": pdf_file})
+            response = await client.files.create([pdf_file])
     assert isinstance(response, list)
     assert len(response) == 1
     file_repr = response[0]