Add Unzip tool

Assisted-by: Codex

Author: datalogics-cgreen

src/pdfrest/client.py

@@ -108,6 +108,7 @@
     SummarizePdfTextPayload,
     TiffPdfRestPayload,
     TranslatePdfTextPayload,
+    UnzipPayload,
     UploadURLs,
     ZipPayload,
 )
@@ -2629,6 +2630,32 @@ def zip_files(
             timeout=timeout,
         )
 
+    def unzip_file(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        password: str | None = None,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Extract files from a zip archive."""
+
+        payload: dict[str, Any] = {"files": file}
+        if password is not None:
+            payload["password"] = password
+
+        return self._post_file_operation(
+            endpoint="/unzip",
+            payload=payload,
+            payload_model=UnzipPayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     def convert_to_excel(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],
@@ -3942,6 +3969,32 @@ async def zip_files(
             timeout=timeout,
         )
 
+    async def unzip_file(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        password: str | None = None,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Asynchronously extract files from a zip archive."""
+
+        payload: dict[str, Any] = {"files": file}
+        if password is not None:
+            payload["password"] = password
+
+        return await self._post_file_operation(
+            endpoint="/unzip",
+            payload=payload,
+            payload_model=UnzipPayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     async def convert_to_excel(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],

src/pdfrest/models/_internal.py

@@ -263,6 +263,29 @@ class ZipPayload(BaseModel):
     ] = None
 
 
+class UnzipPayload(BaseModel):
+    """Adapt caller options into a pdfRest-ready unzip request payload."""
+
+    files: Annotated[
+        list[PdfRestFile],
+        Field(
+            min_length=1,
+            max_length=1,
+            validation_alias=AliasChoices("file", "files"),
+            serialization_alias="id",
+        ),
+        BeforeValidator(_ensure_list),
+        AfterValidator(
+            _allowed_mime_types("application/zip", error_msg="Must be a ZIP file")
+        ),
+        PlainSerializer(_serialize_as_first_file_id),
+    ]
+    password: Annotated[
+        str | None,
+        Field(default=None, min_length=1),
+    ] = None
+
+
 PageNumber = Annotated[int, Field(ge=1), PlainSerializer(lambda x: str(x))]
 
 
@@ -1389,7 +1412,7 @@ class PdfRestRawUploadedFile(BaseModel):
     name: Annotated[str, Field(description="The name of the file")]
     id: Annotated[PdfRestFileID, Field(description="The id of the file")]
     output_url: Annotated[
-        str | None,
+        list[HttpUrl] | HttpUrl | None,
         Field(description="The url of the unzipped file", alias="outputUrl"),
         BeforeValidator(_ensure_list),
     ] = None
@@ -1408,7 +1431,7 @@ class PdfRestRawFileResponse(BaseModel):
         BeforeValidator(_ensure_list),
     ]
     output_urls: Annotated[
-        list[HttpUrl] | None,
+        list[HttpUrl] | HttpUrl | None,
         Field(alias="outputUrl", description="The url of the file"),
         BeforeValidator(_ensure_list),
     ] = None