client: Add extract_pdf_text method for text extraction

- Introduced `extract_pdf_text` to extract text content from PDFs with options
  like `full_text`, `preserve_line_breaks`, `word_style`, and `word_coordinates`.
- Added both sync and async implementations for the `extract_pdf_text` method.
- Validated payloads using `ExtractTextPayload` and model validation.
- Returns structured `ExtractedTextDocument` with extracted text and metadata.

tests: Add unit and live tests for extract_pdf_text

- Added comprehensive unit tests to validate different payload combinations.
- Introduced live tests to ensure end-to-end functionality of API integration.
- Verified error handling for invalid pages, payloads, and server responses.

Assisted-by: Codex

Author: datalogics-kam

src/pdfrest/client.py

@@ -60,6 +60,7 @@
     translate_httpx_error,
 )
 from .models import (
+    ExtractedTextDocument,
     PdfRestDeletionResponse,
     PdfRestErrorResponse,
     PdfRestFile,
@@ -2388,6 +2389,48 @@ def extract_images(
             timeout=timeout,
         )
 
+    def extract_pdf_text(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        pages: PdfPageSelection | None = None,
+        full_text: Literal["off", "by_page", "document"] = "document",
+        preserve_line_breaks: bool = False,
+        word_style: bool = False,
+        word_coordinates: bool = False,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> ExtractedTextDocument:
+        """Extract text content from a PDF and return parsed JSON results."""
+
+        payload: dict[str, Any] = {
+            "files": file,
+            "full_text": full_text,
+            "preserve_line_breaks": preserve_line_breaks,
+            "word_style": word_style,
+            "word_coordinates": word_coordinates,
+            "output_type": "json",
+        }
+        if pages is not None:
+            payload["pages"] = pages
+
+        validated_payload = ExtractTextPayload.model_validate(payload)
+        request = self.prepare_request(
+            "POST",
+            "/extracted-text",
+            json_body=validated_payload.model_dump(
+                mode="json", by_alias=True, exclude_none=True, exclude_unset=True
+            ),
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+        raw_payload = self._send_request(request)
+        return ExtractedTextDocument.model_validate(raw_payload)
+
     def extract_pdf_text_to_file(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],
@@ -3398,6 +3441,48 @@ async def extract_images(
             timeout=timeout,
         )
 
+    async def extract_pdf_text(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        pages: PdfPageSelection | None = None,
+        full_text: Literal["off", "by_page", "document"] = "document",
+        preserve_line_breaks: bool = False,
+        word_style: bool = False,
+        word_coordinates: bool = False,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> ExtractedTextDocument:
+        """Extract text content from a PDF and return parsed JSON results."""
+
+        payload: dict[str, Any] = {
+            "files": file,
+            "full_text": full_text,
+            "preserve_line_breaks": preserve_line_breaks,
+            "word_style": word_style,
+            "word_coordinates": word_coordinates,
+            "output_type": "json",
+        }
+        if pages is not None:
+            payload["pages"] = pages
+
+        validated_payload = ExtractTextPayload.model_validate(payload)
+        request = self.prepare_request(
+            "POST",
+            "/extracted-text",
+            json_body=validated_payload.model_dump(
+                mode="json", by_alias=True, exclude_none=True, exclude_unset=True
+            ),
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+        raw_payload = await self._send_request(request)
+        return ExtractedTextDocument.model_validate(raw_payload)
+
     async def extract_pdf_text_to_file(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],

tests/live/test_live_extract_pdf_text.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from itertools import product
+
+import pytest
+
+from pdfrest import AsyncPdfRestClient, PdfRestApiError, PdfRestClient
+from pdfrest.models import ExtractedTextDocument
+
+from ..resources import get_test_resource_path
+
+FULL_TEXT_OPTIONS = ("off", "by_page", "document")
+BOOL_OPTION_SETS = list(product([False, True], repeat=3))
+
+LIVE_OPTION_SETS = [
+    pytest.param(
+        {
+            "full_text": full_text,
+            "preserve_line_breaks": preserve,
+            "word_style": word_style,
+            "word_coordinates": word_coordinates,
+        },
+        id=f"{full_text}-plb-{int(preserve)}-ws-{int(word_style)}-wc-{int(word_coordinates)}",
+    )
+    for full_text in FULL_TEXT_OPTIONS
+    for preserve, word_style, word_coordinates in BOOL_OPTION_SETS
+]
+
+
+def _assert_live_full_text(
+    response: ExtractedTextDocument,
+    *,
+    full_text_mode: str,
+) -> None:
+    if full_text_mode == "off":
+        assert response.full_text is None
+    elif full_text_mode == "document":
+        assert response.full_text is not None
+        assert response.full_text.document_text is not None
+    else:
+        assert response.full_text is not None
+        assert response.full_text.pages is not None
+
+
+@pytest.mark.parametrize("options", LIVE_OPTION_SETS)
+def test_live_extract_pdf_text_success(
+    options: dict[str, bool | str],
+    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.extract_pdf_text(uploaded, **options)
+
+    assert isinstance(response, ExtractedTextDocument)
+    assert response.input_id == uploaded.id
+    _assert_live_full_text(response, full_text_mode=options["full_text"])
+    if options["word_style"] == "on" or options["word_coordinates"] == "on":
+        assert response.words is not None
+        assert response.words
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("options", LIVE_OPTION_SETS)
+async def test_live_async_extract_pdf_text_success(
+    options: dict[str, bool | str],
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+) -> None:
+    resource = get_test_resource_path("report.pdf")
+    async with AsyncPdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        uploaded = (await client.files.create_from_paths([resource]))[0]
+        response = await client.extract_pdf_text(uploaded, **options)
+
+    assert isinstance(response, ExtractedTextDocument)
+    assert response.input_id == uploaded.id
+    _assert_live_full_text(response, full_text_mode=options["full_text"])
+    if options["word_style"] == "on" or options["word_coordinates"] == "on":
+        assert response.words is not None
+        assert response.words
+
+
+def test_live_extract_pdf_text_invalid_pages(
+    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]
+        with pytest.raises(PdfRestApiError, match=r"(?i)page"):
+            client.extract_pdf_text(
+                uploaded,
+                extra_body={"pages": "last-1"},
+            )
+
+
+@pytest.mark.asyncio
+async def test_live_async_extract_pdf_text_invalid_pages(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+) -> None:
+    resource = get_test_resource_path("report.pdf")
+    async with AsyncPdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        uploaded = (await client.files.create_from_paths([resource]))[0]
+        with pytest.raises(PdfRestApiError, match=r"(?i)page"):
+            await client.extract_pdf_text(
+                uploaded,
+                extra_body={"pages": "last-1"},
+            )