indox-client 0.2.0__tar.gz

indox_client-0.2.0/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2024-2025 Indox
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, modification, distribution, or use of
+this Software, via any medium, is strictly prohibited.
+
+The Software is provided "AS IS", without warranty of any kind, express or implied.
+
+For licensing inquiries, contact: support@indox.org

indox_client-0.2.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: indox-client
+Version: 0.2.0
+Summary: Python SDK for the Indox media and document conversion services.
+Author-email: Indox <support@indox.org>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://indox.org
+Project-URL: Documentation, https://docs.indox.org
+Project-URL: Repository, https://github.com/indox-org/indox_client
+Project-URL: Issues, https://github.com/indox-org/indox_client/issues
+Keywords: indox,document-conversion,media-conversion,sdk,api-client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: types-requests>=2.28; extra == "dev"
+Dynamic: license-file
+
+# indox-client
+
+Python SDK for the Indox media and document conversion services.
+
+## Installation
+
+```bash
+pip install indox-client
+```
+
+## Quick Start
+
+```python
+from indox_client import IndoxClient
+
+# Initialize with API key
+client = IndoxClient(api_key="your-api-key")
+
+# Or use environment variables
+# export INDOX_API_KEY=your-api-key
+client = IndoxClient.from_env()
+
+# Convert a document
+result = client.docs.convert_file(
+    file_path="document.pdf",
+    target_formats=["docx", "txt"]
+)
+
+# Wait for completion
+completed = client.docs.wait_for_completion(result["conversion_id"])
+
+# Download the result
+client.docs.download(
+    conversion_id=result["conversion_id"],
+    output_path="output.docx",
+    fmt="docx"
+)
+```
+
+## Features
+
+- **Document Conversion**: Convert between PDF, DOCX, TXT, and more
+- **Media Conversion**: Convert images and videos between formats
+- **Async Support**: Long-polling for conversion status
+- **Multiple Sources**: Upload files, URLs, or S3 keys
+
+## Usage
+
+### Document Conversion
+
+```python
+# From local file
+result = client.docs.convert_file(
+    file_path="input.pdf",
+    target_formats=["docx"]
+)
+
+# From URL
+result = client.docs.convert_url(
+    file_url="https://example.com/document.pdf",
+    target_formats=["docx"]
+)
+
+# Check supported formats
+formats = client.docs.supported_conversions()
+```
+
+### Media Conversion
+
+```python
+# Convert image
+result = client.media.convert_image(
+    file_path="image.png",
+    target_formats=["webp", "jpg"]
+)
+
+# Convert video
+result = client.media.convert_video(
+    file_path="video.mp4",
+    target_formats=["webm"]
+)
+
+# Check supported formats
+image_formats = client.media.image_formats()
+video_formats = client.media.video_formats()
+```
+
+### Context Manager
+
+```python
+with IndoxClient.from_env() as client:
+    result = client.docs.convert_file(
+        file_path="document.pdf",
+        target_formats=["docx"]
+    )
+```
+
+## Configuration
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `INDOX_API_KEY` | Your API key |
+| `INDOX_DOCS_URL` | Docs service URL (default: https://indox.org/docs) |
+| `INDOX_MEDIA_URL` | Media service URL (default: https://indox.org/media) |
+
+## Error Handling
+
+```python
+from indox_client import IndoxClient, IndoxHTTPError, IndoxClientError
+
+try:
+    result = client.docs.convert_file(
+        file_path="document.pdf",
+        target_formats=["docx"]
+    )
+except IndoxHTTPError as e:
+    print(f"HTTP {e.status_code}: {e}")
+    print(f"Request ID: {e.request_id}")
+except IndoxClientError as e:
+    print(f"Client error: {e}")
+```
+
+## License
+
+Proprietary - see LICENSE for details.

indox_client-0.2.0/README.md

@@ -0,0 +1,125 @@
+# indox-client
+
+Python SDK for the Indox media and document conversion services.
+
+## Installation
+
+```bash
+pip install indox-client
+```
+
+## Quick Start
+
+```python
+from indox_client import IndoxClient
+
+# Initialize with API key
+client = IndoxClient(api_key="your-api-key")
+
+# Or use environment variables
+# export INDOX_API_KEY=your-api-key
+client = IndoxClient.from_env()
+
+# Convert a document
+result = client.docs.convert_file(
+    file_path="document.pdf",
+    target_formats=["docx", "txt"]
+)
+
+# Wait for completion
+completed = client.docs.wait_for_completion(result["conversion_id"])
+
+# Download the result
+client.docs.download(
+    conversion_id=result["conversion_id"],
+    output_path="output.docx",
+    fmt="docx"
+)
+```
+
+## Features
+
+- **Document Conversion**: Convert between PDF, DOCX, TXT, and more
+- **Media Conversion**: Convert images and videos between formats
+- **Async Support**: Long-polling for conversion status
+- **Multiple Sources**: Upload files, URLs, or S3 keys
+
+## Usage
+
+### Document Conversion
+
+```python
+# From local file
+result = client.docs.convert_file(
+    file_path="input.pdf",
+    target_formats=["docx"]
+)
+
+# From URL
+result = client.docs.convert_url(
+    file_url="https://example.com/document.pdf",
+    target_formats=["docx"]
+)
+
+# Check supported formats
+formats = client.docs.supported_conversions()
+```
+
+### Media Conversion
+
+```python
+# Convert image
+result = client.media.convert_image(
+    file_path="image.png",
+    target_formats=["webp", "jpg"]
+)
+
+# Convert video
+result = client.media.convert_video(
+    file_path="video.mp4",
+    target_formats=["webm"]
+)
+
+# Check supported formats
+image_formats = client.media.image_formats()
+video_formats = client.media.video_formats()
+```
+
+### Context Manager
+
+```python
+with IndoxClient.from_env() as client:
+    result = client.docs.convert_file(
+        file_path="document.pdf",
+        target_formats=["docx"]
+    )
+```
+
+## Configuration
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `INDOX_API_KEY` | Your API key |
+| `INDOX_DOCS_URL` | Docs service URL (default: https://indox.org/docs) |
+| `INDOX_MEDIA_URL` | Media service URL (default: https://indox.org/media) |
+
+## Error Handling
+
+```python
+from indox_client import IndoxClient, IndoxHTTPError, IndoxClientError
+
+try:
+    result = client.docs.convert_file(
+        file_path="document.pdf",
+        target_formats=["docx"]
+    )
+except IndoxHTTPError as e:
+    print(f"HTTP {e.status_code}: {e}")
+    print(f"Request ID: {e.request_id}")
+except IndoxClientError as e:
+    print(f"Client error: {e}")
+```
+
+## License
+
+Proprietary - see LICENSE for details.

indox_client-0.2.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=67", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "indox-client"
+version = "0.2.0"
+description = "Python SDK for the Indox media and document conversion services."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "LicenseRef-Proprietary"
+authors = [
+  {name = "Indox", email = "support@indox.org"}
+]
+keywords = ["indox", "document-conversion", "media-conversion", "sdk", "api-client"]
+dependencies = [
+  "requests>=2.28.0"
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://indox.org"
+Documentation = "https://docs.indox.org"
+Repository = "https://github.com/indox-org/indox_client"
+Issues = "https://github.com/indox-org/indox_client/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-cov>=4.0",
+  "responses>=0.23.0",
+  "ruff>=0.1.0",
+  "mypy>=1.0",
+  "types-requests>=2.28",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+exclude = ["tests*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_return_any = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --cov=indox_client --cov-report=term-missing"

indox_client-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

indox_client-0.2.0/src/indox_client/__init__.py

@@ -0,0 +1,16 @@
+"""Indox Python SDK for media and document conversion services."""
+
+from .version import __version__
+from .exceptions import IndoxClientError, IndoxHTTPError
+from .client import IndoxClient
+from .docs import DocsClient
+from .media import MediaClient
+
+__all__ = [
+    "__version__",
+    "IndoxClient",
+    "DocsClient",
+    "MediaClient",
+    "IndoxClientError",
+    "IndoxHTTPError",
+]

indox_client-0.2.0/src/indox_client/base.py

@@ -0,0 +1,131 @@
+"""Shared HTTP plumbing for DocsClient and MediaClient."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Iterable, Mapping, MutableMapping, Optional
+
+import requests
+
+from .exceptions import IndoxClientError, IndoxHTTPError
+from .version import __version__
+
+
+DEFAULT_TIMEOUT = (5, 60)  # (connect, read)
+
+
+class BaseServiceClient:
+    """Convenience wrapper around `requests` with Indox defaults."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout: Optional[tuple[float, float] | float] = None,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url is required")
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key.strip()
+        self.timeout = timeout or DEFAULT_TIMEOUT
+        self._session = session or requests.Session()
+        self._user_agent = f"indox-client/{__version__}"
+
+    # --------------------------------------------------------------------- #
+    # Internal helpers
+    # --------------------------------------------------------------------- #
+    def _build_url(self, path: str) -> str:
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        if not path.startswith("/"):
+            path = f"/{path}"
+        return f"{self.base_url}{path}"
+
+    def _headers(self, extra: Optional[Mapping[str, str]] = None) -> MutableMapping[str, str]:
+        headers: MutableMapping[str, str] = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": self._user_agent,
+        }
+        if extra:
+            headers.update({k: v for k, v in extra.items() if v is not None})
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json_body: Optional[Mapping[str, Any]] = None,
+        data: Optional[Mapping[str, Any]] = None,
+        files: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[tuple[float, float] | float] = None,
+        expected: Iterable[int] = (200, 201, 202),
+        stream: bool = False,
+    ) -> Any:
+        url = self._build_url(path)
+        final_headers = self._headers(headers)
+
+        try:
+            response = self._session.request(
+                method=method.upper(),
+                url=url,
+                params=params,
+                json=json_body,
+                data=data,
+                files=files,
+                headers=final_headers,
+                timeout=timeout or self.timeout,
+                stream=stream,
+            )
+        except requests.RequestException as exc:
+            raise IndoxClientError(f"Request to {url} failed: {exc}") from exc
+
+        if response.status_code not in expected:
+            payload = _safe_json(response)
+            request_id = response.headers.get("X-Request-ID")
+            message = payload.get("detail") if isinstance(payload, dict) else response.text
+            raise IndoxHTTPError(
+                response.status_code,
+                message or f"Unexpected status {response.status_code}",
+                payload=payload if isinstance(payload, Mapping) else {"raw": response.text},
+                request_id=request_id,
+                url=url,
+            )
+
+        if stream:
+            return response
+
+        if not response.content:
+            return {}
+
+        return _safe_json(response)
+
+    def close(self) -> None:
+        self._session.close()
+
+    # ------------------------------------------------------------------ #
+    # Convenience wrappers for subclasses
+    # ------------------------------------------------------------------ #
+    def _post_json(self, path: str, payload: Mapping[str, Any], **kwargs) -> Any:
+        return self._request("POST", path, json_body=payload, **kwargs)
+
+    def _post_multipart(self, path: str, data: Mapping[str, Any], files: Mapping[str, Any], **kwargs) -> Any:
+        return self._request("POST", path, data=data, files=files, **kwargs)
+
+    def _get(self, path: str, params: Optional[Mapping[str, Any]] = None, **kwargs) -> Any:
+        return self._request("GET", path, params=params, **kwargs)
+
+
+def _safe_json(response: requests.Response) -> Any:
+    try:
+        return response.json()
+    except json.JSONDecodeError:
+        return {"raw": response.text}

indox_client-0.2.0/src/indox_client/client.py

@@ -0,0 +1,79 @@
+"""Facade that exposes DocsClient and MediaClient under one object."""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from .docs import DocsClient
+from .media import MediaClient
+
+
+DEFAULT_DOCS_BASE_URL = "https://indox.org/docs"
+DEFAULT_MEDIA_BASE_URL = "https://indox.org/media"
+
+
+class IndoxClient:
+    """Convenience wrapper that bundles docs + media clients."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        docs_base_url: str = DEFAULT_DOCS_BASE_URL,
+        media_base_url: str = DEFAULT_MEDIA_BASE_URL,
+        timeout: Optional[tuple[float, float] | float] = None,
+    ) -> None:
+        docs_url = (docs_base_url or DEFAULT_DOCS_BASE_URL or "").strip().rstrip("/")
+        media_url = (media_base_url or DEFAULT_MEDIA_BASE_URL or "").strip().rstrip("/")
+
+        if not docs_url:
+            raise ValueError("docs_base_url is required")
+        if not media_url:
+            raise ValueError("media_base_url is required")
+
+        self.docs = DocsClient(base_url=docs_url, api_key=api_key, timeout=timeout)
+        self.media = MediaClient(base_url=media_url, api_key=api_key, timeout=timeout)
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        api_key: Optional[str] = None,
+        docs_base_url: Optional[str] = None,
+        media_base_url: Optional[str] = None,
+        timeout: Optional[tuple[float, float] | float] = None,
+    ) -> "IndoxClient":
+        """Instantiate the client using standard environment variables."""
+        key = (api_key or os.getenv("INDOX_API_KEY") or "").strip()
+        docs_url = (
+            docs_base_url
+            or os.getenv("INDOX_DOCS_URL")
+            or DEFAULT_DOCS_BASE_URL
+        ).strip()
+        media_url = (
+            media_base_url
+            or os.getenv("INDOX_MEDIA_URL")
+            or DEFAULT_MEDIA_BASE_URL
+        ).strip()
+
+        if not key:
+            raise ValueError("api_key or INDOX_API_KEY is required")
+
+        return cls(
+            api_key=key,
+            docs_base_url=docs_url,
+            media_base_url=media_url,
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP sessions."""
+        self.docs.close()
+        self.media.close()
+
+    def __enter__(self) -> "IndoxClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()

indox_client-0.2.0/src/indox_client/docs.py

@@ -0,0 +1,139 @@
+"""Client for the Indox document conversion service."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Iterable, Mapping, MutableMapping, Optional
+
+from .base import BaseServiceClient
+from .exceptions import IndoxClientError
+
+
+class DocsClient(BaseServiceClient):
+    """High-level wrapper around `/api/v1/docs/*` endpoints."""
+
+    def supported_conversions(self) -> Mapping[str, Any]:
+        """Return the formats/operations advertised by the service."""
+        return self._get("/api/v1/docs/formats/")
+
+    def convert_file(
+        self,
+        *,
+        file_path: str | os.PathLike[str],
+        target_formats: Iterable[str],
+        destination: str = "aws",
+        redirect_url: Optional[str] = None,
+        engine: Optional[str] = None,
+        options: Optional[Mapping[str, Any]] = None,
+        s3_key: Optional[str] = None,
+    ) -> Mapping[str, Any]:
+        """Upload a local file for conversion."""
+        formats = _clean_formats(target_formats)
+        if not formats:
+            raise IndoxClientError("target_formats is required")
+
+        payload: Dict[str, Any] = {
+            "target_formats": formats,
+            "destination": destination,
+        }
+        if redirect_url:
+            payload["redirect_url"] = redirect_url
+        if engine:
+            payload["engine"] = engine
+        if s3_key:
+            payload["s3_key"] = s3_key
+        if options is not None:
+            payload["options"] = json.dumps(options)
+
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(path)
+
+        with path.open("rb") as fh:
+            files = {"file": (path.name, fh)}
+            return self._post_multipart("/api/v1/docs/convert/", data=payload, files=files)
+
+    def convert_url(
+        self,
+        *,
+        file_url: Optional[str] = None,
+        s3_key: Optional[str] = None,
+        target_formats: Iterable[str],
+        destination: str = "aws",
+        redirect_url: Optional[str] = None,
+        engine: Optional[str] = None,
+        options: Optional[Mapping[str, Any]] = None,
+    ) -> Mapping[str, Any]:
+        """Trigger a conversion for a remote file or S3 object."""
+        formats = _clean_formats(target_formats)
+        if not formats:
+            raise IndoxClientError("target_formats is required")
+        if not file_url and not s3_key:
+            raise IndoxClientError("Provide file_url or s3_key")
+
+        payload: Dict[str, Any] = {
+            "target_formats": formats,
+            "destination": destination,
+        }
+        if file_url:
+            payload["url"] = file_url
+        if s3_key:
+            payload["s3_key"] = s3_key
+        if redirect_url:
+            payload["redirect_url"] = redirect_url
+        if engine:
+            payload["engine"] = engine
+        if options is not None:
+            payload["options"] = options
+
+        return self._post_json("/api/v1/docs/convert/json/", payload)
+
+    def get_conversion(self, conversion_id: str) -> Mapping[str, Any]:
+        """Fetch metadata for a conversion or batch."""
+        return self._get(f"/api/v1/conversion/{conversion_id}/")
+
+    def wait_for_completion(
+        self,
+        conversion_id: str,
+        *,
+        timeout_seconds: float = 60.0,
+        poll_interval: float = 0.5,
+    ) -> Mapping[str, Any]:
+        """Block until a conversion completes or the timeout elapses."""
+        params = {"timeout": timeout_seconds, "interval": poll_interval}
+        return self._get(f"/api/v1/conversion/wait/{conversion_id}/", params=params)
+
+    def download(
+        self,
+        *,
+        conversion_id: str,
+        output_path: str | os.PathLike[str],
+        fmt: Optional[str] = None,
+    ) -> Path:
+        """Download the converted artifact to disk."""
+        params = {"format": fmt} if fmt else None
+        response = self._request(
+            "GET",
+            f"/api/v1/docs/{conversion_id}/download/",
+            params=params,
+            stream=True,
+            expected=(200,),
+        )
+        target = Path(output_path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with target.open("wb") as fh:
+            for chunk in response.iter_content(chunk_size=8192):
+                if chunk:
+                    fh.write(chunk)
+        return target
+
+
+def _clean_formats(formats: Iterable[str]) -> list[str]:
+    cleaned: list[str] = []
+    for fmt in formats:
+        token = (fmt or "").strip().lower().lstrip(".")
+        if token:
+            cleaned.append(token)
+    return cleaned

indox_client-0.2.0/src/indox_client/exceptions.py

@@ -0,0 +1,41 @@
+"""Custom exception hierarchy used by the Indox client."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, MutableMapping, Optional
+
+
+class IndoxClientError(Exception):
+    """Base class for all SDK errors."""
+
+    def __init__(self, message: str, *, payload: Optional[Mapping[str, Any]] = None):
+        super().__init__(message)
+        self.payload = payload or {}
+
+
+class IndoxHTTPError(IndoxClientError):
+    """Raised when the remote service returns a non-success HTTP status."""
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        *,
+        payload: Optional[Mapping[str, Any]] = None,
+        request_id: Optional[str] = None,
+        url: Optional[str] = None,
+    ):
+        super().__init__(message, payload=payload)
+        self.status_code = status_code
+        self.request_id = request_id
+        self.url = url
+
+    def to_dict(self) -> MutableMapping[str, Any]:
+        """Return a dict representation that is easy to log/serialize."""
+        return {
+            "status_code": self.status_code,
+            "message": str(self),
+            "request_id": self.request_id,
+            "url": self.url,
+            "payload": self.payload,
+        }

indox_client-0.2.0/src/indox_client/media.py

@@ -0,0 +1,175 @@
+"""Client for the Indox media service (images + videos)."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Optional
+
+from .base import BaseServiceClient
+from .exceptions import IndoxClientError
+
+
+class MediaClient(BaseServiceClient):
+    """Wrapper around `/api/v1/image/*`, `/api/v1/video/*`, and download routes."""
+
+    def image_formats(self) -> Mapping[str, Any]:
+        """List supported image formats from `/api/v1/image/formats/`."""
+        return self._get("/api/v1/image/formats/")
+
+    def video_formats(self) -> Mapping[str, Any]:
+        """List supported video formats from `/api/v1/video/formats/`."""
+        return self._get("/api/v1/video/formats/")
+
+    def image_operations(self) -> Mapping[str, Any]:
+        """Fetch the advertised image operations for discovery."""
+        return self._get("/api/v1/image/operations/")
+
+    def video_operations(self) -> Mapping[str, Any]:
+        """Fetch the advertised video operations for discovery."""
+        return self._get("/api/v1/video/operations/")
+
+    def convert_image(
+        self,
+        file_path: str | os.PathLike[str] | None = None,
+        target_formats: Iterable[str] = (),
+        *,
+        file_url: Optional[str] = None,
+        s3_key: Optional[str] = None,
+        destination: str = "aws",
+        redirect_url: Optional[str] = None,
+        engine: Optional[str] = None,
+        options: Optional[Mapping[str, Any]] = None,
+    ) -> Mapping[str, Any]:
+        """Start an image conversion job."""
+        return self._convert_media(
+            endpoint="/api/v1/image/convert/",
+            file_path=file_path,
+            file_url=file_url,
+            s3_key=s3_key,
+            target_formats=target_formats,
+            destination=destination,
+            redirect_url=redirect_url,
+            engine=engine,
+            options=options,
+        )
+
+    def convert_video(
+        self,
+        file_path: str | os.PathLike[str] | None = None,
+        target_formats: Iterable[str] = (),
+        *,
+        file_url: Optional[str] = None,
+        s3_key: Optional[str] = None,
+        destination: str = "aws",
+        redirect_url: Optional[str] = None,
+        engine: Optional[str] = None,
+        options: Optional[Mapping[str, Any]] = None,
+    ) -> Mapping[str, Any]:
+        """Start a video conversion job."""
+        return self._convert_media(
+            endpoint="/api/v1/video/convert/",
+            file_path=file_path,
+            file_url=file_url,
+            s3_key=s3_key,
+            target_formats=target_formats,
+            destination=destination,
+            redirect_url=redirect_url,
+            engine=engine,
+            options=options,
+        )
+
+    def get_image_conversion(self, conversion_id: str) -> Mapping[str, Any]:
+        return self._get(f"/api/v1/image/conversion/{conversion_id}/")
+
+    def get_video_conversion(self, conversion_id: str) -> Mapping[str, Any]:
+        return self._get(f"/api/v1/video/conversion/{conversion_id}/")
+
+    def wait_for_conversion(
+        self,
+        conversion_id: str,
+        *,
+        timeout_seconds: float = 60.0,
+        poll_interval: float = 0.5,
+    ) -> Mapping[str, Any]:
+        params = {"timeout": timeout_seconds, "interval": poll_interval}
+        return self._get(f"/api/v1/conversion/wait/{conversion_id}/", params=params)
+
+    def download_media(
+        self,
+        *,
+        conversion_id: str,
+        output_path: str | os.PathLike[str],
+        fmt: Optional[str] = None,
+    ) -> Path:
+        params = {"format": fmt} if fmt else None
+        response = self._request(
+            "GET",
+            f"/api/v1/media/{conversion_id}/download/",
+            params=params,
+            stream=True,
+            expected=(200,),
+        )
+        target = Path(output_path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with target.open("wb") as fh:
+            for chunk in response.iter_content(chunk_size=8192):
+                if chunk:
+                    fh.write(chunk)
+        return target
+
+    def _convert_media(
+        self,
+        *,
+        endpoint: str,
+        file_path: str | os.PathLike[str] | None,
+        file_url: Optional[str],
+        s3_key: Optional[str],
+        target_formats: Iterable[str],
+        destination: str,
+        redirect_url: Optional[str],
+        engine: Optional[str],
+        options: Optional[Mapping[str, Any]],
+    ) -> Mapping[str, Any]:
+        formats = _clean_formats(target_formats)
+        if not formats:
+            raise IndoxClientError("target_formats is required")
+
+        payload: dict[str, Any] = {
+            "target_formats": formats,
+            "destination": destination,
+        }
+        if file_url:
+            payload["file_url"] = file_url
+        if s3_key:
+            payload["s3_key"] = s3_key
+        if redirect_url:
+            payload["redirect_url"] = redirect_url
+        if engine:
+            payload["engine"] = engine
+        if options is not None:
+            payload["options"] = json.dumps(options) if file_path else options
+
+        has_upload = file_path is not None
+        if has_upload:
+            path = Path(file_path)
+            if not path.exists():
+                raise FileNotFoundError(path)
+            with path.open("rb") as fh:
+                files = {"file": (path.name, fh)}
+                return self._post_multipart(endpoint, data=payload, files=files)
+
+        if not file_url and not s3_key:
+            raise IndoxClientError("Provide file_path, file_url, or s3_key")
+
+        return self._post_json(endpoint, payload)
+
+
+def _clean_formats(formats: Iterable[str]) -> list[str]:
+    cleaned: list[str] = []
+    for fmt in formats:
+        token = (fmt or "").strip().lower().lstrip(".")
+        if token:
+            cleaned.append(token)
+    return cleaned

indox_client-0.2.0/src/indox_client/version.py

@@ -0,0 +1,3 @@
+"""Central place for the package version so every module can import it."""
+
+__version__ = "0.1.1"

indox_client-0.2.0/src/indox_client.egg-info/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: indox-client
+Version: 0.2.0
+Summary: Python SDK for the Indox media and document conversion services.
+Author-email: Indox <support@indox.org>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://indox.org
+Project-URL: Documentation, https://docs.indox.org
+Project-URL: Repository, https://github.com/indox-org/indox_client
+Project-URL: Issues, https://github.com/indox-org/indox_client/issues
+Keywords: indox,document-conversion,media-conversion,sdk,api-client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: types-requests>=2.28; extra == "dev"
+Dynamic: license-file
+
+# indox-client
+
+Python SDK for the Indox media and document conversion services.
+
+## Installation
+
+```bash
+pip install indox-client
+```
+
+## Quick Start
+
+```python
+from indox_client import IndoxClient
+
+# Initialize with API key
+client = IndoxClient(api_key="your-api-key")
+
+# Or use environment variables
+# export INDOX_API_KEY=your-api-key
+client = IndoxClient.from_env()
+
+# Convert a document
+result = client.docs.convert_file(
+    file_path="document.pdf",
+    target_formats=["docx", "txt"]
+)
+
+# Wait for completion
+completed = client.docs.wait_for_completion(result["conversion_id"])
+
+# Download the result
+client.docs.download(
+    conversion_id=result["conversion_id"],
+    output_path="output.docx",
+    fmt="docx"
+)
+```
+
+## Features
+
+- **Document Conversion**: Convert between PDF, DOCX, TXT, and more
+- **Media Conversion**: Convert images and videos between formats
+- **Async Support**: Long-polling for conversion status
+- **Multiple Sources**: Upload files, URLs, or S3 keys
+
+## Usage
+
+### Document Conversion
+
+```python
+# From local file
+result = client.docs.convert_file(
+    file_path="input.pdf",
+    target_formats=["docx"]
+)
+
+# From URL
+result = client.docs.convert_url(
+    file_url="https://example.com/document.pdf",
+    target_formats=["docx"]
+)
+
+# Check supported formats
+formats = client.docs.supported_conversions()
+```
+
+### Media Conversion
+
+```python
+# Convert image
+result = client.media.convert_image(
+    file_path="image.png",
+    target_formats=["webp", "jpg"]
+)
+
+# Convert video
+result = client.media.convert_video(
+    file_path="video.mp4",
+    target_formats=["webm"]
+)
+
+# Check supported formats
+image_formats = client.media.image_formats()
+video_formats = client.media.video_formats()
+```
+
+### Context Manager
+
+```python
+with IndoxClient.from_env() as client:
+    result = client.docs.convert_file(
+        file_path="document.pdf",
+        target_formats=["docx"]
+    )
+```
+
+## Configuration
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `INDOX_API_KEY` | Your API key |
+| `INDOX_DOCS_URL` | Docs service URL (default: https://indox.org/docs) |
+| `INDOX_MEDIA_URL` | Media service URL (default: https://indox.org/media) |
+
+## Error Handling
+
+```python
+from indox_client import IndoxClient, IndoxHTTPError, IndoxClientError
+
+try:
+    result = client.docs.convert_file(
+        file_path="document.pdf",
+        target_formats=["docx"]
+    )
+except IndoxHTTPError as e:
+    print(f"HTTP {e.status_code}: {e}")
+    print(f"Request ID: {e.request_id}")
+except IndoxClientError as e:
+    print(f"Client error: {e}")
+```
+
+## License
+
+Proprietary - see LICENSE for details.

indox_client-0.2.0/src/indox_client.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/indox_client/__init__.py
+src/indox_client/base.py
+src/indox_client/client.py
+src/indox_client/docs.py
+src/indox_client/exceptions.py
+src/indox_client/media.py
+src/indox_client/version.py
+src/indox_client.egg-info/PKG-INFO
+src/indox_client.egg-info/SOURCES.txt
+src/indox_client.egg-info/dependency_links.txt
+src/indox_client.egg-info/requires.txt
+src/indox_client.egg-info/top_level.txt
+tests/test_client.py

indox_client-0.2.0/src/indox_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

indox_client-0.2.0/src/indox_client.egg-info/requires.txt

@@ -0,0 +1,9 @@
+requests>=2.28.0
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0
+responses>=0.23.0
+ruff>=0.1.0
+mypy>=1.0
+types-requests>=2.28

indox_client-0.2.0/src/indox_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+indox_client

indox_client-0.2.0/tests/test_client.py

@@ -0,0 +1,128 @@
+"""Unit tests for indox_client."""
+
+import pytest
+import responses
+from indox_client import IndoxClient, IndoxClientError, IndoxHTTPError
+
+
+class TestIndoxClient:
+    """Test IndoxClient initialization."""
+
+    def test_init_requires_api_key(self):
+        with pytest.raises(ValueError, match="api_key is required"):
+            IndoxClient(api_key="")
+
+    def test_init_with_api_key(self):
+        client = IndoxClient(api_key="test-key")
+        assert client.docs.api_key == "test-key"
+        assert client.media.api_key == "test-key"
+
+    def test_context_manager(self):
+        with IndoxClient(api_key="test-key") as client:
+            assert client.docs is not None
+            assert client.media is not None
+
+
+class TestDocsClient:
+    """Test DocsClient methods."""
+
+    @responses.activate
+    def test_supported_conversions(self):
+        responses.add(
+            responses.GET,
+            "https://indox.org/docs/api/v1/docs/formats/",
+            json={"formats": ["pdf", "docx"]},
+            status=200,
+        )
+        client = IndoxClient(api_key="test-key")
+        result = client.docs.supported_conversions()
+        assert result["formats"] == ["pdf", "docx"]
+
+    @responses.activate
+    def test_convert_url(self):
+        responses.add(
+            responses.POST,
+            "https://indox.org/docs/api/v1/docs/convert/json/",
+            json={"conversion_id": "abc123", "status": "pending"},
+            status=202,
+        )
+        client = IndoxClient(api_key="test-key")
+        result = client.docs.convert_url(
+            file_url="https://example.com/doc.pdf",
+            target_formats=["docx"],
+        )
+        assert result["conversion_id"] == "abc123"
+
+    def test_convert_url_requires_source(self):
+        client = IndoxClient(api_key="test-key")
+        with pytest.raises(IndoxClientError, match="Provide file_url or s3_key"):
+            client.docs.convert_url(target_formats=["docx"])
+
+    def test_convert_url_requires_formats(self):
+        client = IndoxClient(api_key="test-key")
+        with pytest.raises(IndoxClientError, match="target_formats is required"):
+            client.docs.convert_url(file_url="https://example.com/doc.pdf", target_formats=[])
+
+
+class TestMediaClient:
+    """Test MediaClient methods."""
+
+    @responses.activate
+    def test_image_formats(self):
+        responses.add(
+            responses.GET,
+            "https://indox.org/media/api/v1/image/formats/",
+            json={"formats": ["png", "jpg", "webp"]},
+            status=200,
+        )
+        client = IndoxClient(api_key="test-key")
+        result = client.media.image_formats()
+        assert "png" in result["formats"]
+
+    @responses.activate
+    def test_convert_image_from_url(self):
+        responses.add(
+            responses.POST,
+            "https://indox.org/media/api/v1/image/convert/",
+            json={"conversion_id": "img123", "status": "pending"},
+            status=202,
+        )
+        client = IndoxClient(api_key="test-key")
+        result = client.media.convert_image(
+            file_url="https://example.com/image.png",
+            target_formats=["webp"],
+        )
+        assert result["conversion_id"] == "img123"
+
+
+class TestHTTPErrors:
+    """Test error handling."""
+
+    @responses.activate
+    def test_http_error_raised(self):
+        responses.add(
+            responses.GET,
+            "https://indox.org/docs/api/v1/docs/formats/",
+            json={"detail": "Unauthorized"},
+            status=401,
+        )
+        client = IndoxClient(api_key="bad-key")
+        with pytest.raises(IndoxHTTPError) as exc_info:
+            client.docs.supported_conversions()
+        assert exc_info.value.status_code == 401
+
+    @responses.activate
+    def test_http_error_to_dict(self):
+        responses.add(
+            responses.GET,
+            "https://indox.org/docs/api/v1/docs/formats/",
+            json={"detail": "Not found"},
+            status=404,
+            headers={"X-Request-ID": "req-123"},
+        )
+        client = IndoxClient(api_key="test-key")
+        with pytest.raises(IndoxHTTPError) as exc_info:
+            client.docs.supported_conversions()
+        error_dict = exc_info.value.to_dict()
+        assert error_dict["status_code"] == 404
+        assert error_dict["request_id"] == "req-123"