Split Translate PDF methods by output type

Assisted-by: Codex

Author: datalogics-cgreen

src/pdfrest/client.py

@@ -109,7 +109,6 @@
     SummaryOutputFormat,
     SummaryOutputType,
     TranslateOutputFormat,
-    TranslateOutputType,
 )
 
 DEFAULT_BASE_URL = "https://api.pdfrest.com"
@@ -2166,20 +2165,19 @@ def translate_pdf_text(
         source_language: str | None = None,
         pages: PdfPageSelection | None = None,
         output_format: TranslateOutputFormat = "markdown",
-        output_type: TranslateOutputType = "json",
         output: str | None = None,
         extra_query: Query | None = None,
         extra_headers: AnyMapping | None = None,
         extra_body: Body | None = None,
         timeout: TimeoutTypes | None = None,
     ) -> TranslatePdfTextResponse:
-        """Translate the textual content of a PDF, Markdown, or text document."""
+        """Translate the textual content of a PDF, Markdown, or text document (JSON)."""
 
         payload: dict[str, Any] = {
             "files": file,
             "target_language": target_language,
             "output_format": output_format,
-            "output_type": output_type,
+            "output_type": "json",
         }
         if source_language is not None:
             payload["source_language"] = source_language
@@ -2203,6 +2201,45 @@ def translate_pdf_text(
         raw_payload = self._send_request(request)
         return TranslatePdfTextResponse.model_validate(raw_payload)
 
+    def translate_pdf_text_to_file(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        target_language: str,
+        source_language: str | None = None,
+        pages: PdfPageSelection | None = None,
+        output_format: TranslateOutputFormat = "markdown",
+        output: str | None = None,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Translate textual content and receive a file-based response."""
+
+        payload: dict[str, Any] = {
+            "files": file,
+            "target_language": target_language,
+            "output_format": output_format,
+            "output_type": "file",
+        }
+        if source_language is not None:
+            payload["source_language"] = source_language
+        if pages is not None:
+            payload["pages"] = pages
+        if output is not None:
+            payload["output"] = output
+
+        return self._post_file_operation(
+            endpoint="/translated-pdf-text",
+            payload=payload,
+            payload_model=TranslatePdfTextPayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     def extract_images(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],
@@ -2881,20 +2918,19 @@ async def translate_pdf_text(
         source_language: str | None = None,
         pages: PdfPageSelection | None = None,
         output_format: TranslateOutputFormat = "markdown",
-        output_type: TranslateOutputType = "json",
         output: str | None = None,
         extra_query: Query | None = None,
         extra_headers: AnyMapping | None = None,
         extra_body: Body | None = None,
         timeout: TimeoutTypes | None = None,
     ) -> TranslatePdfTextResponse:
-        """Translate the textual content of a PDF, Markdown, or text document."""
+        """Translate the textual content of a PDF, Markdown, or text document (JSON)."""
 
         payload: dict[str, Any] = {
             "files": file,
             "target_language": target_language,
             "output_format": output_format,
-            "output_type": output_type,
+            "output_type": "json",
         }
         if source_language is not None:
             payload["source_language"] = source_language
@@ -2918,6 +2954,45 @@ async def translate_pdf_text(
         raw_payload = await self._send_request(request)
         return TranslatePdfTextResponse.model_validate(raw_payload)
 
+    async def translate_pdf_text_to_file(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        target_language: str,
+        source_language: str | None = None,
+        pages: PdfPageSelection | None = None,
+        output_format: TranslateOutputFormat = "markdown",
+        output: str | None = None,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Translate textual content and receive a file-based response."""
+
+        payload: dict[str, Any] = {
+            "files": file,
+            "target_language": target_language,
+            "output_format": output_format,
+            "output_type": "file",
+        }
+        if source_language is not None:
+            payload["source_language"] = source_language
+        if pages is not None:
+            payload["pages"] = pages
+        if output is not None:
+            payload["output"] = output
+
+        return await self._post_file_operation(
+            endpoint="/translated-pdf-text",
+            payload=payload,
+            payload_model=TranslatePdfTextPayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     async def extract_images(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],

src/pdfrest/models/_internal.py

@@ -28,7 +28,6 @@
     SummaryOutputFormat,
     SummaryOutputType,
     TranslateOutputFormat,
-    TranslateOutputType,
 )
 from . import PdfRestFile
 from .public import PdfRestFileID
@@ -432,7 +431,8 @@ class TranslatePdfTextPayload(BaseModel):
         Field(serialization_alias="output_format", default="markdown"),
     ] = "markdown"
     output_type: Annotated[
-        TranslateOutputType, Field(serialization_alias="output_type", default="json")
+        Literal["json", "file"],
+        Field(serialization_alias="output_type", default="json"),
     ] = "json"
     output: Annotated[
         str | None,

src/pdfrest/types/__init__.py

@@ -15,7 +15,6 @@
     SummaryOutputFormat,
     SummaryOutputType,
     TranslateOutputFormat,
-    TranslateOutputType,
 )
 
 __all__ = [
@@ -33,5 +32,4 @@
     "SummaryOutputFormat",
     "SummaryOutputType",
     "TranslateOutputFormat",
-    "TranslateOutputType",
 ]

src/pdfrest/types/public.py

@@ -27,7 +27,6 @@
     "SummaryOutputFormat",
     "SummaryOutputType",
     "TranslateOutputFormat",
-    "TranslateOutputType",
 )
 
 PdfInfoQuery = Literal[
@@ -121,4 +120,3 @@ class PdfMergeSource(TypedDict, total=False):
 SummaryOutputType = Literal["json", "file"]
 
 TranslateOutputFormat = Literal["plaintext", "markdown"]
-TranslateOutputType = Literal["json", "file"]

tests/live/test_live_translate_pdf_text.py

@@ -3,7 +3,7 @@
 import pytest
 
 from pdfrest import PdfRestApiError, PdfRestClient
-from pdfrest.models import TranslatePdfTextResponse
+from pdfrest.models import PdfRestFileBasedResponse, TranslatePdfTextResponse
 
 from ..resources import get_test_resource_path
 
@@ -21,7 +21,6 @@ def test_live_translate_pdf_text_success(
         response = client.translate_pdf_text(
             uploaded,
             target_language="fr",
-            output_type="json",
             output_format="plaintext",
         )
 
@@ -46,3 +45,24 @@ def test_live_translate_pdf_text_invalid_output_format(
                 target_language="es",
                 extra_body={"output_format": "invalid-format"},
             )
+
+
+def test_live_translate_pdf_text_file_success(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+) -> None:
+    resource = get_test_resource_path("report.pdf")
+    with PdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        uploaded = client.files.create_from_paths([resource])[0]
+        response = client.translate_pdf_text_to_file(
+            uploaded,
+            target_language="fr",
+            output_format="plaintext",
+        )
+
+    assert isinstance(response, PdfRestFileBasedResponse)
+    assert response.output_files
+    assert response.input_id == uploaded.id

tests/test_translate_pdf_text.py

@@ -7,7 +7,12 @@
 from pydantic import ValidationError
 
 from pdfrest import AsyncPdfRestClient, PdfRestClient
-from pdfrest.models import PdfRestFile, PdfRestFileID, TranslatePdfTextResponse
+from pdfrest.models import (
+    PdfRestFile,
+    PdfRestFileBasedResponse,
+    PdfRestFileID,
+    TranslatePdfTextResponse,
+)
 from pdfrest.models._internal import TranslatePdfTextPayload
 
 from .graphics_test_helpers import ASYNC_API_KEY, VALID_API_KEY, make_pdf_file
@@ -95,7 +100,6 @@ def handler(request: httpx.Request) -> httpx.Response:
             source_language="en",
             pages=["1-2"],
             output_format="plaintext",
-            output_type="json",
             output="translation",
         )
 
@@ -145,19 +149,17 @@ def handler(request: httpx.Request) -> httpx.Response:
 
     transport = httpx.MockTransport(handler)
     with PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client:
-        response = client.translate_pdf_text(
+        response = client.translate_pdf_text_to_file(
             input_file,
             target_language="es",
-            output_type="file",
             extra_query={"trace": "true"},
             extra_headers={"X-Debug": "sync"},
             extra_body={"debug": True},
             timeout=0.3,
         )
 
-    assert isinstance(response, TranslatePdfTextResponse)
-    assert response.output_id == output_id
-    assert response.output_url
+    assert isinstance(response, PdfRestFileBasedResponse)
+    assert response.output_file.id == output_id
     timeout_value = captured_timeout["value"]
     assert timeout_value is not None
     if isinstance(timeout_value, dict):
@@ -199,7 +201,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.translate_pdf_text(
-            input_file, target_language="de", output_type="json"
+            input_file,
+            target_language="de",
         )
 
     assert seen == {"post": 1}