export-form-data: Enumerate export formats, shore up test coverage

Assisted-by: Codex

Author: datalogics-cgreen

src/pdfrest/client.py

@@ -2887,7 +2887,12 @@ def export_form_data(
         extra_body: Body | None = None,
         timeout: TimeoutTypes | None = None,
     ) -> PdfRestFileBasedResponse:
-        """Export form data from a PDF with form fields to an external data file."""
+        """Export form data from a PDF into an external data file.
+
+        `data_format` support depends on detected form type:
+        - AcroForm PDFs: `xfdf`, `fdf`, `xml`
+        - XFA PDFs: `xfd`, `xdp`, `xml`
+        """
 
         payload: dict[str, Any] = {
             "files": file,
@@ -4647,7 +4652,12 @@ async def export_form_data(
         extra_body: Body | None = None,
         timeout: TimeoutTypes | None = None,
     ) -> PdfRestFileBasedResponse:
-        """Asynchronously export form data from a PDF into a data file."""
+        """Asynchronously export form data from a PDF into a data file.
+
+        `data_format` support depends on detected form type:
+        - AcroForm PDFs: `xfdf`, `fdf`, `xml`
+        - XFA PDFs: `xfd`, `xdp`, `xml`
+        """
 
         payload: dict[str, Any] = {
             "files": file,

src/pdfrest/types/public.py

@@ -168,6 +168,8 @@ class PdfMergeSource(TypedDict, total=False):
 JpegColorModel = Literal["rgb", "cmyk", "gray"]
 TiffColorModel = Literal["rgb", "rgba", "cmyk", "lab", "gray"]
 GraphicSmoothing = Literal["none", "all", "text", "line", "image"]
+# Server accepts all values here, but enforces form-type subsets at runtime:
+# AcroForm -> xfdf/fdf/xml, XFA -> xfd/xdp/xml.
 ExportDataFormat = Literal["fdf", "xfdf", "xml", "xdp", "xfd"]
 
 SummaryFormat = Literal[

tests/live/test_live_export_form_data.py

@@ -4,6 +4,7 @@
 
 from pdfrest import AsyncPdfRestClient, PdfRestApiError, PdfRestClient
 from pdfrest.models import PdfRestFile
+from pdfrest.types import ExportDataFormat
 
 from ..resources import get_test_resource_path
 
@@ -24,84 +25,251 @@ def uploaded_pdf_with_forms(
 @pytest.mark.parametrize(
     "data_format",
     [
-        pytest.param("xml", id="xml"),
+        pytest.param("fdf", id="fdf"),
         pytest.param("xfdf", id="xfdf"),
+        pytest.param("xml", id="xml"),
     ],
 )
-def test_live_export_form_data(
+def test_live_export_form_data_acroform(
     pdfrest_api_key: str,
     pdfrest_live_base_url: str,
     uploaded_pdf_with_forms: PdfRestFile,
-    data_format: str,
+    data_format: ExportDataFormat,
 ) -> None:
     with PdfRestClient(
         api_key=pdfrest_api_key,
         base_url=pdfrest_live_base_url,
     ) as client:
         response = client.export_form_data(
             uploaded_pdf_with_forms,
-            data_format=data_format,  # type: ignore[arg-type]
+            data_format=data_format,
             output=f"exported-{data_format}",
         )
 
     assert response.output_files
     output_file = response.output_file
     assert output_file.name.startswith(f"exported-{data_format}")
-    assert str(response.input_id) == str(uploaded_pdf_with_forms.id)
+    assert output_file.type
+    assert output_file.size > 0
+    assert response.warning is None
+    assert str(uploaded_pdf_with_forms.id) in {
+        str(file_id) for file_id in response.input_ids
+    }
+
+
+@pytest.fixture(scope="module")
+def uploaded_xfa_pdf(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+) -> PdfRestFile:
+    resource = get_test_resource_path("xfa.pdf")
+    with PdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        return client.files.create_from_paths([resource])[0]
+
+
+@pytest.mark.parametrize(
+    "data_format",
+    [
+        pytest.param("xfd", id="xfd"),
+        pytest.param("xdp", id="xdp"),
+        pytest.param("xml", id="xml"),
+    ],
+)
+def test_live_export_form_data_xfa(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    uploaded_xfa_pdf: PdfRestFile,
+    data_format: ExportDataFormat,
+) -> None:
+    with PdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        response = client.export_form_data(
+            uploaded_xfa_pdf,
+            data_format=data_format,
+            output=f"exported-xfa-{data_format}",
+        )
+
+    assert response.output_files
+    output_file = response.output_file
+    assert output_file.name.startswith(f"exported-xfa-{data_format}")
+    assert output_file.type
+    assert output_file.size > 0
+    assert response.warning is None
+    assert str(uploaded_xfa_pdf.id) in {str(file_id) for file_id in response.input_ids}
 
 
 @pytest.mark.asyncio
-async def test_live_async_export_form_data_success(
+@pytest.mark.parametrize(
+    "data_format",
+    [
+        pytest.param("fdf", id="fdf"),
+        pytest.param("xfdf", id="xfdf"),
+        pytest.param("xml", id="xml"),
+    ],
+)
+async def test_live_async_export_form_data_acroform(
     pdfrest_api_key: str,
     pdfrest_live_base_url: str,
     uploaded_pdf_with_forms: PdfRestFile,
+    data_format: ExportDataFormat,
 ) -> None:
     async with AsyncPdfRestClient(
         api_key=pdfrest_api_key,
         base_url=pdfrest_live_base_url,
     ) as client:
         response = await client.export_form_data(
             uploaded_pdf_with_forms,
-            data_format="xml",
-            output="async-exported",
+            data_format=data_format,
+            output=f"async-acro-{data_format}",
+        )
+
+    assert response.output_files
+    output_file = response.output_file
+    assert output_file.name.startswith(f"async-acro-{data_format}")
+    assert output_file.type
+    assert output_file.size > 0
+    assert response.warning is None
+    assert str(uploaded_pdf_with_forms.id) in {
+        str(file_id) for file_id in response.input_ids
+    }
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "data_format",
+    [
+        pytest.param("xfd", id="xfd"),
+        pytest.param("xdp", id="xdp"),
+        pytest.param("xml", id="xml"),
+    ],
+)
+async def test_live_async_export_form_data_xfa(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    uploaded_xfa_pdf: PdfRestFile,
+    data_format: ExportDataFormat,
+) -> None:
+    async with AsyncPdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        response = await client.export_form_data(
+            uploaded_xfa_pdf,
+            data_format=data_format,
+            output=f"async-xfa-{data_format}",
         )
 
     assert response.output_files
     output_file = response.output_file
-    assert output_file.name.startswith("async-exported")
-    assert str(response.input_id) == str(uploaded_pdf_with_forms.id)
+    assert output_file.name.startswith(f"async-xfa-{data_format}")
+    assert output_file.type
+    assert output_file.size > 0
+    assert response.warning is None
+    assert str(uploaded_xfa_pdf.id) in {str(file_id) for file_id in response.input_ids}
 
 
+@pytest.mark.parametrize(
+    "invalid_format",
+    [
+        pytest.param("xdp", id="xdp"),
+        pytest.param("xfd", id="xfd"),
+    ],
+)
 def test_live_export_form_data_invalid_format_for_pdf_type(
     pdfrest_api_key: str,
     pdfrest_live_base_url: str,
     uploaded_pdf_with_forms: PdfRestFile,
+    invalid_format: ExportDataFormat,
 ) -> None:
     with (
         PdfRestClient(
             api_key=pdfrest_api_key,
             base_url=pdfrest_live_base_url,
         ) as client,
-        pytest.raises(PdfRestApiError, match=r"(?i)data_format"),
+        pytest.raises(PdfRestApiError, match=r"(?i)(acroform|data_format)"),
     ):
         client.export_form_data(
             uploaded_pdf_with_forms,
-            data_format="xdp",  # type: ignore[arg-type]
+            data_format=invalid_format,
         )
 
 
 @pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "invalid_format",
+    [
+        pytest.param("xdp", id="xdp"),
+        pytest.param("xfd", id="xfd"),
+    ],
+)
 async def test_live_async_export_form_data_invalid_format_for_pdf_type(
     pdfrest_api_key: str,
     pdfrest_live_base_url: str,
     uploaded_pdf_with_forms: PdfRestFile,
+    invalid_format: ExportDataFormat,
 ) -> None:
     async with AsyncPdfRestClient(
         api_key=pdfrest_api_key,
         base_url=pdfrest_live_base_url,
     ) as client:
-        with pytest.raises(PdfRestApiError, match=r"(?i)data_format"):
+        with pytest.raises(PdfRestApiError, match=r"(?i)(acroform|data_format)"):
             await client.export_form_data(
                 uploaded_pdf_with_forms,
-                data_format="xdp",  # type: ignore[arg-type]
+                data_format=invalid_format,
+            )
+
+
+@pytest.mark.parametrize(
+    "invalid_format",
+    [
+        pytest.param("xfdf", id="xfdf"),
+        pytest.param("fdf", id="fdf"),
+    ],
+)
+def test_live_export_form_data_invalid_format_for_xfa(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    uploaded_xfa_pdf: PdfRestFile,
+    invalid_format: ExportDataFormat,
+) -> None:
+    with (
+        PdfRestClient(
+            api_key=pdfrest_api_key,
+            base_url=pdfrest_live_base_url,
+        ) as client,
+        pytest.raises(PdfRestApiError, match=r"(?i)(xfa|data_format)"),
+    ):
+        client.export_form_data(
+            uploaded_xfa_pdf,
+            data_format=invalid_format,
+        )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "invalid_format",
+    [
+        pytest.param("xfdf", id="xfdf"),
+        pytest.param("fdf", id="fdf"),
+    ],
+)
+async def test_live_async_export_form_data_invalid_format_for_xfa(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    uploaded_xfa_pdf: PdfRestFile,
+    invalid_format: ExportDataFormat,
+) -> None:
+    async with AsyncPdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        with pytest.raises(PdfRestApiError, match=r"(?i)(xfa|data_format)"):
+            await client.export_form_data(
+                uploaded_xfa_pdf,
+                data_format=invalid_format,
             )