feat: add download_stream, on_progress downloads, configurable user_agent, full test suite

- FilesAPI: add download_stream/download_stream_async, on_progress param in download_to/download_to_async
- Task: add download_stream/download_stream_async, on_progress param in download_to/download_to_async
- client: wire on_download_progress in convert/convert_async, configurable user_agent config option
- tests: 139 tests covering exceptions, validation, retry, polling, files API, task model, client

Author: drdmitry

conversiontools/api/files.py

@@ -4,16 +4,27 @@
 
 import os
 import re
+import httpx
 from pathlib import Path
-from typing import Optional, Union, BinaryIO
+from typing import Optional, Union, BinaryIO, Iterator, AsyncIterator, Callable
 from urllib.parse import quote
-from ..types.config import FileUploadResponse, FileInfo, FileUploadOptions
+from ..types.config import FileUploadResponse, FileInfo, FileUploadOptions, ProgressEvent
 from ..utils.errors import ValidationError
 from ..utils.validation import validate_file_id
 from ..utils.progress import create_progress_event
 from .http import HttpClient
 
 
+def _extract_filename(disposition: Optional[str]) -> Optional[str]:
+    """Extract filename from Content-Disposition header"""
+    if not disposition:
+        return None
+    matches = re.search(r'filename[^;=\n]*=(([\'"]).*?\2|[^;\n]*)', disposition)
+    if matches and matches.group(1):
+        return matches.group(1).strip('\'"')
+    return None
+
+
 class FilesAPI:
     """Files API for upload, download, and file management"""
 
@@ -61,8 +72,6 @@ def upload(
             on_progress(create_progress_event(total, total))
 
         # Create multipart form data
-        import httpx
-
         files = {"file": (filename or "file", file_data)}
 
         # Upload file using httpx directly with multipart
@@ -125,8 +134,6 @@ async def upload_async(
             on_progress(create_progress_event(total, total))
 
         # Create multipart form data
-        import httpx
-
         files = {"file": (filename or "file", file_data)}
 
         # Upload file using httpx directly with multipart
@@ -170,59 +177,146 @@ async def download_bytes_async(self, file_id: str) -> bytes:
         response = await self.http.get_async(f"/files/{quote(file_id)}", raw=True)
         return response.content
 
-    def download_to(self, file_id: str, output_path: Optional[str] = None) -> str:
+    def download_stream(self, file_id: str) -> Iterator[bytes]:
+        """Download file as a byte stream (sync)"""
+        validate_file_id(file_id)
+        url = f"{self.http.base_url}/files/{quote(file_id)}"
+        headers = {"Authorization": f"Bearer {self.http.api_token}"}
+        if self.http.user_agent:
+            headers["User-Agent"] = self.http.user_agent
+
+        with httpx.Client(timeout=self.http.timeout) as client:
+            with client.stream("GET", url, headers=headers) as response:
+                if not response.is_success:
+                    self.http._handle_error_response(response)
+                self.http._extract_rate_limits(response.headers)
+                yield from response.iter_bytes()
+
+    async def download_stream_async(self, file_id: str) -> AsyncIterator[bytes]:
+        """Download file as a byte stream (async)"""
+        validate_file_id(file_id)
+        url = f"{self.http.base_url}/files/{quote(file_id)}"
+        headers = {"Authorization": f"Bearer {self.http.api_token}"}
+        if self.http.user_agent:
+            headers["User-Agent"] = self.http.user_agent
+
+        async with httpx.AsyncClient(timeout=self.http.timeout) as client:
+            async with client.stream("GET", url, headers=headers) as response:
+                if not response.is_success:
+                    self.http._handle_error_response(response)
+                self.http._extract_rate_limits(response.headers)
+                async for chunk in response.aiter_bytes():
+                    yield chunk
+
+    def download_to(
+        self,
+        file_id: str,
+        output_path: Optional[str] = None,
+        on_progress: Optional[Callable[[ProgressEvent], None]] = None,
+    ) -> str:
         """Download file to path (sync)"""
         validate_file_id(file_id)
-        response = self.http.get(f"/files/{quote(file_id)}", raw=True)
 
-        # Determine output filename
-        filename = output_path
-        if not filename:
-            # Try to get filename from Content-Disposition header
-            disposition = response.headers.get("content-disposition")
-            if disposition:
-                matches = re.search(r'filename[^;=\n]*=(([\'"]).*?\2|[^;\n]*)', disposition)
-                if matches and matches.group(1):
-                    filename = matches.group(1).strip('\'"')
+        if on_progress:
+            url = f"{self.http.base_url}/files/{quote(file_id)}"
+            headers = {"Authorization": f"Bearer {self.http.api_token}"}
+            if self.http.user_agent:
+                headers["User-Agent"] = self.http.user_agent
+
+            with httpx.Client(timeout=self.http.timeout) as client:
+                with client.stream("GET", url, headers=headers) as response:
+                    if not response.is_success:
+                        self.http._handle_error_response(response)
+                    self.http._extract_rate_limits(response.headers)
+
+                    filename = (
+                        output_path
+                        or _extract_filename(response.headers.get("content-disposition"))
+                        or "result"
+                    )
+                    output_dir = os.path.dirname(filename)
+                    if output_dir and not os.path.exists(output_dir):
+                        os.makedirs(output_dir, exist_ok=True)
+
+                    content_length = response.headers.get("content-length")
+                    total = int(content_length) if content_length else None
+                    loaded = 0
+
+                    with open(filename, "wb") as f:
+                        for chunk in response.iter_bytes():
+                            f.write(chunk)
+                            loaded += len(chunk)
+                            on_progress(create_progress_event(loaded, total))
+
+            return filename
 
-            filename = filename or "result"
+        response = self.http.get(f"/files/{quote(file_id)}", raw=True)
+
+        filename = output_path or _extract_filename(
+            response.headers.get("content-disposition")
+        ) or "result"
 
-        # Ensure directory exists
         output_dir = os.path.dirname(filename)
         if output_dir and not os.path.exists(output_dir):
             os.makedirs(output_dir, exist_ok=True)
 
-        # Write file
         with open(filename, "wb") as f:
             f.write(response.content)
 
         return filename
 
     async def download_to_async(
-        self, file_id: str, output_path: Optional[str] = None
+        self,
+        file_id: str,
+        output_path: Optional[str] = None,
+        on_progress: Optional[Callable[[ProgressEvent], None]] = None,
     ) -> str:
         """Download file to path (async)"""
         validate_file_id(file_id)
-        response = await self.http.get_async(f"/files/{quote(file_id)}", raw=True)
 
-        # Determine output filename
-        filename = output_path
-        if not filename:
-            # Try to get filename from Content-Disposition header
-            disposition = response.headers.get("content-disposition")
-            if disposition:
-                matches = re.search(r'filename[^;=\n]*=(([\'"]).*?\2|[^;\n]*)', disposition)
-                if matches and matches.group(1):
-                    filename = matches.group(1).strip('\'"')
+        if on_progress:
+            url = f"{self.http.base_url}/files/{quote(file_id)}"
+            headers = {"Authorization": f"Bearer {self.http.api_token}"}
+            if self.http.user_agent:
+                headers["User-Agent"] = self.http.user_agent
+
+            async with httpx.AsyncClient(timeout=self.http.timeout) as client:
+                async with client.stream("GET", url, headers=headers) as response:
+                    if not response.is_success:
+                        self.http._handle_error_response(response)
+                    self.http._extract_rate_limits(response.headers)
+
+                    filename = (
+                        output_path
+                        or _extract_filename(response.headers.get("content-disposition"))
+                        or "result"
+                    )
+                    output_dir = os.path.dirname(filename)
+                    if output_dir and not os.path.exists(output_dir):
+                        os.makedirs(output_dir, exist_ok=True)
+
+                    content_length = response.headers.get("content-length")
+                    total = int(content_length) if content_length else None
+                    loaded = 0
+
+                    with open(filename, "wb") as f:
+                        async for chunk in response.aiter_bytes():
+                            f.write(chunk)
+                            loaded += len(chunk)
+                            on_progress(create_progress_event(loaded, total))
+
+            return filename
+
+        response = await self.http.get_async(f"/files/{quote(file_id)}", raw=True)
 
-            filename = filename or "result"
+        filename = output_path or _extract_filename(
+            response.headers.get("content-disposition")
+        ) or "result"
 
-        # Ensure directory exists
         output_dir = os.path.dirname(filename)
         if output_dir and not os.path.exists(output_dir):
             os.makedirs(output_dir, exist_ok=True)
 
-        # Write file
         with open(filename, "wb") as f:
             f.write(response.content)
 

conversiontools/client.py

@@ -44,6 +44,7 @@ def __init__(self, config: ConversionToolsConfig):
             "max_polling_interval": config.get("max_polling_interval", 30000),
             "polling_backoff": config.get("polling_backoff", 1.5),
             "webhook_url": config.get("webhook_url"),
+            "user_agent": config.get("user_agent", f"conversiontools-python/{VERSION}"),
             "on_upload_progress": config.get("on_upload_progress"),
             "on_download_progress": config.get("on_download_progress"),
             "on_conversion_progress": config.get("on_conversion_progress"),
@@ -57,7 +58,7 @@ def __init__(self, config: ConversionToolsConfig):
             retries=self.config["retries"],
             retry_delay=self.config["retry_delay"],
             retryable_statuses=self.config["retryable_statuses"],
-            user_agent=f"conversiontools-python/{VERSION}",
+            user_agent=self.config["user_agent"],
         )
 
         # Initialize API clients
@@ -153,7 +154,7 @@ def on_progress(status: Dict[str, Any]) -> None:
         task.wait(wait_options)
 
         # Download result
-        output_path = task.download_to(output)
+        output_path = task.download_to(output, on_progress=self.config["on_download_progress"])
 
         return output_path
 
@@ -245,7 +246,7 @@ def on_progress(status: Dict[str, Any]) -> None:
         await task.wait_async(wait_options)
 
         # Download result
-        output_path = await task.download_to_async(output)
+        output_path = await task.download_to_async(output, on_progress=self.config["on_download_progress"])
 
         return output_path
 

conversiontools/models/task.py

@@ -2,8 +2,8 @@
 Task model - High-level interface for conversion tasks
 """
 
-from typing import Optional, Dict, Any, TYPE_CHECKING
-from ..types.config import TaskStatus, TaskStatusResponse, WaitOptions
+from typing import Optional, Dict, Any, Iterator, AsyncIterator, Callable, TYPE_CHECKING
+from ..types.config import TaskStatus, TaskStatusResponse, WaitOptions, ProgressEvent
 from ..utils.errors import ConversionError
 from ..utils.polling import poll_task_status_sync, poll_task_status_async
 
@@ -204,25 +204,54 @@ async def download_bytes_async(self) -> bytes:
 
         return await self._files_api.download_bytes_async(self._file_id)
 
-    def download_to(self, output_path: Optional[str] = None) -> str:
+    def download_stream(self) -> Iterator[bytes]:
+        """Download result file as a byte stream (sync)"""
+        if not self._file_id:
+            raise ConversionError(
+                "No result file available. Task may not be complete.",
+                self.id,
+            )
+
+        yield from self._files_api.download_stream(self._file_id)
+
+    async def download_stream_async(self) -> AsyncIterator[bytes]:
+        """Download result file as a byte stream (async)"""
+        if not self._file_id:
+            raise ConversionError(
+                "No result file available. Task may not be complete.",
+                self.id,
+            )
+
+        async for chunk in self._files_api.download_stream_async(self._file_id):
+            yield chunk
+
+    def download_to(
+        self,
+        output_path: Optional[str] = None,
+        on_progress: Optional[Callable[[ProgressEvent], None]] = None,
+    ) -> str:
         """Download result file to path (sync)"""
         if not self._file_id:
             raise ConversionError(
                 "No result file available. Task may not be complete.",
                 self.id,
             )
 
-        return self._files_api.download_to(self._file_id, output_path)
+        return self._files_api.download_to(self._file_id, output_path, on_progress)
 
-    async def download_to_async(self, output_path: Optional[str] = None) -> str:
+    async def download_to_async(
+        self,
+        output_path: Optional[str] = None,
+        on_progress: Optional[Callable[[ProgressEvent], None]] = None,
+    ) -> str:
         """Download result file to path (async)"""
         if not self._file_id:
             raise ConversionError(
                 "No result file available. Task may not be complete.",
                 self.id,
             )
 
-        return await self._files_api.download_to_async(self._file_id, output_path)
+        return await self._files_api.download_to_async(self._file_id, output_path, on_progress)
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary"""

conversiontools/types/config.py

@@ -53,6 +53,7 @@ class ConversionToolsConfig(TypedDict, total=False):
     max_polling_interval: float
     polling_backoff: float
     webhook_url: str
+    user_agent: str
     on_upload_progress: Callable[[ProgressEvent], None]
     on_download_progress: Callable[[ProgressEvent], None]
     on_conversion_progress: Callable[[ConversionProgressEvent], None]