From 182f169d4290c7b8bfbbb2b631c875c8e94baccf Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Mon, 16 Feb 2026 14:27:22 -0600 Subject: [PATCH 01/18] client: Add PdfRestFilesClient and AsyncPdfRestFilesClient interfaces - Introduced `PdfRestFilesClient` and `AsyncPdfRestFilesClient` protocol interfaces for managing file operations, including methods to handle file uploads, retrievals, deletions, and content operations. - Updated the `PdfRestClient` and `AsyncPdfRestClient` classes to expose the file clients via the `files` property. - Updated `__all__` definitions in `__init__.py` and `client.py` to include the newly added clients. - Refactored `_FilesClient` and `_AsyncFilesClient` to adhere to the new interface protocols, improving type safety and clarity. Assisted-by: Codex --- src/pdfrest/__init__.py | 9 +- src/pdfrest/client.py | 234 +++++++++++++++++++++++++++++++++++++++- 2 files changed, 237 insertions(+), 6 deletions(-) diff --git a/src/pdfrest/__init__.py b/src/pdfrest/__init__.py index f809dc5b..deece790 100644 --- a/src/pdfrest/__init__.py +++ b/src/pdfrest/__init__.py @@ -2,7 +2,12 @@ from importlib import metadata -from .client import AsyncPdfRestClient, PdfRestClient +from .client import ( + AsyncPdfRestClient, + AsyncPdfRestFilesClient, + PdfRestClient, + PdfRestFilesClient, +) from .exceptions import ( PdfRestApiError, PdfRestAuthenticationError, @@ -19,6 +24,7 @@ __all__ = ( "AsyncPdfRestClient", + "AsyncPdfRestFilesClient", "PdfRestApiError", "PdfRestAuthenticationError", "PdfRestClient", @@ -26,6 +32,7 @@ "PdfRestDeleteError", "PdfRestError", "PdfRestErrorGroup", + "PdfRestFilesClient", "PdfRestRequestError", "PdfRestTimeoutError", "PdfRestTransportError", diff --git a/src/pdfrest/client.py b/src/pdfrest/client.py index 49f65d8f..31ba5691 100644 --- a/src/pdfrest/client.py +++ b/src/pdfrest/client.py @@ -28,6 +28,7 @@ Any, Generic, Literal, + Protocol, TypeAlias, TypeVar, cast, @@ -170,7 +171,12 @@ WatermarkVerticalAlignment, ) -__all__ = ("AsyncPdfRestClient", "PdfRestClient") +__all__ = ( + "AsyncPdfRestClient", + "AsyncPdfRestFilesClient", + "PdfRestClient", + "PdfRestFilesClient", +) FileResponseModel = TypeVar("FileResponseModel", bound=PdfRestFileBasedResponse) DEFAULT_BASE_URL = "https://api.pdfrest.com" @@ -1494,6 +1500,210 @@ async def __aexit__(self, exc_type: Any, exc: Any, traceback: Any) -> None: await self.close() +class PdfRestFilesClient(Protocol): + """Public interface for file operations returned by + [`PdfRestClient.files`][pdfrest.PdfRestClient.files]. + + Retrieve this helper from `client.files`; do not instantiate it directly. + """ + + def get( + self, + id: PdfRestFileID | str, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> PdfRestFile: ... + + def create( + self, + files: UploadFiles, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> list[PdfRestFile]: ... + + def create_from_paths( + self, + file_paths: FilePathInput, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> list[PdfRestFile]: ... + + def create_from_urls( + self, + urls: UrlInput, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + extra_body: Body | None = None, + timeout: TimeoutTypes | None = None, + ) -> list[PdfRestFile]: ... + + def delete( + self, + files: PdfRestFile | Sequence[PdfRestFile], + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + extra_body: Body | None = None, + timeout: TimeoutTypes | None = None, + ) -> None: ... + + def read_bytes( + self, + file_ref: PdfRestFile | str, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> bytes: ... + + def read_text( + self, + file_ref: PdfRestFile | str, + *, + encoding: str = "utf-8", + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> str: ... + + def read_json( + self, + file_ref: PdfRestFile | str, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> Any: ... + + def write_bytes( + self, + file_ref: PdfRestFile | str, + destination: DestinationPath, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> Path: ... + + def stream( + self, + file_ref: PdfRestFile | str, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> PdfRestFileStream: ... + + +class AsyncPdfRestFilesClient(Protocol): + """Public interface for file operations returned by + [`AsyncPdfRestClient.files`][pdfrest.AsyncPdfRestClient.files]. + + Retrieve this helper from `client.files`; do not instantiate it directly. + """ + + async def get( + self, + id: PdfRestFileID | str, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> PdfRestFile: ... + + async def create( + self, + files: UploadFiles, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> list[PdfRestFile]: ... + + async def create_from_paths( + self, + file_paths: FilePathInput, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> list[PdfRestFile]: ... + + async def create_from_urls( + self, + urls: UrlInput, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + extra_body: Body | None = None, + timeout: TimeoutTypes | None = None, + ) -> list[PdfRestFile]: ... + + async def delete( + self, + files: PdfRestFile | Sequence[PdfRestFile], + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + extra_body: Body | None = None, + timeout: TimeoutTypes | None = None, + ) -> None: ... + + async def read_bytes( + self, + file_ref: PdfRestFile | str, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> bytes: ... + + async def read_text( + self, + file_ref: PdfRestFile | str, + *, + encoding: str = "utf-8", + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> str: ... + + async def read_json( + self, + file_ref: PdfRestFile | str, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> Any: ... + + async def write_bytes( + self, + file_ref: PdfRestFile | str, + destination: DestinationPath, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> Path: ... + + async def stream( + self, + file_ref: PdfRestFile | str, + *, + extra_query: Query | None = None, + extra_headers: AnyMapping | None = None, + timeout: TimeoutTypes | None = None, + ) -> AsyncPdfRestFileStream: ... + + class _FilesClient: """Expose file-related operations for the synchronous client.""" @@ -2099,7 +2309,8 @@ def __init__( transport=transport, max_retries=max_retries, ) - self._files_client = _FilesClient(self) + files_client: PdfRestFilesClient = _FilesClient(self) + self._files_client = files_client @override def __enter__(self) -> PdfRestClient: @@ -2111,7 +2322,13 @@ def __exit__(self, exc_type: Any, exc: Any, traceback: Any) -> None: super().__exit__(exc_type, exc, traceback) @property - def files(self) -> _FilesClient: + def files(self) -> PdfRestFilesClient: + """File-management helper implementing + [`PdfRestFilesClient`][pdfrest.PdfRestFilesClient]. + + Retrieve this helper from `client.files`; do not instantiate it directly. + """ + return self._files_client def up( @@ -4032,7 +4249,8 @@ def __init__( concurrency_limit=concurrency_limit, max_retries=max_retries, ) - self._files_client = _AsyncFilesClient(self) + files_client: AsyncPdfRestFilesClient = _AsyncFilesClient(self) + self._files_client = files_client @override async def __aenter__(self) -> AsyncPdfRestClient: @@ -4044,7 +4262,13 @@ async def __aexit__(self, exc_type: Any, exc: Any, traceback: Any) -> None: await super().__aexit__(exc_type, exc, traceback) @property - def files(self) -> _AsyncFilesClient: + def files(self) -> AsyncPdfRestFilesClient: + """Async file-management helper implementing + [`AsyncPdfRestFilesClient`][pdfrest.AsyncPdfRestFilesClient]. + + Retrieve this helper from `client.files`; do not instantiate it directly. + """ + return self._files_client async def query_pdf_info( From 4d532cead42c2b968c1eca826b842fa4068dcac2 Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Mon, 16 Feb 2026 14:44:23 -0600 Subject: [PATCH 02/18] client: Add detailed docstrings to PdfRestFilesClient and AsyncPdfRestFilesClient - Added Google-style docstrings to all methods in `PdfRestFilesClient` and `AsyncPdfRestFilesClient`, documenting parameters, return types, and exceptions for improved clarity and usability. - This change enhances developer experience by providing comprehensive method documentation directly in the codebase. Assisted-by: Codex --- src/pdfrest/client.py | 290 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 270 insertions(+), 20 deletions(-) diff --git a/src/pdfrest/client.py b/src/pdfrest/client.py index 31ba5691..c4af6022 100644 --- a/src/pdfrest/client.py +++ b/src/pdfrest/client.py @@ -1514,7 +1514,19 @@ def get( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> PdfRestFile: ... + ) -> PdfRestFile: + """Retrieve metadata for an uploaded file. + + Args: + id: Uploaded file identifier. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + The resolved file metadata. + """ + ... def create( self, @@ -1523,7 +1535,19 @@ def create( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> list[PdfRestFile]: ... + ) -> list[PdfRestFile]: + """Upload one or more local file objects. + + Args: + files: Multipart file payload(s) accepted by httpx upload APIs. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + Metadata for uploaded files. + """ + ... def create_from_paths( self, @@ -1532,7 +1556,19 @@ def create_from_paths( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> list[PdfRestFile]: ... + ) -> list[PdfRestFile]: + """Upload one or more files by filesystem path. + + Args: + file_paths: Path input(s), optionally with content type and headers. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + Metadata for uploaded files. + """ + ... def create_from_urls( self, @@ -1542,7 +1578,20 @@ def create_from_urls( extra_headers: AnyMapping | None = None, extra_body: Body | None = None, timeout: TimeoutTypes | None = None, - ) -> list[PdfRestFile]: ... + ) -> list[PdfRestFile]: + """Upload one or more files by remote URL. + + Args: + urls: One URL or a sequence of URLs to upload. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + extra_body: Additional JSON body fields merged into the request. + timeout: Optional request timeout override. + + Returns: + Metadata for uploaded files. + """ + ... def delete( self, @@ -1552,7 +1601,21 @@ def delete( extra_headers: AnyMapping | None = None, extra_body: Body | None = None, timeout: TimeoutTypes | None = None, - ) -> None: ... + ) -> None: + """Delete one or more previously uploaded files. + + Args: + files: File reference(s) to delete. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + extra_body: Additional JSON body fields merged into the request. + timeout: Optional request timeout override. + + Raises: + PdfRestErrorGroup: Raised when one or more deletions fail. Individual + failures are reported as `PdfRestDeleteError` items in the group. + """ + ... def read_bytes( self, @@ -1561,7 +1624,19 @@ def read_bytes( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> bytes: ... + ) -> bytes: + """Download a file and return its raw bytes. + + Args: + file_ref: File object or file id to download. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + The downloaded bytes. + """ + ... def read_text( self, @@ -1571,7 +1646,20 @@ def read_text( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> str: ... + ) -> str: + """Download a file and decode it into text. + + Args: + file_ref: File object or file id to download. + encoding: Text encoding used when decoding the response. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + The decoded text content. + """ + ... def read_json( self, @@ -1580,7 +1668,19 @@ def read_json( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> Any: ... + ) -> Any: + """Download a file and parse its content as JSON. + + Args: + file_ref: File object or file id to download. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + Parsed JSON value. + """ + ... def write_bytes( self, @@ -1590,7 +1690,20 @@ def write_bytes( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> Path: ... + ) -> Path: + """Download a file and persist it to disk. + + Args: + file_ref: File object or file id to download. + destination: Output path for the downloaded file. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + The written destination path. + """ + ... def stream( self, @@ -1599,7 +1712,19 @@ def stream( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> PdfRestFileStream: ... + ) -> PdfRestFileStream: + """Open a streaming download for a file. + + Args: + file_ref: File object or file id to download. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + A synchronous streaming wrapper around the HTTP response. + """ + ... class AsyncPdfRestFilesClient(Protocol): @@ -1616,7 +1741,19 @@ async def get( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> PdfRestFile: ... + ) -> PdfRestFile: + """Retrieve metadata for an uploaded file. + + Args: + id: Uploaded file identifier. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + The resolved file metadata. + """ + ... async def create( self, @@ -1625,7 +1762,19 @@ async def create( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> list[PdfRestFile]: ... + ) -> list[PdfRestFile]: + """Upload one or more local file objects. + + Args: + files: Multipart file payload(s) accepted by httpx upload APIs. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + Metadata for uploaded files. + """ + ... async def create_from_paths( self, @@ -1634,7 +1783,19 @@ async def create_from_paths( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> list[PdfRestFile]: ... + ) -> list[PdfRestFile]: + """Upload one or more files by filesystem path. + + Args: + file_paths: Path input(s), optionally with content type and headers. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + Metadata for uploaded files. + """ + ... async def create_from_urls( self, @@ -1644,7 +1805,20 @@ async def create_from_urls( extra_headers: AnyMapping | None = None, extra_body: Body | None = None, timeout: TimeoutTypes | None = None, - ) -> list[PdfRestFile]: ... + ) -> list[PdfRestFile]: + """Upload one or more files by remote URL. + + Args: + urls: One URL or a sequence of URLs to upload. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + extra_body: Additional JSON body fields merged into the request. + timeout: Optional request timeout override. + + Returns: + Metadata for uploaded files. + """ + ... async def delete( self, @@ -1654,7 +1828,21 @@ async def delete( extra_headers: AnyMapping | None = None, extra_body: Body | None = None, timeout: TimeoutTypes | None = None, - ) -> None: ... + ) -> None: + """Delete one or more previously uploaded files. + + Args: + files: File reference(s) to delete. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + extra_body: Additional JSON body fields merged into the request. + timeout: Optional request timeout override. + + Raises: + PdfRestErrorGroup: Raised when one or more deletions fail. Individual + failures are reported as `PdfRestDeleteError` items in the group. + """ + ... async def read_bytes( self, @@ -1663,7 +1851,19 @@ async def read_bytes( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> bytes: ... + ) -> bytes: + """Download a file and return its raw bytes. + + Args: + file_ref: File object or file id to download. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + The downloaded bytes. + """ + ... async def read_text( self, @@ -1673,7 +1873,20 @@ async def read_text( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> str: ... + ) -> str: + """Download a file and decode it into text. + + Args: + file_ref: File object or file id to download. + encoding: Text encoding used when decoding the response. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + The decoded text content. + """ + ... async def read_json( self, @@ -1682,7 +1895,19 @@ async def read_json( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> Any: ... + ) -> Any: + """Download a file and parse its content as JSON. + + Args: + file_ref: File object or file id to download. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + Parsed JSON value. + """ + ... async def write_bytes( self, @@ -1692,7 +1917,20 @@ async def write_bytes( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> Path: ... + ) -> Path: + """Download a file and persist it to disk. + + Args: + file_ref: File object or file id to download. + destination: Output path for the downloaded file. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + The written destination path. + """ + ... async def stream( self, @@ -1701,7 +1939,19 @@ async def stream( extra_query: Query | None = None, extra_headers: AnyMapping | None = None, timeout: TimeoutTypes | None = None, - ) -> AsyncPdfRestFileStream: ... + ) -> AsyncPdfRestFileStream: + """Open a streaming download for a file. + + Args: + file_ref: File object or file id to download. + extra_query: Additional query parameters appended to the request. + extra_headers: Additional headers merged into the request. + timeout: Optional request timeout override. + + Returns: + An asynchronous streaming wrapper around the HTTP response. + """ + ... class _FilesClient: From 643786b4eac71f7682f508d87d2f4e0f6dcb7fb8 Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Mon, 16 Feb 2026 18:38:42 -0600 Subject: [PATCH 03/18] docs: Update MkDocs configuration with enhanced signature options - Added `line_length`, `separate_signature`, `show_signature_annotations`, and `signature_crossrefs` options in `mkdocstrings` plugin configuration. - Improves API documentation readability and presentation by better handling function signatures and annotations. Assisted-by: Codex --- mkdocs.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index abbd1008..b55ea0a7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,7 +19,11 @@ plugins: options: docstring_style: google heading_level: 2 + line_length: 50 members_order: source + separate_signature: true + show_signature_annotations: true + signature_crossrefs: true show_source: false show_root_heading: true From 747db4f9b91853c7a12bb86677a70ebdef44d4ef Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Mon, 16 Feb 2026 18:39:15 -0600 Subject: [PATCH 04/18] models: Add comprehensive docstrings to public API types - Provided detailed docstrings for all properties, methods, and fields within public models to enhance clarity and usability of the API. - Added type-level descriptions for key API response types and utilities. - Improved coverage of metadata details, structured data, and edge cases for PDF processing operations. Assisted-by: Codex --- docs/api-reference.md | 8 ++ src/pdfrest/models/public.py | 168 +++++++++++++++++++++++++++++++++++ src/pdfrest/types/public.py | 44 +++++++++ 3 files changed, 220 insertions(+) diff --git a/docs/api-reference.md b/docs/api-reference.md index 2a5b4ddd..94dc7763 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -3,3 +3,11 @@ ## Package ::: pdfrest + +## Public Types + +::: pdfrest.types + +## Public Models + +::: pdfrest.models diff --git a/src/pdfrest/models/public.py b/src/pdfrest/models/public.py index 811aa112..4ffddf5e 100644 --- a/src/pdfrest/models/public.py +++ b/src/pdfrest/models/public.py @@ -207,9 +207,16 @@ class UpResponse(BaseModel): """Response payload returned by the `/up` health endpoint.""" status: str + """Service health status string returned by pdfRest.""" + product: str + """Product identifier reported by the service.""" + release_date: date = Field(alias="releaseDate") + """Release date for the deployed pdfRest version.""" + version: str + """Semantic version identifier for the running service.""" model_config = ConfigDict(frozen=True) @@ -218,6 +225,8 @@ class PdfRestErrorResponse(BaseModel): """Error response payloads from pdfRest.""" error: str | None = Field(alias="message") + """Human-readable error message returned by the API.""" + model_config = ConfigDict(extra="allow", frozen=True) @@ -228,29 +237,42 @@ class PdfRestFile(BaseModel): min_length=1, description="Identifier of the file on the pdfRest server", ) + """Identifier of the file on the pdfRest server.""" + name: str = Field( min_length=1, description="Name of the file", ) + """Name of the file.""" + url: HttpUrl = Field( description="URL from which the file can be downloaded", ) + """URL from which the file can be downloaded.""" + type: str = Field( min_length=1, description="MIME type of the file", ) + """MIME type of the file.""" + size: int = Field( description="Size of the file", ) + """Size of the file.""" + modified: AwareDatetime = Field( description="The last modified time of the file, which must include time zone " "info.", ) + """The last modified time of the file, which must include time zone info.""" + scheduled_deletion_time_utc: AwareDatetime | None = Field( alias="scheduledDeletionTimeUtc", default=None, description="The UTC time at which the file will be deleted from the server.", ) + """The UTC time at which the file will be deleted from the server.""" model_config = ConfigDict(frozen=True) @@ -272,6 +294,7 @@ class PdfRestFileBasedResponse(BaseModel): validation_alias=AliasChoices("input_id", "inputId"), ), ] + """The ids of the files that were input to the pdfRest operation.""" # Optional because some endpoints may not make output output_files: Annotated[ @@ -281,6 +304,7 @@ class PdfRestFileBasedResponse(BaseModel): validation_alias=AliasChoices("output_file", "outputFile"), ), ] + """The list of files returned by the pdfRest operation.""" warning: Annotated[ str | None, @@ -288,9 +312,16 @@ class PdfRestFileBasedResponse(BaseModel): description="A warning that was generated during the pdfRest operation", ), ] = None + """A warning that was generated during the pdfRest operation.""" @property def input_id(self) -> PdfRestFileID: + """Return the lone input id when exactly one input file was supplied. + + Raises: + ValueError: If no input id is available or multiple input ids exist. + """ + if len(self.input_ids) == 1: return self.input_ids[0] if len(self.input_ids) == 0: @@ -301,6 +332,12 @@ def input_id(self) -> PdfRestFileID: @property def output_file(self) -> PdfRestFile: + """Return the lone output file when exactly one output is available. + + Raises: + ValueError: If no output file is available or multiple outputs exist. + """ + if len(self.output_files) == 1: return self.output_files[0] if len(self.output_files) == 0: @@ -324,6 +361,7 @@ class PdfRestDeletionResponse(BaseModel): min_length=1, ), ] + """Mapping of file ids to deletion results.""" class SummarizePdfTextResponse(BaseModel): @@ -338,6 +376,8 @@ class SummarizePdfTextResponse(BaseModel): default=None, ), ] = None + """Summary content.""" + input_id: Annotated[ PdfRestFileID, Field( @@ -345,6 +385,7 @@ class SummarizePdfTextResponse(BaseModel): description="The id of the input file.", ), ] + """The id of the input file.""" class TranslatePdfTextResponse(BaseModel): @@ -361,6 +402,8 @@ class TranslatePdfTextResponse(BaseModel): default=None, ), ] = None + """Languages detected in the source content.""" + output_language: Annotated[ str | None, Field( @@ -370,6 +413,8 @@ class TranslatePdfTextResponse(BaseModel): default=None, ), ] = None + """Target language used for the translation.""" + translated_text: Annotated[ str | None, Field( @@ -379,6 +424,8 @@ class TranslatePdfTextResponse(BaseModel): default=None, ), ] = None + """Inline translation content when output_type is json.""" + input_id: Annotated[ PdfRestFileID, Field( @@ -386,6 +433,7 @@ class TranslatePdfTextResponse(BaseModel): description="The id of the input file.", ), ] + """The id of the input file.""" class TranslatePdfTextFileResponse(PdfRestFileBasedResponse): @@ -402,6 +450,8 @@ class TranslatePdfTextFileResponse(PdfRestFileBasedResponse): default=None, ), ] = None + """Languages detected in the source content.""" + output_language: Annotated[ str | None, Field( @@ -411,6 +461,7 @@ class TranslatePdfTextFileResponse(PdfRestFileBasedResponse): default=None, ), ] = None + """Target language used for the translation.""" class ExtractTextResponse(BaseModel): @@ -427,6 +478,8 @@ class ExtractTextResponse(BaseModel): default=None, ), ] = None + """Inline extracted text when output_type is json.""" + input_id: Annotated[ PdfRestFileID, Field( @@ -434,10 +487,13 @@ class ExtractTextResponse(BaseModel): description="The id of the input file.", ), ] + """The id of the input file.""" + warning: Annotated[ str | None, Field(description="A warning that was generated during text extraction."), ] = None + """A warning that was generated during text extraction.""" class ExtractedTextPoint(BaseModel): @@ -449,10 +505,13 @@ class ExtractedTextPoint(BaseModel): float, Field(description="Horizontal position in PDF points."), ] + """Horizontal position in PDF points.""" + y: Annotated[ float, Field(description="Vertical position in PDF points."), ] + """Vertical position in PDF points.""" class ExtractedTextWordCoordinates(BaseModel): @@ -468,6 +527,8 @@ class ExtractedTextWordCoordinates(BaseModel): description="Upper-left corner of the word bounds.", ), ] + """Upper-left corner of the word bounds.""" + top_right: Annotated[ ExtractedTextPoint, Field( @@ -476,6 +537,8 @@ class ExtractedTextWordCoordinates(BaseModel): description="Upper-right corner of the word bounds.", ), ] + """Upper-right corner of the word bounds.""" + bottom_left: Annotated[ ExtractedTextPoint, Field( @@ -484,6 +547,8 @@ class ExtractedTextWordCoordinates(BaseModel): description="Lower-left corner of the word bounds.", ), ] + """Lower-left corner of the word bounds.""" + bottom_right: Annotated[ ExtractedTextPoint, Field( @@ -492,6 +557,7 @@ class ExtractedTextWordCoordinates(BaseModel): description="Lower-right corner of the word bounds.", ), ] + """Lower-right corner of the word bounds.""" class ExtractedTextWordColor(BaseModel): @@ -503,6 +569,8 @@ class ExtractedTextWordColor(BaseModel): str, Field(description="Color space name reported by pdfRest (e.g., DeviceRGB)."), ] + """Color space name reported by pdfRest (e.g., DeviceRGB).""" + values: Annotated[ list[float], Field( @@ -510,6 +578,7 @@ class ExtractedTextWordColor(BaseModel): min_length=1, ), ] + """Numeric components in the reported color space.""" class ExtractedTextWordFont(BaseModel): @@ -521,10 +590,13 @@ class ExtractedTextWordFont(BaseModel): str, Field(description="Reported font face name."), ] + """Reported font face name.""" + size: Annotated[ float, Field(description="Font size in points."), ] + """Font size in points.""" class ExtractedTextWordStyle(BaseModel): @@ -536,10 +608,13 @@ class ExtractedTextWordStyle(BaseModel): ExtractedTextWordColor, Field(description="Color information for the word."), ] + """Color information for the word.""" + font: Annotated[ ExtractedTextWordFont, Field(description="Font information for the word."), ] + """Font information for the word.""" class ExtractedTextWord(BaseModel): @@ -551,10 +626,14 @@ class ExtractedTextWord(BaseModel): str, Field(description="Word content as rendered by the PDF."), ] + """Word content as rendered by the PDF.""" + page: Annotated[ int, Field(description="1-indexed page number containing the word.", ge=1), ] + """1-indexed page number containing the word.""" + coordinates: Annotated[ ExtractedTextWordCoordinates | None, Field( @@ -562,6 +641,8 @@ class ExtractedTextWord(BaseModel): default=None, ), ] = None + """Bounding box for the word when positional data is requested.""" + style: Annotated[ ExtractedTextWordStyle | None, Field( @@ -569,6 +650,7 @@ class ExtractedTextWord(BaseModel): default=None, ), ] = None + """Font/color details captured for the word.""" class ExtractedTextFullTextPage(BaseModel): @@ -580,10 +662,13 @@ class ExtractedTextFullTextPage(BaseModel): int, Field(description="1-indexed page number.", ge=1), ] + """1-indexed page number.""" + text: Annotated[ str, Field(description="Concatenated text for the page."), ] + """Concatenated text for the page.""" class ExtractedTextFullTextPages(BaseModel): @@ -598,6 +683,7 @@ class ExtractedTextFullTextPages(BaseModel): min_length=1, ), ] + """Ordered text for each page present in the document.""" class ExtractedTextFullText(RootModel[str | ExtractedTextFullTextPages]): @@ -607,6 +693,7 @@ class ExtractedTextFullText(RootModel[str | ExtractedTextFullTextPages]): """ root: str | ExtractedTextFullTextPages + """Raw payload in document-text or per-page form.""" @property def document_text(self) -> str | None: @@ -653,6 +740,8 @@ class ExtractedTextDocument(BaseModel): description="Identifier of the uploaded PDF.", ), ] + """Identifier of the uploaded PDF.""" + words: Annotated[ list[ExtractedTextWord] | None, Field( @@ -660,6 +749,8 @@ class ExtractedTextDocument(BaseModel): default=None, ), ] = None + """Individual word records when word-level extraction is enabled.""" + full_text: Annotated[ ExtractedTextFullText | None, Field( @@ -669,6 +760,7 @@ class ExtractedTextDocument(BaseModel): default=None, ), ] = None + """Full text output (document string or per-page content).""" class ConvertToMarkdownResponse(BaseModel): @@ -683,6 +775,8 @@ class ConvertToMarkdownResponse(BaseModel): default=None, ), ] = None + """Inline markdown content when output_type is json.""" + input_id: Annotated[ PdfRestFileID, Field( @@ -690,6 +784,8 @@ class ConvertToMarkdownResponse(BaseModel): description="The id of the input file.", ), ] + """The id of the input file.""" + output_url: Annotated[ HttpUrl | None, Field( @@ -699,6 +795,8 @@ class ConvertToMarkdownResponse(BaseModel): default=None, ), ] = None + """Download URL for file output.""" + output_id: Annotated[ PdfRestFileID | None, Field( @@ -708,10 +806,13 @@ class ConvertToMarkdownResponse(BaseModel): default=None, ), ] = None + """The id of the generated output when output_type is file.""" + warning: Annotated[ str | None, Field(description="A warning that was generated during markdown conversion."), ] = None + """A warning that was generated during markdown conversion.""" class PdfRestInfoResponse(BaseModel): @@ -728,6 +829,8 @@ class PdfRestInfoResponse(BaseModel): description="The id of the input file", ), ] + """The id of the input file.""" + tagged: Annotated[ bool | None, Field( @@ -735,6 +838,8 @@ class PdfRestInfoResponse(BaseModel): "document. The result is true or false." ), ] = None + """Indicates whether structure tags are present in the PDF document. The result is true or false.""" + image_only: Annotated[ bool | None, Field( @@ -746,6 +851,8 @@ class PdfRestInfoResponse(BaseModel): ) ), ] = None + """Indicates whether the document is 'image only,' meaning it consists solely of embedded graphical images with no text or other standard PDF document features except for metadata. The result is true or false.""" + title: Annotated[ str | None, Field( @@ -755,6 +862,8 @@ class PdfRestInfoResponse(BaseModel): ) ), ] = None + """The title of the PDF as retrieved from the metadata. The result is a string that may be empty if the document does not have a title.""" + subject: Annotated[ str | None, Field( @@ -764,6 +873,8 @@ class PdfRestInfoResponse(BaseModel): ) ), ] = None + """The subject of the PDF as retrieved from the metadata. The result is a string that may be empty if the document does not have a subject.""" + author: Annotated[ str | None, Field( @@ -773,6 +884,8 @@ class PdfRestInfoResponse(BaseModel): ) ), ] = None + """The author of the PDF as retrieved from the metadata. The result is a string that may be empty if the document does not have an author.""" + producer: Annotated[ str | None, Field( @@ -783,6 +896,8 @@ class PdfRestInfoResponse(BaseModel): ) ), ] = None + """The producer of the PDF as retrieved from the metadata. The result is a string that may be empty if the document does not have a producer.""" + creator: Annotated[ str | None, Field( @@ -792,6 +907,8 @@ class PdfRestInfoResponse(BaseModel): ) ), ] = None + """The creator of the PDF as retrieved from the metadata. The result is a string that may be empty if the document does not have a creator.""" + creation_date: Annotated[ str | None, Field( @@ -802,6 +919,8 @@ class PdfRestInfoResponse(BaseModel): ) ), ] = None + """The creation date of the PDF as retrieved from the metadata. The result is a string that may be empty if the document does not have a creation date.""" + modified_date: Annotated[ str | None, Field( @@ -812,6 +931,8 @@ class PdfRestInfoResponse(BaseModel): ) ), ] = None + """The most recent modification date of the PDF as retrieved from the metadata. The result is a string that may be empty if the document does not have a modification date.""" + keywords: Annotated[ str | None, Field( @@ -822,6 +943,8 @@ class PdfRestInfoResponse(BaseModel): ) ), ] = None + """The keywords of the PDF as retrieved from the metadata. The result is a string that may be empty if the document does not include keywords.""" + custom_metadata: Annotated[ dict[str, Any] | None, Field( @@ -832,6 +955,8 @@ class PdfRestInfoResponse(BaseModel): ) ), ] = None + """Custom metadata entries extracted from the PDF. The result is a dictionary mapping keys to their stored values, or None when no custom metadata exists.""" + doc_language: Annotated[ str | None, Field( @@ -839,6 +964,8 @@ class PdfRestInfoResponse(BaseModel): "The result is a string." ), ] = None + """The language of the document as declared in its metadata. The result is a string.""" + page_count: Annotated[ int | None, Field( @@ -846,6 +973,8 @@ class PdfRestInfoResponse(BaseModel): "integer." ), ] = None + """The number of pages in the PDF document. The result is an integer.""" + contains_annotations: Annotated[ bool | None, Field( @@ -856,6 +985,8 @@ class PdfRestInfoResponse(BaseModel): ) ), ] = None + """Indicates whether the PDF document contains annotations such as notes, highlighted text, file attachments, crossed-out text, or text callout boxes. The result is true or false.""" + contains_signature: Annotated[ bool | None, Field( @@ -863,6 +994,8 @@ class PdfRestInfoResponse(BaseModel): "The result is true or false." ), ] = None + """Indicates whether the PDF contains any digital signatures. The result is true or false.""" + pdf_version: Annotated[ str | None, Field( @@ -873,16 +1006,22 @@ class PdfRestInfoResponse(BaseModel): ) ), ] = None + """The version of the PDF standard used to create the document. The result is a string in the format X.Y.Z, where X, Y, and Z represent the major, minor, and extension versions.""" + file_size: Annotated[ int | None, Field( description="The size of the PDF file in bytes. The result is an integer." ), ] = None + """The size of the PDF file in bytes. The result is an integer.""" + filename: Annotated[ str | None, Field(description="The name of the PDF file. The result is a string."), ] = None + """The name of the PDF file. The result is a string.""" + restrict_permissions_set: Annotated[ bool | None, Field( @@ -893,6 +1032,8 @@ class PdfRestInfoResponse(BaseModel): ) ), ] = None + """Indicates whether the PDF file has restricted permissions, such as preventing printing, copying, or signing. The result is true or false.""" + contains_xfa: Annotated[ bool | None, Field( @@ -900,6 +1041,8 @@ class PdfRestInfoResponse(BaseModel): "true or false." ), ] = None + """Indicates whether the PDF contains XFA forms. The result is true or false.""" + contains_acroforms: Annotated[ bool | None, Field( @@ -907,6 +1050,8 @@ class PdfRestInfoResponse(BaseModel): "true or false." ), ] = None + """Indicates whether the PDF contains Acroforms. The result is true or false.""" + contains_javascript: Annotated[ bool | None, Field( @@ -914,6 +1059,8 @@ class PdfRestInfoResponse(BaseModel): "true or false." ), ] = None + """Indicates whether the PDF contains JavaScript. The result is true or false.""" + contains_transparency: Annotated[ bool | None, Field( @@ -921,6 +1068,8 @@ class PdfRestInfoResponse(BaseModel): "result is true or false." ), ] = None + """Indicates whether the PDF contains transparent objects. The result is true or false.""" + contains_embedded_file: Annotated[ bool | None, Field( @@ -928,6 +1077,8 @@ class PdfRestInfoResponse(BaseModel): "files. The result is true or false." ), ] = None + """Indicates whether the PDF contains one or more embedded files. The result is true or false.""" + uses_embedded_fonts: Annotated[ bool | None, Field( @@ -935,6 +1086,8 @@ class PdfRestInfoResponse(BaseModel): "The result is true or false." ), ] = None + """Indicates whether the PDF contains fully embedded fonts. The result is true or false.""" + uses_nonembedded_fonts: Annotated[ bool | None, Field( @@ -942,6 +1095,8 @@ class PdfRestInfoResponse(BaseModel): "result is true or false." ), ] = None + """Indicates whether the PDF contains non-embedded fonts. The result is true or false.""" + pdfa: Annotated[ bool | None, Field( @@ -949,6 +1104,8 @@ class PdfRestInfoResponse(BaseModel): "standard. The result is true or false." ), ] = None + """Indicates whether the document conforms to the PDF/A standard. The result is true or false.""" + pdfua_claim: Annotated[ bool | None, Field( @@ -956,6 +1113,8 @@ class PdfRestInfoResponse(BaseModel): "PDF/UA standard. The result is true or false." ), ] = None + """Indicates whether the document claims to conform to the PDF/UA standard. The result is true or false.""" + pdfe_claim: Annotated[ bool | None, Field( @@ -963,6 +1122,8 @@ class PdfRestInfoResponse(BaseModel): "PDF/E standard. The result is true or false." ), ] = None + """Indicates whether the document claims to conform to the PDF/E standard. The result is true or false.""" + pdfx_claim: Annotated[ bool | None, Field( @@ -970,6 +1131,8 @@ class PdfRestInfoResponse(BaseModel): "PDF/X standard. The result is true or false." ), ] = None + """Indicates whether the document claims to conform to the PDF/X standard. The result is true or false.""" + requires_password_to_open: Annotated[ bool | None, Field( @@ -980,6 +1143,8 @@ class PdfRestInfoResponse(BaseModel): ) ), ] = None + """Indicates whether the PDF requires a password to open. The result is true or false. *Note*: A document requiring a password cannot be opened by this route and will not provide much other information.""" + all_queries_processed: Annotated[ bool, Field( @@ -993,9 +1158,12 @@ class PdfRestInfoResponse(BaseModel): ), ), ] + """Indicates whether all possible queries about the PDF document were successfully processed. This field is required, and the result is true or false.""" + warning: Annotated[ str | None, Field( description="A warning indicating why not all queries could be processed.", ), ] = None + """A warning indicating why not all queries could be processed.""" diff --git a/src/pdfrest/types/public.py b/src/pdfrest/types/public.py index 742d3fd9..462a701b 100644 --- a/src/pdfrest/types/public.py +++ b/src/pdfrest/types/public.py @@ -64,6 +64,8 @@ "WatermarkVerticalAlignment", ) +#: Supported query keys for :meth:`pdfrest.PdfRestClient.query_pdf_info` and +#: :meth:`pdfrest.AsyncPdfRestClient.query_pdf_info`. PdfInfoQuery = Literal[ "tagged", "image_only", @@ -102,8 +104,10 @@ tuple[PdfInfoQuery, ...], get_args(PdfInfoQuery) ) +#: Redaction match mode used by :class:`PdfRedactionInstruction`. PdfRedactionType = Literal["literal", "regex", "preset"] +#: Built-in redaction presets accepted by pdfRest. PdfRedactionPreset = Literal[ "email", "phone_number", @@ -121,6 +125,8 @@ class PdfRedactionInstruction(TypedDict): + """Single redaction rule for preview/apply redaction operations.""" + type: PdfRedactionType value: PdfRedactionPreset | str @@ -131,6 +137,23 @@ class PdfRedactionInstruction(TypedDict): class PdfAddTextObject(TypedDict, total=False): + """Text overlay object used by add-text style operations. + + Attributes: + font: Font family name used to render text. + max_width: Maximum text box width in PDF points. + opacity: Opacity value from 0.0 (transparent) to 1.0 (opaque). + page: One-based page number or ``\"all\"`` for every page. + rotation: Rotation angle in degrees. + text: Text content to draw. + text_color_rgb: Optional RGB text color tuple. + text_color_cmyk: Optional CMYK text color tuple. + text_size: Font size in points. + x: Horizontal origin in PDF points. + y: Vertical origin in PDF points. + is_right_to_left: Whether text should be rendered right-to-left. + """ + font: Required[str] max_width: Required[float] opacity: Required[float] @@ -150,14 +173,18 @@ class PdfCustomPageSize(TypedDict): custom_width: Required[float] +#: Page selector accepted by endpoints that support page filtering. PdfPageSelection = str | int | Sequence[str | int] class PdfMergeSource(TypedDict, total=False): + """Merge item containing an uploaded file and optional page selection.""" + file: Required[PdfRestFile] pages: PdfPageSelection | None +#: Merge input item accepted by merge APIs. PdfMergeInput = PdfRestFile | PdfMergeSource | tuple[PdfRestFile, PdfPageSelection] PdfConversionCompression = Literal["lossy", "lossless"] @@ -221,21 +248,33 @@ class PdfPemCredentials(TypedDict): PdfSignatureCredentials = PdfPfxCredentials | PdfPemCredentials +#: PDF/A conformance targets accepted by ``convert_to_pdfa``. PdfAType = Literal["PDF/A-1b", "PDF/A-2b", "PDF/A-2u", "PDF/A-3b", "PDF/A-3u"] +#: PDF/X conformance targets accepted by ``convert_to_pdfx``. PdfXType = Literal["PDF/X-1a", "PDF/X-3", "PDF/X-4", "PDF/X-6"] +#: Granularity modes for extracted full text payloads. ExtractTextGranularity = Literal["off", "by_page", "document"] +#: Compression levels accepted by ``compress_pdf``. CompressionLevel = Literal["low", "medium", "high", "custom"] +#: Quality presets for transparency flattening. FlattenQuality = Literal["low", "medium", "high"] +#: PNG output color models accepted by ``convert_to_png``. PngColorModel = Literal["rgb", "rgba", "gray"] +#: BMP output color models accepted by ``convert_to_bmp``. BmpColorModel = Literal["rgb", "gray"] +#: GIF output color models accepted by ``convert_to_gif``. GifColorModel = Literal["rgb", "gray"] +#: JPEG output color models accepted by ``convert_to_jpeg``. JpegColorModel = Literal["rgb", "cmyk", "gray"] +#: TIFF output color models accepted by ``convert_to_tiff``. TiffColorModel = Literal["rgb", "rgba", "cmyk", "lab", "gray"] +#: Graphic smoothing modes for image conversion endpoints. 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"] +#: Summary styles accepted by summarize-text endpoints. SummaryFormat = Literal[ "overview", "highlight", @@ -248,11 +287,15 @@ class PdfPemCredentials(TypedDict): "action_items", ] +#: Output text format for summary endpoints. SummaryOutputFormat = Literal["plaintext", "markdown"] +#: Output mode for summary endpoints. SummaryOutputType = Literal["json", "file"] +#: Output text format for translate-text endpoints. TranslateOutputFormat = Literal["plaintext", "markdown"] +#: OCR languages accepted by ``ocr_pdf``. OcrLanguage = Literal[ "ChineseSimplified", "ChineseTraditional", @@ -271,6 +314,7 @@ class PdfPemCredentials(TypedDict): tuple[OcrLanguage, ...], get_args(OcrLanguage) ) +#: Document permissions accepted by password restriction endpoints. PdfRestriction = Literal[ "print_low", "print_high", From 431b32a2b3b360fa7c69767ed858812397101f82 Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Tue, 17 Feb 2026 15:09:02 -0600 Subject: [PATCH 05/18] github: Add docs artifact upload step to CI for pull requests - Updated `.github/workflows/test-and-publish.yml` to add a step for uploading documentation preview artifacts when triggered by pull requests. - Artifacts are retained for 7 days to aid in documentation review and testing. Assisted-by: Codex --- .github/workflows/test-and-publish.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/workflows/test-and-publish.yml b/.github/workflows/test-and-publish.yml index 48c73f1f..b086834e 100644 --- a/.github/workflows/test-and-publish.yml +++ b/.github/workflows/test-and-publish.yml @@ -29,6 +29,13 @@ jobs: run: uv sync --group dev - name: Build docs with MkDocs run: uv run mkdocs build --strict + - name: Upload docs preview artifact + if: github.event_name == 'pull_request' + uses: actions/upload-artifact@v4 + with: + name: docs-site + path: site/ + retention-days: 7 tests: name: Tests (Python ${{ matrix.python-version }}) From 154ecfd6bd5e3cb44e0f242120f283e72b552aa4 Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Wed, 18 Feb 2026 12:35:08 -0600 Subject: [PATCH 06/18] docs: Add client configuration guide and update navigation - Added `client-configuration.md` detailing setup options for `PdfRestClient` and `AsyncPdfRestClient`, including parameters, timeout configurations, custom HTTPX client usage, and headers. - Updated `index.md` to include links to the new `getting-started.md` and `client-configuration.md` guides. - Modified `mkdocs.yml` to reflect the new navigation structure. Assisted-by: Codex --- docs/client-configuration.md | 149 +++++++++++++++++++++++++++++++++++ docs/index.md | 2 + mkdocs.yml | 1 + 3 files changed, 152 insertions(+) create mode 100644 docs/client-configuration.md diff --git a/docs/client-configuration.md b/docs/client-configuration.md new file mode 100644 index 00000000..c774b47c --- /dev/null +++ b/docs/client-configuration.md @@ -0,0 +1,149 @@ +# Client configuration + +This guide explains how to configure +[`PdfRestClient`](api-reference.md#pdfrest.PdfRestClient) and +[`AsyncPdfRestClient`](api-reference.md#pdfrest.AsyncPdfRestClient), including +how SDK settings map to HTTPX behavior. + +## Constructor parameters + +Both clients support a shared baseline: + +- `api_key`: API key used for the `Api-Key` header. If omitted, the SDK reads + `PDFREST_API_KEY` from the environment. +- `base_url`: API host (defaults to `https://api.pdfrest.com`). +- `timeout`: `float` seconds or an + [`httpx.Timeout`](https://www.python-httpx.org/api/#timeout) object. +- `headers`: default headers merged into every request. +- `max_retries`: retry count for retryable transport/timeouts and retryable + HTTP status responses. + +Sync-only options ([`PdfRestClient`](api-reference.md#pdfrest.PdfRestClient)): + +- `http_client`: preconfigured + [`httpx.Client`](https://www.python-httpx.org/api/#client) instance to reuse. +- `transport`: custom + [`httpx.BaseTransport`](https://www.python-httpx.org/advanced/transports/). + +Async-only options +([`AsyncPdfRestClient`](api-reference.md#pdfrest.AsyncPdfRestClient)): + +- `http_client`: preconfigured + [`httpx.AsyncClient`](https://www.python-httpx.org/api/#asyncclient) instance + to reuse. +- `transport`: custom + [`httpx.AsyncBaseTransport`](https://www.python-httpx.org/advanced/transports/). +- `concurrency_limit`: controls async file-info fetch fanout in multi-file + operations. + +## Timeout configuration + +By default, the SDK uses an HTTPX timeout profile with a longer read timeout. +You can override with either a single float or a full timeout object: + +```python +import httpx +from pdfrest import PdfRestClient + +with PdfRestClient( + timeout=httpx.Timeout(connect=5.0, read=180.0, write=30.0, pool=10.0) +) as client: + status = client.up() +``` + +HTTPX references: + +- [Timeouts](https://www.python-httpx.org/advanced/timeouts/) +- [API reference: `httpx.Timeout`](https://www.python-httpx.org/api/) + +## Using a custom HTTPX client + +If you need advanced HTTP behavior (custom TLS, proxies, limits, event hooks, +or a shared connection pool), provide a preconfigured HTTPX client. + +```python +import httpx +from pdfrest import PdfRestClient + +http_client = httpx.Client( + timeout=httpx.Timeout(20.0), + limits=httpx.Limits(max_connections=20, max_keepalive_connections=10), +) + +with PdfRestClient(http_client=http_client) as client: + response = client.up() +``` + +HTTPX references: + +- [Clients](https://www.python-httpx.org/advanced/clients/) +- [Resource Limits](https://www.python-httpx.org/advanced/resource-limits/) +- [Proxies](https://www.python-httpx.org/advanced/proxies/) +- [SSL](https://www.python-httpx.org/advanced/ssl/) +- [Event Hooks](https://www.python-httpx.org/advanced/event-hooks/) + +## Using a custom transport + +For low-level customization (for example test transports and custom routing), +pass `transport=...`: + +```python +import httpx +from pdfrest import PdfRestClient + +transport = httpx.HTTPTransport(retries=0) + +with PdfRestClient(transport=transport) as client: + response = client.up() +``` + +HTTPX reference: + +- [Transports](https://www.python-httpx.org/advanced/transports/) + +## Default and per-request headers + +`headers=` on the client sets default headers for all calls. Endpoint methods +also accept `extra_headers=` to override or add request-specific headers. + +```python +from pdfrest import PdfRestClient + +with PdfRestClient(headers={"X-App-Name": "my-service"}) as client: + info = client.up(extra_headers={"X-Request-ID": "req-123"}) +``` + +## `no-id-prefix` header + +pdfRest supports a `no-id-prefix: true` request header used for +pdfAssistant compatibility. When enabled, generated IDs omit the leading +numeric prefix and return a plain UUIDv4 string. + +### How to enable it + +Set it as a default client header or per-request `extra_headers`: + +```python +from pdfrest import PdfRestClient + +with PdfRestClient(headers={"no-id-prefix": "true"}) as client: + uploaded = client.files.create_from_paths(["./input.pdf"]) +``` + +### Effect on `PdfRestFileID` + +[`PdfRestFileID`](api-reference.md#pdfrest.models.PdfRestFileID) accepts both +forms: + +- prefixed: `1` or `2` (37 chars) +- no prefix: `` (36 chars) + +When `no-id-prefix` is enabled, returned IDs are the 36-character no-prefix +variant. In that case: + +- `file_id.prefix` is `None` +- `file_id.uuid` is still the UUID portion + +This means existing SDK code that uses +[`PdfRestFileID`](api-reference.md#pdfrest.models.PdfRestFileID) remains +compatible with either server ID format. diff --git a/docs/index.md b/docs/index.md index 9befddd3..7226a126 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,6 +16,8 @@ Useful references: - [pdfRest homepage](https://pdfrest.com/) - [API reference](https://pdfrest.com/apidocs/) - [API Lab (interactive testing)](https://pdfrest.com/apilab/) +- [Getting started guide](getting-started.md) +- [Client configuration guide](client-configuration.md) ## How this Python API relates to pdfRest diff --git a/mkdocs.yml b/mkdocs.yml index b55ea0a7..c21ee504 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -37,4 +37,5 @@ markdown_extensions: nav: - Home: index.md - Getting Started: getting-started.md + - Client Configuration: client-configuration.md - API Reference: api-reference.md From 66b9e409d47301e141d8bee9daffc385a2953307 Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Wed, 18 Feb 2026 12:52:38 -0600 Subject: [PATCH 07/18] docs: Add using-files guide and update navigation - Added `using-files.md` to provide a comprehensive guide on file operations in the SDK, covering uploads, downloads, metadata retrieval, and deletions. - Updated `index.md` to include a link to the new `using-files.md` guide. - Modified `mkdocs.yml` to reflect the updated navigation structure. Assisted-by: Codex --- docs/index.md | 1 + docs/using-files.md | 562 ++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 564 insertions(+) create mode 100644 docs/using-files.md diff --git a/docs/index.md b/docs/index.md index 7226a126..cb97b3f5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,6 +18,7 @@ Useful references: - [API Lab (interactive testing)](https://pdfrest.com/apilab/) - [Getting started guide](getting-started.md) - [Client configuration guide](client-configuration.md) +- [Using files guide](using-files.md) ## How this Python API relates to pdfRest diff --git a/docs/using-files.md b/docs/using-files.md new file mode 100644 index 00000000..13afbde9 --- /dev/null +++ b/docs/using-files.md @@ -0,0 +1,562 @@ +# Using files + +This guide covers the file lifecycle in the SDK: creating files on pdfRest, +retrieving file metadata/content, streaming downloads, and deleting files. + +File operations are exposed from +[`PdfRestClient.files`](api-reference.md#pdfrest.PdfRestClient.files) and +[`AsyncPdfRestClient.files`](api-reference.md#pdfrest.AsyncPdfRestClient.files), +which implement +[`PdfRestFilesClient`](api-reference.md#pdfrest.PdfRestFilesClient) and +[`AsyncPdfRestFilesClient`](api-reference.md#pdfrest.AsyncPdfRestFilesClient). + +## Core file types + +- [`PdfRestFile`](api-reference.md#pdfrest.models.PdfRestFile): metadata for a + server-side file (`id`, `name`, `url`, `type`, `size`, and more). +- [`PdfRestFileID`](api-reference.md#pdfrest.models.PdfRestFileID): typed file + identifier accepted by file lookup and endpoint methods. + +All file creation methods return +`list[`[`PdfRestFile`](api-reference.md#pdfrest.models.PdfRestFile)`]`, which is +designed to flow directly into endpoint helpers. + +## Async usage + +Use [`AsyncPdfRestClient`](api-reference.md#pdfrest.AsyncPdfRestClient) when: + +- Your app already uses `asyncio` (FastAPI, async workers, async CLIs). +- You need higher throughput across many concurrent uploads/downloads. +- You want non-blocking network I/O while other tasks run. + +The async files API mirrors sync methods with `await`, and the stream behavior +is documented on +[`AsyncPdfRestFilesClient.stream`](api-reference.md#pdfrest.AsyncPdfRestFilesClient.stream). + +```python +from pdfrest import AsyncPdfRestClient + +async def process_pdf() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_paths(["./input.pdf"]) + result = await client.extract_pdf_text(uploaded, full_text="document") + await client.files.write_bytes(uploaded[0], "./copy-of-input.pdf") +``` + +## Create files on pdfRest + +### 1) Upload in-memory/file-like content with `files.create(...)` + +Use this when you already have open file handles, bytes, or HTTPX-style +multipart tuples. + +=== "Sync" + ```python + from pathlib import Path + from pdfrest import PdfRestClient + + with PdfRestClient() as client, Path("input.pdf").open("rb") as fh: + uploaded = client.files.create([("input.pdf", fh, "application/pdf")]) + ``` + +=== "Async" + ```python + from pathlib import Path + from pdfrest import AsyncPdfRestClient + + async def upload() -> None: + async with AsyncPdfRestClient() as client, Path("input.pdf").open("rb") as fh: + uploaded = await client.files.create([("input.pdf", fh, "application/pdf")]) + ``` + +HTTPX references: + +- [Sending Multipart File Uploads](https://www.python-httpx.org/quickstart/#sending-multipart-file-uploads) +- [API: `files=` parameter shapes](https://www.python-httpx.org/api/) + +### 2) Upload from local paths with `files.create_from_paths(...)` + +Best default for local files. Each entry can be: + +- `path` +- `(path, content_type)` +- `(path, content_type, headers)` + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + with PdfRestClient() as client: + uploaded = client.files.create_from_paths( + [ + "./input.pdf", + ("./profile.json", "application/json"), + ] + ) + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + async def upload_from_paths() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_paths( + [ + "./input.pdf", + ("./profile.json", "application/json"), + ] + ) + ``` + +### 3) Upload from remote URLs with `files.create_from_urls(...)` + +Use this when pdfRest should fetch files from `http`/`https` URLs. + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + with PdfRestClient() as client: + uploaded = client.files.create_from_urls( + ["https://example.com/document.pdf"] + ) + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + async def upload_from_urls() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_urls( + ["https://example.com/document.pdf"] + ) + ``` + +## Retrieve files from pdfRest + +### If you already have a file ID + +Yes. If you already have an ID (for example from direct pdfRest API usage), the +SDK way to get a [`PdfRestFile`](api-reference.md#pdfrest.models.PdfRestFile) +is to call `files.get(id)`. + +Use `files.get(id)` when: + +- You need the full metadata object (`name`, `url`, `type`, `size`, etc.). +- You want a typed [`PdfRestFile`](api-reference.md#pdfrest.models.PdfRestFile) + to pass into endpoint helpers. + +You can also pass a file ID string directly to file-content helpers such as +`read_bytes`, `read_text`, `read_json`, `write_bytes`, and `stream` when you do +not need metadata first. + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + existing_id = "1de305d2-b6a0-4b5d-9a55-4e4e6d8c2d39" + + with PdfRestClient() as client: + # Hydrate metadata into PdfRestFile + file_meta = client.files.get(existing_id) + + # Or use the ID directly for content retrieval + raw = client.files.read_bytes(existing_id) + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + existing_id = "1de305d2-b6a0-4b5d-9a55-4e4e6d8c2d39" + + async def work_with_existing_id() -> None: + async with AsyncPdfRestClient() as client: + # Hydrate metadata into PdfRestFile + file_meta = await client.files.get(existing_id) + + # Or use the ID directly for content retrieval + raw = await client.files.read_bytes(existing_id) + ``` + +### Get metadata by ID with `files.get(...)` + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + with PdfRestClient() as client: + file_meta = client.files.get("1de305d2-b6a0-4b5d-9a55-4e4e6d8c2d39") + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + async def fetch_metadata() -> None: + async with AsyncPdfRestClient() as client: + file_meta = await client.files.get("1de305d2-b6a0-4b5d-9a55-4e4e6d8c2d39") + ``` + +### Choose a content retrieval method + +`file_ref` can be either a [`PdfRestFile`](api-reference.md#pdfrest.models.PdfRestFile) +or a file ID string for all methods below. + +- `files.read_bytes(file_ref)`: + best when you need raw binary in memory (hashing, passing to other APIs, + custom parsers). +- `files.read_text(file_ref, encoding=...)`: + best when the file is textual and you want decoded `str` content. +- `files.read_json(file_ref)`: + best when the file contains JSON and you want parsed Python objects. +- `files.write_bytes(file_ref, destination)`: + best when you want a local file saved to disk without handling chunks. +- `files.stream(file_ref)`: + best for large files or progressive processing to avoid loading the whole + file into memory. + +### `files.read_bytes(...)` + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + with PdfRestClient() as client: + uploaded = client.files.create_from_paths(["./input.pdf"]) + raw = client.files.read_bytes(uploaded[0]) + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + async def read_as_bytes() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_paths(["./input.pdf"]) + raw = await client.files.read_bytes(uploaded[0]) + ``` + +### `files.read_text(...)` + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + with PdfRestClient() as client: + uploaded = client.files.create_from_paths(["./notes.txt"]) + text = client.files.read_text(uploaded[0], encoding="utf-8") + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + async def read_as_text() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_paths(["./notes.txt"]) + text = await client.files.read_text(uploaded[0], encoding="utf-8") + ``` + +### `files.read_json(...)` + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + with PdfRestClient() as client: + uploaded = client.files.create_from_paths(["./metadata.json"]) + payload = client.files.read_json(uploaded[0]) + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + async def read_as_json() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_paths(["./metadata.json"]) + payload = await client.files.read_json(uploaded[0]) + ``` + +### `files.write_bytes(...)` + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + with PdfRestClient() as client: + uploaded = client.files.create_from_paths(["./input.pdf"]) + saved_path = client.files.write_bytes(uploaded[0], "./downloaded.pdf") + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + async def write_to_disk() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_paths(["./input.pdf"]) + saved_path = await client.files.write_bytes(uploaded[0], "./downloaded.pdf") + ``` + +### `files.stream(...)` + +Use this when files are large or you need chunk/line-level processing. + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + with PdfRestClient() as client: + uploaded = client.files.create_from_paths(["./input.pdf"]) + with client.files.stream(uploaded[0]) as stream: + for chunk in stream.iter_bytes(): + # process chunk + pass + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + async def stream_download() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_paths(["./input.pdf"]) + async with await client.files.stream(uploaded[0]) as stream: + async for chunk in stream.iter_bytes(): + # process chunk + pass + ``` + +Both stream wrappers also expose text/line/raw iterators: + +- sync: `iter_text`, `iter_lines`, `iter_raw` +- async: `iter_text`, `iter_lines`, `iter_raw` + +### Choosing a stream iterator + +- `iter_bytes(...)`: default choice for binary data when you want chunked, + decoded-bytes reads. +- `iter_text(...)`: use when the response is textual and you want decoded string + chunks instead of bytes. +- `iter_lines()`: use for line-oriented formats (logs, NDJSON, CSV-like text) + where processing per line is easiest. +- `iter_raw(...)`: use for the lowest-level byte access without higher-level + decoding conveniences. + +#### `iter_bytes(...)` example + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + with PdfRestClient() as client: + uploaded = client.files.create_from_paths(["./input.pdf"]) + with client.files.stream(uploaded[0]) as stream: + for chunk in stream.iter_bytes(chunk_size=65536): + # process binary chunk + pass + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + async def stream_bytes() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_paths(["./input.pdf"]) + async with await client.files.stream(uploaded[0]) as stream: + async for chunk in stream.iter_bytes(chunk_size=65536): + # process binary chunk + pass + ``` + +#### `iter_text(...)` example + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + with PdfRestClient() as client: + uploaded = client.files.create_from_paths(["./notes.txt"]) + with client.files.stream(uploaded[0]) as stream: + for text_chunk in stream.iter_text(): + # process decoded text chunk + pass + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + async def stream_text() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_paths(["./notes.txt"]) + async with await client.files.stream(uploaded[0]) as stream: + async for text_chunk in stream.iter_text(): + # process decoded text chunk + pass + ``` + +#### `iter_lines()` example + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + with PdfRestClient() as client: + uploaded = client.files.create_from_paths(["./events.ndjson"]) + with client.files.stream(uploaded[0]) as stream: + for line in stream.iter_lines(): + # process one logical line at a time + pass + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + async def stream_lines() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_paths(["./events.ndjson"]) + async with await client.files.stream(uploaded[0]) as stream: + async for line in stream.iter_lines(): + # process one logical line at a time + pass + ``` + +#### `iter_raw(...)` example + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + with PdfRestClient() as client: + uploaded = client.files.create_from_paths(["./input.pdf"]) + with client.files.stream(uploaded[0]) as stream: + for raw_chunk in stream.iter_raw(chunk_size=65536): + # lowest-level raw chunks + pass + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + async def stream_raw() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_paths(["./input.pdf"]) + async with await client.files.stream(uploaded[0]) as stream: + async for raw_chunk in stream.iter_raw(chunk_size=65536): + # lowest-level raw chunks + pass + ``` + +HTTPX reference: + +- [Streaming Responses](https://www.python-httpx.org/quickstart/#streaming-responses) + +## Chaining: upload output directly into endpoint calls + +The SDK consistently models file inputs as one-or-many, so the list returned by +upload calls can be passed directly into many endpoint helpers. + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + with PdfRestClient() as client: + uploaded = client.files.create_from_paths(["./input.pdf"]) + + # Direct chain: list[PdfRestFile] -> endpoint + images = client.convert_to_png(uploaded, resolution=144) + + # Single-file endpoints also accept one-or-many file inputs in this SDK. + text = client.extract_pdf_text(uploaded, full_text="document") + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + async def chain_calls() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_paths(["./input.pdf"]) + + images = await client.convert_to_png(uploaded, resolution=144) + text = await client.extract_pdf_text(uploaded, full_text="document") + ``` + +This avoids manual ID extraction and keeps call sites typed as +[`PdfRestFile`](api-reference.md#pdfrest.models.PdfRestFile) objects. + +## Delete files + +Delete uploaded files when you no longer need them: + +=== "Sync" + ```python + from pdfrest import PdfRestClient + + with PdfRestClient() as client: + uploaded = client.files.create_from_paths(["./input.pdf"]) + client.files.delete(uploaded) + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient + + async def delete_files() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_paths(["./input.pdf"]) + await client.files.delete(uploaded) + ``` + +`delete(...)` accepts one file or a sequence of files. + +### Handling delete failures (`PdfRestErrorGroup`) + +When one or more file deletions fail, `delete(...)` raises +[`PdfRestErrorGroup`](api-reference.md#pdfrest.PdfRestErrorGroup). The group +contains one +[`PdfRestDeleteError`](api-reference.md#pdfrest.PdfRestDeleteError) per file +that failed, so you can report each file-level failure precisely. + +=== "Sync" + ```python + from pdfrest import PdfRestClient, PdfRestDeleteError, PdfRestErrorGroup + + with PdfRestClient() as client: + uploaded = client.files.create_from_paths(["./input.pdf", "./second.pdf"]) + try: + client.files.delete(uploaded) + except PdfRestErrorGroup as exc: + for err in exc.exceptions: + if isinstance(err, PdfRestDeleteError): + print(f"Delete failed for file_id={err.file_id}: {err.detail}") + else: + print(f"Unexpected delete error: {err}") + raise + ``` + +=== "Async" + ```python + from pdfrest import AsyncPdfRestClient, PdfRestDeleteError, PdfRestErrorGroup + + async def delete_with_error_handling() -> None: + async with AsyncPdfRestClient() as client: + uploaded = await client.files.create_from_paths(["./input.pdf", "./second.pdf"]) + try: + await client.files.delete(uploaded) + except PdfRestErrorGroup as exc: + for err in exc.exceptions: + if isinstance(err, PdfRestDeleteError): + print(f"Delete failed for file_id={err.file_id}: {err.detail}") + else: + print(f"Unexpected delete error: {err}") + raise + ``` diff --git a/mkdocs.yml b/mkdocs.yml index c21ee504..60c6a356 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -38,4 +38,5 @@ nav: - Home: index.md - Getting Started: getting-started.md - Client Configuration: client-configuration.md + - Using Files: using-files.md - API Reference: api-reference.md From c24fc2b0ab368369f744ad38f7340e4d44d84bcf Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Thu, 19 Feb 2026 11:20:02 -0600 Subject: [PATCH 08/18] types: Add PdfSignaturePoint and enhance API docstrings - Introduced `PdfSignaturePoint` to the public API for handling signature placement coordinates in PDF documents. - Enhanced docstrings for `PdfSignatureLocation`, `PdfSignatureDisplay`, `PdfNewSignatureConfiguration`, and related types with detailed attribute descriptions for improved clarity. - Updated `mkdocs.yml` to include the `autorefs` plugin for better cross-referencing in documentation. Assisted-by: Codex --- mkdocs.yml | 1 + src/pdfrest/types/__init__.py | 2 + src/pdfrest/types/public.py | 81 +++++++++++++++++++++++++++++++++-- 3 files changed, 81 insertions(+), 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 60c6a356..dadfb9da 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,6 +12,7 @@ theme: plugins: - search + - autorefs - mkdocstrings: handlers: python: diff --git a/src/pdfrest/types/__init__.py b/src/pdfrest/types/__init__.py index 389e3346..f662b0b4 100644 --- a/src/pdfrest/types/__init__.py +++ b/src/pdfrest/types/__init__.py @@ -40,6 +40,7 @@ PdfSignatureCredentials, PdfSignatureDisplay, PdfSignatureLocation, + PdfSignaturePoint, PdfTextColor, PdfXType, PngColorModel, @@ -92,6 +93,7 @@ "PdfSignatureCredentials", "PdfSignatureDisplay", "PdfSignatureLocation", + "PdfSignaturePoint", "PdfTextColor", "PdfXType", "PngColorModel", diff --git a/src/pdfrest/types/public.py b/src/pdfrest/types/public.py index 462a701b..36c6b0e1 100644 --- a/src/pdfrest/types/public.py +++ b/src/pdfrest/types/public.py @@ -52,6 +52,7 @@ "PdfSignatureCredentials", "PdfSignatureDisplay", "PdfSignatureLocation", + "PdfSignaturePoint", "PdfTextColor", "PdfXType", "PngColorModel", @@ -64,8 +65,9 @@ "WatermarkVerticalAlignment", ) -#: Supported query keys for :meth:`pdfrest.PdfRestClient.query_pdf_info` and -#: :meth:`pdfrest.AsyncPdfRestClient.query_pdf_info`. +#: Supported query keys for +#: [PdfRestClient.query_pdf_info][pdfrest.PdfRestClient.query_pdf_info] and +#: [AsyncPdfRestClient.query_pdf_info][pdfrest.AsyncPdfRestClient.query_pdf_info]. PdfInfoQuery = Literal[ "tagged", "image_only", @@ -104,7 +106,7 @@ tuple[PdfInfoQuery, ...], get_args(PdfInfoQuery) ) -#: Redaction match mode used by :class:`PdfRedactionInstruction`. +#: Redaction match mode used by [PdfRedactionInstruction][]. PdfRedactionType = Literal["literal", "regex", "preset"] #: Built-in redaction presets accepted by pdfRest. @@ -169,6 +171,13 @@ class PdfAddTextObject(TypedDict, total=False): class PdfCustomPageSize(TypedDict): + """Custom page dimensions for page-size aware conversions. + + Attributes: + custom_height: Page height in points. + custom_width: Page width in points. + """ + custom_height: Required[float] custom_width: Required[float] @@ -196,17 +205,43 @@ class PdfMergeSource(TypedDict, total=False): class PdfSignaturePoint(TypedDict): + """Coordinate point used for signature placement in PDF points. + + Attributes: + x: Horizontal position in points. + y: Vertical position in points. + """ + x: float y: float class PdfSignatureLocation(TypedDict): + """Bounding box and page where a signature field should be rendered. + + Attributes: + bottom_left: Bottom-left [PdfSignaturePoint][pdfrest.types.PdfSignaturePoint] of the signature rectangle. + top_right: Top-right [PdfSignaturePoint][pdfrest.types.PdfSignaturePoint] of the signature rectangle. + page: One-based page index or ``"all"``. + """ + bottom_left: Required[PdfSignaturePoint] top_right: Required[PdfSignaturePoint] page: Required[str | int] class PdfSignatureDisplay(TypedDict, total=False): + """Optional text fields included in visible signature appearances. + + Attributes: + include_distinguished_name: Whether to include signer DN text. + include_datetime: Whether to include signing date/time text. + contact: Contact text shown in the visible signature. + location: Location text shown in the visible signature. + name: Signer name text shown in the visible signature. + reason: Signing reason text shown in the visible signature. + """ + include_distinguished_name: bool include_datetime: bool contact: str @@ -216,6 +251,16 @@ class PdfSignatureDisplay(TypedDict, total=False): class PdfNewSignatureConfiguration(TypedDict, total=False): + """Configuration for creating and signing a new signature field. + + Attributes: + type: Must be ``"new"``. + location: Placement rectangle and page as [PdfSignatureLocation][pdfrest.types.PdfSignatureLocation]. + name: Optional name for the signature field. + logo_opacity: Optional logo opacity in the range ``(0, 1]``. + display: Optional visible-signature settings as [PdfSignatureDisplay][pdfrest.types.PdfSignatureDisplay]. + """ + type: Required[Literal["new"]] location: Required[PdfSignatureLocation] name: str @@ -224,6 +269,16 @@ class PdfNewSignatureConfiguration(TypedDict, total=False): class PdfExistingSignatureConfiguration(TypedDict, total=False): + """Configuration for signing an existing signature field. + + Attributes: + type: Must be ``"existing"``. + location: Optional placement override as [PdfSignatureLocation][pdfrest.types.PdfSignatureLocation]. + name: Optional existing signature field name. + logo_opacity: Optional logo opacity in the range ``(0, 1]``. + display: Optional visible-signature settings as [PdfSignatureDisplay][pdfrest.types.PdfSignatureDisplay]. + """ + type: Required[Literal["existing"]] location: PdfSignatureLocation name: str @@ -231,21 +286,41 @@ class PdfExistingSignatureConfiguration(TypedDict, total=False): display: PdfSignatureDisplay +#: Signature placement configuration accepted by +#: [PdfRestClient.sign_pdf][pdfrest.PdfRestClient.sign_pdf] and +#: [AsyncPdfRestClient.sign_pdf][pdfrest.AsyncPdfRestClient.sign_pdf]. PdfSignatureConfiguration = ( PdfNewSignatureConfiguration | PdfExistingSignatureConfiguration ) class PdfPfxCredentials(TypedDict): + """Credentials bundle using a PFX/P12 file plus passphrase file. + + Attributes: + pfx: Uploaded credentials archive as a [PdfRestFile][pdfrest.models.PdfRestFile]. + passphrase: Uploaded text passphrase as a [PdfRestFile][pdfrest.models.PdfRestFile]. + """ + pfx: Required[PdfRestFile] passphrase: Required[PdfRestFile] class PdfPemCredentials(TypedDict): + """Credentials bundle using certificate and private key uploads. + + Attributes: + certificate: Uploaded certificate as a [PdfRestFile][pdfrest.models.PdfRestFile]. + private_key: Uploaded private key as a [PdfRestFile][pdfrest.models.PdfRestFile]. + """ + certificate: Required[PdfRestFile] private_key: Required[PdfRestFile] +#: Credentials accepted by +#: [PdfRestClient.sign_pdf][pdfrest.PdfRestClient.sign_pdf] and +#: [AsyncPdfRestClient.sign_pdf][pdfrest.AsyncPdfRestClient.sign_pdf]. PdfSignatureCredentials = PdfPfxCredentials | PdfPemCredentials #: PDF/A conformance targets accepted by ``convert_to_pdfa``. From 153835ee554e626144a5a7f6f99cf6b10cffa2c1 Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Thu, 19 Feb 2026 11:42:47 -0600 Subject: [PATCH 09/18] client: Add detailed docstrings to PdfRestClient public methods - Enhanced docstrings for all methods in `PdfRestClient` with Google-style formatting, detailing parameters, return types, and exceptions for improved clarity and usability. - Included comprehensive descriptions for method functionality to assist developers in understanding each operation and its use cases. - Improved documentation of common arguments like `file`, `timeout`, and `extra_*` fields for consistency across methods. Assisted-by: Codex --- src/pdfrest/client.py | 2517 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 2381 insertions(+), 136 deletions(-) diff --git a/src/pdfrest/client.py b/src/pdfrest/client.py index c4af6022..0c474690 100644 --- a/src/pdfrest/client.py +++ b/src/pdfrest/client.py @@ -2548,7 +2548,16 @@ def __init__( transport: httpx.BaseTransport | None = None, max_retries: int = DEFAULT_MAX_RETRIES, ) -> None: - """Create a synchronous pdfRest client.""" + """Initialize a synchronous pdfRest client. + + Args: + api_key: API key sent in the `Api-Key` header. + base_url: Base URL for the pdfRest API service. + timeout: Request timeout override for this call. + headers: Default headers merged into every request. + http_client: Optional preconfigured `httpx.Client` instance to reuse. + transport: Optional custom `httpx` transport. + max_retries: Maximum number of retries for retryable failures.""" super().__init__( api_key=api_key, @@ -2564,20 +2573,29 @@ def __init__( @override def __enter__(self) -> PdfRestClient: + """Enter the client context manager and return this client instance. + + Returns: + The current client instance.""" _ = super().__enter__() return self @override def __exit__(self, exc_type: Any, exc: Any, traceback: Any) -> None: + """Exit the client context manager and close underlying HTTP resources. + + Args: + exc_type: Exception type raised in the managed context, if any. + exc: Exception instance raised in the managed context, if any. + traceback: Traceback object for exceptions raised in the managed context.""" super().__exit__(exc_type, exc, traceback) @property def files(self) -> PdfRestFilesClient: - """File-management helper implementing - [`PdfRestFilesClient`][pdfrest.PdfRestFilesClient]. + """Return the [PdfRestFilesClient][pdfrest.PdfRestFilesClient] helper bound to this client. - Retrieve this helper from `client.files`; do not instantiate it directly. - """ + Returns: + The file-management helper bound to this client.""" return self._files_client @@ -2589,7 +2607,22 @@ def up( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> UpResponse: - """Call the `/up` health endpoint and return server metadata.""" + """Call the `/up` health endpoint and return server metadata. + + Calls the health endpoint and returns service metadata such as status, product, version, and release date. Use this as a lightweight connectivity check before running document workflows. + + Args: + extra_headers: Additional HTTP headers merged into the request. + extra_query: Additional query parameters merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated `UpResponse` model. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" request = self._prepare_request( "GET", @@ -2613,6 +2646,19 @@ def _convert_to_graphic( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: + """Shared helper used by image conversion endpoint methods. + + Args: + endpoint: API endpoint path used for this request helper. + payload: Raw payload values forwarded to payload validation. + payload_model: Payload model class used to validate and serialize inputs. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest.""" return self._post_file_operation( endpoint=endpoint, payload=payload, @@ -2633,7 +2679,24 @@ def query_pdf_info( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestInfoResponse: - """Query pdfRest for metadata describing a PDF document.""" + """Query pdfRest for metadata describing a PDF document. + + Retrieves PDF metadata and structural flags (for example page count, tags, signatures, forms, transparency, and permission state). The `queries` argument controls which info keys pdfRest computes and returns. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + queries: Info fields to query from the `/pdf-info` endpoint. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated `PdfRestInfoResponse` model. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload = PdfInfoPayload.model_validate({"file": file, "queries": queries}) request = self.prepare_request( @@ -2666,9 +2729,26 @@ def summarize_text( ) -> SummarizePdfTextResponse: """Summarize the textual content of a PDF, Markdown, or text document. - Always requests JSON output and returns the inline summary response defined in - the pdfRest API reference. - """ + Generates an inline summary from document text and returns it in a structured response model. You can scope to pages, choose summary style, and control output formatting for downstream display. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + target_word_count: Approximate target length for generated summary text. + summary_format: Summary layout/style requested from pdfRest. + pages: Page selection to constrain processing to specific pages. + output_format: Text format returned for generated textual output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated `SummarizePdfTextResponse` model. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -2711,7 +2791,28 @@ def summarize_text_to_file( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Summarize a document and return the result as a downloadable file.""" + """Summarize a document and return the result as a downloadable file. + + Generates a summary and returns a file-based response containing the produced summary document. Use this when you want downloadable artifacts instead of inline summary text. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + target_word_count: Approximate target length for generated summary text. + summary_format: Summary layout/style requested from pdfRest. + pages: Page selection to constrain processing to specific pages. + output_format: Text format returned for generated textual output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -2747,7 +2848,26 @@ def convert_to_markdown( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert a PDF to Markdown and return a file-based response.""" + """Convert a PDF to Markdown and return a file-based response. + + Converts document content into Markdown and supports either inline text output or file output. This is useful when preparing PDFs for LLM/RAG indexing and markdown-centric tooling. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + pages: Page selection to constrain processing to specific pages. + page_break_comments: When true, inserts page-break marker comments in generated Markdown between source pages. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -2781,7 +2901,26 @@ def ocr_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Perform OCR on a PDF to make text searchable and extractable.""" + """Perform OCR on a PDF to make text searchable and extractable. + + Runs OCR on image-based PDFs to produce searchable text layers while preserving PDF layout. Use `language` to guide recognition and `output` to control output naming. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + languages: OCR language(s) to use when recognizing text in scanned or image-based pages. + pages: Page selection to constrain processing to specific pages. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "languages": languages} if pages is not None: @@ -2812,7 +2951,27 @@ def translate_pdf_text( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> TranslatePdfTextResponse: - """Translate the textual content of a PDF, Markdown, or text document (JSON).""" + """Translate the textual content of a PDF, Markdown, or text document (JSON). + + Translates extracted document text and returns translated content inline when `output_type` is JSON. Supports page scoping and output formatting for multilingual text workflows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output_language: Target language for translated output text. + pages: Page selection to constrain processing to specific pages. + output_format: Text format returned for generated textual output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated `TranslatePdfTextResponse` model. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -2853,7 +3012,27 @@ def translate_pdf_text_to_file( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> TranslatePdfTextFileResponse: - """Translate textual content and receive a file-based response.""" + """Translate textual content and receive a file-based response. + + Translates document text and returns a file-based response with translated output artifacts. Choose this when you need downloadable translated files instead of inline text. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output_language: Target language for translated output text. + pages: Page selection to constrain processing to specific pages. + output_format: Text format returned for generated textual output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated `TranslatePdfTextFileResponse` model. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -2888,7 +3067,25 @@ def extract_images( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Extract embedded images from a PDF.""" + """Extract embedded images from a PDF. + + Extracts embedded images from the source PDF and returns them as output files. This is useful for asset reuse, auditing image quality, or downstream image processing. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + pages: Page selection to constrain processing to specific pages. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if pages is not None: @@ -2920,7 +3117,28 @@ def extract_pdf_text( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> ExtractedTextDocument: - """Extract text content from a PDF and return parsed JSON results.""" + """Extract text content from a PDF and return parsed JSON results. + + Extracts text from a PDF as inline JSON text content. Use `pages` to limit scope and `granularity`/related options to control how text is aggregated. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + pages: Page selection to constrain processing to specific pages. + full_text: Controls full-text output mode: disabled, aggregated document text, or per-page text blocks. + preserve_line_breaks: Preserves detected line breaks in full-text output instead of flattening lines. + word_style: Includes per-word style metadata such as font, size, and color in structured output. + word_coordinates: Includes per-word coordinate metadata for positional text extraction. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated `ExtractedTextDocument` model. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -2963,7 +3181,29 @@ def extract_pdf_text_to_file( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Extract text content from a PDF and return a file-based response.""" + """Extract text content from a PDF and return a file-based response. + + Extracts text into file outputs (including richer structured formats when requested). Use this for large outputs or when you need durable extracted-text artifacts. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + pages: Page selection to constrain processing to specific pages. + full_text: Controls full-text output mode: disabled, aggregated document text, or per-page text blocks. + preserve_line_breaks: Preserves detected line breaks in full-text output instead of flattening lines. + word_style: Includes per-word style metadata such as font, size, and color in structured output. + word_coordinates: Includes per-word coordinate metadata for positional text extraction. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -2999,7 +3239,25 @@ def preview_redactions( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Generate a PDF redaction preview with annotated redaction rectangles.""" + """Generate a PDF redaction preview with annotated redaction rectangles. + + Builds a redaction preview PDF so you can inspect matches before permanently removing content. Redaction rules support literals, regex patterns, and preset detectors. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + redactions: Redaction rules to preview or apply. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3029,7 +3287,25 @@ def apply_redactions( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Apply previously previewed redactions and return the final redacted PDF.""" + """Apply previously previewed redactions and return the final redacted PDF. + + Applies irreversible redactions to the PDF based on provided rules and outputs a redacted document. Use this after validating coverage with `preview_redactions`. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + rgb_color: RGB fill color applied to redaction rectangles when previewing/applying redactions. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3060,7 +3336,25 @@ def add_text_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Insert one or more text blocks into a PDF.""" + """Insert one or more text blocks into a PDF. + + Places one or more text overlays onto a PDF with font, size, color, opacity, position, and rotation controls. This supports annotations, stamps, and templated labeling workflows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + text_objects: Text overlay objects to draw onto the document. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3093,7 +3387,28 @@ def add_image_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Insert an image into a single page of a PDF.""" + """Insert an image into a single page of a PDF. + + Places an uploaded image onto target pages in a PDF with size/position controls. This is commonly used for logos, seals, and branding overlays. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + image: Image/PDF resource to place into the source document. + x: Horizontal position in PDF points. + y: Vertical position in PDF points. + page: Target page number (or selector) where inserted content should be applied. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3126,7 +3441,25 @@ def split_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Split a PDF into one or more PDF files based on the provided page groups.""" + """Split a PDF into one or more PDF files based on the provided page groups. + + Splits a PDF into multiple outputs using page selections and grouping rules. Use this to break long documents into per-range or per-section files. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + page_groups: Page-selection groups that define each split output document. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if page_groups is not None: @@ -3154,7 +3487,24 @@ def merge_pdfs( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Merge multiple PDFs (or page subsets) into a single PDF file.""" + """Merge multiple PDFs (or page subsets) into a single PDF file. + + Merges multiple uploaded PDFs into a single output, with optional per-input page selections. This is useful for packet assembly and document bundling. + + Args: + sources: Merge source list containing files with optional page selections per source. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"sources": sources} if output_prefix is not None: @@ -3180,7 +3530,24 @@ def zip_files( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Compress one or more files into a zip archive.""" + """Compress one or more files into a zip archive. + + Packages uploaded files into a ZIP archive and returns it as a file-based response. Use this to consolidate multiple outputs for a single download. + + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": files} if output is not None: @@ -3206,7 +3573,24 @@ def unzip_file( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Extract files from a zip archive.""" + """Extract files from a zip archive. + + Expands an uploaded ZIP archive into individual files on pdfRest storage and returns metadata for the extracted resources. This is useful when reusing uploaded bundles in later API calls. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + password: Password value used by encrypt/decrypt endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if password is not None: @@ -3232,7 +3616,24 @@ def convert_to_excel( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert a PDF to an Excel spreadsheet.""" + """Convert a PDF to an Excel spreadsheet. + + Converts PDF content into Excel workbook output optimized for tabular data extraction. Use this for spreadsheet-centric review or data cleanup workflows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -3258,7 +3659,24 @@ def convert_to_powerpoint( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert a PDF to a PowerPoint presentation.""" + """Convert a PDF to a PowerPoint presentation. + + Converts PDF pages into PowerPoint output suitable for slide editing and presentation reuse. This helps repurpose static PDF material into editable decks. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -3284,7 +3702,24 @@ def convert_xfa_to_acroforms( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert an XFA PDF to an AcroForm-enabled PDF.""" + """Convert an XFA PDF to an AcroForm-enabled PDF. + + Converts XFA form PDFs into AcroForm-compatible PDFs for broader tooling compatibility. Use this before importing/exporting form data with AcroForm-focused flows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -3310,7 +3745,24 @@ def convert_to_word( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert a PDF to a Word document.""" + """Convert a PDF to a Word document. + + Converts PDF content into Word output for document editing workflows. This is useful when users need editable text and layout reconstruction in DOCX format. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -3337,7 +3789,25 @@ def import_form_data( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Import form data from a data file into an existing PDF with form fields.""" + """Import form data from a data file into an existing PDF with form fields. + + Imports external form-data files (XFDF/FDF/XML variants) into a source PDF and outputs a filled document. This supports bulk form-filling and integration pipelines. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + data_file: Uploaded form-data file (for example XFDF/FDF/XML/XDP/XFD) to import into the PDF. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "data_file": data_file} if output is not None: @@ -3366,10 +3836,23 @@ def export_form_data( ) -> PdfRestFileBasedResponse: """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` - """ + Exports form field data from a PDF into a structured data format (such as XFDF/FDF/XML). Use this for downstream processing, storage, or migration of form values. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + data_format: Output form-data format to export (for example XFDF, FDF, XML, XDP, or XFD). + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3398,7 +3881,24 @@ def flatten_pdf_forms( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Flatten form fields in a PDF so they are no longer editable.""" + """Flatten form fields in a PDF so they are no longer editable. + + Flattens interactive form fields into static page content so values are no longer editable. This is commonly used for finalization and archival workflows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -3427,7 +3927,27 @@ def add_permissions_password( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Add a permissions password and optional restrictions to a PDF.""" + """Add a permissions password and optional restrictions to a PDF. + + Applies owner permissions and restriction flags (print/copy/edit controls) to a PDF. This secures document capabilities without requiring an open password. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + new_permissions_password: New owner/permissions password to apply to the output PDF. + restrictions: Permission restriction literals for protected PDFs. + current_open_password: Current user/open password required to unlock the source PDF before changes. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3464,7 +3984,28 @@ def change_permissions_password( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Rotate the permissions password and optionally update restrictions.""" + """Rotate the permissions password and optionally update restrictions. + + Updates owner permissions/password settings and restriction flags on an already protected PDF. Use this to rotate credentials or revise allowed actions. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + new_permissions_password: New owner/permissions password to apply to the output PDF. + restrictions: Permission restriction literals for protected PDFs. + current_open_password: Current user/open password required to unlock the source PDF before changes. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3500,7 +4041,26 @@ def add_open_password( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Encrypt a PDF with a new open password.""" + """Encrypt a PDF with a new open password. + + Applies a user/open password so the PDF requires authentication before viewing. Optional permissions controls can also be set for opened documents. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + new_open_password: New user/open password required to open the output PDF. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3534,7 +4094,27 @@ def change_open_password( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Rotate the open password for an encrypted PDF.""" + """Rotate the open password for an encrypted PDF. + + Replaces the existing open password with a new one while preserving or updating related protection options. Use this for credential rotation. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + current_open_password: Current user/open password required to unlock the source PDF before changes. + new_open_password: New user/open password required to open the output PDF. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3568,7 +4148,26 @@ def remove_open_password( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Decrypt a PDF by removing its open password.""" + """Decrypt a PDF by removing its open password. + + Removes the user/open password requirement from a PDF when the current password is provided. The output document can be opened without viewer authentication. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + current_open_password: Current user/open password required to unlock the source PDF before changes. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3601,7 +4200,26 @@ def remove_permissions_password( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Remove permissions restrictions from a PDF.""" + """Remove permissions restrictions from a PDF. + + Removes owner permission restrictions from a PDF when authorized with the existing owner password. This restores unrestricted editing/printing capabilities. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + current_open_password: Current user/open password required to unlock the source PDF before changes. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3634,7 +4252,26 @@ def compress_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Compress a PDF using preset or custom compression profiles.""" + """Compress a PDF using preset or custom compression profiles. + + Reduces PDF file size using preset or custom compression settings, with optional profile uploads. Use this for storage/bandwidth optimization while balancing quality. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + compression_level: Compression level or strategy option. + profile: Uploaded color/compression profile as a `PdfRestFile`. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3666,7 +4303,25 @@ def add_attachment_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Attach an uploaded file to a PDF.""" + """Attach an uploaded file to a PDF. + + Embeds an uploaded file as an attachment inside a PDF container document. This supports package-style delivery where supplemental files travel with the PDF. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + attachment: Uploaded file to embed as an attachment in the output PDF. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "attachment": attachment} if output is not None: @@ -3695,7 +4350,27 @@ def sign_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Digitally sign a PDF using PFX credentials or a certificate/private key.""" + """Digitally sign a PDF using PFX credentials or a certificate/private key. + + Applies digital signatures using either PFX credentials or certificate/private-key inputs, with configurable visible signature placement and appearance. Use this for integrity, authenticity, and non-repudiation workflows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + signature_configuration: Signature placement and appearance settings. + credentials: Digital signing credential bundle (PFX or cert/key files). + logo: Optional uploaded logo file displayed in visible digital signature appearances. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3730,7 +4405,26 @@ def blank_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Create a blank PDF with configurable size, count, and orientation.""" + """Create a blank PDF with configurable size, count, and orientation. + + Creates a new blank PDF with configurable page size, orientation, and page count. This is useful as a template baseline for downstream stamping/filling workflows. + + Args: + page_size: Target page size preset or custom size settings used for output page dimensions. + page_count: Number of blank pages to generate in the new PDF. + page_orientation: Page orientation for standard page sizes (portrait or landscape). + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "page_size": page_size, @@ -3763,7 +4457,26 @@ def convert_colors( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert PDF colors using presets or a custom uploaded ICC profile.""" + """Convert PDF colors using presets or a custom uploaded ICC profile. + + Converts document color spaces using preset profiles and optional black-preservation behavior. Use this to normalize output for print pipelines or color-management requirements. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + color_profile: Named color profile used by color conversion. + preserve_black: When true, keeps pure black content from being remapped during color-profile conversion. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3794,7 +4507,25 @@ def flatten_transparencies( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Flatten transparent objects in a PDF.""" + """Flatten transparent objects in a PDF. + + Flattens transparent objects into opaque content using selectable quality levels. This improves compatibility with workflows/devices that do not fully support transparency. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + quality: Quality preset understood by the selected endpoint. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "quality": quality} if output is not None: @@ -3820,7 +4551,24 @@ def linearize_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Linearize a PDF for optimized fast web view.""" + """Linearize a PDF for optimized fast web view. + + Linearizes the PDF for fast web view so first pages render sooner over network delivery. This improves user experience for browser-based document viewing. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -3846,7 +4594,24 @@ def flatten_annotations( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Flatten annotations into the PDF content.""" + """Flatten annotations into the PDF content. + + Burns annotation markup into page content so comments/highlights become static and non-editable. Use this when sharing finalized review copies. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -3872,7 +4637,24 @@ def flatten_layers( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Flatten all layers in a PDF into a single layer.""" + """Flatten all layers in a PDF into a single layer. + + Flattens optional content groups (layers) into a single visible page representation. This avoids layer-dependent rendering differences across viewers. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -3898,7 +4680,24 @@ def rasterize_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Rasterize a PDF into a flattened bitmap-based PDF.""" + """Rasterize a PDF into a flattened bitmap-based PDF. + + Rasterizes PDF pages into image-based page content at a specified resolution. Use this for visual normalization, redaction hardening, or viewer compatibility scenarios. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -3932,7 +4731,32 @@ def convert_office_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert a Microsoft Office file (Word, Excel, PowerPoint) to PDF.""" + """Convert a Microsoft Office file (Word, Excel, PowerPoint) to PDF. + + Converts Office documents into PDF output using conversion options for layout and fidelity. This is the main entry point for Word/Excel/PowerPoint-to-PDF workflows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + compression: Compression mode used during conversion. + downsample: Image downsampling setting for conversion. + tagged_pdf: For Office conversion, toggles generation of tagged PDFs for accessibility workflows. + locale: Locale used by locale-aware conversion options. + page_size: Target page size preset or custom size settings used for output page dimensions. + page_margin: Page margin setting (for example `8mm` or `0.5in`) for HTML/URL rendering outputs. + page_orientation: Page orientation for standard page sizes (portrait or landscape). + web_layout: Rendering viewport profile (`desktop`, `tablet`, or `mobile`) for HTML/URL conversion. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -3970,7 +4794,26 @@ def convert_postscript_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert a PostScript or EPS file to PDF.""" + """Convert a PostScript or EPS file to PDF. + + Converts PostScript content to PDF while preserving page content for modern PDF workflows. Use this when ingesting legacy print-oriented document formats. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + compression: Compression mode used during conversion. + downsample: Image downsampling setting for conversion. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4000,7 +4843,24 @@ def convert_email_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert an RFC822 email file to PDF.""" + """Convert an RFC822 email file to PDF. + + Converts email message files into PDF, including rendered message content and supported metadata/body parts. This supports archiving and compliance workflows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4028,7 +4888,24 @@ def convert_image_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert a supported image file to PDF.""" + """Convert a supported image file to PDF. + + Converts one or more image files into PDF output and can combine them into multipage documents. Use this to normalize scanned/image assets into PDF containers. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4062,7 +4939,30 @@ def convert_html_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert an uploaded HTML file to PDF.""" + """Convert an uploaded HTML file to PDF. + + Renders HTML content into PDF with page-size/orientation/layout and related rendering controls. This supports report generation and web-to-PDF publishing use cases. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + compression: Compression mode used during conversion. + downsample: Image downsampling setting for conversion. + page_size: Target page size preset or custom size settings used for output page dimensions. + page_margin: Page margin setting (for example `8mm` or `0.5in`) for HTML/URL rendering outputs. + page_orientation: Page orientation for standard page sizes (portrait or landscape). + web_layout: Rendering viewport profile (`desktop`, `tablet`, or `mobile`) for HTML/URL conversion. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4102,7 +5002,30 @@ def convert_url_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert HTML content from one URL to PDF.""" + """Convert HTML content from one URL to PDF. + + Fetches remote web content by URL and renders it to PDF using HTML rendering options. Use this for automated webpage capture and archival. + + Args: + url: Remote URL to ingest and convert. + output: Output filename prefix used by pdfRest when creating files. + compression: Compression mode used during conversion. + downsample: Image downsampling setting for conversion. + page_size: Target page size preset or custom size settings used for output page dimensions. + page_margin: Page margin setting (for example `8mm` or `0.5in`) for HTML/URL rendering outputs. + page_orientation: Page orientation for standard page sizes (portrait or landscape). + web_layout: Rendering viewport profile (`desktop`, `tablet`, or `mobile`) for HTML/URL conversion. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "url": url, @@ -4148,7 +5071,36 @@ def watermark_pdf_with_text( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Apply a text watermark to a PDF.""" + """Apply a text watermark to a PDF. + + Applies text watermarks with control over placement, rotation, color, opacity, and alignment. Use this for confidentiality marks, drafts, and document branding. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + watermark_text: Text content to render as the watermark. + output: Output filename prefix used by pdfRest when creating files. + font: Font family name for rendered text. + text_size: Watermark text size in points. + text_color: Watermark text color as RGB or CMYK channel values. + opacity: Opacity in range 0.0 to 1.0. + horizontal_alignment: Horizontal alignment anchor used when placing watermark content. + vertical_alignment: Vertical alignment anchor used when placing watermark content. + x: Horizontal position in PDF points. + y: Vertical position in PDF points. + rotation: Rotation angle in degrees. + pages: Page selection to constrain processing to specific pages. + behind_page: Target page number (or selector) where inserted content should be applied. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4198,7 +5150,34 @@ def watermark_pdf_with_image( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Apply an image watermark to a PDF.""" + """Apply an image watermark to a PDF. + + Applies image watermarks (for example logos/seals) with placement and opacity controls. This is useful for branded overlays and visual ownership marks. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + watermark_file: Uploaded image used as watermark content. + output: Output filename prefix used by pdfRest when creating files. + watermark_file_scale: Scale multiplier applied to the watermark file graphic before placement. + opacity: Opacity in range 0.0 to 1.0. + horizontal_alignment: Horizontal alignment anchor used when placing watermark content. + vertical_alignment: Vertical alignment anchor used when placing watermark content. + x: Horizontal position in PDF points. + y: Vertical position in PDF points. + rotation: Rotation angle in degrees. + pages: Page selection to constrain processing to specific pages. + behind_page: Target page number (or selector) where inserted content should be applied. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4238,7 +5217,26 @@ def convert_to_pdfa( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert a PDF to a specified PDF/A version.""" + """Convert a PDF to a specified PDF/A version. + + Converts input PDFs to selected PDF/A conformance levels for long-term archival compatibility. Choose the target conformance profile that matches your compliance requirements. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output_type: Output mode for endpoints supporting inline or file output. + output: Output filename prefix used by pdfRest when creating files. + rasterize_if_errors_encountered: When enabled, allows rasterized fallback if strict conformance conversion encounters nonconforming content. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4268,7 +5266,25 @@ def convert_to_pdfx( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert a PDF to a specified PDF/X version.""" + """Convert a PDF to a specified PDF/X version. + + Converts input PDFs to selected PDF/X conformance levels for print-production workflows. Use this when downstream print tooling expects standardized PDF/X output. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output_type: Output mode for endpoints supporting inline or file output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "output_type": output_type} if output is not None: @@ -4298,7 +5314,28 @@ def convert_to_png( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert one or more pdfRest files to PNG images.""" + """Convert one or more pdfRest files to PNG images. + + Converts PDF pages to PNG images with configurable color model, smoothing, and page selection controls. Suitable for high-fidelity raster exports and previews. + + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, @@ -4335,7 +5372,28 @@ def convert_to_bmp( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert one or more pdfRest files to BMP images.""" + """Convert one or more pdfRest files to BMP images. + + Converts PDF pages to BMP images with configurable color model and page selection. Use this for legacy bitmap workflows that require BMP output. + + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, @@ -4372,7 +5430,28 @@ def convert_to_gif( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert one or more pdfRest files to GIF images.""" + """Convert one or more pdfRest files to GIF images. + + Converts PDF pages to GIF images with configurable color model and page selection. Useful for lightweight graphics workflows and compatibility scenarios. + + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, @@ -4410,7 +5489,29 @@ def convert_to_jpeg( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert one or more pdfRest files to JPEG images.""" + """Convert one or more pdfRest files to JPEG images. + + Converts PDF pages to JPEG images with configurable color model and page selection. Use this for compressed photo-friendly page exports. + + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + jpeg_quality: JPEG quality setting (1-100) controlling compression level and output fidelity. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, @@ -4448,7 +5549,28 @@ def convert_to_tiff( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert one or more pdfRest files to TIFF images.""" + """Convert one or more pdfRest files to TIFF images. + + Converts PDF pages to TIFF images with configurable color model and page selection. This is commonly used in archival, scanning, and print-imaging pipelines. + + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, @@ -4487,7 +5609,17 @@ def __init__( concurrency_limit: int = DEFAULT_FILE_INFO_CONCURRENCY, max_retries: int = DEFAULT_MAX_RETRIES, ) -> None: - """Create an asynchronous pdfRest client.""" + """Initialize an asynchronous pdfRest client. + + Args: + api_key: API key sent in the `Api-Key` header. + base_url: Base URL for the pdfRest API service. + timeout: Request timeout override for this call. + headers: Default headers merged into every request. + http_client: Optional preconfigured `httpx.Client` instance to reuse. + transport: Optional custom `httpx` transport. + concurrency_limit: Maximum concurrent file-info fetch operations used by async file helper methods. + max_retries: Maximum number of retries for retryable failures.""" super().__init__( api_key=api_key, @@ -4504,20 +5636,29 @@ def __init__( @override async def __aenter__(self) -> AsyncPdfRestClient: + """Enter the client context manager and return this client instance. + + Returns: + The current client instance.""" _ = await super().__aenter__() return self @override async def __aexit__(self, exc_type: Any, exc: Any, traceback: Any) -> None: + """Exit the client context manager and close underlying HTTP resources. + + Args: + exc_type: Exception type raised in the managed context, if any. + exc: Exception instance raised in the managed context, if any. + traceback: Traceback object for exceptions raised in the managed context.""" await super().__aexit__(exc_type, exc, traceback) @property def files(self) -> AsyncPdfRestFilesClient: - """Async file-management helper implementing - [`AsyncPdfRestFilesClient`][pdfrest.AsyncPdfRestFilesClient]. + """Return the [AsyncPdfRestFilesClient][pdfrest.AsyncPdfRestFilesClient] helper bound to this client. - Retrieve this helper from `client.files`; do not instantiate it directly. - """ + Returns: + The file-management helper bound to this client.""" return self._files_client @@ -4531,7 +5672,24 @@ async def query_pdf_info( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestInfoResponse: - """Query pdfRest for metadata describing a PDF document asynchronously.""" + """Asynchronous variant of [PdfRestClient.query_pdf_info][pdfrest.PdfRestClient.query_pdf_info]. + + Retrieves PDF metadata and structural flags (for example page count, tags, signatures, forms, transparency, and permission state). The `queries` argument controls which info keys pdfRest computes and returns. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + queries: Info fields to query from the `/pdf-info` endpoint. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated `PdfRestInfoResponse` model. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload = PdfInfoPayload.model_validate({"file": file, "queries": queries}) request = self.prepare_request( @@ -4562,11 +5720,28 @@ async def summarize_text( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> SummarizePdfTextResponse: - """Summarize the textual content of a PDF, Markdown, or text document. + """Asynchronous variant of [PdfRestClient.summarize_text][pdfrest.PdfRestClient.summarize_text]. - Always requests JSON output and returns the inline summary response defined in - the pdfRest API reference. - """ + Generates an inline summary from document text and returns it in a structured response model. You can scope to pages, choose summary style, and control output formatting for downstream display. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + target_word_count: Approximate target length for generated summary text. + summary_format: Summary layout/style requested from pdfRest. + pages: Page selection to constrain processing to specific pages. + output_format: Text format returned for generated textual output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated `SummarizePdfTextResponse` model. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4609,7 +5784,28 @@ async def summarize_text_to_file( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Summarize a document and return the result as a downloadable file.""" + """Asynchronous variant of [PdfRestClient.summarize_text_to_file][pdfrest.PdfRestClient.summarize_text_to_file]. + + Generates a summary and returns a file-based response containing the produced summary document. Use this when you want downloadable artifacts instead of inline summary text. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + target_word_count: Approximate target length for generated summary text. + summary_format: Summary layout/style requested from pdfRest. + pages: Page selection to constrain processing to specific pages. + output_format: Text format returned for generated textual output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4645,7 +5841,26 @@ async def convert_to_markdown( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Convert a PDF to Markdown and return a file-based response.""" + """Asynchronous variant of [PdfRestClient.convert_to_markdown][pdfrest.PdfRestClient.convert_to_markdown]. + + Converts document content into Markdown and supports either inline text output or file output. This is useful when preparing PDFs for LLM/RAG indexing and markdown-centric tooling. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + pages: Page selection to constrain processing to specific pages. + page_break_comments: When true, inserts page-break marker comments in generated Markdown between source pages. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4679,7 +5894,26 @@ async def ocr_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Perform OCR on a PDF to make text searchable and extractable.""" + """Asynchronous variant of [PdfRestClient.ocr_pdf][pdfrest.PdfRestClient.ocr_pdf]. + + Runs OCR on image-based PDFs to produce searchable text layers while preserving PDF layout. Use `language` to guide recognition and `output` to control output naming. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + languages: OCR language(s) to use when recognizing text in scanned or image-based pages. + pages: Page selection to constrain processing to specific pages. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "languages": languages} if pages is not None: @@ -4710,7 +5944,27 @@ async def translate_pdf_text( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> TranslatePdfTextResponse: - """Translate the textual content of a PDF, Markdown, or text document (JSON).""" + """Asynchronous variant of [PdfRestClient.translate_pdf_text][pdfrest.PdfRestClient.translate_pdf_text]. + + Translates extracted document text and returns translated content inline when `output_type` is JSON. Supports page scoping and output formatting for multilingual text workflows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output_language: Target language for translated output text. + pages: Page selection to constrain processing to specific pages. + output_format: Text format returned for generated textual output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated `TranslatePdfTextResponse` model. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4751,7 +6005,27 @@ async def translate_pdf_text_to_file( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> TranslatePdfTextFileResponse: - """Translate textual content and receive a file-based response.""" + """Asynchronous variant of [PdfRestClient.translate_pdf_text_to_file][pdfrest.PdfRestClient.translate_pdf_text_to_file]. + + Translates document text and returns a file-based response with translated output artifacts. Choose this when you need downloadable translated files instead of inline text. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output_language: Target language for translated output text. + pages: Page selection to constrain processing to specific pages. + output_format: Text format returned for generated textual output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated `TranslatePdfTextFileResponse` model. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4786,7 +6060,25 @@ async def extract_images( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Extract embedded images from a PDF.""" + """Asynchronous variant of [PdfRestClient.extract_images][pdfrest.PdfRestClient.extract_images]. + + Extracts embedded images from the source PDF and returns them as output files. This is useful for asset reuse, auditing image quality, or downstream image processing. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + pages: Page selection to constrain processing to specific pages. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if pages is not None: @@ -4818,7 +6110,28 @@ async def extract_pdf_text( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> ExtractedTextDocument: - """Extract text content from a PDF and return parsed JSON results.""" + """Asynchronous variant of [PdfRestClient.extract_pdf_text][pdfrest.PdfRestClient.extract_pdf_text]. + + Extracts text from a PDF as inline JSON text content. Use `pages` to limit scope and `granularity`/related options to control how text is aggregated. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + pages: Page selection to constrain processing to specific pages. + full_text: Controls full-text output mode: disabled, aggregated document text, or per-page text blocks. + preserve_line_breaks: Preserves detected line breaks in full-text output instead of flattening lines. + word_style: Includes per-word style metadata such as font, size, and color in structured output. + word_coordinates: Includes per-word coordinate metadata for positional text extraction. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated `ExtractedTextDocument` model. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4861,7 +6174,29 @@ async def extract_pdf_text_to_file( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Extract text content from a PDF and return a file-based response.""" + """Asynchronous variant of [PdfRestClient.extract_pdf_text_to_file][pdfrest.PdfRestClient.extract_pdf_text_to_file]. + + Extracts text into file outputs (including richer structured formats when requested). Use this for large outputs or when you need durable extracted-text artifacts. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + pages: Page selection to constrain processing to specific pages. + full_text: Controls full-text output mode: disabled, aggregated document text, or per-page text blocks. + preserve_line_breaks: Preserves detected line breaks in full-text output instead of flattening lines. + word_style: Includes per-word style metadata such as font, size, and color in structured output. + word_coordinates: Includes per-word coordinate metadata for positional text extraction. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4897,7 +6232,25 @@ async def preview_redactions( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously generate a PDF redaction preview.""" + """Asynchronous variant of [PdfRestClient.preview_redactions][pdfrest.PdfRestClient.preview_redactions]. + + Builds a redaction preview PDF so you can inspect matches before permanently removing content. Redaction rules support literals, regex patterns, and preset detectors. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + redactions: Redaction rules to preview or apply. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4927,7 +6280,25 @@ async def apply_redactions( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously apply PDF redactions.""" + """Asynchronous variant of [PdfRestClient.apply_redactions][pdfrest.PdfRestClient.apply_redactions]. + + Applies irreversible redactions to the PDF based on provided rules and outputs a redacted document. Use this after validating coverage with `preview_redactions`. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + rgb_color: RGB fill color applied to redaction rectangles when previewing/applying redactions. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4958,7 +6329,25 @@ async def add_text_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously insert text blocks into a PDF.""" + """Asynchronous variant of [PdfRestClient.add_text_to_pdf][pdfrest.PdfRestClient.add_text_to_pdf]. + + Places one or more text overlays onto a PDF with font, size, color, opacity, position, and rotation controls. This supports annotations, stamps, and templated labeling workflows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + text_objects: Text overlay objects to draw onto the document. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -4991,7 +6380,28 @@ async def add_image_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously insert an image into a PDF.""" + """Asynchronous variant of [PdfRestClient.add_image_to_pdf][pdfrest.PdfRestClient.add_image_to_pdf]. + + Places an uploaded image onto target pages in a PDF with size/position controls. This is commonly used for logos, seals, and branding overlays. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + image: Image/PDF resource to place into the source document. + x: Horizontal position in PDF points. + y: Vertical position in PDF points. + page: Target page number (or selector) where inserted content should be applied. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5021,7 +6431,22 @@ async def up( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> UpResponse: - """Call the `/up` health endpoint asynchronously and return server metadata.""" + """Asynchronous variant of [PdfRestClient.up][pdfrest.PdfRestClient.up]. + + Calls the health endpoint and returns service metadata such as status, product, version, and release date. Use this as a lightweight connectivity check before running document workflows. + + Args: + extra_headers: Additional HTTP headers merged into the request. + extra_query: Additional query parameters merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated `UpResponse` model. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" request = self._prepare_request( "GET", @@ -5045,6 +6470,19 @@ async def _convert_to_graphic( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: + """Asynchronous shared helper for image conversion endpoint methods. Mirrors [PdfRestClient._convert_to_graphic][pdfrest.PdfRestClient._convert_to_graphic]. + + Args: + endpoint: API endpoint path used for this request helper. + payload: Raw payload values forwarded to payload validation. + payload_model: Payload model class used to validate and serialize inputs. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest.""" return await self._post_file_operation( endpoint=endpoint, payload=payload, @@ -5066,7 +6504,25 @@ async def split_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously split a PDF into one or more PDF files.""" + """Asynchronous variant of [PdfRestClient.split_pdf][pdfrest.PdfRestClient.split_pdf]. + + Splits a PDF into multiple outputs using page selections and grouping rules. Use this to break long documents into per-range or per-section files. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + page_groups: Page-selection groups that define each split output document. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if page_groups is not None: @@ -5094,7 +6550,24 @@ async def merge_pdfs( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously merge multiple PDFs (or page subsets) into a single PDF.""" + """Asynchronous variant of [PdfRestClient.merge_pdfs][pdfrest.PdfRestClient.merge_pdfs]. + + Merges multiple uploaded PDFs into a single output, with optional per-input page selections. This is useful for packet assembly and document bundling. + + Args: + sources: Merge source list containing files with optional page selections per source. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"sources": sources} if output_prefix is not None: @@ -5120,7 +6593,24 @@ async def zip_files( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously compress one or more files into a zip archive.""" + """Asynchronous variant of [PdfRestClient.zip_files][pdfrest.PdfRestClient.zip_files]. + + Packages uploaded files into a ZIP archive and returns it as a file-based response. Use this to consolidate multiple outputs for a single download. + + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": files} if output is not None: @@ -5146,7 +6636,24 @@ async def unzip_file( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously extract files from a zip archive.""" + """Asynchronous variant of [PdfRestClient.unzip_file][pdfrest.PdfRestClient.unzip_file]. + + Expands an uploaded ZIP archive into individual files on pdfRest storage and returns metadata for the extracted resources. This is useful when reusing uploaded bundles in later API calls. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + password: Password value used by encrypt/decrypt endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if password is not None: @@ -5172,7 +6679,24 @@ async def convert_to_excel( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert a PDF to an Excel spreadsheet.""" + """Asynchronous variant of [PdfRestClient.convert_to_excel][pdfrest.PdfRestClient.convert_to_excel]. + + Converts PDF content into Excel workbook output optimized for tabular data extraction. Use this for spreadsheet-centric review or data cleanup workflows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -5198,7 +6722,24 @@ async def convert_to_powerpoint( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert a PDF to a PowerPoint presentation.""" + """Asynchronous variant of [PdfRestClient.convert_to_powerpoint][pdfrest.PdfRestClient.convert_to_powerpoint]. + + Converts PDF pages into PowerPoint output suitable for slide editing and presentation reuse. This helps repurpose static PDF material into editable decks. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -5224,7 +6765,24 @@ async def convert_xfa_to_acroforms( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert an XFA PDF to an AcroForm-enabled PDF.""" + """Asynchronous variant of [PdfRestClient.convert_xfa_to_acroforms][pdfrest.PdfRestClient.convert_xfa_to_acroforms]. + + Converts XFA form PDFs into AcroForm-compatible PDFs for broader tooling compatibility. Use this before importing/exporting form data with AcroForm-focused flows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -5250,7 +6808,24 @@ async def convert_to_word( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert a PDF to a Word document.""" + """Asynchronous variant of [PdfRestClient.convert_to_word][pdfrest.PdfRestClient.convert_to_word]. + + Converts PDF content into Word output for document editing workflows. This is useful when users need editable text and layout reconstruction in DOCX format. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -5277,7 +6852,25 @@ async def import_form_data( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously import form data from a data file into a PDF.""" + """Asynchronous variant of [PdfRestClient.import_form_data][pdfrest.PdfRestClient.import_form_data]. + + Imports external form-data files (XFDF/FDF/XML variants) into a source PDF and outputs a filled document. This supports bulk form-filling and integration pipelines. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + data_file: Uploaded form-data file (for example XFDF/FDF/XML/XDP/XFD) to import into the PDF. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "data_file": data_file} if output is not None: @@ -5304,12 +6897,25 @@ 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. + """Asynchronous variant of [PdfRestClient.export_form_data][pdfrest.PdfRestClient.export_form_data]. - `data_format` support depends on detected form type: - - AcroForm PDFs: `xfdf`, `fdf`, `xml` - - XFA PDFs: `xfd`, `xdp`, `xml` - """ + Exports form field data from a PDF into a structured data format (such as XFDF/FDF/XML). Use this for downstream processing, storage, or migration of form values. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + data_format: Output form-data format to export (for example XFDF, FDF, XML, XDP, or XFD). + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5338,7 +6944,24 @@ async def flatten_pdf_forms( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously flatten form fields in a PDF.""" + """Asynchronous variant of [PdfRestClient.flatten_pdf_forms][pdfrest.PdfRestClient.flatten_pdf_forms]. + + Flattens interactive form fields into static page content so values are no longer editable. This is commonly used for finalization and archival workflows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -5367,7 +6990,27 @@ async def add_permissions_password( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously add a permissions password and optional restrictions to a PDF.""" + """Asynchronous variant of [PdfRestClient.add_permissions_password][pdfrest.PdfRestClient.add_permissions_password]. + + Applies owner permissions and restriction flags (print/copy/edit controls) to a PDF. This secures document capabilities without requiring an open password. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + new_permissions_password: New owner/permissions password to apply to the output PDF. + restrictions: Permission restriction literals for protected PDFs. + current_open_password: Current user/open password required to unlock the source PDF before changes. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5404,7 +7047,28 @@ async def change_permissions_password( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously rotate the permissions password and optionally update restrictions.""" + """Asynchronous variant of [PdfRestClient.change_permissions_password][pdfrest.PdfRestClient.change_permissions_password]. + + Updates owner permissions/password settings and restriction flags on an already protected PDF. Use this to rotate credentials or revise allowed actions. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + new_permissions_password: New owner/permissions password to apply to the output PDF. + restrictions: Permission restriction literals for protected PDFs. + current_open_password: Current user/open password required to unlock the source PDF before changes. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5440,7 +7104,26 @@ async def remove_permissions_password( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously remove permissions restrictions from a PDF.""" + """Asynchronous variant of [PdfRestClient.remove_permissions_password][pdfrest.PdfRestClient.remove_permissions_password]. + + Removes owner permission restrictions from a PDF when authorized with the existing owner password. This restores unrestricted editing/printing capabilities. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + current_open_password: Current user/open password required to unlock the source PDF before changes. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5473,7 +7156,26 @@ async def add_open_password( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously encrypt a PDF with a new open password.""" + """Asynchronous variant of [PdfRestClient.add_open_password][pdfrest.PdfRestClient.add_open_password]. + + Applies a user/open password so the PDF requires authentication before viewing. Optional permissions controls can also be set for opened documents. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + new_open_password: New user/open password required to open the output PDF. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5507,7 +7209,27 @@ async def change_open_password( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously rotate the open password for an encrypted PDF.""" + """Asynchronous variant of [PdfRestClient.change_open_password][pdfrest.PdfRestClient.change_open_password]. + + Replaces the existing open password with a new one while preserving or updating related protection options. Use this for credential rotation. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + current_open_password: Current user/open password required to unlock the source PDF before changes. + new_open_password: New user/open password required to open the output PDF. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5541,7 +7263,26 @@ async def remove_open_password( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously decrypt a PDF by removing its open password.""" + """Asynchronous variant of [PdfRestClient.remove_open_password][pdfrest.PdfRestClient.remove_open_password]. + + Removes the user/open password requirement from a PDF when the current password is provided. The output document can be opened without viewer authentication. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + current_open_password: Current user/open password required to unlock the source PDF before changes. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5574,7 +7315,26 @@ async def compress_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously compress a PDF.""" + """Asynchronous variant of [PdfRestClient.compress_pdf][pdfrest.PdfRestClient.compress_pdf]. + + Reduces PDF file size using preset or custom compression settings, with optional profile uploads. Use this for storage/bandwidth optimization while balancing quality. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + compression_level: Compression level or strategy option. + profile: Uploaded color/compression profile as a `PdfRestFile`. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5606,7 +7366,25 @@ async def add_attachment_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously attach an uploaded file to a PDF.""" + """Asynchronous variant of [PdfRestClient.add_attachment_to_pdf][pdfrest.PdfRestClient.add_attachment_to_pdf]. + + Embeds an uploaded file as an attachment inside a PDF container document. This supports package-style delivery where supplemental files travel with the PDF. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + attachment: Uploaded file to embed as an attachment in the output PDF. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "attachment": attachment} if output is not None: @@ -5635,7 +7413,27 @@ async def sign_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Digitally sign a PDF using PFX credentials or a certificate/private key.""" + """Asynchronous variant of [PdfRestClient.sign_pdf][pdfrest.PdfRestClient.sign_pdf]. + + Applies digital signatures using either PFX credentials or certificate/private-key inputs, with configurable visible signature placement and appearance. Use this for integrity, authenticity, and non-repudiation workflows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + signature_configuration: Signature placement and appearance settings. + credentials: Digital signing credential bundle (PFX or cert/key files). + logo: Optional uploaded logo file displayed in visible digital signature appearances. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5670,7 +7468,26 @@ async def blank_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously create a blank PDF with configurable size and count.""" + """Asynchronous variant of [PdfRestClient.blank_pdf][pdfrest.PdfRestClient.blank_pdf]. + + Creates a new blank PDF with configurable page size, orientation, and page count. This is useful as a template baseline for downstream stamping/filling workflows. + + Args: + page_size: Target page size preset or custom size settings used for output page dimensions. + page_count: Number of blank pages to generate in the new PDF. + page_orientation: Page orientation for standard page sizes (portrait or landscape). + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "page_size": page_size, @@ -5703,7 +7520,26 @@ async def convert_colors( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert PDF colors using presets or a custom ICC profile.""" + """Asynchronous variant of [PdfRestClient.convert_colors][pdfrest.PdfRestClient.convert_colors]. + + Converts document color spaces using preset profiles and optional black-preservation behavior. Use this to normalize output for print pipelines or color-management requirements. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + color_profile: Named color profile used by color conversion. + preserve_black: When true, keeps pure black content from being remapped during color-profile conversion. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5734,7 +7570,25 @@ async def flatten_transparencies( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously flatten transparent objects in a PDF.""" + """Asynchronous variant of [PdfRestClient.flatten_transparencies][pdfrest.PdfRestClient.flatten_transparencies]. + + Flattens transparent objects into opaque content using selectable quality levels. This improves compatibility with workflows/devices that do not fully support transparency. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + quality: Quality preset understood by the selected endpoint. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "quality": quality} if output is not None: @@ -5760,7 +7614,24 @@ async def linearize_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously linearize a PDF for optimized fast web view.""" + """Asynchronous variant of [PdfRestClient.linearize_pdf][pdfrest.PdfRestClient.linearize_pdf]. + + Linearizes the PDF for fast web view so first pages render sooner over network delivery. This improves user experience for browser-based document viewing. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -5786,7 +7657,24 @@ async def flatten_annotations( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously flatten annotations into the PDF content.""" + """Asynchronous variant of [PdfRestClient.flatten_annotations][pdfrest.PdfRestClient.flatten_annotations]. + + Burns annotation markup into page content so comments/highlights become static and non-editable. Use this when sharing finalized review copies. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -5812,7 +7700,24 @@ async def flatten_layers( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously flatten all layers in a PDF.""" + """Asynchronous variant of [PdfRestClient.flatten_layers][pdfrest.PdfRestClient.flatten_layers]. + + Flattens optional content groups (layers) into a single visible page representation. This avoids layer-dependent rendering differences across viewers. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -5838,7 +7743,24 @@ async def rasterize_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously rasterize a PDF into a flattened bitmap-based PDF.""" + """Asynchronous variant of [PdfRestClient.rasterize_pdf][pdfrest.PdfRestClient.rasterize_pdf]. + + Rasterizes PDF pages into image-based page content at a specified resolution. Use this for visual normalization, redaction hardening, or viewer compatibility scenarios. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -5872,7 +7794,32 @@ async def convert_office_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert a Microsoft Office file to PDF.""" + """Asynchronous variant of [PdfRestClient.convert_office_to_pdf][pdfrest.PdfRestClient.convert_office_to_pdf]. + + Converts Office documents into PDF output using conversion options for layout and fidelity. This is the main entry point for Word/Excel/PowerPoint-to-PDF workflows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + compression: Compression mode used during conversion. + downsample: Image downsampling setting for conversion. + tagged_pdf: For Office conversion, toggles generation of tagged PDFs for accessibility workflows. + locale: Locale used by locale-aware conversion options. + page_size: Target page size preset or custom size settings used for output page dimensions. + page_margin: Page margin setting (for example `8mm` or `0.5in`) for HTML/URL rendering outputs. + page_orientation: Page orientation for standard page sizes (portrait or landscape). + web_layout: Rendering viewport profile (`desktop`, `tablet`, or `mobile`) for HTML/URL conversion. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5910,7 +7857,26 @@ async def convert_postscript_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert a PostScript or EPS file to PDF.""" + """Asynchronous variant of [PdfRestClient.convert_postscript_to_pdf][pdfrest.PdfRestClient.convert_postscript_to_pdf]. + + Converts PostScript content to PDF while preserving page content for modern PDF workflows. Use this when ingesting legacy print-oriented document formats. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + compression: Compression mode used during conversion. + downsample: Image downsampling setting for conversion. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5940,7 +7906,24 @@ async def convert_email_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert an RFC822 email file to PDF.""" + """Asynchronous variant of [PdfRestClient.convert_email_to_pdf][pdfrest.PdfRestClient.convert_email_to_pdf]. + + Converts email message files into PDF, including rendered message content and supported metadata/body parts. This supports archiving and compliance workflows. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5968,7 +7951,24 @@ async def convert_image_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert a supported image file to PDF.""" + """Asynchronous variant of [PdfRestClient.convert_image_to_pdf][pdfrest.PdfRestClient.convert_image_to_pdf]. + + Converts one or more image files into PDF output and can combine them into multipage documents. Use this to normalize scanned/image assets into PDF containers. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -6002,7 +8002,30 @@ async def convert_html_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert an uploaded HTML file to PDF.""" + """Asynchronous variant of [PdfRestClient.convert_html_to_pdf][pdfrest.PdfRestClient.convert_html_to_pdf]. + + Renders HTML content into PDF with page-size/orientation/layout and related rendering controls. This supports report generation and web-to-PDF publishing use cases. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + compression: Compression mode used during conversion. + downsample: Image downsampling setting for conversion. + page_size: Target page size preset or custom size settings used for output page dimensions. + page_margin: Page margin setting (for example `8mm` or `0.5in`) for HTML/URL rendering outputs. + page_orientation: Page orientation for standard page sizes (portrait or landscape). + web_layout: Rendering viewport profile (`desktop`, `tablet`, or `mobile`) for HTML/URL conversion. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -6042,7 +8065,30 @@ async def convert_url_to_pdf( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert HTML content from one URL to PDF.""" + """Asynchronous variant of [PdfRestClient.convert_url_to_pdf][pdfrest.PdfRestClient.convert_url_to_pdf]. + + Fetches remote web content by URL and renders it to PDF using HTML rendering options. Use this for automated webpage capture and archival. + + Args: + url: Remote URL to ingest and convert. + output: Output filename prefix used by pdfRest when creating files. + compression: Compression mode used during conversion. + downsample: Image downsampling setting for conversion. + page_size: Target page size preset or custom size settings used for output page dimensions. + page_margin: Page margin setting (for example `8mm` or `0.5in`) for HTML/URL rendering outputs. + page_orientation: Page orientation for standard page sizes (portrait or landscape). + web_layout: Rendering viewport profile (`desktop`, `tablet`, or `mobile`) for HTML/URL conversion. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "url": url, @@ -6088,7 +8134,36 @@ async def watermark_pdf_with_text( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously apply a text watermark to a PDF.""" + """Asynchronous variant of [PdfRestClient.watermark_pdf_with_text][pdfrest.PdfRestClient.watermark_pdf_with_text]. + + Applies text watermarks with control over placement, rotation, color, opacity, and alignment. Use this for confidentiality marks, drafts, and document branding. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + watermark_text: Text content to render as the watermark. + output: Output filename prefix used by pdfRest when creating files. + font: Font family name for rendered text. + text_size: Watermark text size in points. + text_color: Watermark text color as RGB or CMYK channel values. + opacity: Opacity in range 0.0 to 1.0. + horizontal_alignment: Horizontal alignment anchor used when placing watermark content. + vertical_alignment: Vertical alignment anchor used when placing watermark content. + x: Horizontal position in PDF points. + y: Vertical position in PDF points. + rotation: Rotation angle in degrees. + pages: Page selection to constrain processing to specific pages. + behind_page: Target page number (or selector) where inserted content should be applied. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -6138,7 +8213,34 @@ async def watermark_pdf_with_image( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously apply an image watermark to a PDF.""" + """Asynchronous variant of [PdfRestClient.watermark_pdf_with_image][pdfrest.PdfRestClient.watermark_pdf_with_image]. + + Applies image watermarks (for example logos/seals) with placement and opacity controls. This is useful for branded overlays and visual ownership marks. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + watermark_file: Uploaded image used as watermark content. + output: Output filename prefix used by pdfRest when creating files. + watermark_file_scale: Scale multiplier applied to the watermark file graphic before placement. + opacity: Opacity in range 0.0 to 1.0. + horizontal_alignment: Horizontal alignment anchor used when placing watermark content. + vertical_alignment: Vertical alignment anchor used when placing watermark content. + x: Horizontal position in PDF points. + y: Vertical position in PDF points. + rotation: Rotation angle in degrees. + pages: Page selection to constrain processing to specific pages. + behind_page: Target page number (or selector) where inserted content should be applied. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -6178,7 +8280,26 @@ async def convert_to_pdfa( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert a PDF to a specified PDF/A version.""" + """Asynchronous variant of [PdfRestClient.convert_to_pdfa][pdfrest.PdfRestClient.convert_to_pdfa]. + + Converts input PDFs to selected PDF/A conformance levels for long-term archival compatibility. Choose the target conformance profile that matches your compliance requirements. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output_type: Output mode for endpoints supporting inline or file output. + output: Output filename prefix used by pdfRest when creating files. + rasterize_if_errors_encountered: When enabled, allows rasterized fallback if strict conformance conversion encounters nonconforming content. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -6209,7 +8330,25 @@ async def convert_to_pdfx( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert a PDF to a specified PDF/X version.""" + """Asynchronous variant of [PdfRestClient.convert_to_pdfx][pdfrest.PdfRestClient.convert_to_pdfx]. + + Converts input PDFs to selected PDF/X conformance levels for print-production workflows. Use this when downstream print tooling expects standardized PDF/X output. + + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output_type: Output mode for endpoints supporting inline or file output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "output_type": output_type} if output is not None: @@ -6239,7 +8378,28 @@ async def convert_to_png( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert one or more pdfRest files to PNG images.""" + """Asynchronous variant of [PdfRestClient.convert_to_png][pdfrest.PdfRestClient.convert_to_png]. + + Converts PDF pages to PNG images with configurable color model, smoothing, and page selection controls. Suitable for high-fidelity raster exports and previews. + + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, @@ -6276,7 +8436,28 @@ async def convert_to_bmp( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert one or more pdfRest files to BMP images.""" + """Asynchronous variant of [PdfRestClient.convert_to_bmp][pdfrest.PdfRestClient.convert_to_bmp]. + + Converts PDF pages to BMP images with configurable color model and page selection. Use this for legacy bitmap workflows that require BMP output. + + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, @@ -6313,7 +8494,28 @@ async def convert_to_gif( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert one or more pdfRest files to GIF images.""" + """Asynchronous variant of [PdfRestClient.convert_to_gif][pdfrest.PdfRestClient.convert_to_gif]. + + Converts PDF pages to GIF images with configurable color model and page selection. Useful for lightweight graphics workflows and compatibility scenarios. + + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, @@ -6351,7 +8553,29 @@ async def convert_to_jpeg( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert one or more pdfRest files to JPEG images.""" + """Asynchronous variant of [PdfRestClient.convert_to_jpeg][pdfrest.PdfRestClient.convert_to_jpeg]. + + Converts PDF pages to JPEG images with configurable color model and page selection. Use this for compressed photo-friendly page exports. + + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + jpeg_quality: JPEG quality setting (1-100) controlling compression level and output fidelity. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, @@ -6389,7 +8613,28 @@ async def convert_to_tiff( extra_body: Body | None = None, timeout: TimeoutTypes | None = None, ) -> PdfRestFileBasedResponse: - """Asynchronously convert one or more pdfRest files to TIFF images.""" + """Asynchronous variant of [PdfRestClient.convert_to_tiff][pdfrest.PdfRestClient.convert_to_tiff]. + + Converts PDF pages to TIFF images with configurable color model and page selection. This is commonly used in archival, scanning, and print-imaging pipelines. + + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, From 346156668fcc583a10843c3f941dd5024058d143 Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Thu, 19 Feb 2026 11:49:42 -0600 Subject: [PATCH 10/18] mkdocs: Configure members_order as alphabetical in docstrings plugin - Changed `members_order` in `mkdocstrings` from `source` to `alphabetical` for better organization and readability of API documentation. Assisted-by: Codex --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index dadfb9da..918d980a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -21,7 +21,7 @@ plugins: docstring_style: google heading_level: 2 line_length: 50 - members_order: source + members_order: alphabetical separate_signature: true show_signature_annotations: true signature_crossrefs: true From c813edf20a0002c3d955acc382f10c72049dd7d0 Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Thu, 19 Feb 2026 11:54:32 -0600 Subject: [PATCH 11/18] docs: Add API guide and update site navigation - Added `api-guide.md` to provide an organized overview of `PdfRestClient` and `AsyncPdfRestClient` methods, grouped by workflow and functionality. - Updated `index.md` to include a link to the new API guide. - Modified `mkdocs.yml` to reflect the updated navigation structure. Assisted-by: Codex --- docs/api-guide.md | 164 ++++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 1 + mkdocs.yml | 1 + 3 files changed, 166 insertions(+) create mode 100644 docs/api-guide.md diff --git a/docs/api-guide.md b/docs/api-guide.md new file mode 100644 index 00000000..838170f5 --- /dev/null +++ b/docs/api-guide.md @@ -0,0 +1,164 @@ +# API guide + +This guide organizes `PdfRestClient` and `AsyncPdfRestClient` methods by +workflow, so you can quickly find the right call for a user task. + +Notes: + +- Every sync method has an async counterpart with the same name. +- Sync client: [PdfRestClient][pdfrest.PdfRestClient] +- Async client: [AsyncPdfRestClient][pdfrest.AsyncPdfRestClient] + +## Start here: common flow + +1. Upload file(s): [files.create_from_paths][pdfrest.PdfRestFilesClient.create_from_paths] +2. Call one processing method from a category below. +3. Download outputs: [files.read_bytes][pdfrest.PdfRestFilesClient.read_bytes] or + [files.write_bytes][pdfrest.PdfRestFilesClient.write_bytes] +4. (Optional) clean up: [files.delete][pdfrest.PdfRestFilesClient.delete] + +## Service and file operations + +Use these methods to check service status and manage uploaded resources. + +- Health check: + [up][pdfrest.PdfRestClient.up] +- File helper: + [files][pdfrest.PdfRestClient.files] +- File upload and fetch: + [files.create][pdfrest.PdfRestFilesClient.create], + [files.create_from_paths][pdfrest.PdfRestFilesClient.create_from_paths], + [files.create_from_urls][pdfrest.PdfRestFilesClient.create_from_urls], + [files.get][pdfrest.PdfRestFilesClient.get] +- File read/write: + [files.read_bytes][pdfrest.PdfRestFilesClient.read_bytes], + [files.read_text][pdfrest.PdfRestFilesClient.read_text], + [files.read_json][pdfrest.PdfRestFilesClient.read_json], + [files.write_bytes][pdfrest.PdfRestFilesClient.write_bytes], + [files.stream][pdfrest.PdfRestFilesClient.stream] +- File delete: + [files.delete][pdfrest.PdfRestFilesClient.delete] + +## Inspect, extract, summarize, and translate + +Use this group when users need metadata or text intelligence. + +- Metadata and document properties: + [query_pdf_info][pdfrest.PdfRestClient.query_pdf_info] +- OCR and text extraction: + [ocr_pdf][pdfrest.PdfRestClient.ocr_pdf], + [extract_pdf_text][pdfrest.PdfRestClient.extract_pdf_text], + [extract_pdf_text_to_file][pdfrest.PdfRestClient.extract_pdf_text_to_file] +- Image extraction: + [extract_images][pdfrest.PdfRestClient.extract_images] +- Summaries: + [summarize_text][pdfrest.PdfRestClient.summarize_text], + [summarize_text_to_file][pdfrest.PdfRestClient.summarize_text_to_file] +- Translation: + [translate_pdf_text][pdfrest.PdfRestClient.translate_pdf_text], + [translate_pdf_text_to_file][pdfrest.PdfRestClient.translate_pdf_text_to_file] +- Markdown output: + [convert_to_markdown][pdfrest.PdfRestClient.convert_to_markdown] + +## Compose, split, merge, and package + +Use this group for document assembly and distribution. + +- Create or partition documents: + [blank_pdf][pdfrest.PdfRestClient.blank_pdf], + [split_pdf][pdfrest.PdfRestClient.split_pdf] +- Combine documents: + [merge_pdfs][pdfrest.PdfRestClient.merge_pdfs] +- Package/unpackage output sets: + [zip_files][pdfrest.PdfRestClient.zip_files], + [unzip_file][pdfrest.PdfRestClient.unzip_file] +- Embed attachments: + [add_attachment_to_pdf][pdfrest.PdfRestClient.add_attachment_to_pdf] + +## Markup, branding, and redaction + +Use this group to add visible content or remove sensitive content. + +- Add overlays: + [add_text_to_pdf][pdfrest.PdfRestClient.add_text_to_pdf], + [add_image_to_pdf][pdfrest.PdfRestClient.add_image_to_pdf] +- Watermarking: + [watermark_pdf_with_text][pdfrest.PdfRestClient.watermark_pdf_with_text], + [watermark_pdf_with_image][pdfrest.PdfRestClient.watermark_pdf_with_image] +- Redaction workflow: + [preview_redactions][pdfrest.PdfRestClient.preview_redactions] first, + then [apply_redactions][pdfrest.PdfRestClient.apply_redactions] + +## Security, signing, and compliance + +Use this group for password protection, permissions, signatures, and standards. + +- Permissions password: + [add_permissions_password][pdfrest.PdfRestClient.add_permissions_password], + [change_permissions_password][pdfrest.PdfRestClient.change_permissions_password], + [remove_permissions_password][pdfrest.PdfRestClient.remove_permissions_password] +- Open password: + [add_open_password][pdfrest.PdfRestClient.add_open_password], + [change_open_password][pdfrest.PdfRestClient.change_open_password], + [remove_open_password][pdfrest.PdfRestClient.remove_open_password] +- Digital signatures: + [sign_pdf][pdfrest.PdfRestClient.sign_pdf] +- Archival/print conformance: + [convert_to_pdfa][pdfrest.PdfRestClient.convert_to_pdfa], + [convert_to_pdfx][pdfrest.PdfRestClient.convert_to_pdfx] + +## PDF cleanup and rendering normalization + +Use this group to improve compatibility, performance, or file size. + +- Size and optimization: + [compress_pdf][pdfrest.PdfRestClient.compress_pdf], + [linearize_pdf][pdfrest.PdfRestClient.linearize_pdf] +- Flattening: + [flatten_pdf_forms][pdfrest.PdfRestClient.flatten_pdf_forms], + [flatten_annotations][pdfrest.PdfRestClient.flatten_annotations], + [flatten_layers][pdfrest.PdfRestClient.flatten_layers], + [flatten_transparencies][pdfrest.PdfRestClient.flatten_transparencies] +- Raster and color normalization: + [rasterize_pdf][pdfrest.PdfRestClient.rasterize_pdf], + [convert_colors][pdfrest.PdfRestClient.convert_colors] + +## Convert into or out of PDF + +Use this group when the user starts with non-PDF content or needs downstream +formats. + +- Into PDF: + [convert_office_to_pdf][pdfrest.PdfRestClient.convert_office_to_pdf], + [convert_postscript_to_pdf][pdfrest.PdfRestClient.convert_postscript_to_pdf], + [convert_email_to_pdf][pdfrest.PdfRestClient.convert_email_to_pdf], + [convert_image_to_pdf][pdfrest.PdfRestClient.convert_image_to_pdf], + [convert_html_to_pdf][pdfrest.PdfRestClient.convert_html_to_pdf], + [convert_url_to_pdf][pdfrest.PdfRestClient.convert_url_to_pdf] +- Out of PDF: + [convert_to_word][pdfrest.PdfRestClient.convert_to_word], + [convert_to_excel][pdfrest.PdfRestClient.convert_to_excel], + [convert_to_powerpoint][pdfrest.PdfRestClient.convert_to_powerpoint], + [convert_xfa_to_acroforms][pdfrest.PdfRestClient.convert_xfa_to_acroforms] +- PDF to image: + [convert_to_png][pdfrest.PdfRestClient.convert_to_png], + [convert_to_bmp][pdfrest.PdfRestClient.convert_to_bmp], + [convert_to_gif][pdfrest.PdfRestClient.convert_to_gif], + [convert_to_jpeg][pdfrest.PdfRestClient.convert_to_jpeg], + [convert_to_tiff][pdfrest.PdfRestClient.convert_to_tiff] + +## Forms data workflows + +Use this group when users need to transfer form field values in/out of PDFs. + +- Import external form data into a PDF: + [import_form_data][pdfrest.PdfRestClient.import_form_data] +- Export form data from a PDF: + [export_form_data][pdfrest.PdfRestClient.export_form_data] + +## Async equivalents + +For any sync method listed above, use the same method name on +[AsyncPdfRestClient][pdfrest.AsyncPdfRestClient] when your app is async. For +file helpers, use +[AsyncPdfRestFilesClient][pdfrest.AsyncPdfRestFilesClient]. diff --git a/docs/index.md b/docs/index.md index cb97b3f5..479b12be 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,6 +19,7 @@ Useful references: - [Getting started guide](getting-started.md) - [Client configuration guide](client-configuration.md) - [Using files guide](using-files.md) +- [API guide](api-guide.md) ## How this Python API relates to pdfRest diff --git a/mkdocs.yml b/mkdocs.yml index 918d980a..8d70eac9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -40,4 +40,5 @@ nav: - Getting Started: getting-started.md - Client Configuration: client-configuration.md - Using Files: using-files.md + - API Guide: api-guide.md - API Reference: api-reference.md From 0eaa09bac2dc689487448944a8ffcef0f575cc2e Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Thu, 19 Feb 2026 11:58:55 -0600 Subject: [PATCH 12/18] client: Reformat docstrings in PdfRestClient methods for consistency - Adjusted indentation and formatting of docstrings in all `PdfRestClient` methods to improve readability and alignment with Google-style documentation standards. - Ensured consistent structure for sections like `Args`, `Returns`, and `Raises` across all methods. Assisted-by: Codex --- src/pdfrest/client.py | 1708 ++++++++++++++++++++--------------------- 1 file changed, 854 insertions(+), 854 deletions(-) diff --git a/src/pdfrest/client.py b/src/pdfrest/client.py index 0c474690..f768bf07 100644 --- a/src/pdfrest/client.py +++ b/src/pdfrest/client.py @@ -5676,20 +5676,20 @@ async def query_pdf_info( Retrieves PDF metadata and structural flags (for example page count, tags, signatures, forms, transparency, and permission state). The `queries` argument controls which info keys pdfRest computes and returns. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - queries: Info fields to query from the `/pdf-info` endpoint. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + queries: Info fields to query from the `/pdf-info` endpoint. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated `PdfRestInfoResponse` model. + Returns: + Validated `PdfRestInfoResponse` model. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload = PdfInfoPayload.model_validate({"file": file, "queries": queries}) request = self.prepare_request( @@ -5724,24 +5724,24 @@ async def summarize_text( Generates an inline summary from document text and returns it in a structured response model. You can scope to pages, choose summary style, and control output formatting for downstream display. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - target_word_count: Approximate target length for generated summary text. - summary_format: Summary layout/style requested from pdfRest. - pages: Page selection to constrain processing to specific pages. - output_format: Text format returned for generated textual output. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated `SummarizePdfTextResponse` model. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + target_word_count: Approximate target length for generated summary text. + summary_format: Summary layout/style requested from pdfRest. + pages: Page selection to constrain processing to specific pages. + output_format: Text format returned for generated textual output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated `SummarizePdfTextResponse` model. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5788,24 +5788,24 @@ async def summarize_text_to_file( Generates a summary and returns a file-based response containing the produced summary document. Use this when you want downloadable artifacts instead of inline summary text. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - target_word_count: Approximate target length for generated summary text. - summary_format: Summary layout/style requested from pdfRest. - pages: Page selection to constrain processing to specific pages. - output_format: Text format returned for generated textual output. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + target_word_count: Approximate target length for generated summary text. + summary_format: Summary layout/style requested from pdfRest. + pages: Page selection to constrain processing to specific pages. + output_format: Text format returned for generated textual output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5845,22 +5845,22 @@ async def convert_to_markdown( Converts document content into Markdown and supports either inline text output or file output. This is useful when preparing PDFs for LLM/RAG indexing and markdown-centric tooling. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - pages: Page selection to constrain processing to specific pages. - page_break_comments: When true, inserts page-break marker comments in generated Markdown between source pages. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + pages: Page selection to constrain processing to specific pages. + page_break_comments: When true, inserts page-break marker comments in generated Markdown between source pages. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -5898,22 +5898,22 @@ async def ocr_pdf( Runs OCR on image-based PDFs to produce searchable text layers while preserving PDF layout. Use `language` to guide recognition and `output` to control output naming. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - languages: OCR language(s) to use when recognizing text in scanned or image-based pages. - pages: Page selection to constrain processing to specific pages. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + languages: OCR language(s) to use when recognizing text in scanned or image-based pages. + pages: Page selection to constrain processing to specific pages. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "languages": languages} if pages is not None: @@ -5948,23 +5948,23 @@ async def translate_pdf_text( Translates extracted document text and returns translated content inline when `output_type` is JSON. Supports page scoping and output formatting for multilingual text workflows. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output_language: Target language for translated output text. - pages: Page selection to constrain processing to specific pages. - output_format: Text format returned for generated textual output. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output_language: Target language for translated output text. + pages: Page selection to constrain processing to specific pages. + output_format: Text format returned for generated textual output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated `TranslatePdfTextResponse` model. + Returns: + Validated `TranslatePdfTextResponse` model. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -6009,23 +6009,23 @@ async def translate_pdf_text_to_file( Translates document text and returns a file-based response with translated output artifacts. Choose this when you need downloadable translated files instead of inline text. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output_language: Target language for translated output text. - pages: Page selection to constrain processing to specific pages. - output_format: Text format returned for generated textual output. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output_language: Target language for translated output text. + pages: Page selection to constrain processing to specific pages. + output_format: Text format returned for generated textual output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated `TranslatePdfTextFileResponse` model. + Returns: + Validated `TranslatePdfTextFileResponse` model. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -6064,21 +6064,21 @@ async def extract_images( Extracts embedded images from the source PDF and returns them as output files. This is useful for asset reuse, auditing image quality, or downstream image processing. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - pages: Page selection to constrain processing to specific pages. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + pages: Page selection to constrain processing to specific pages. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if pages is not None: @@ -6114,24 +6114,24 @@ async def extract_pdf_text( Extracts text from a PDF as inline JSON text content. Use `pages` to limit scope and `granularity`/related options to control how text is aggregated. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - pages: Page selection to constrain processing to specific pages. - full_text: Controls full-text output mode: disabled, aggregated document text, or per-page text blocks. - preserve_line_breaks: Preserves detected line breaks in full-text output instead of flattening lines. - word_style: Includes per-word style metadata such as font, size, and color in structured output. - word_coordinates: Includes per-word coordinate metadata for positional text extraction. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated `ExtractedTextDocument` model. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + pages: Page selection to constrain processing to specific pages. + full_text: Controls full-text output mode: disabled, aggregated document text, or per-page text blocks. + preserve_line_breaks: Preserves detected line breaks in full-text output instead of flattening lines. + word_style: Includes per-word style metadata such as font, size, and color in structured output. + word_coordinates: Includes per-word coordinate metadata for positional text extraction. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated `ExtractedTextDocument` model. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -6178,25 +6178,25 @@ async def extract_pdf_text_to_file( Extracts text into file outputs (including richer structured formats when requested). Use this for large outputs or when you need durable extracted-text artifacts. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - pages: Page selection to constrain processing to specific pages. - full_text: Controls full-text output mode: disabled, aggregated document text, or per-page text blocks. - preserve_line_breaks: Preserves detected line breaks in full-text output instead of flattening lines. - word_style: Includes per-word style metadata such as font, size, and color in structured output. - word_coordinates: Includes per-word coordinate metadata for positional text extraction. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + pages: Page selection to constrain processing to specific pages. + full_text: Controls full-text output mode: disabled, aggregated document text, or per-page text blocks. + preserve_line_breaks: Preserves detected line breaks in full-text output instead of flattening lines. + word_style: Includes per-word style metadata such as font, size, and color in structured output. + word_coordinates: Includes per-word coordinate metadata for positional text extraction. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -6236,21 +6236,21 @@ async def preview_redactions( Builds a redaction preview PDF so you can inspect matches before permanently removing content. Redaction rules support literals, regex patterns, and preset detectors. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - redactions: Redaction rules to preview or apply. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + redactions: Redaction rules to preview or apply. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -6284,21 +6284,21 @@ async def apply_redactions( Applies irreversible redactions to the PDF based on provided rules and outputs a redacted document. Use this after validating coverage with `preview_redactions`. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - rgb_color: RGB fill color applied to redaction rectangles when previewing/applying redactions. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + rgb_color: RGB fill color applied to redaction rectangles when previewing/applying redactions. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -6333,21 +6333,21 @@ async def add_text_to_pdf( Places one or more text overlays onto a PDF with font, size, color, opacity, position, and rotation controls. This supports annotations, stamps, and templated labeling workflows. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - text_objects: Text overlay objects to draw onto the document. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + text_objects: Text overlay objects to draw onto the document. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -6384,24 +6384,24 @@ async def add_image_to_pdf( Places an uploaded image onto target pages in a PDF with size/position controls. This is commonly used for logos, seals, and branding overlays. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - image: Image/PDF resource to place into the source document. - x: Horizontal position in PDF points. - y: Vertical position in PDF points. - page: Target page number (or selector) where inserted content should be applied. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + image: Image/PDF resource to place into the source document. + x: Horizontal position in PDF points. + y: Vertical position in PDF points. + page: Target page number (or selector) where inserted content should be applied. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -6435,18 +6435,18 @@ async def up( Calls the health endpoint and returns service metadata such as status, product, version, and release date. Use this as a lightweight connectivity check before running document workflows. - Args: - extra_headers: Additional HTTP headers merged into the request. - extra_query: Additional query parameters merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + extra_headers: Additional HTTP headers merged into the request. + extra_query: Additional query parameters merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated `UpResponse` model. + Returns: + Validated `UpResponse` model. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" request = self._prepare_request( "GET", @@ -6508,21 +6508,21 @@ async def split_pdf( Splits a PDF into multiple outputs using page selections and grouping rules. Use this to break long documents into per-range or per-section files. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - page_groups: Page-selection groups that define each split output document. - output_prefix: Filename prefix used for generated per-page/per-file image outputs. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + page_groups: Page-selection groups that define each split output document. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if page_groups is not None: @@ -6554,20 +6554,20 @@ async def merge_pdfs( Merges multiple uploaded PDFs into a single output, with optional per-input page selections. This is useful for packet assembly and document bundling. - Args: - sources: Merge source list containing files with optional page selections per source. - output_prefix: Filename prefix used for generated per-page/per-file image outputs. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + sources: Merge source list containing files with optional page selections per source. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"sources": sources} if output_prefix is not None: @@ -6597,20 +6597,20 @@ async def zip_files( Packages uploaded files into a ZIP archive and returns it as a file-based response. Use this to consolidate multiple outputs for a single download. - Args: - files: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": files} if output is not None: @@ -6640,20 +6640,20 @@ async def unzip_file( Expands an uploaded ZIP archive into individual files on pdfRest storage and returns metadata for the extracted resources. This is useful when reusing uploaded bundles in later API calls. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - password: Password value used by encrypt/decrypt endpoints. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + password: Password value used by encrypt/decrypt endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if password is not None: @@ -6683,20 +6683,20 @@ async def convert_to_excel( Converts PDF content into Excel workbook output optimized for tabular data extraction. Use this for spreadsheet-centric review or data cleanup workflows. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -6726,20 +6726,20 @@ async def convert_to_powerpoint( Converts PDF pages into PowerPoint output suitable for slide editing and presentation reuse. This helps repurpose static PDF material into editable decks. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -6769,20 +6769,20 @@ async def convert_xfa_to_acroforms( Converts XFA form PDFs into AcroForm-compatible PDFs for broader tooling compatibility. Use this before importing/exporting form data with AcroForm-focused flows. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -6812,20 +6812,20 @@ async def convert_to_word( Converts PDF content into Word output for document editing workflows. This is useful when users need editable text and layout reconstruction in DOCX format. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -6856,21 +6856,21 @@ async def import_form_data( Imports external form-data files (XFDF/FDF/XML variants) into a source PDF and outputs a filled document. This supports bulk form-filling and integration pipelines. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - data_file: Uploaded form-data file (for example XFDF/FDF/XML/XDP/XFD) to import into the PDF. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + data_file: Uploaded form-data file (for example XFDF/FDF/XML/XDP/XFD) to import into the PDF. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "data_file": data_file} if output is not None: @@ -6901,21 +6901,21 @@ async def export_form_data( Exports form field data from a PDF into a structured data format (such as XFDF/FDF/XML). Use this for downstream processing, storage, or migration of form values. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - data_format: Output form-data format to export (for example XFDF, FDF, XML, XDP, or XFD). - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + data_format: Output form-data format to export (for example XFDF, FDF, XML, XDP, or XFD). + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -6948,20 +6948,20 @@ async def flatten_pdf_forms( Flattens interactive form fields into static page content so values are no longer editable. This is commonly used for finalization and archival workflows. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -6994,23 +6994,23 @@ async def add_permissions_password( Applies owner permissions and restriction flags (print/copy/edit controls) to a PDF. This secures document capabilities without requiring an open password. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - new_permissions_password: New owner/permissions password to apply to the output PDF. - restrictions: Permission restriction literals for protected PDFs. - current_open_password: Current user/open password required to unlock the source PDF before changes. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + new_permissions_password: New owner/permissions password to apply to the output PDF. + restrictions: Permission restriction literals for protected PDFs. + current_open_password: Current user/open password required to unlock the source PDF before changes. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -7051,24 +7051,24 @@ async def change_permissions_password( Updates owner permissions/password settings and restriction flags on an already protected PDF. Use this to rotate credentials or revise allowed actions. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. - new_permissions_password: New owner/permissions password to apply to the output PDF. - restrictions: Permission restriction literals for protected PDFs. - current_open_password: Current user/open password required to unlock the source PDF before changes. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + new_permissions_password: New owner/permissions password to apply to the output PDF. + restrictions: Permission restriction literals for protected PDFs. + current_open_password: Current user/open password required to unlock the source PDF before changes. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -7108,22 +7108,22 @@ async def remove_permissions_password( Removes owner permission restrictions from a PDF when authorized with the existing owner password. This restores unrestricted editing/printing capabilities. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. - current_open_password: Current user/open password required to unlock the source PDF before changes. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + current_open_password: Current user/open password required to unlock the source PDF before changes. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -7160,22 +7160,22 @@ async def add_open_password( Applies a user/open password so the PDF requires authentication before viewing. Optional permissions controls can also be set for opened documents. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - new_open_password: New user/open password required to open the output PDF. - current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + new_open_password: New user/open password required to open the output PDF. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -7213,23 +7213,23 @@ async def change_open_password( Replaces the existing open password with a new one while preserving or updating related protection options. Use this for credential rotation. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - current_open_password: Current user/open password required to unlock the source PDF before changes. - new_open_password: New user/open password required to open the output PDF. - current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + current_open_password: Current user/open password required to unlock the source PDF before changes. + new_open_password: New user/open password required to open the output PDF. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -7267,22 +7267,22 @@ async def remove_open_password( Removes the user/open password requirement from a PDF when the current password is provided. The output document can be opened without viewer authentication. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - current_open_password: Current user/open password required to unlock the source PDF before changes. - current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + current_open_password: Current user/open password required to unlock the source PDF before changes. + current_permissions_password: Current owner/permissions password used to authorize permission updates/removal. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -7319,22 +7319,22 @@ async def compress_pdf( Reduces PDF file size using preset or custom compression settings, with optional profile uploads. Use this for storage/bandwidth optimization while balancing quality. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - compression_level: Compression level or strategy option. - profile: Uploaded color/compression profile as a `PdfRestFile`. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + compression_level: Compression level or strategy option. + profile: Uploaded color/compression profile as a `PdfRestFile`. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -7370,21 +7370,21 @@ async def add_attachment_to_pdf( Embeds an uploaded file as an attachment inside a PDF container document. This supports package-style delivery where supplemental files travel with the PDF. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - attachment: Uploaded file to embed as an attachment in the output PDF. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + attachment: Uploaded file to embed as an attachment in the output PDF. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "attachment": attachment} if output is not None: @@ -7417,23 +7417,23 @@ async def sign_pdf( Applies digital signatures using either PFX credentials or certificate/private-key inputs, with configurable visible signature placement and appearance. Use this for integrity, authenticity, and non-repudiation workflows. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - signature_configuration: Signature placement and appearance settings. - credentials: Digital signing credential bundle (PFX or cert/key files). - logo: Optional uploaded logo file displayed in visible digital signature appearances. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + signature_configuration: Signature placement and appearance settings. + credentials: Digital signing credential bundle (PFX or cert/key files). + logo: Optional uploaded logo file displayed in visible digital signature appearances. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -7472,22 +7472,22 @@ async def blank_pdf( Creates a new blank PDF with configurable page size, orientation, and page count. This is useful as a template baseline for downstream stamping/filling workflows. - Args: - page_size: Target page size preset or custom size settings used for output page dimensions. - page_count: Number of blank pages to generate in the new PDF. - page_orientation: Page orientation for standard page sizes (portrait or landscape). - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + page_size: Target page size preset or custom size settings used for output page dimensions. + page_count: Number of blank pages to generate in the new PDF. + page_orientation: Page orientation for standard page sizes (portrait or landscape). + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "page_size": page_size, @@ -7524,26 +7524,26 @@ async def convert_colors( Converts document color spaces using preset profiles and optional black-preservation behavior. Use this to normalize output for print pipelines or color-management requirements. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - color_profile: Named color profile used by color conversion. - preserve_black: When true, keeps pure black content from being remapped during color-profile conversion. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - - payload: dict[str, Any] = { - "files": file, - "color_profile": color_profile, + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + color_profile: Named color profile used by color conversion. + preserve_black: When true, keeps pure black content from being remapped during color-profile conversion. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" + + payload: dict[str, Any] = { + "files": file, + "color_profile": color_profile, "preserve_black": preserve_black, } if output is not None: @@ -7574,21 +7574,21 @@ async def flatten_transparencies( Flattens transparent objects into opaque content using selectable quality levels. This improves compatibility with workflows/devices that do not fully support transparency. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - quality: Quality preset understood by the selected endpoint. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + quality: Quality preset understood by the selected endpoint. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "quality": quality} if output is not None: @@ -7618,20 +7618,20 @@ async def linearize_pdf( Linearizes the PDF for fast web view so first pages render sooner over network delivery. This improves user experience for browser-based document viewing. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -7661,20 +7661,20 @@ async def flatten_annotations( Burns annotation markup into page content so comments/highlights become static and non-editable. Use this when sharing finalized review copies. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -7704,20 +7704,20 @@ async def flatten_layers( Flattens optional content groups (layers) into a single visible page representation. This avoids layer-dependent rendering differences across viewers. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -7747,20 +7747,20 @@ async def rasterize_pdf( Rasterizes PDF pages into image-based page content at a specified resolution. Use this for visual normalization, redaction hardening, or viewer compatibility scenarios. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file} if output is not None: @@ -7798,28 +7798,28 @@ async def convert_office_to_pdf( Converts Office documents into PDF output using conversion options for layout and fidelity. This is the main entry point for Word/Excel/PowerPoint-to-PDF workflows. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - compression: Compression mode used during conversion. - downsample: Image downsampling setting for conversion. - tagged_pdf: For Office conversion, toggles generation of tagged PDFs for accessibility workflows. - locale: Locale used by locale-aware conversion options. - page_size: Target page size preset or custom size settings used for output page dimensions. - page_margin: Page margin setting (for example `8mm` or `0.5in`) for HTML/URL rendering outputs. - page_orientation: Page orientation for standard page sizes (portrait or landscape). - web_layout: Rendering viewport profile (`desktop`, `tablet`, or `mobile`) for HTML/URL conversion. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + compression: Compression mode used during conversion. + downsample: Image downsampling setting for conversion. + tagged_pdf: For Office conversion, toggles generation of tagged PDFs for accessibility workflows. + locale: Locale used by locale-aware conversion options. + page_size: Target page size preset or custom size settings used for output page dimensions. + page_margin: Page margin setting (for example `8mm` or `0.5in`) for HTML/URL rendering outputs. + page_orientation: Page orientation for standard page sizes (portrait or landscape). + web_layout: Rendering viewport profile (`desktop`, `tablet`, or `mobile`) for HTML/URL conversion. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -7861,22 +7861,22 @@ async def convert_postscript_to_pdf( Converts PostScript content to PDF while preserving page content for modern PDF workflows. Use this when ingesting legacy print-oriented document formats. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - compression: Compression mode used during conversion. - downsample: Image downsampling setting for conversion. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + compression: Compression mode used during conversion. + downsample: Image downsampling setting for conversion. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -7910,20 +7910,20 @@ async def convert_email_to_pdf( Converts email message files into PDF, including rendered message content and supported metadata/body parts. This supports archiving and compliance workflows. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -7955,20 +7955,20 @@ async def convert_image_to_pdf( Converts one or more image files into PDF output and can combine them into multipage documents. Use this to normalize scanned/image assets into PDF containers. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -8006,26 +8006,26 @@ async def convert_html_to_pdf( Renders HTML content into PDF with page-size/orientation/layout and related rendering controls. This supports report generation and web-to-PDF publishing use cases. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output: Output filename prefix used by pdfRest when creating files. - compression: Compression mode used during conversion. - downsample: Image downsampling setting for conversion. - page_size: Target page size preset or custom size settings used for output page dimensions. - page_margin: Page margin setting (for example `8mm` or `0.5in`) for HTML/URL rendering outputs. - page_orientation: Page orientation for standard page sizes (portrait or landscape). - web_layout: Rendering viewport profile (`desktop`, `tablet`, or `mobile`) for HTML/URL conversion. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output: Output filename prefix used by pdfRest when creating files. + compression: Compression mode used during conversion. + downsample: Image downsampling setting for conversion. + page_size: Target page size preset or custom size settings used for output page dimensions. + page_margin: Page margin setting (for example `8mm` or `0.5in`) for HTML/URL rendering outputs. + page_orientation: Page orientation for standard page sizes (portrait or landscape). + web_layout: Rendering viewport profile (`desktop`, `tablet`, or `mobile`) for HTML/URL conversion. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -8069,26 +8069,26 @@ async def convert_url_to_pdf( Fetches remote web content by URL and renders it to PDF using HTML rendering options. Use this for automated webpage capture and archival. - Args: - url: Remote URL to ingest and convert. - output: Output filename prefix used by pdfRest when creating files. - compression: Compression mode used during conversion. - downsample: Image downsampling setting for conversion. - page_size: Target page size preset or custom size settings used for output page dimensions. - page_margin: Page margin setting (for example `8mm` or `0.5in`) for HTML/URL rendering outputs. - page_orientation: Page orientation for standard page sizes (portrait or landscape). - web_layout: Rendering viewport profile (`desktop`, `tablet`, or `mobile`) for HTML/URL conversion. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + url: Remote URL to ingest and convert. + output: Output filename prefix used by pdfRest when creating files. + compression: Compression mode used during conversion. + downsample: Image downsampling setting for conversion. + page_size: Target page size preset or custom size settings used for output page dimensions. + page_margin: Page margin setting (for example `8mm` or `0.5in`) for HTML/URL rendering outputs. + page_orientation: Page orientation for standard page sizes (portrait or landscape). + web_layout: Rendering viewport profile (`desktop`, `tablet`, or `mobile`) for HTML/URL conversion. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "url": url, @@ -8138,32 +8138,32 @@ async def watermark_pdf_with_text( Applies text watermarks with control over placement, rotation, color, opacity, and alignment. Use this for confidentiality marks, drafts, and document branding. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - watermark_text: Text content to render as the watermark. - output: Output filename prefix used by pdfRest when creating files. - font: Font family name for rendered text. - text_size: Watermark text size in points. - text_color: Watermark text color as RGB or CMYK channel values. - opacity: Opacity in range 0.0 to 1.0. - horizontal_alignment: Horizontal alignment anchor used when placing watermark content. - vertical_alignment: Vertical alignment anchor used when placing watermark content. - x: Horizontal position in PDF points. - y: Vertical position in PDF points. - rotation: Rotation angle in degrees. - pages: Page selection to constrain processing to specific pages. - behind_page: Target page number (or selector) where inserted content should be applied. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + watermark_text: Text content to render as the watermark. + output: Output filename prefix used by pdfRest when creating files. + font: Font family name for rendered text. + text_size: Watermark text size in points. + text_color: Watermark text color as RGB or CMYK channel values. + opacity: Opacity in range 0.0 to 1.0. + horizontal_alignment: Horizontal alignment anchor used when placing watermark content. + vertical_alignment: Vertical alignment anchor used when placing watermark content. + x: Horizontal position in PDF points. + y: Vertical position in PDF points. + rotation: Rotation angle in degrees. + pages: Page selection to constrain processing to specific pages. + behind_page: Target page number (or selector) where inserted content should be applied. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -8217,30 +8217,30 @@ async def watermark_pdf_with_image( Applies image watermarks (for example logos/seals) with placement and opacity controls. This is useful for branded overlays and visual ownership marks. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - watermark_file: Uploaded image used as watermark content. - output: Output filename prefix used by pdfRest when creating files. - watermark_file_scale: Scale multiplier applied to the watermark file graphic before placement. - opacity: Opacity in range 0.0 to 1.0. - horizontal_alignment: Horizontal alignment anchor used when placing watermark content. - vertical_alignment: Vertical alignment anchor used when placing watermark content. - x: Horizontal position in PDF points. - y: Vertical position in PDF points. - rotation: Rotation angle in degrees. - pages: Page selection to constrain processing to specific pages. - behind_page: Target page number (or selector) where inserted content should be applied. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + watermark_file: Uploaded image used as watermark content. + output: Output filename prefix used by pdfRest when creating files. + watermark_file_scale: Scale multiplier applied to the watermark file graphic before placement. + opacity: Opacity in range 0.0 to 1.0. + horizontal_alignment: Horizontal alignment anchor used when placing watermark content. + vertical_alignment: Vertical alignment anchor used when placing watermark content. + x: Horizontal position in PDF points. + y: Vertical position in PDF points. + rotation: Rotation angle in degrees. + pages: Page selection to constrain processing to specific pages. + behind_page: Target page number (or selector) where inserted content should be applied. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -8284,22 +8284,22 @@ async def convert_to_pdfa( Converts input PDFs to selected PDF/A conformance levels for long-term archival compatibility. Choose the target conformance profile that matches your compliance requirements. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output_type: Output mode for endpoints supporting inline or file output. - output: Output filename prefix used by pdfRest when creating files. - rasterize_if_errors_encountered: When enabled, allows rasterized fallback if strict conformance conversion encounters nonconforming content. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output_type: Output mode for endpoints supporting inline or file output. + output: Output filename prefix used by pdfRest when creating files. + rasterize_if_errors_encountered: When enabled, allows rasterized fallback if strict conformance conversion encounters nonconforming content. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": file, @@ -8334,21 +8334,21 @@ async def convert_to_pdfx( Converts input PDFs to selected PDF/X conformance levels for print-production workflows. Use this when downstream print tooling expects standardized PDF/X output. - Args: - file: Uploaded input file or files as `PdfRestFile` objects. - output_type: Output mode for endpoints supporting inline or file output. - output: Output filename prefix used by pdfRest when creating files. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. + Args: + file: Uploaded input file or files as `PdfRestFile` objects. + output_type: Output mode for endpoints supporting inline or file output. + output: Output filename prefix used by pdfRest when creating files. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. - Returns: - Validated file-based response returned by pdfRest. + Returns: + Validated file-based response returned by pdfRest. - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = {"files": file, "output_type": output_type} if output is not None: @@ -8382,24 +8382,24 @@ async def convert_to_png( Converts PDF pages to PNG images with configurable color model, smoothing, and page selection controls. Suitable for high-fidelity raster exports and previews. - Args: - files: Uploaded input file or files as `PdfRestFile` objects. - output_prefix: Filename prefix used for generated per-page/per-file image outputs. - page_range: Page selection string/list for image conversion outputs. - resolution: Raster output resolution in DPI for generated image files. - color_model: Output image color model. - smoothing: Graphic smoothing mode for image output endpoints. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, @@ -8440,24 +8440,24 @@ async def convert_to_bmp( Converts PDF pages to BMP images with configurable color model and page selection. Use this for legacy bitmap workflows that require BMP output. - Args: - files: Uploaded input file or files as `PdfRestFile` objects. - output_prefix: Filename prefix used for generated per-page/per-file image outputs. - page_range: Page selection string/list for image conversion outputs. - resolution: Raster output resolution in DPI for generated image files. - color_model: Output image color model. - smoothing: Graphic smoothing mode for image output endpoints. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, @@ -8498,24 +8498,24 @@ async def convert_to_gif( Converts PDF pages to GIF images with configurable color model and page selection. Useful for lightweight graphics workflows and compatibility scenarios. - Args: - files: Uploaded input file or files as `PdfRestFile` objects. - output_prefix: Filename prefix used for generated per-page/per-file image outputs. - page_range: Page selection string/list for image conversion outputs. - resolution: Raster output resolution in DPI for generated image files. - color_model: Output image color model. - smoothing: Graphic smoothing mode for image output endpoints. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, @@ -8557,25 +8557,25 @@ async def convert_to_jpeg( Converts PDF pages to JPEG images with configurable color model and page selection. Use this for compressed photo-friendly page exports. - Args: - files: Uploaded input file or files as `PdfRestFile` objects. - output_prefix: Filename prefix used for generated per-page/per-file image outputs. - page_range: Page selection string/list for image conversion outputs. - resolution: Raster output resolution in DPI for generated image files. - color_model: Output image color model. - smoothing: Graphic smoothing mode for image output endpoints. - jpeg_quality: JPEG quality setting (1-100) controlling compression level and output fidelity. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + jpeg_quality: JPEG quality setting (1-100) controlling compression level and output fidelity. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, @@ -8617,24 +8617,24 @@ async def convert_to_tiff( Converts PDF pages to TIFF images with configurable color model and page selection. This is commonly used in archival, scanning, and print-imaging pipelines. - Args: - files: Uploaded input file or files as `PdfRestFile` objects. - output_prefix: Filename prefix used for generated per-page/per-file image outputs. - page_range: Page selection string/list for image conversion outputs. - resolution: Raster output resolution in DPI for generated image files. - color_model: Output image color model. - smoothing: Graphic smoothing mode for image output endpoints. - extra_query: Additional query parameters merged into the request. - extra_headers: Additional HTTP headers merged into the request. - extra_body: Additional request body fields merged into the payload. - timeout: Request timeout override for this call. - - Returns: - Validated file-based response returned by pdfRest. - - Raises: - PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" + Args: + files: Uploaded input file or files as `PdfRestFile` objects. + output_prefix: Filename prefix used for generated per-page/per-file image outputs. + page_range: Page selection string/list for image conversion outputs. + resolution: Raster output resolution in DPI for generated image files. + color_model: Output image color model. + smoothing: Graphic smoothing mode for image output endpoints. + extra_query: Additional query parameters merged into the request. + extra_headers: Additional HTTP headers merged into the request. + extra_body: Additional request body fields merged into the payload. + timeout: Request timeout override for this call. + + Returns: + Validated file-based response returned by pdfRest. + + Raises: + PdfRestError: If request execution fails at the client or API layer. + ValidationError: If local payload validation fails before sending.""" payload: dict[str, Any] = { "files": files, From 365934fb6ea26632c3650b3e8e070ebba4686620 Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Thu, 19 Feb 2026 12:08:51 -0600 Subject: [PATCH 13/18] docs: Document per-call request overrides in client configuration - Added a new section in `client-configuration.md` detailing per-call request override options for `PdfRestClient` and `AsyncPdfRestClient`. - Explained new arguments like `extra_query`, `extra_headers`, `extra_body`, and `timeout` with example usage. - Clarified behavior notes, including merging and overriding logic for query parameters, headers, and timeouts. Assisted-by: Codex --- docs/client-configuration.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/client-configuration.md b/docs/client-configuration.md index c774b47c..1ebaf0d2 100644 --- a/docs/client-configuration.md +++ b/docs/client-configuration.md @@ -113,6 +113,41 @@ with PdfRestClient(headers={"X-App-Name": "my-service"}) as client: info = client.up(extra_headers={"X-Request-ID": "req-123"}) ``` +## Per-call request overrides + +Most endpoint helpers on `PdfRestClient` and `AsyncPdfRestClient` accept the +same request-affecting keyword arguments so you can tune one call without +changing client-wide configuration. + +| Argument | Type | Purpose | Default | +| --- | --- | --- | --- | +| `extra_query` | `Query \| None` | Additional query parameters merged into the request URL. | `None` | +| `extra_headers` | `AnyMapping \| None` | Additional HTTP headers merged into the request headers. | `None` | +| `extra_body` | `Body \| None` | Additional request body fields merged into JSON payloads. | `None` | +| `timeout` | `TimeoutTypes \| None` | Per-call timeout override (float seconds or `httpx.Timeout`). | `None` | + +Behavior notes: + +- `timeout=None` means “use the client default timeout profile.” +- `extra_headers` values override same-name default headers for that request. +- `extra_query` is merged with method-provided query params. +- `extra_body` is merged only for JSON requests. + For multipart/form-data endpoint calls, `extra_body` is rejected by the SDK. + +Example: + +```python +from pdfrest import PdfRestClient + +with PdfRestClient() as client: + result = client.query_pdf_info( + file=my_file, + extra_query={"trace": "true"}, + extra_headers={"X-Request-ID": "req-123"}, + timeout=30.0, + ) +``` + ## `no-id-prefix` header pdfRest supports a `no-id-prefix: true` request header used for From 038f1c06820803891ae0ba0dd46b02503d41d24b Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Thu, 19 Feb 2026 12:36:47 -0600 Subject: [PATCH 14/18] docs: Add custom branding support with new styles and assets - Added a new `brand.css` for custom palette and branding styles. - Configured `mkdocs.yml` to use the custom primary and accent colors, logo (`pdfrest-logo-dark-bg.png`), and favicon (`favicon.ico`). - Registered `brand.css` as an additional stylesheet for use in the documentation site. Assisted-by: Codex --- docs/assets/favicon.ico | Bin 0 -> 15086 bytes docs/assets/pdfrest-logo-dark-bg.png | Bin 0 -> 7443 bytes docs/assets/stylesheets/brand.css | 26 ++++++++++++++++++++++++++ mkdocs.yml | 9 +++++++++ 4 files changed, 35 insertions(+) create mode 100644 docs/assets/favicon.ico create mode 100644 docs/assets/pdfrest-logo-dark-bg.png create mode 100644 docs/assets/stylesheets/brand.css diff --git a/docs/assets/favicon.ico b/docs/assets/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..8b576ad194a8247b4ef1bba072272d4dd32e36e5 GIT binary patch literal 15086 zcmeHN2Y6LQ7JkaQuIuji=~i8J&9|b0f{J2W8`##i7F4PrMKn|qkS0P*Ae0blLJ5#W z=|qqa5Tu40ga|?m34{{T6H-VaJvsaT=idAB@_Y#)gq7Vdlkd;Gd+*GgGiT16Idf)g zwySJSY!5tOL+)lPwHLm5=DbqDxfQ&S^r z{NE^nMhP@Zpiu%1BLVMwy4(P~4m<>0>#9|}ZvtEg+z8wP+y%4(o&sJ1+5ugFo`5^h z7w8Z4GoO1Q?+UyFybL@IuzpkECgAtLHLhs8dWW)CS?}??4Uh+90;_;NKqr7aj0OCG zmB3cuAP@(n0NFqRPy&<#6@b)&O0yixvmWaw0Wm-X5DLrzMgXM$B=8S_^8GFFci=5x z1~3F@!ag8(15N-IZPFpE=U*bHEb@T_-~bQ~kVp2N{7{})t(E_)@jKXj|4Z;%ADZLH zyOqHENIU<{yU6&vJIT1aJ8JHYXZyEbc1$cjs2g1^-kIZ>Iwj=Q=b;`F)Zuek`oRRv zCqLN3s&}R2oNMhY{_*>Fzz*gA-uGnZ?A20~e_qOpOC>KOTY@`}#aMK@Qh2xc7~sJF zJ>Wf6We-`OIS?aODlIIQMeloEiTwLH@ZTQ%mn;9RdrIQLW6FM|R7y!lO*dpPxLS*`r?k?Lm>!c%Z4crbK(|0cTuS6eQrNZ0-^kc0|dE|rYG%){H zeKJGRj-8Q;iV9a%rJ}rC(&G~3n<2AwJiO75DXn`+{P)rJ@`dN}Wx-n`F%C7_jY9DJ zCh#=Cb=?ZGt1&-02Q5D1_eZN;-9CLqwSGk| z-BdNVFAx7;f%mYB<$ujkKea6u|ED6NWa53@WQ)_d&~{d}eev?2|Hg3DS=wV)>jm0g z0BoqDLEp{6{!mA$|M2CgH`cnfXMSikIUfn#rFL%h;F;CNCH3fO*zi8adPN%vTbpzw z&Zx__YnZ>B8??_W`ud3fi-TnLOM}Jlxq&JpJFmuiGY!wi+GWk(pZO2P^3Bj$;)D03 zA2PsK&ZV5S^UpEZ@Wn!%zjIz0BIlB;zEQ{aFWxAAu#xm(=e{~r?LI5lHh=5M`M3QpMR}mpGb!`QfZ(awndwl_~UWN?t~QOowtAEkJOmc z##)Loo`AJ$Z(x}HyTwOVLYkb3jFHUK$wGU~_ZQ-yWt>y=h6wvw1D;EOZoqO!{`q^W z?^5*}oa;M3Q`XDfC);(C`ZeR3zH)3^qB;VAzc z@cIlezZ(DWAvgwWN6t~dB|r0=_JzIxQCeK0V;Z$?x2_A$J`CsC^r!j=*Mzetldv8X zt1eI<_`5Fhr<^iRr)c|gULGveOM?3Auoq+ufqVPO)%Z8(0eu0^jI$!nYt_OwRfI(#N8WhbWVob|k; zz0NJJkF+5Uyl%no>w#f_>sSNEf;`gqXI%yN#E`K=J2n2c>=o;gKG(0b*mz~J8vj@u z>06)Nec1R0{o>r`7_aE#qx+9lgQm;6F#%Y^IR;99y6O9K4jBHAVUud)r!G9#REB+_ zjMHKb8CUT?N@E0+(?+i#!~SA)tocj-oqH(iUCH?(9Z&cIl=u54|1aP-V^^1jZ>wF4 ze@7k3j89SjQ`aZ-&-c*}bbr9P>nd@*__B)!*Ax27txf)0;5TDnmz96E&%ImdaDUl7 zca6^PB|XNg&9!K=kK6}@j+m``CiazfpL2#bo&FWuKzYXNZZi458NYwB+PK^~{Xh#Y z=Rf+u@3aro;8XiOKTu}2>8G}Y{WJNa?YYh5-wnTyUv9qZ(?0pNbj!hRvJdBh=S=?F z;y2do4gS0hDnuV9EDO{Jsi!4zN{p>?PBEWu?01eSM%8vZerZCog1Yn$=zWq3W^l2j>1YQNa zfepZ5Q~tlf?^^(k1@WD$gzvuw{s`OwJPN!5u)hO<(ZEE2G1R%hLLeBRjF<-k^MF|Z z*Lx3O2+$jN7kD0c2%takCx9`Xt6lNIclbtLGa%n1P|kzp@LX$-BKjS9oswm>Yso#> zkVO~#>2qCk)C*#Te9A4niAeqB$9r0CKpVh*PYZXs8dIYLoFxE%gnng>cRcXzYJk2G z;}X0xL0{@Gz+X-L8TlUo-W8$W2aT^=GRx0Kz6|IH(5LJG@C?Nh;5Ww7=v(drA_4lM zM}b%%2H-xCJ}~ckYzDpt=ofwg&=-6OXbF&C`kIdbJ%QT*`r4#H|GNyJFJ56jTR!=v z z?=N+a>#(n_t)2RQ`vLT+M@@i5yw|bA?`vHy7|RWOceHWGqiSDNUph6_O90*Gz|Fv6 z?)moxu2=euu`g&hQe$IQOaNtm){gbfh{c)rQXIxj$CL3n*JtzvXp{SDtRFL9 zW1J50IjbMk@lSw0K$#LcbktfIg>ltagQ9AxhdU^}bteK8(+^1););)}D zoF6cb?A5e`EdOYdJ+}YdxL~D!@WS-BgZ4g`^l?VczEalgBU2L2I_5#PJfCKY+i^(a zQ7pIY!+O!*1KPAlKkNVeH%DmyHGX|OLFw@fnlW<5@0ob6&-gH7$c&$JjF?>YKj8IY zRpXBMHE9Cj0ByNR-b$o)0knh&vLbcWi5#$v#-2MK-x^j z1%+BJFFo6?lg{)lU1fRRL7;4@Z=gF9;F_lV@GOrylarJorA0UsL4Qbx`o_8KjdLuP z<-LZ`;j<+r`jpZ)V%f#ef8$ihnLh7o(WZxeHdh$0=lKWXevI#MjaB`(c;I~;+KsPZ zTbA_lmcVyDgAVovzxEiX^1x@_LkaFQR?qS`Ph6z@vX4q1ayo!BLZu_fR zHaQwJZv_}Lsz(1}pUDGtgY)w2sbpCSxzXnPAm+_GL9{>Cof+Cp(~hkIooj#|z$KrP za6O>@FeYuk_X7Fwo&wLisXsi24(c#QCf$!%dvlGQ(f8>GP!}#q2CQ$7DLb`AU8jvA zxXzoj_9DL#pr6Kf^oeMTP6LI2Rj#3Ou6OxB7Qp_d0`~(S0h53y0Q#`E1J43|foTB8 ziF1^8>LkE3m2`mqT&4;7a%}Gma15YL*$#vNT;qlV^leFlG}{A1fm;A;H|f%0#&`Nh z*8}vGsIN@{`YkPh`+%0fJ-}Un8$f@Ca=i|yvmfq~c;n0edkLt)bov*Fu!9G}2H__7 z+X1#(5_Q=Qs}A37v)RTvk4;mMlFqa+#Ud6twHS!k$&S!UE z2rvTR93KSq0^R@~12`Y=0Ga`B1KF_0xyXwF+M}9m8~33sM|+Y8Ou>5Ad11Rz#qzmWb@;eX`H2G2lUkGT$T4duGQyAX?UADVaZ zxJC!HA8oDEtiK+9&z_KezUqr59gdS6++)~^y$5}nGh*Ng3*gM1LEh=gYiDMjw9L)a8b+)x7g*$R>rn(uYoqiI;Tvw7hTY_x#5a zhrI@Uy~3P)Il5t=us-*oyywSt6YCe(s#rkpZSnpp>+xO@@LhR+!^O`O>%KJsa*}qSo#rj}=(Y>8I@kl7SR}`cqZk z{H^OR{YvA02z`od@W=Je8)ysM3ET}Z9?}~a35*9O16%{WfMEc2_%(n!-wJ4Pk<+EY aiyN^}#zT#msz+@UXn~N*pE1g_&VK;y#R-A{ literal 0 HcmV?d00001 diff --git a/docs/assets/pdfrest-logo-dark-bg.png b/docs/assets/pdfrest-logo-dark-bg.png new file mode 100644 index 0000000000000000000000000000000000000000..867716bedfda56bc5a84e5756ea38d173fe8d38e GIT binary patch literal 7443 zcmZ`;2QZw`w_m-jRYG*pOSHubR=0YTkcbv#Sv7j^b*&A8RYLSgkVHukM2p@#(W8sr zOBNyC{%792dGlu8d~?5Z=id3vx!>G#?*0AF_v(qhCM7vDIRF5l)Yein!r3ldQzj+G zz18Dpi*bg-PRmFS00`y-03wk9z%_0tavK2f0|NlNHUI!L3jkp7%xyH3$4wC1KGswN z-2LY%Y$;8{jga_i>#39M;@_iXk^TIKat;8%cM5)H>T3iK;PCYJaBz0D=kN{kwC4zP z^8^57US}Aq)GdHXfBD3-s}K`Tc(D%7U$lsZ+<>arFXjHZ-D~XvaX8qd=(a}uD|&Du zXs&gC$4Y( zU(M(FVo1qq;%U54C6DC5j-p~Sv?!1*k*zQ7=XVfa;&L5cBqjk?u#IL&Cqf=a*yE9> zkgI;38vhgz;#}LQe>L{?(8=}dJafo27jrqKQL7hw!8xmE-Av~2;9xWYt3V(=^y9M2tb{=4#P1Ve561lytH@1+7WSZ$*l zGmk062))I)kfL3-o3-yoBe6HDS3_qU%H+2p9?JY)poqyI_!%XlCJcrD>)<1lp6=jW z@v--g38ers;(rD{ThZKP3nM>Qo+kSjEe;`5rf z+hfX7gb_RG2B2h^S@<G>mierax0D=GU;Op#W@8b){ z#qxVJq(1>s?9&!O!GceFRMha-Z#`t5N!#bmCn zrt&Os{va<3hEt88+-dYEmg&a>7YUvdO$ccwrwK z)FX5>(tIR$bQ6B`w@K5@DqPO$`_^x<6_VDMY^3HkryO@Nw|>d`b>wx456sFZ%|+2@*b$UQRU345 zAQ@#r-4Tj63;LN{#YV}w;castO!AS~rToqWU{5;Ez=5nJz}u6#2d3WC28g5H7E-}e z{R@el2=y%rD3!}DLJIu!prrVdQB0(1Y*mUrx?XQ!B<_U&=s9;8PmkG&4+;Ko3RT`C zHyamYI#^)cI&HGd%&Du&2Yx>W!j^H`9iL1RDg4>Qoc2mp7Uhl`DT(>m& zLpZj?|8NfkfVKdTF4inN^s7#v#P(K9=Z0#%q8uM?nq1fC(nIPzng2SH&F)_7& z!gS`Di!Xk&KtuUCg14kuC9-O5I`$gEC2-p;zHB4HPH3<|WQm~eJzysXyB>7{UmIi` zBJx%xo0@I-X~Z!+QobwRIPuc&lxb(-6*qYZzwN(+fR|#u9Ck4WB9(9VqY(7u(VTf5 zso>QcYMpkQh{UBNydsQD_M2=i-A*;<`1oDg`&Q4oo9QLrnn}JEEWRRyT~kZ?)?*DL z%3sIG>7Nc91{cMM^V5I;G5KMMJWCvF+s%ZgFK-nnPGUB=foljfVF%$NdM%uqX0(o5 z*J(CvBa16+TdS{ozn@*J&W4dsXnN-OO>(*8{E+P_xd>`I!F$(9D0#6a0VcO+RA(sO zge>#;j(%Ke*>nEc2*0s)J#6wXmutudp!M(4({q2&teVU)G}{OmB6v)+!feC$iLeTu z&Y@dF_?`LEqATYI(RYeK8gE_k``djV^b2sGOi|)&BpboZVD%{Cr$@%wz+2e>=H-S9 zD{}+CcQ5?OC&6ZomD$7fZisfG447L<>cJUBXY)VQ6lA*Ytj|);HB}V${5mElbNP_> z(Qmvv{AO;7`Y)VKw-spEMM#@LWO&HUmZaT>vWTnUC{*BwQ6aVt2)md8 zM$t4!Mn0)Q$K%zA`L1Y+hm*F*cZz!VVr}OdnWKa1Tr@~cGu9>~R*J~7P&zys2mWg0 zffa?MrXlGHx_aNyIWaN77C$K&~n?A|Fktogz&(@?6F%kE|J z{UY-8C+d~WNkWpgHte?V} z_}rUf+Eb;BU-(|(x8*UV8wnJHfiX@z`o3U&`Fube(cV-hGaA&Bmnov|zuF&-0(bB6 zdjTD3d9{{aKi!$cv<;4?saj9dpvHn;!-ycytrQEIqf_<{3)72QKIP;^K!?U#E_@$h z;f#Dl-S7biddYw}V8@k8evnP;@#Hbr3$h`S-LP}?vu%ysQa7}{AQesRXH0IwGXZtF zL&xK);5`20g?S;G9+}^M(Mjc2>r2(Ks9ZZHUZ`$gMNX3J6K57j4Q{&Ww=I2PoF+Qs z)3e=d*7F@v2eph|cH2w)a?=-ps6q|-RITUJ2`RtOjy+zbRDg(NFbo*vPSod8Pj)E- z7E@v)P&BG;8{?>lbwK2%G zOkI$4JNqTeiBrd*4b-Z*fl6Dg8ly~`3{BywJZM|IlvJ1X6n`W5Xe#u3oBkdpheQye z=IN|yg(-U&l5r;z!ZhNpi9Dg&&}lSyhNCVQjt;WOU(W>)MRttCv(^)*iTTs zmn3)qdu({w@9z4L?TjKz@XFxE}Jm(Ox)v2_n||k z5t!G2aTv05^m@#*`E^HXvv~a%$ZxsI$=ZV~R1`Vl+gnlf=8>?sFA`&hbJbP?KaS$J z0)AkM@_56Q_-I}wWhKsVCv{w*4S1g$!pF;`D^17wLZ;!;jG|S>T5i- zs3SAccPx)KIpn-bfUD%i&m^9na~GvE?C68?iGcx#weYWQqb$?skC$ZuJt zI`2)gNyytrWoWAK3-dP>741A>j>g_{0DH;!pixI_1MMJA>>Wa=N~^=K6pUMAG_`d2 zwN7P&Gi8)A$6(n%Q(~%@U(AQ*%kGEd(eXo4DF8ONeYuI9*C?PWWQPz=Oc z^K7YEtAlM@eZPRMr~0K&g+;@h?4o%-RwU7cfn12Q(j_hAzZal9&d2 zNex&ce`>iA4LHenO152m_*!VAz64$HTzQUgWc*^_!gtKpWwHN=s=zjM$mTscHX5|9 z67|LfKfUB*uJxwS{A}w5R%6@csJNAXt?YPK*Xx!+{Ei(c&|LK zy>(eDBE9mD;n{{y)5de*pS@-^_n)dXKkFD?GF(WB-t-qwGc_qg4qvlwjF z^qJ6K@qP^PBQL(6{se+0d9w?6B{m01~ z?)e=1l|@W-fT-mjXLSdi+rAq4IB&8TdLJaIP?>;#M|ne6^-vv?w~epX75u)}Zw5aT zFT!6QCih{HVw5W?=`W3KJ;jPKr+s84VWl#V4x7>_gJM}rq+`jrxQl74-w!3V4y*{$ z5xfp2zA89U>>pR4w5@w)i?2}qmrm?vhxF**zOifIp3Z2UiHB+5`+%dOTB{-h%1*>c zhqvf=-^!z`{II|W*nca|=6g;1?UByjPL6B@3Wjg2W>x&d6aemIg#N%^ytBJ-gbeRVkw-1MTpB(FZ>;kRJJ+wEa9bztT@F~t`t zl-<8PotvBJ4O0q61r0h%IG!XLmbEx%r<=TaQsW98E`^eDsI?&6q`K`7n_`UOP5$Js z)i2*t9K3FE;-)k0M{o}g)EmW@H2UW^-tn$gVMe5h)QHzvmy9(RSMMuXYY28wTYkFs zQ6XDT%RC}J#9khFH+S9za9>B7eD5u5`*PwhUupm0&K}?)@=UXN$AGhY`Bw@6WJ&^d z*m{8v7askH$Hq4j{)vdLf^u>H-=N{9us>A;8HxvCJF~92!E9-FIKd>4?nu2JE zQ56?inkM`gs&VKb9#6=*EozBqt?J11-rW?k0Onq!DT%^y%5v#Tyyh;T$0g`d^ zU6Xeq<*B@;EjN8`efOAiIQ2Q7zcWfcQvx-E0-47-|8VodG2lqb6$Z8SEuWFSndDF$rNkyL+r#tRnB=AfGngNX&p{oQfhf$2RX zZtqgzuPxxP_^6&f8S*urDpKfVWAz|wirRs3R5w6!LT;JthJ;I}*qjv~-TIF8BsYR? zHsMk>+^#myudK*2(;5FA8q^iq$$oC5>^?wu2W#WE5|CizrZMmYsjd&j&IND^eSRRR z?83)JCCP|hN_{c&#|mlIyZeNKJMqL0DY)qnF^^Ea?p=%*(~X8Nn*7l3qMXAwc8S%n zEgk7k6jR?MoJL;)_A|SL+mxdHd5=f6K*)lMr6itVVqN5$#>n+Hk0@)(#T(CG#=uKH zPtr@E>c)=gfa^B;lPqZ{wbSUP=)1JAt)7o&4<8QmGfpeKR%)?~;aRK3H8QT4C8HPN zaI|N5O1}Sy)DLj~3+oWP*~I-#V%6hT&2)3IW|pdoWe_8~+CBLG^Din$2Xlo|eEof1jwWEt*=+|}GhRmbSZwL-;NH3(>X z;o%Nq&uO<^OUqr|mqR}wXQss72vQq~6B_3Fe)&P&!J%Mk)jmSL4&Wahcn+*J8N17@ zyp{^$wvEqeRzOo%FuW~Qc%SoZD(q=%Tof5Qc#=;z$@sH+u(NlKsuz$ zA@`V|`lSF5*7m(rxEQ{9WZ;k9n?^h_@yDI~t&j>7W|n)BDH$;k5LMXIlk;3MLcO>& zt)iwja~?L_3GYDl;|TE@;H+(LDHKmgdZ-tih`BYFc455dqCG-qSk3W8j@?#FRrpi> zvg(ROVC$?s%aV~Quk9j}J}eM32WQ6oL(G+iI5YaToxt_fh*% zO#Dm{0mCNCv~i@c+RrBoYDXUY1V$mCdIg<&{4j8It8(+2ssdZf%=RlN^-bdlXR(EI z{QD3VC;7QUCIVygN3m34_V;i!MKj2lto;c>pBsDVYy!&)irVHcO-+GXb=0 ziH5jf8ECNA%`x0~6x8O)`csnXko*2Cs#qI=Vkf!9;W`nL@2f|Z=i4(MLZ6f6cr>A; ze*}o&Zi{oQMxPL=c$mN7q~l-5ZvE85@!?Cg5*nYatjQ+oap$M;gNlG=!kZ?AxcgjM zxsxoOSPl}*P@P_%`zaUKd{;_fu?x?bN5(~c%XJv>D?e|EJuV)YC~_mfIuVU%qKUI) z<0^4RN4LS)fM&`Rz211Pk(Ltgz*-2{SX@FtkjIA%3)g`R#W5S|6IO) z4J?88`5d&-AmO+EZT3$%A0^q( z!TYv}_Z?l!o;?~Py-6J}*@yC^iQXHUNU6A)64poZryCX8j7n-=O-ZxAKk!XY0?-WVoBdNaA z2a_Z3+eSmfJ=77`$z0?id_ro{sWZp0%;jsEsslxd;b!G0+zteFxs zMF5mrpT{6_eY-wqMq;@e+lafU;9P6n1bqW@0Pa@;+S(5Y|54D$RjNF6F4x$y{&|0)*j|JP9M4oWH?4W9JcnpHSl7c9FS z){368RWtBUQc40JpJ^4J=eeAnE~v;y8>~36JU_;Kxsx(!vCA0T%P#!lm~s?$stC;v zc`NStu$Vs936GK+KDM}IfTJ?=%#AyH>|NiYu@bR)A#5X5M&^cnKX=sApV1jTp{wKT zK@>{sIQobk=qdQtozw0l7pIkR)Oajf|4YYJ!V1A}1?fpi{=R2?mH1Q>ib)?}8=-}W zUME?8oC$Y|A+5Tw6<5n9YEwmLl;G2FGE?s*tj`r&Y7JE$%JjNSj@(F=d)1m9%y0&$ zu1+OCUQj{ceN;KmkwET5qp!X#Fb9aNi5#7|$aO2EbLsqfv1iqRHl2-^5usXeTexSP z?3q_k(?vk*ZW!?`W3qQ%vH-?$bPz?-8*wEguXFe-VLP=_pxjmK+ST}z41##r; zOUZ_1$QC|ACAb|L3YS!qu3oHsu-AqlR4upT{Bfe{?9y>V_VD#gLK00WV}%X$dQjhb z&R0YKgWZ{~jGp8{r*?Z&R-5m{j7$>dx5OJ+T_7Y*w~3()?FusMg?lFq%i?W;ynu0k z6bbJYVaRGn3y#p7d@Z;FsSHyQTjmoR+-{9S-pQ(M$u*ularcq=yMiFSCoL3hw7(o4 zJ>4V95SMW(w3roB$TZjiQ88}y>ElXGTf%bar@Zqt)O(sMGuFpueM#`2`heNlK%W>X zO)|^5ALSFQ4h3#s&4T2{g5sYdoOFg)hwRYtA|#fwv{W?@uhcrhgb`aX-IHc6t}%{%dpk3)Yd(tdf_U%I>HUCZ3Q9 zppiN>KPo^x*DZg6D2@2kY%&*4#S6L&8Vb=s&?E7np7K81SlU1LG zWH)8wYUujqx>))u9OioHjG95xaWy3R#f`|HuXbh8`SzKvuBtacaWzPG+}{w^&CA*xyM>fO zg~{yXZmmz)GR%D0B*s!^YLMDT=J5&wZL6X99rOX(d4vIe)IiGmBJoN%?6q_lMJ=qN zs8xu#g7s>{>#gsndRVf2O_DVGx%924z~+0O$Ai?4IaK+1DF(qH_pf#Qx`Jhn{s#Zt zyuywpRZ;dqKctNB>;sl{1e^=3A_=;8%gl3np~AxpZg6)XdO wj;cqF_=k5HtU!t}xEdf^p^w=5PuNZ)~y1rVas!jBN0T_YB^#A|> literal 0 HcmV?d00001 diff --git a/docs/assets/stylesheets/brand.css b/docs/assets/stylesheets/brand.css new file mode 100644 index 00000000..52eab576 --- /dev/null +++ b/docs/assets/stylesheets/brand.css @@ -0,0 +1,26 @@ +:root > * { + /* Keep body black-on-white. */ + --md-default-bg-color: #ffffff; + --md-default-fg-color: #0c0c0c; + --md-default-fg-color--light: rgba(12, 12, 12, 0.75); + --md-default-fg-color--lighter: rgba(12, 12, 12, 0.55); + --md-default-fg-color--lightest: rgba(12, 12, 12, 0.18); +} + +[data-md-color-primary="custom"] { + --md-primary-fg-color: #0c0c0c; + --md-primary-fg-color--light: #1a1a1a; + --md-primary-fg-color--dark: #000000; + --md-primary-bg-color: #ffffff; + --md-primary-bg-color--light: rgba(255, 255, 255, 0.7); +} + +[data-md-color-accent="custom"] { + --md-accent-fg-color: #d14081; + --md-accent-fg-color--transparent: rgba(209, 64, 129, 0.12); +} + +[data-md-color-scheme="default"] { + /* Body/docs links */ + --md-typeset-a-color: #5b2a86; +} diff --git a/mkdocs.yml b/mkdocs.yml index 8d70eac9..6546c793 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,6 +7,12 @@ strict: true theme: name: material + logo: assets/pdfrest-logo-dark-bg.png + favicon: assets/favicon.ico + palette: + scheme: default + primary: custom + accent: custom features: - content.code.copy @@ -35,6 +41,9 @@ markdown_extensions: alternate_style: true - pymdownx.superfences +extra_css: + - assets/stylesheets/brand.css + nav: - Home: index.md - Getting Started: getting-started.md From d61291f75e071b997fd03bee8ea5a5c2d9781e98 Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Thu, 19 Feb 2026 13:29:01 -0600 Subject: [PATCH 15/18] docs: Update branding and introduce custom layout for docs site - Renamed the title in `index.md` to "pdfRest API Toolkit Python SDK." - Added a custom sidebar separator via `brand.css` for better navigation grouping. - Configured `mkdocs.yml` to use a new `custom_dir` for overrides and branding. - Introduced `overrides/main.html` to update the page `` dynamically. Assisted-by: Codex --- docs/assets/stylesheets/brand.css | 11 +++++++++++ docs/index.md | 2 +- mkdocs.yml | 1 + overrides/main.html | 5 +++++ 4 files changed, 18 insertions(+), 1 deletion(-) create mode 100644 overrides/main.html diff --git a/docs/assets/stylesheets/brand.css b/docs/assets/stylesheets/brand.css index 52eab576..76be0273 100644 --- a/docs/assets/stylesheets/brand.css +++ b/docs/assets/stylesheets/brand.css @@ -24,3 +24,14 @@ /* Body/docs links */ --md-typeset-a-color: #5b2a86; } + +/* Left sidebar grouping: keep Home + Getting Started visually separated + from the rest of the navigation entries. */ +.md-sidebar--primary + .md-nav--primary + > .md-nav__list + > .md-nav__item:nth-child(3) { + border-top: 1px solid rgba(12, 12, 12, 0.18); + margin-top: 0.5rem; + padding-top: 0.5rem; +} diff --git a/docs/index.md b/docs/index.md index 479b12be..d79c6dd1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -# pdfrest documentation +# pdfRest API Toolkit Python SDK Welcome to the docs for `pdfrest`, a Python client for [pdfRest](https://pdfrest.com/). diff --git a/mkdocs.yml b/mkdocs.yml index 6546c793..f74272ea 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,6 +7,7 @@ strict: true theme: name: material + custom_dir: overrides logo: assets/pdfrest-logo-dark-bg.png favicon: assets/favicon.ico palette: diff --git a/overrides/main.html b/overrides/main.html new file mode 100644 index 00000000..a69cb38c --- /dev/null +++ b/overrides/main.html @@ -0,0 +1,5 @@ +{% extends "base.html" %} {% block htmltitle %} {% if page and page.title %} +<title>pdfRest API Toolkit Python SDK | {{ page.title | striptags }} +{% else %} +pdfRest API Toolkit Python SDK +{% endif %} {% endblock %} From f21dbcc655a41240d403d1babf4bad23d9566e87 Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Thu, 19 Feb 2026 13:42:53 -0600 Subject: [PATCH 16/18] ruff: Add Pydocstyle (D) rules configuration for docstring linting - Enabled Pydocstyle rules (D) in the `pyproject.toml` to enforce Google-style docstring conventions using Ruff. - Configured `tool.ruff.lint.pydocstyle.convention` to "google". - Applied Pydocstyle to specific file patterns like `scripts/**/*.py`, `examples/**/*.py`, and `noxfile.py`. Assisted-by: Codex --- pyproject.toml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index b14d546e..5786a16b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -84,6 +84,8 @@ extend-select = [ "RSE", # raise https://docs.astral.sh/ruff/rules/#flake8-raise-rse "TRY", # tryceratops https://docs.astral.sh/ruff/rules/#tryceratops-try exception antipatterns "COM818", # prohibit trailing bare commas making tuples, see https://docs.astral.sh/ruff/rules/trailing-comma-on-bare-tuple/ + "D", # pydocstyle https://docs.astral.sh/ruff/rules/#pydocstyle-d + "D417", # undocumented-param https://docs.astral.sh/ruff/rules/undocumented-param/ ] # Allow autofix for all enabled rules (when `--fix`) is provided. fixable = ["ALL"] @@ -101,7 +103,20 @@ known-first-party = ["pdfrest"] "S101", # asserts allowed in tests... "ARG", # Unused function args -> fixtures nevertheless are functionally relevant... "FBT", # Don't care about booleans as positional arguments in tests, e.g. via @pytest.mark.parametrize() + "D", # pydocstyle https://docs.astral.sh/ruff/rules/#pydocstyle-d ] +"scripts/**/*.py" = [ + "D", # pydocstyle https://docs.astral.sh/ruff/rules/#pydocstyle-d +] +"examples/**/*.py" = [ + "D", # pydocstyle https://docs.astral.sh/ruff/rules/#pydocstyle-d +] +"noxfile.py" = [ + "D", # pydocstyle https://docs.astral.sh/ruff/rules/#pydocstyle-d +] + +[tool.ruff.lint.pydocstyle] +convention = "google" # https://docs.astral.sh/ruff/settings/#lint_pydocstyle_convention [tool.tomlsort] sort_first = ["project", "build-system"] From b4a91eeba82b37cc4bb33241ab6cb53ad07a5530 Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Thu, 19 Feb 2026 13:44:09 -0600 Subject: [PATCH 17/18] ruff: Automated fixes to docstrings Ran `uv run ruff check --fix` --- src/pdfrest/client.py | 495 ++++++++++++++++---------------- src/pdfrest/exceptions.py | 1 - src/pdfrest/models/_internal.py | 3 +- src/pdfrest/models/public.py | 37 +-- 4 files changed, 262 insertions(+), 274 deletions(-) diff --git a/src/pdfrest/client.py b/src/pdfrest/client.py index f768bf07..22a7b724 100644 --- a/src/pdfrest/client.py +++ b/src/pdfrest/client.py @@ -688,7 +688,6 @@ def _validate_pdfrest_api_key(api_key: str, url: URL) -> None: @property def base_url(self) -> URL: """Resolved base URL for the client.""" - return self._config.base_url def _prepare_request( @@ -2077,7 +2076,6 @@ def create_from_urls( timeout: TimeoutTypes | None = None, ) -> list[PdfRestFile]: """Upload one or more files by providing remote URLs.""" - normalized_urls = UploadURLs.model_validate({"url": urls}) request = self._client.prepare_request( "POST", @@ -2110,7 +2108,6 @@ def delete( timeout: TimeoutTypes | None = None, ) -> None: """Delete one or more uploaded files by reference.""" - payload = DeletePayload.model_validate({"files": files}) request = self._client.prepare_request( "POST", @@ -2376,7 +2373,6 @@ async def create_from_urls( timeout: TimeoutTypes | None = None, ) -> list[PdfRestFile]: """Upload one or more files by providing remote URLs.""" - normalized_urls = UploadURLs.model_validate({"url": urls}) request = self._client.prepare_request( "POST", @@ -2412,7 +2408,6 @@ async def delete( timeout: TimeoutTypes | None = None, ) -> None: """Delete one or more uploaded files by reference.""" - payload = DeletePayload.model_validate({"files": files}) request = self._client.prepare_request( "POST", @@ -2557,8 +2552,8 @@ def __init__( headers: Default headers merged into every request. http_client: Optional preconfigured `httpx.Client` instance to reuse. transport: Optional custom `httpx` transport. - max_retries: Maximum number of retries for retryable failures.""" - + max_retries: Maximum number of retries for retryable failures. + """ super().__init__( api_key=api_key, base_url=base_url, @@ -2576,7 +2571,8 @@ def __enter__(self) -> PdfRestClient: """Enter the client context manager and return this client instance. Returns: - The current client instance.""" + The current client instance. + """ _ = super().__enter__() return self @@ -2587,7 +2583,8 @@ def __exit__(self, exc_type: Any, exc: Any, traceback: Any) -> None: Args: exc_type: Exception type raised in the managed context, if any. exc: Exception instance raised in the managed context, if any. - traceback: Traceback object for exceptions raised in the managed context.""" + traceback: Traceback object for exceptions raised in the managed context. + """ super().__exit__(exc_type, exc, traceback) @property @@ -2595,8 +2592,8 @@ def files(self) -> PdfRestFilesClient: """Return the [PdfRestFilesClient][pdfrest.PdfRestFilesClient] helper bound to this client. Returns: - The file-management helper bound to this client.""" - + The file-management helper bound to this client. + """ return self._files_client def up( @@ -2622,8 +2619,8 @@ def up( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ request = self._prepare_request( "GET", "/up", @@ -2658,7 +2655,8 @@ def _convert_to_graphic( timeout: Request timeout override for this call. Returns: - Validated file-based response returned by pdfRest.""" + Validated file-based response returned by pdfRest. + """ return self._post_file_operation( endpoint=endpoint, payload=payload, @@ -2696,8 +2694,8 @@ def query_pdf_info( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload = PdfInfoPayload.model_validate({"file": file, "queries": queries}) request = self.prepare_request( "POST", @@ -2748,8 +2746,8 @@ def summarize_text( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "target_word_count": target_word_count, @@ -2812,8 +2810,8 @@ def summarize_text_to_file( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "target_word_count": target_word_count, @@ -2867,8 +2865,8 @@ def convert_to_markdown( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output_type": "file", @@ -2920,8 +2918,8 @@ def ocr_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file, "languages": languages} if pages is not None: payload["pages"] = pages @@ -2971,8 +2969,8 @@ def translate_pdf_text( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output_language": output_language, @@ -3032,8 +3030,8 @@ def translate_pdf_text_to_file( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output_language": output_language, @@ -3085,8 +3083,8 @@ def extract_images( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if pages is not None: payload["pages"] = pages @@ -3138,8 +3136,8 @@ def extract_pdf_text( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "full_text": full_text, @@ -3203,8 +3201,8 @@ def extract_pdf_text_to_file( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "full_text": full_text, @@ -3257,8 +3255,8 @@ def preview_redactions( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "redactions": redactions, @@ -3305,8 +3303,8 @@ def apply_redactions( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, } @@ -3354,8 +3352,8 @@ def add_text_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "text_objects": text_objects, @@ -3408,8 +3406,8 @@ def add_image_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "image": image, @@ -3459,8 +3457,8 @@ def split_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if page_groups is not None: payload["page_groups"] = page_groups @@ -3504,8 +3502,8 @@ def merge_pdfs( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"sources": sources} if output_prefix is not None: payload["output_prefix"] = output_prefix @@ -3547,8 +3545,8 @@ def zip_files( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": files} if output is not None: payload["output"] = output @@ -3590,8 +3588,8 @@ def unzip_file( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if password is not None: payload["password"] = password @@ -3633,8 +3631,8 @@ def convert_to_excel( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -3676,8 +3674,8 @@ def convert_to_powerpoint( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -3719,8 +3717,8 @@ def convert_xfa_to_acroforms( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -3762,8 +3760,8 @@ def convert_to_word( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -3807,8 +3805,8 @@ def import_form_data( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file, "data_file": data_file} if output is not None: payload["output"] = output @@ -3852,8 +3850,8 @@ def export_form_data( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "data_format": data_format, @@ -3898,8 +3896,8 @@ def flatten_pdf_forms( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -3947,8 +3945,8 @@ def add_permissions_password( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "new_permissions_password": new_permissions_password, @@ -4005,8 +4003,8 @@ def change_permissions_password( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "current_permissions_password": current_permissions_password, @@ -4060,8 +4058,8 @@ def add_open_password( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "new_open_password": new_open_password, @@ -4114,8 +4112,8 @@ def change_open_password( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "current_open_password": current_open_password, @@ -4167,8 +4165,8 @@ def remove_open_password( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "current_open_password": current_open_password, @@ -4219,8 +4217,8 @@ def remove_permissions_password( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "current_permissions_password": current_permissions_password, @@ -4271,8 +4269,8 @@ def compress_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "compression_level": compression_level, @@ -4321,8 +4319,8 @@ def add_attachment_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file, "attachment": attachment} if output is not None: payload["output"] = output @@ -4370,8 +4368,8 @@ def sign_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "signature_configuration": signature_configuration, @@ -4424,8 +4422,8 @@ def blank_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "page_size": page_size, "page_count": page_count, @@ -4476,8 +4474,8 @@ def convert_colors( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "color_profile": color_profile, @@ -4525,8 +4523,8 @@ def flatten_transparencies( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file, "quality": quality} if output is not None: payload["output"] = output @@ -4568,8 +4566,8 @@ def linearize_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -4611,8 +4609,8 @@ def flatten_annotations( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -4654,8 +4652,8 @@ def flatten_layers( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -4697,8 +4695,8 @@ def rasterize_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -4756,8 +4754,8 @@ def convert_office_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output": output, @@ -4813,8 +4811,8 @@ def convert_postscript_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output": output, @@ -4860,8 +4858,8 @@ def convert_email_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output": output, @@ -4905,8 +4903,8 @@ def convert_image_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output": output, @@ -4962,8 +4960,8 @@ def convert_html_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output": output, @@ -5025,8 +5023,8 @@ def convert_url_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "url": url, "output": output, @@ -5100,8 +5098,8 @@ def watermark_pdf_with_text( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "watermark_text": watermark_text, @@ -5177,8 +5175,8 @@ def watermark_pdf_with_image( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "watermark_file": watermark_file, @@ -5236,8 +5234,8 @@ def convert_to_pdfa( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output_type": output_type, @@ -5284,8 +5282,8 @@ def convert_to_pdfx( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file, "output_type": output_type} if output is not None: payload["output"] = output @@ -5335,8 +5333,8 @@ def convert_to_png( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": files, "resolution": resolution, @@ -5393,8 +5391,8 @@ def convert_to_bmp( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": files, "resolution": resolution, @@ -5451,8 +5449,8 @@ def convert_to_gif( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": files, "resolution": resolution, @@ -5511,8 +5509,8 @@ def convert_to_jpeg( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": files, "resolution": resolution, @@ -5570,8 +5568,8 @@ def convert_to_tiff( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": files, "resolution": resolution, @@ -5619,8 +5617,8 @@ def __init__( http_client: Optional preconfigured `httpx.Client` instance to reuse. transport: Optional custom `httpx` transport. concurrency_limit: Maximum concurrent file-info fetch operations used by async file helper methods. - max_retries: Maximum number of retries for retryable failures.""" - + max_retries: Maximum number of retries for retryable failures. + """ super().__init__( api_key=api_key, base_url=base_url, @@ -5639,7 +5637,8 @@ async def __aenter__(self) -> AsyncPdfRestClient: """Enter the client context manager and return this client instance. Returns: - The current client instance.""" + The current client instance. + """ _ = await super().__aenter__() return self @@ -5650,7 +5649,8 @@ async def __aexit__(self, exc_type: Any, exc: Any, traceback: Any) -> None: Args: exc_type: Exception type raised in the managed context, if any. exc: Exception instance raised in the managed context, if any. - traceback: Traceback object for exceptions raised in the managed context.""" + traceback: Traceback object for exceptions raised in the managed context. + """ await super().__aexit__(exc_type, exc, traceback) @property @@ -5658,8 +5658,8 @@ def files(self) -> AsyncPdfRestFilesClient: """Return the [AsyncPdfRestFilesClient][pdfrest.AsyncPdfRestFilesClient] helper bound to this client. Returns: - The file-management helper bound to this client.""" - + The file-management helper bound to this client. + """ return self._files_client async def query_pdf_info( @@ -5689,8 +5689,8 @@ async def query_pdf_info( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload = PdfInfoPayload.model_validate({"file": file, "queries": queries}) request = self.prepare_request( "POST", @@ -5741,8 +5741,8 @@ async def summarize_text( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "target_word_count": target_word_count, @@ -5805,8 +5805,8 @@ async def summarize_text_to_file( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "target_word_count": target_word_count, @@ -5860,8 +5860,8 @@ async def convert_to_markdown( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output_type": "file", @@ -5913,8 +5913,8 @@ async def ocr_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file, "languages": languages} if pages is not None: payload["pages"] = pages @@ -5964,8 +5964,8 @@ async def translate_pdf_text( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output_language": output_language, @@ -6025,8 +6025,8 @@ async def translate_pdf_text_to_file( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output_language": output_language, @@ -6078,8 +6078,8 @@ async def extract_images( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if pages is not None: payload["pages"] = pages @@ -6131,8 +6131,8 @@ async def extract_pdf_text( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "full_text": full_text, @@ -6196,8 +6196,8 @@ async def extract_pdf_text_to_file( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "full_text": full_text, @@ -6250,8 +6250,8 @@ async def preview_redactions( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "redactions": redactions, @@ -6298,8 +6298,8 @@ async def apply_redactions( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, } @@ -6347,8 +6347,8 @@ async def add_text_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "text_objects": text_objects, @@ -6401,8 +6401,8 @@ async def add_image_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "image": image, @@ -6446,8 +6446,8 @@ async def up( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ request = self._prepare_request( "GET", "/up", @@ -6482,7 +6482,8 @@ async def _convert_to_graphic( timeout: Request timeout override for this call. Returns: - Validated file-based response returned by pdfRest.""" + Validated file-based response returned by pdfRest. + """ return await self._post_file_operation( endpoint=endpoint, payload=payload, @@ -6522,8 +6523,8 @@ async def split_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if page_groups is not None: payload["page_groups"] = page_groups @@ -6567,8 +6568,8 @@ async def merge_pdfs( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"sources": sources} if output_prefix is not None: payload["output_prefix"] = output_prefix @@ -6610,8 +6611,8 @@ async def zip_files( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": files} if output is not None: payload["output"] = output @@ -6653,8 +6654,8 @@ async def unzip_file( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if password is not None: payload["password"] = password @@ -6696,8 +6697,8 @@ async def convert_to_excel( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -6739,8 +6740,8 @@ async def convert_to_powerpoint( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -6782,8 +6783,8 @@ async def convert_xfa_to_acroforms( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -6825,8 +6826,8 @@ async def convert_to_word( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -6870,8 +6871,8 @@ async def import_form_data( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file, "data_file": data_file} if output is not None: payload["output"] = output @@ -6915,8 +6916,8 @@ async def export_form_data( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "data_format": data_format, @@ -6961,8 +6962,8 @@ async def flatten_pdf_forms( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -7010,8 +7011,8 @@ async def add_permissions_password( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "new_permissions_password": new_permissions_password, @@ -7068,8 +7069,8 @@ async def change_permissions_password( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "current_permissions_password": current_permissions_password, @@ -7123,8 +7124,8 @@ async def remove_permissions_password( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "current_permissions_password": current_permissions_password, @@ -7175,8 +7176,8 @@ async def add_open_password( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "new_open_password": new_open_password, @@ -7229,8 +7230,8 @@ async def change_open_password( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "current_open_password": current_open_password, @@ -7282,8 +7283,8 @@ async def remove_open_password( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "current_open_password": current_open_password, @@ -7334,8 +7335,8 @@ async def compress_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "compression_level": compression_level, @@ -7384,8 +7385,8 @@ async def add_attachment_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file, "attachment": attachment} if output is not None: payload["output"] = output @@ -7433,8 +7434,8 @@ async def sign_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "signature_configuration": signature_configuration, @@ -7487,8 +7488,8 @@ async def blank_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "page_size": page_size, "page_count": page_count, @@ -7539,8 +7540,8 @@ async def convert_colors( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "color_profile": color_profile, @@ -7588,8 +7589,8 @@ async def flatten_transparencies( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file, "quality": quality} if output is not None: payload["output"] = output @@ -7631,8 +7632,8 @@ async def linearize_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -7674,8 +7675,8 @@ async def flatten_annotations( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -7717,8 +7718,8 @@ async def flatten_layers( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -7760,8 +7761,8 @@ async def rasterize_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file} if output is not None: payload["output"] = output @@ -7819,8 +7820,8 @@ async def convert_office_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output": output, @@ -7876,8 +7877,8 @@ async def convert_postscript_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output": output, @@ -7923,8 +7924,8 @@ async def convert_email_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output": output, @@ -7968,8 +7969,8 @@ async def convert_image_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output": output, @@ -8025,8 +8026,8 @@ async def convert_html_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output": output, @@ -8088,8 +8089,8 @@ async def convert_url_to_pdf( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "url": url, "output": output, @@ -8163,8 +8164,8 @@ async def watermark_pdf_with_text( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "watermark_text": watermark_text, @@ -8240,8 +8241,8 @@ async def watermark_pdf_with_image( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "watermark_file": watermark_file, @@ -8299,8 +8300,8 @@ async def convert_to_pdfa( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": file, "output_type": output_type, @@ -8348,8 +8349,8 @@ async def convert_to_pdfx( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = {"files": file, "output_type": output_type} if output is not None: payload["output"] = output @@ -8399,8 +8400,8 @@ async def convert_to_png( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": files, "resolution": resolution, @@ -8457,8 +8458,8 @@ async def convert_to_bmp( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": files, "resolution": resolution, @@ -8515,8 +8516,8 @@ async def convert_to_gif( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": files, "resolution": resolution, @@ -8575,8 +8576,8 @@ async def convert_to_jpeg( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": files, "resolution": resolution, @@ -8634,8 +8635,8 @@ async def convert_to_tiff( Raises: PdfRestError: If request execution fails at the client or API layer. - ValidationError: If local payload validation fails before sending.""" - + ValidationError: If local payload validation fails before sending. + """ payload: dict[str, Any] = { "files": files, "resolution": resolution, diff --git a/src/pdfrest/exceptions.py b/src/pdfrest/exceptions.py index 9894fdbb..07bfe13e 100644 --- a/src/pdfrest/exceptions.py +++ b/src/pdfrest/exceptions.py @@ -109,7 +109,6 @@ def __init__(self, message: str, exceptions: Sequence[Exception], /) -> None: def translate_httpx_error(exc: httpx.HTTPError) -> PdfRestError: """Convert an httpx exception into a library-specific exception.""" - if isinstance(exc, httpx.ConnectTimeout): return PdfRestConnectTimeoutError( str(exc) or "Connection timed out while calling pdfRest." diff --git a/src/pdfrest/models/_internal.py b/src/pdfrest/models/_internal.py index dec907e8..17442b38 100644 --- a/src/pdfrest/models/_internal.py +++ b/src/pdfrest/models/_internal.py @@ -2578,7 +2578,8 @@ class TiffPdfRestPayload( class PdfRestRawUploadedFile(BaseModel): """The response sent by /upload is a list of these. /unzip returns files like this - with outputUrl""" + with outputUrl + """ name: Annotated[str, Field(description="The name of the file")] id: Annotated[PdfRestFileID, Field(description="The id of the file")] diff --git a/src/pdfrest/models/public.py b/src/pdfrest/models/public.py index 4ffddf5e..11982f22 100644 --- a/src/pdfrest/models/public.py +++ b/src/pdfrest/models/public.py @@ -46,8 +46,7 @@ class PdfRestFileID(str): - """ - A str-like type representing: + """A str-like type representing: [optional '1' or '2' prefix] + [UUIDv4 with hyphens] Examples: @@ -90,8 +89,7 @@ def __repr__(self) -> str: @property def prefix(self) -> str | None: - """ - The leading prefix digit ('1' or '2') if present, else None. + """The leading prefix digit ('1' or '2') if present, else None. Note: Presence is unambiguous by length: - 36 chars => no prefix @@ -118,8 +116,7 @@ def is_valid(cls, value: str) -> bool: def from_parts( cls, u: str | _uuid.UUID, prefix: int | str | None = None ) -> PdfRestFileID: - """ - Build from a UUIDv4 (str or uuid.UUID) and an optional prefix (1 or 2). + """Build from a UUIDv4 (str or uuid.UUID) and an optional prefix (1 or 2). Raises ValueError if not a v4 UUID or bad prefix. """ if isinstance(prefix, int): @@ -159,10 +156,9 @@ def generate(cls, prefix: int | str | None = None) -> PdfRestFileID: # ------------------------- @classmethod def __get_pydantic_core_schema__(cls, source_type: Any, handler: Any) -> CoreSchema: - """ - Build a Pydantic v2 core schema that accepts: - - a UUID (validated as v4) -> converted to this type (no prefix) - - a string matching our pattern + """Build a Pydantic v2 core schema that accepts: + - a UUID (validated as v4) -> converted to this type (no prefix) + - a string matching our pattern """ from pydantic_core import core_schema @@ -187,9 +183,7 @@ def to_class(v: Any) -> PdfRestFileID: def __get_pydantic_json_schema__( cls, core_schema: Any, handler: Any ) -> JsonSchemaValue: - """ - Provide a clean JSON Schema for OpenAPI/JSON Schema generators. - """ + """Provide a clean JSON Schema for OpenAPI/JSON Schema generators.""" # Prefer a single-string schema with pattern and examples return { "type": "string", @@ -278,8 +272,7 @@ class PdfRestFile(BaseModel): class PdfRestFileBasedResponse(BaseModel): - """ - Represents a response from a pdfRest API operation that is file-based, allowing + """Represents a response from a pdfRest API operation that is file-based, allowing handling of input and output files along with additional warnings. """ @@ -321,7 +314,6 @@ def input_id(self) -> PdfRestFileID: Raises: ValueError: If no input id is available or multiple input ids exist. """ - if len(self.input_ids) == 1: return self.input_ids[0] if len(self.input_ids) == 0: @@ -337,7 +329,6 @@ def output_file(self) -> PdfRestFile: Raises: ValueError: If no output file is available or multiple outputs exist. """ - if len(self.output_files) == 1: return self.output_files[0] if len(self.output_files) == 0: @@ -687,8 +678,7 @@ class ExtractedTextFullTextPages(BaseModel): class ExtractedTextFullText(RootModel[str | ExtractedTextFullTextPages]): - """ - Represents full-text extraction in either "document" (str) or "page" (object) + """Represents full-text extraction in either "document" (str) or "page" (object) modes while providing convenience accessors for both forms. """ @@ -697,8 +687,7 @@ class ExtractedTextFullText(RootModel[str | ExtractedTextFullTextPages]): @property def document_text(self) -> str | None: - """ - Return the document-level string. Falls back to space-joining per-page text + """Return the document-level string. Falls back to space-joining per-page text when only the page-structured payload is available. """ if isinstance(self.root, str): @@ -707,8 +696,7 @@ def document_text(self) -> str | None: @property def pages(self) -> list[ExtractedTextFullTextPage]: - """ - Return page entries when pdfRest emits per-page text. + """Return page entries when pdfRest emits per-page text. Raises ValueError when the payload is in document-string mode. """ if isinstance(self.root, ExtractedTextFullTextPages): @@ -717,8 +705,7 @@ def pages(self) -> list[ExtractedTextFullTextPage]: raise ValueError(msg) def iter_pages(self) -> list[ExtractedTextFullTextPage]: - """ - Convenience helper that provides a stable iterable without requiring + """Convenience helper that provides a stable iterable without requiring callers to guard against the document-only representation. """ try: From 1dea28faa6d8c6bd19ba3ade5f0403adb84f31dc Mon Sep 17 00:00:00 2001 From: "Kevin A. Mitchell" Date: Thu, 19 Feb 2026 13:46:53 -0600 Subject: [PATCH 18/18] client: Enhance docstrings for consistency and clarity - Revised docstrings across `PdfRestClient`, `AsyncPdfRestFilesClient`, and exception classes to follow Google-style formatting. - Improved descriptions and added missing sections like `Args`, `Returns`, and `Raises` for better usability and readability. - Updated models and types with refined docstrings to clearly explain usage, structure, and expected behaviors. Assisted-by: Codex --- src/pdfrest/client.py | 10 +++--- src/pdfrest/exceptions.py | 23 ++++++++++++ src/pdfrest/models/__init__.py | 2 ++ src/pdfrest/models/_internal.py | 6 ++-- src/pdfrest/models/public.py | 63 ++++++++++++++++++++++++--------- src/pdfrest/types/public.py | 2 +- 6 files changed, 83 insertions(+), 23 deletions(-) diff --git a/src/pdfrest/client.py b/src/pdfrest/client.py index 22a7b724..b3b3f6aa 100644 --- a/src/pdfrest/client.py +++ b/src/pdfrest/client.py @@ -1500,9 +1500,10 @@ async def __aexit__(self, exc_type: Any, exc: Any, traceback: Any) -> None: class PdfRestFilesClient(Protocol): - """Public interface for file operations returned by - [`PdfRestClient.files`][pdfrest.PdfRestClient.files]. + """Public interface for file operations returned by files helpers. + This protocol describes the object returned by + [`PdfRestClient.files`][pdfrest.PdfRestClient.files]. Retrieve this helper from `client.files`; do not instantiate it directly. """ @@ -1727,9 +1728,10 @@ def stream( class AsyncPdfRestFilesClient(Protocol): - """Public interface for file operations returned by - [`AsyncPdfRestClient.files`][pdfrest.AsyncPdfRestClient.files]. + """Public interface for async file operations returned by files helpers. + This protocol describes the object returned by + [`AsyncPdfRestClient.files`][pdfrest.AsyncPdfRestClient.files]. Retrieve this helper from `client.files`; do not instantiate it directly. """ diff --git a/src/pdfrest/exceptions.py b/src/pdfrest/exceptions.py index 07bfe13e..b8fcb899 100644 --- a/src/pdfrest/exceptions.py +++ b/src/pdfrest/exceptions.py @@ -68,6 +68,14 @@ def __init__( *, retry_after: float | None = None, ) -> None: + """Initialize an API error with HTTP status and response details. + + Args: + status_code: HTTP status code returned by pdfRest. + message: Optional human-readable error message. + response_content: Parsed or raw error payload from the API response. + retry_after: Optional retry delay in seconds parsed from headers. + """ self.status_code = status_code self.response_content = response_content self.retry_after = retry_after @@ -90,6 +98,12 @@ class PdfRestDeleteError(PdfRestError): """Raised when an individual file cannot be deleted.""" def __init__(self, file_id: PdfRestFileID | str, message: str) -> None: + """Initialize a delete failure for one uploaded file. + + Args: + file_id: Identifier of the file that failed to delete. + message: Error detail returned for the deletion attempt. + """ self.file_id = str(file_id) self.detail = message super().__init__(f"Failed to delete file {self.file_id}: {message}") @@ -99,6 +113,15 @@ class PdfRestErrorGroup(ExceptionGroup): """Group of PdfRestError exceptions produced by the PDF REST library.""" def __init__(self, message: str, exceptions: Sequence[Exception], /) -> None: + """Initialize a grouped pdfRest failure. + + Args: + message: Summary message for the grouped error. + exceptions: Collection of `PdfRestError` instances. + + Raises: + TypeError: If any item in `exceptions` is not a `PdfRestError`. + """ # enforce that everything inside is from your library for e in exceptions: if not isinstance(e, PdfRestError): diff --git a/src/pdfrest/models/__init__.py b/src/pdfrest/models/__init__.py index 2ee3d5a2..2ed95632 100644 --- a/src/pdfrest/models/__init__.py +++ b/src/pdfrest/models/__init__.py @@ -1,3 +1,5 @@ +"""Public model exports for the `pdfrest.models` package.""" + from .public import ( ExtractedTextDocument, ExtractedTextFullText, diff --git a/src/pdfrest/models/_internal.py b/src/pdfrest/models/_internal.py index 17442b38..918f24b6 100644 --- a/src/pdfrest/models/_internal.py +++ b/src/pdfrest/models/_internal.py @@ -2577,8 +2577,10 @@ class TiffPdfRestPayload( class PdfRestRawUploadedFile(BaseModel): - """The response sent by /upload is a list of these. /unzip returns files like this - with outputUrl + """Raw uploaded-file entry returned by pdfRest upload-style endpoints. + + The `/upload` response is a list of these objects. The `/unzip` response + also uses this shape and may include `outputUrl` entries. """ name: Annotated[str, Field(description="The name of the file")] diff --git a/src/pdfrest/models/public.py b/src/pdfrest/models/public.py index 11982f22..da316d35 100644 --- a/src/pdfrest/models/public.py +++ b/src/pdfrest/models/public.py @@ -46,7 +46,9 @@ class PdfRestFileID(str): - """A str-like type representing: + """Str-like identifier for pdfRest files. + + Format: [optional '1' or '2' prefix] + [UUIDv4 with hyphens] Examples: @@ -71,6 +73,17 @@ class PdfRestFileID(str): ) def __new__(cls, value: str) -> PdfRestFileID: + """Create a normalized file identifier from a validated string. + + Args: + value: Candidate pdfRest file id string. + + Returns: + Lower-cased, validated file id value. + + Raises: + ValueError: If `value` is not a valid prefixed UUIDv4 identifier. + """ if not cls._PY_PATTERN.fullmatch(value): msg = ( "Invalid PdfRestPrefixedUUID4. Expected: " @@ -116,8 +129,14 @@ def is_valid(cls, value: str) -> bool: def from_parts( cls, u: str | _uuid.UUID, prefix: int | str | None = None ) -> PdfRestFileID: - """Build from a UUIDv4 (str or uuid.UUID) and an optional prefix (1 or 2). - Raises ValueError if not a v4 UUID or bad prefix. + """Build a file id from a UUIDv4 and optional prefix. + + Args: + u: UUID value as string or `uuid.UUID`. + prefix: Optional leading prefix (`1` or `2`). + + Raises: + ValueError: If the UUID is not version 4 or the prefix is invalid. """ if isinstance(prefix, int): prefix = str(prefix) # allow 1/2 as int @@ -156,9 +175,11 @@ def generate(cls, prefix: int | str | None = None) -> PdfRestFileID: # ------------------------- @classmethod def __get_pydantic_core_schema__(cls, source_type: Any, handler: Any) -> CoreSchema: - """Build a Pydantic v2 core schema that accepts: - - a UUID (validated as v4) -> converted to this type (no prefix) - - a string matching our pattern + """Build a Pydantic v2 core schema for `PdfRestFileID`. + + Accepted inputs: + - a UUID (validated as v4) converted to this type with no prefix + - a string matching the `PdfRestFileID` pattern """ from pydantic_core import core_schema @@ -272,8 +293,10 @@ class PdfRestFile(BaseModel): class PdfRestFileBasedResponse(BaseModel): - """Represents a response from a pdfRest API operation that is file-based, allowing - handling of input and output files along with additional warnings. + """Response model for file-based pdfRest operations. + + Includes input file identifiers, output files, and optional warnings from + the API response payload. """ # Allow all extra fields to be stored and serialized @@ -678,8 +701,10 @@ class ExtractedTextFullTextPages(BaseModel): class ExtractedTextFullText(RootModel[str | ExtractedTextFullTextPages]): - """Represents full-text extraction in either "document" (str) or "page" (object) - modes while providing convenience accessors for both forms. + """Full-text extraction payload in document or per-page mode. + + Wraps either a single document-level string or a per-page text object and + provides convenience accessors for both shapes. """ root: str | ExtractedTextFullTextPages @@ -687,8 +712,10 @@ class ExtractedTextFullText(RootModel[str | ExtractedTextFullTextPages]): @property def document_text(self) -> str | None: - """Return the document-level string. Falls back to space-joining per-page text - when only the page-structured payload is available. + """Return document-level text for either payload shape. + + Falls back to joining per-page text when only the page-structured + payload is available. """ if isinstance(self.root, str): return self.root @@ -696,8 +723,10 @@ def document_text(self) -> str | None: @property def pages(self) -> list[ExtractedTextFullTextPage]: - """Return page entries when pdfRest emits per-page text. - Raises ValueError when the payload is in document-string mode. + """Return per-page text entries when page mode is available. + + Raises: + ValueError: If the payload is in document-string mode. """ if isinstance(self.root, ExtractedTextFullTextPages): return self.root.pages @@ -705,8 +734,10 @@ def pages(self) -> list[ExtractedTextFullTextPage]: raise ValueError(msg) def iter_pages(self) -> list[ExtractedTextFullTextPage]: - """Convenience helper that provides a stable iterable without requiring - callers to guard against the document-only representation. + """Return per-page text entries or an empty list in document mode. + + This helper avoids forcing callers to catch mode errors when they only + need an iterable. """ try: return self.pages diff --git a/src/pdfrest/types/public.py b/src/pdfrest/types/public.py index 36c6b0e1..0f15ec2b 100644 --- a/src/pdfrest/types/public.py +++ b/src/pdfrest/types/public.py @@ -145,7 +145,7 @@ class PdfAddTextObject(TypedDict, total=False): font: Font family name used to render text. max_width: Maximum text box width in PDF points. opacity: Opacity value from 0.0 (transparent) to 1.0 (opaque). - page: One-based page number or ``\"all\"`` for every page. + page: One-based page number or ``"all"`` for every page. rotation: Rotation angle in degrees. text: Text content to draw. text_color_rgb: Optional RGB text color tuple.