polylingo 0.1.0__tar.gz

polylingo-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.venv/
+venv/

polylingo-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: polylingo
+Version: 0.1.0
+Summary: Official Python SDK for the PolyLingo translation API
+Project-URL: Homepage, https://usepolylingo.com
+Project-URL: Documentation, https://usepolylingo.com/en/docs/sdk/python
+Project-URL: Repository, https://github.com/UsePolyLingo/polylingo-python
+Project-URL: Issues, https://github.com/UsePolyLingo/polylingo-python/issues
+Author: PolyLingo
+License-Expression: MIT
+Keywords: api,i18n,markdown,polylingo,translation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: httpx>=0.24; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# polylingo (Python)
+
+Official Python SDK for the [PolyLingo](https://usepolylingo.com) translation API.
+
+**Requirements:** Python 3.9+
+
+## Install
+
+```bash
+pip install polylingo
+```
+
+## Sync usage
+
+```python
+import os
+import polylingo
+
+client = polylingo.PolyLingo(
+    api_key=os.environ["POLYLINGO_API_KEY"],
+    # base_url="https://api.polylingo.io/v1",
+    # timeout=120.0,
+)
+
+result = client.translate(content="# Hello", targets=["es", "fr"], format="markdown")
+print(result["translations"]["es"])
+client.close()
+```
+
+Context manager:
+
+```python
+with polylingo.PolyLingo(api_key="...") as client:
+    print(client.languages())
+```
+
+## Async usage
+
+```python
+import polylingo
+
+async with polylingo.AsyncPolyLingo(api_key="...") as client:
+    r = await client.translate(content="Hi", targets=["de"])
+```
+
+## API
+
+- `health()` / `await health()`
+- `languages()`
+- `translate(content=..., targets=..., format=..., source=..., model=...)`
+- `batch(items=..., targets=..., source=..., model=...)`
+- `usage()`
+- `jobs.create(...)` — returns 202 payload
+- `jobs.get(job_id)`
+- `jobs.translate(..., poll_interval=5.0, timeout=1200.0, on_progress=...)`
+
+## Exceptions
+
+- `PolyLingoError` — base (`status`, `error`, `args[0]` message)
+- `AuthError` — 401
+- `RateLimitError` — 429 (`retry_after`)
+- `JobFailedError` — failed job (`job_id`)
+
+## Docs
+
+[Python SDK reference](https://usepolylingo.com/en/docs/sdk/python) (when deployed).
+
+## Repository
+
+[UsePolyLingo/polylingo-python](https://github.com/UsePolyLingo/polylingo-python)
+
+## License
+
+MIT

polylingo-0.1.0/README.md

@@ -0,0 +1,74 @@
+# polylingo (Python)
+
+Official Python SDK for the [PolyLingo](https://usepolylingo.com) translation API.
+
+**Requirements:** Python 3.9+
+
+## Install
+
+```bash
+pip install polylingo
+```
+
+## Sync usage
+
+```python
+import os
+import polylingo
+
+client = polylingo.PolyLingo(
+    api_key=os.environ["POLYLINGO_API_KEY"],
+    # base_url="https://api.polylingo.io/v1",
+    # timeout=120.0,
+)
+
+result = client.translate(content="# Hello", targets=["es", "fr"], format="markdown")
+print(result["translations"]["es"])
+client.close()
+```
+
+Context manager:
+
+```python
+with polylingo.PolyLingo(api_key="...") as client:
+    print(client.languages())
+```
+
+## Async usage
+
+```python
+import polylingo
+
+async with polylingo.AsyncPolyLingo(api_key="...") as client:
+    r = await client.translate(content="Hi", targets=["de"])
+```
+
+## API
+
+- `health()` / `await health()`
+- `languages()`
+- `translate(content=..., targets=..., format=..., source=..., model=...)`
+- `batch(items=..., targets=..., source=..., model=...)`
+- `usage()`
+- `jobs.create(...)` — returns 202 payload
+- `jobs.get(job_id)`
+- `jobs.translate(..., poll_interval=5.0, timeout=1200.0, on_progress=...)`
+
+## Exceptions
+
+- `PolyLingoError` — base (`status`, `error`, `args[0]` message)
+- `AuthError` — 401
+- `RateLimitError` — 429 (`retry_after`)
+- `JobFailedError` — failed job (`job_id`)
+
+## Docs
+
+[Python SDK reference](https://usepolylingo.com/en/docs/sdk/python) (when deployed).
+
+## Repository
+
+[UsePolyLingo/polylingo-python](https://github.com/UsePolyLingo/polylingo-python)
+
+## License
+
+MIT

polylingo-0.1.0/polylingo/__init__.py

@@ -0,0 +1,14 @@
+from polylingo._async_client import AsyncPolyLingo
+from polylingo._client import PolyLingo
+from polylingo._errors import AuthError, JobFailedError, PolyLingoError, RateLimitError
+
+__all__ = [
+    "PolyLingo",
+    "AsyncPolyLingo",
+    "PolyLingoError",
+    "AuthError",
+    "RateLimitError",
+    "JobFailedError",
+]
+
+__version__ = "0.1.0"

polylingo-0.1.0/polylingo/_async_client.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from typing import Any, Literal, Optional, Union
+
+import httpx
+
+from polylingo._errors import PolyLingoError
+from polylingo._http_utils import error_from_response
+from polylingo.resources._async_batch import batch_async
+from polylingo.resources._async_health import health_async
+from polylingo.resources._async_jobs import AsyncJobsResource
+from polylingo.resources._async_languages import languages_async
+from polylingo.resources._async_translate import translate_async
+from polylingo.resources._async_usage import usage_async
+
+DEFAULT_BASE_URL = "https://api.polylingo.io/v1"
+
+ExpectStatus = Union[int, tuple[int, ...]]
+
+
+class AsyncPolyLingo:
+    """Asynchronous PolyLingo API client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 120.0,
+    ) -> None:
+        if not api_key or not isinstance(api_key, str):
+            raise TypeError("AsyncPolyLingo: api_key is required")
+        self._base = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+        self._client = httpx.AsyncClient(
+            base_url=self._base,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Accept": "application/json",
+            },
+            timeout=httpx.Timeout(timeout),
+        )
+        self.jobs = AsyncJobsResource(self)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncPolyLingo:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()
+
+    async def _request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[dict[str, Any]] = None,
+        expect_status: Optional[ExpectStatus] = None,
+    ) -> Any:
+        try:
+            response = await self._client.request(method, path, json=json)
+        except httpx.TimeoutException:
+            raise PolyLingoError(
+                408,
+                "timeout",
+                f"Request timed out after {self._timeout}s",
+            ) from None
+
+        exp = expect_status
+        if exp is None:
+            ok = response.is_success
+        elif isinstance(exp, tuple):
+            ok = response.status_code in exp
+        else:
+            ok = response.status_code == exp
+
+        if not ok:
+            raise error_from_response(response)
+
+        if response.status_code == 204 or not response.content:
+            return {}
+        return response.json()
+
+    async def health(self) -> dict[str, Any]:
+        return await health_async(self)
+
+    async def languages(self) -> dict[str, Any]:
+        return await languages_async(self)
+
+    async def translate(
+        self,
+        *,
+        content: str,
+        targets: list[str],
+        format: Optional[Literal["plain", "markdown", "json", "html"]] = None,
+        source: Optional[str] = None,
+        model: Optional[Literal["standard", "advanced"]] = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {"content": content, "targets": targets}
+        if format is not None:
+            params["format"] = format
+        if source is not None:
+            params["source"] = source
+        if model is not None:
+            params["model"] = model
+        return await translate_async(self, params)
+
+    async def batch(
+        self,
+        *,
+        items: list[dict[str, Any]],
+        targets: list[str],
+        source: Optional[str] = None,
+        model: Optional[Literal["standard", "advanced"]] = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {"items": items, "targets": targets}
+        if source is not None:
+            params["source"] = source
+        if model is not None:
+            params["model"] = model
+        return await batch_async(self, params)
+
+    async def usage(self) -> dict[str, Any]:
+        return await usage_async(self)

polylingo-0.1.0/polylingo/_client.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from typing import Any, Literal, Optional, Union
+
+import httpx
+
+from polylingo._errors import PolyLingoError
+from polylingo._http_utils import error_from_response
+from polylingo.resources._batch import batch
+from polylingo.resources._health import health
+from polylingo.resources._jobs import JobsResource
+from polylingo.resources._languages import languages
+from polylingo.resources._translate import translate
+from polylingo.resources._usage import usage
+
+DEFAULT_BASE_URL = "https://api.polylingo.io/v1"
+
+ExpectStatus = Union[int, tuple[int, ...]]
+
+
+class PolyLingo:
+    """Synchronous PolyLingo API client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 120.0,
+    ) -> None:
+        if not api_key or not isinstance(api_key, str):
+            raise TypeError("PolyLingo: api_key is required")
+        self._base = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+        self._client = httpx.Client(
+            base_url=self._base,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Accept": "application/json",
+            },
+            timeout=httpx.Timeout(timeout),
+        )
+        self.jobs = JobsResource(self)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> PolyLingo:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def _request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[dict[str, Any]] = None,
+        expect_status: Optional[ExpectStatus] = None,
+    ) -> Any:
+        try:
+            response = self._client.request(method, path, json=json)
+        except httpx.TimeoutException:
+            raise PolyLingoError(
+                408,
+                "timeout",
+                f"Request timed out after {self._timeout}s",
+            ) from None
+
+        exp = expect_status
+        if exp is None:
+            ok = response.is_success
+        elif isinstance(exp, tuple):
+            ok = response.status_code in exp
+        else:
+            ok = response.status_code == exp
+
+        if not ok:
+            raise error_from_response(response)
+
+        if response.status_code == 204 or not response.content:
+            return {}
+        return response.json()
+
+    def health(self) -> dict[str, Any]:
+        return health(self)
+
+    def languages(self) -> dict[str, Any]:
+        return languages(self)
+
+    def translate(
+        self,
+        *,
+        content: str,
+        targets: list[str],
+        format: Optional[Literal["plain", "markdown", "json", "html"]] = None,
+        source: Optional[str] = None,
+        model: Optional[Literal["standard", "advanced"]] = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {"content": content, "targets": targets}
+        if format is not None:
+            params["format"] = format
+        if source is not None:
+            params["source"] = source
+        if model is not None:
+            params["model"] = model
+        return translate(self, params)
+
+    def batch(
+        self,
+        *,
+        items: list[dict[str, Any]],
+        targets: list[str],
+        source: Optional[str] = None,
+        model: Optional[Literal["standard", "advanced"]] = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {"items": items, "targets": targets}
+        if source is not None:
+            params["source"] = source
+        if model is not None:
+            params["model"] = model
+        return batch(self, params)
+
+    def usage(self) -> dict[str, Any]:
+        return usage(self)

polylingo-0.1.0/polylingo/_errors.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+
+class PolyLingoError(Exception):
+    """Base error for PolyLingo API failures."""
+
+    def __init__(self, status: int, error: str, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.error = error
+
+
+class AuthError(PolyLingoError):
+    """Invalid or missing API key (HTTP 401)."""
+
+
+class RateLimitError(PolyLingoError):
+    """Rate limited (HTTP 429)."""
+
+    def __init__(
+        self,
+        status: int,
+        error: str,
+        message: str,
+        retry_after: int | None = None,
+    ) -> None:
+        super().__init__(status, error, message)
+        self.retry_after = retry_after
+
+
+class JobFailedError(PolyLingoError):
+    """Async job finished with status ``failed``."""
+
+    def __init__(self, job_id: str, status: int, error: str, message: str) -> None:
+        super().__init__(status, error, message)
+        self.job_id = job_id

polylingo-0.1.0/polylingo/_http_utils.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import httpx
+
+from ._errors import AuthError, PolyLingoError, RateLimitError
+
+
+def error_from_response(response: httpx.Response) -> PolyLingoError:
+    try:
+        data = response.json()
+    except Exception:
+        data = {}
+    if not isinstance(data, dict):
+        data = {}
+    code = str(data.get("error", "unknown_error"))
+    message = str(data.get("message", f"Request failed with status {response.status_code}"))
+    status = response.status_code
+
+    if status == 401:
+        return AuthError(status, code, message)
+    if status == 429:
+        retry_raw = data.get("retry_after")
+        retry_after: int | None
+        if isinstance(retry_raw, int):
+            retry_after = retry_raw
+        elif isinstance(retry_raw, str) and retry_raw.isdigit():
+            retry_after = int(retry_raw)
+        else:
+            retry_after = None
+        if retry_after is None:
+            h = response.headers.get("retry-after")
+            if h and h.isdigit():
+                retry_after = int(h)
+        return RateLimitError(status, code, message, retry_after=retry_after)
+    return PolyLingoError(status, code, message)

polylingo-0.1.0/polylingo/_types.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+ContentFormat = Literal["plain", "markdown", "json", "html"]
+ModelTier = Literal["standard", "advanced"]
+JobStatus = Literal["pending", "processing", "completed", "failed"]
+
+
+class TranslateUsage(TypedDict, total=False):
+    total_tokens: int
+    input_tokens: int
+    output_tokens: int
+    model: str
+    detected_format: str
+    detection_confidence: float
+
+
+class TranslateResult(TypedDict):
+    translations: dict[str, str]
+    usage: TranslateUsage
+
+
+class BatchItem(TypedDict, total=False):
+    id: str
+    content: str
+    format: ContentFormat
+    source: str
+
+
+class BatchItemResult(TypedDict):
+    id: str
+    translations: dict[str, str]
+
+
+class BatchUsage(TypedDict, total=False):
+    total_tokens: int
+    input_tokens: int
+    output_tokens: int
+    model: str
+
+
+class BatchResult(TypedDict):
+    results: list[BatchItemResult]
+    usage: BatchUsage
+
+
+class Job(TypedDict, total=False):
+    job_id: str
+    status: JobStatus
+    queue_position: int
+    translations: dict[str, str]
+    usage: TranslateUsage
+    error: str
+    message: str
+    created_at: str
+    updated_at: str
+    completed_at: str | None
+
+
+class HealthResponse(TypedDict):
+    status: str
+    timestamp: str
+
+
+class LanguageEntry(TypedDict):
+    code: str
+    name: str
+
+
+class LanguagesResponse(TypedDict):
+    languages: list[LanguageEntry]
+
+
+class UsagePayload(TypedDict, total=False):
+    period_start: str
+    period_end: str
+    translations_used: int
+    translations_limit: int | None
+    tokens_used: int
+    tokens_limit: int | None
+
+
+class UsageResponse(TypedDict):
+    usage: UsagePayload
+
+
+# --- Params (plain dicts are fine; these document expected keys) ---
+
+
+class TranslateParams(TypedDict, total=False):
+    content: str
+    targets: list[str]
+    format: ContentFormat
+    source: str
+    model: ModelTier
+
+
+class BatchParams(TypedDict, total=False):
+    items: list[BatchItem]
+    targets: list[str]
+    source: str
+    model: ModelTier
+
+
+class CreateJobParams(TypedDict, total=False):
+    content: str
+    targets: list[str]
+    format: ContentFormat
+    source: str
+    model: ModelTier
+
+
+class JobsTranslateParams(CreateJobParams, total=False):
+    poll_interval: float
+    timeout: float
+    on_progress: Any  # Callable[[int | None], None] — avoid circular import

polylingo-0.1.0/polylingo/resources/_async_batch.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Mapping
+
+if TYPE_CHECKING:
+    from polylingo._async_client import AsyncPolyLingo
+
+
+async def batch_async(client: AsyncPolyLingo, params: Mapping[str, Any]) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "items": params["items"],
+        "targets": params["targets"],
+    }
+    if params.get("source") is not None:
+        body["source"] = params["source"]
+    if params.get("model") is not None:
+        body["model"] = params["model"]
+    return await client._request_json("POST", "/translate/batch", json=body, expect_status=200)

polylingo-0.1.0/polylingo/resources/_async_health.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from polylingo._async_client import AsyncPolyLingo
+
+
+async def health_async(client: AsyncPolyLingo) -> dict[str, object]:
+    return await client._request_json("GET", "/health", expect_status=200)

polylingo-0.1.0/polylingo/resources/_async_jobs.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import TYPE_CHECKING, Any, Callable, Mapping, Optional
+
+from polylingo._errors import JobFailedError
+from polylingo.resources._jobs import DEFAULT_JOB_TIMEOUT_S, DEFAULT_POLL_S, _job_body, _merge_params
+
+if TYPE_CHECKING:
+    from polylingo._async_client import AsyncPolyLingo
+
+
+class AsyncJobsResource:
+    def __init__(self, client: AsyncPolyLingo) -> None:
+        self._client = client
+
+    async def create(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> dict[str, Any]:
+        p = _merge_params(params, kwargs)
+        body = _job_body(p)
+        return await self._client._request_json("POST", "/jobs", json=body, expect_status=202)
+
+    async def get(self, job_id: str) -> dict[str, Any]:
+        return await self._client._request_json("GET", f"/jobs/{job_id}", expect_status=200)
+
+    async def translate(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        poll_interval: float = DEFAULT_POLL_S,
+        timeout: float = DEFAULT_JOB_TIMEOUT_S,
+        on_progress: Optional[Callable[[Optional[int]], None]] = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        p = _merge_params(params, kwargs)
+        job = await self.create(p)
+        jid = str(job["job_id"])
+        deadline = time.monotonic() + timeout
+
+        while time.monotonic() < deadline:
+            status = await self.get(jid)
+            st = status.get("status")
+            if st in ("pending", "processing") and on_progress is not None:
+                on_progress(status.get("queue_position"))  # type: ignore[arg-type]
+            if st == "completed":
+                translations = status.get("translations")
+                usage = status.get("usage")
+                if not translations or not usage:
+                    raise JobFailedError(
+                        jid,
+                        500,
+                        "invalid_response",
+                        "Job completed but translations or usage was missing",
+                    )
+                return {"translations": translations, "usage": usage}
+            if st == "failed":
+                raise JobFailedError(
+                    jid,
+                    200,
+                    str(status.get("error") or "job_failed"),
+                    str(status.get("message") or status.get("error") or "Translation job failed"),
+                )
+            await asyncio.sleep(poll_interval)
+
+        raise JobFailedError(jid, 408, "timeout", "Job polling exceeded the configured timeout")

polylingo-0.1.0/polylingo/resources/_async_languages.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from polylingo._async_client import AsyncPolyLingo
+
+
+async def languages_async(client: AsyncPolyLingo) -> dict[str, object]:
+    return await client._request_json("GET", "/languages", expect_status=200)

polylingo-0.1.0/polylingo/resources/_async_translate.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Mapping
+
+if TYPE_CHECKING:
+    from polylingo._async_client import AsyncPolyLingo
+
+
+async def translate_async(client: AsyncPolyLingo, params: Mapping[str, Any]) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "content": params["content"],
+        "targets": params["targets"],
+    }
+    if params.get("format") is not None:
+        body["format"] = params["format"]
+    if params.get("source") is not None:
+        body["source"] = params["source"]
+    if params.get("model") is not None:
+        body["model"] = params["model"]
+    return await client._request_json("POST", "/translate", json=body, expect_status=200)

polylingo-0.1.0/polylingo/resources/_async_usage.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from polylingo._async_client import AsyncPolyLingo
+
+
+async def usage_async(client: AsyncPolyLingo) -> dict[str, object]:
+    return await client._request_json("GET", "/usage", expect_status=200)

polylingo-0.1.0/polylingo/resources/_batch.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Mapping
+
+if TYPE_CHECKING:
+    from polylingo._client import PolyLingo
+
+
+def batch(client: PolyLingo, params: Mapping[str, Any]) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "items": params["items"],
+        "targets": params["targets"],
+    }
+    if params.get("source") is not None:
+        body["source"] = params["source"]
+    if params.get("model") is not None:
+        body["model"] = params["model"]
+    return client._request_json("POST", "/translate/batch", json=body, expect_status=200)

polylingo-0.1.0/polylingo/resources/_health.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from polylingo._client import PolyLingo
+
+
+def health(client: PolyLingo) -> dict[str, object]:
+    return client._request_json("GET", "/health", expect_status=200)

polylingo-0.1.0/polylingo/resources/_jobs.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any, Callable, Mapping, Optional
+
+from polylingo._errors import JobFailedError
+
+if TYPE_CHECKING:
+    from polylingo._client import PolyLingo
+
+DEFAULT_POLL_S = 5.0
+DEFAULT_JOB_TIMEOUT_S = 1200.0  # 20 minutes (matches Node default)
+
+
+class JobsResource:
+    def __init__(self, client: PolyLingo) -> None:
+        self._client = client
+
+    def create(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> dict[str, Any]:
+        p = _merge_params(params, kwargs)
+        body = _job_body(p)
+        return self._client._request_json("POST", "/jobs", json=body, expect_status=202)
+
+    def get(self, job_id: str) -> dict[str, Any]:
+        return self._client._request_json("GET", f"/jobs/{job_id}", expect_status=200)
+
+    def translate(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        poll_interval: float = DEFAULT_POLL_S,
+        timeout: float = DEFAULT_JOB_TIMEOUT_S,
+        on_progress: Optional[Callable[[Optional[int]], None]] = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        p = _merge_params(params, kwargs)
+        job = self.create(p)
+        jid = str(job["job_id"])
+        deadline = time.monotonic() + timeout
+
+        while time.monotonic() < deadline:
+            status = self.get(jid)
+            st = status.get("status")
+            if st in ("pending", "processing") and on_progress is not None:
+                on_progress(status.get("queue_position"))  # type: ignore[arg-type]
+            if st == "completed":
+                translations = status.get("translations")
+                usage = status.get("usage")
+                if not translations or not usage:
+                    raise JobFailedError(
+                        jid,
+                        500,
+                        "invalid_response",
+                        "Job completed but translations or usage was missing",
+                    )
+                return {"translations": translations, "usage": usage}
+            if st == "failed":
+                raise JobFailedError(
+                    jid,
+                    200,
+                    str(status.get("error") or "job_failed"),
+                    str(status.get("message") or status.get("error") or "Translation job failed"),
+                )
+            time.sleep(poll_interval)
+
+        raise JobFailedError(jid, 408, "timeout", "Job polling exceeded the configured timeout")
+
+
+def _merge_params(
+    params: Optional[Mapping[str, Any]],
+    kwargs: dict[str, Any],
+) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    if params:
+        out.update(dict(params))
+    out.update(kwargs)
+    return out
+
+
+def _job_body(p: Mapping[str, Any]) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "content": p["content"],
+        "targets": p["targets"],
+    }
+    if p.get("format") is not None:
+        body["format"] = p["format"]
+    if p.get("source") is not None:
+        body["source"] = p["source"]
+    if p.get("model") is not None:
+        body["model"] = p["model"]
+    return body

polylingo-0.1.0/polylingo/resources/_languages.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from polylingo._client import PolyLingo
+
+
+def languages(client: PolyLingo) -> dict[str, object]:
+    return client._request_json("GET", "/languages", expect_status=200)

polylingo-0.1.0/polylingo/resources/_translate.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Mapping
+
+if TYPE_CHECKING:
+    from polylingo._client import PolyLingo
+
+
+def translate(client: PolyLingo, params: Mapping[str, Any]) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "content": params["content"],
+        "targets": params["targets"],
+    }
+    if params.get("format") is not None:
+        body["format"] = params["format"]
+    if params.get("source") is not None:
+        body["source"] = params["source"]
+    if params.get("model") is not None:
+        body["model"] = params["model"]
+    return client._request_json("POST", "/translate", json=body, expect_status=200)

polylingo-0.1.0/polylingo/resources/_usage.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from polylingo._client import PolyLingo
+
+
+def usage(client: PolyLingo) -> dict[str, object]:
+    return client._request_json("GET", "/usage", expect_status=200)

polylingo-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "polylingo"
+version = "0.1.0"
+description = "Official Python SDK for the PolyLingo translation API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "PolyLingo" }]
+keywords = ["translation", "i18n", "polylingo", "markdown", "api"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://usepolylingo.com"
+Documentation = "https://usepolylingo.com/en/docs/sdk/python"
+Repository = "https://github.com/UsePolyLingo/polylingo-python"
+Issues = "https://github.com/UsePolyLingo/polylingo-python/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.24",
+  "pytest-httpx>=0.30",
+  "httpx>=0.24",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["polylingo"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/polylingo", "/README.md", "/tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

polylingo-0.1.0/tests/test_errors.py

@@ -0,0 +1,42 @@
+import pytest
+
+from polylingo import AsyncPolyLingo, AuthError, PolyLingo, RateLimitError
+
+
+def test_auth_error_on_401(httpx_mock):
+    httpx_mock.add_response(
+        method="POST",
+        url="https://api.example.com/v1/translate",
+        status_code=401,
+        json={"error": "invalid_api_key", "message": "Bad"},
+    )
+    client = PolyLingo("k", base_url="https://api.example.com/v1")
+    with pytest.raises(AuthError):
+        client.translate(content="hi", targets=["es"])
+
+
+def test_rate_limit_retry_after_header(httpx_mock):
+    httpx_mock.add_response(
+        method="POST",
+        url="https://api.example.com/v1/translate",
+        status_code=429,
+        json={"error": "rate_limited", "message": "Slow"},
+        headers={"Retry-After": "60"},
+    )
+    client = PolyLingo("k", base_url="https://api.example.com/v1")
+    with pytest.raises(RateLimitError) as ei:
+        client.translate(content="hi", targets=["es"])
+    assert ei.value.retry_after == 60
+
+
+@pytest.mark.asyncio
+async def test_async_auth_error(httpx_mock):
+    httpx_mock.add_response(
+        method="POST",
+        url="https://api.example.com/v1/translate",
+        status_code=401,
+        json={"error": "invalid_api_key", "message": "Bad"},
+    )
+    async with AsyncPolyLingo("k", base_url="https://api.example.com/v1") as c:
+        with pytest.raises(AuthError):
+            await c.translate(content="hi", targets=["es"])

polylingo-0.1.0/tests/test_jobs.py

@@ -0,0 +1,45 @@
+import pytest
+
+from polylingo import JobFailedError, PolyLingo
+
+
+def test_jobs_translate_completed(httpx_mock):
+    httpx_mock.add_response(
+        method="POST",
+        url="https://api.example.com/v1/jobs",
+        status_code=202,
+        json={"job_id": "j1", "status": "pending"},
+    )
+    httpx_mock.add_response(
+        method="GET",
+        url="https://api.example.com/v1/jobs/j1",
+        status_code=200,
+        json={
+            "job_id": "j1",
+            "status": "completed",
+            "translations": {"fr": "Salut"},
+            "usage": {"total_tokens": 2, "input_tokens": 1, "output_tokens": 1},
+        },
+    )
+    client = PolyLingo("k", base_url="https://api.example.com/v1")
+    done = client.jobs.translate(content="Hi", targets=["fr"], poll_interval=0.01, timeout=5.0)
+    assert done["translations"]["fr"] == "Salut"
+
+
+def test_jobs_translate_failed(httpx_mock):
+    httpx_mock.add_response(
+        method="POST",
+        url="https://api.example.com/v1/jobs",
+        status_code=202,
+        json={"job_id": "j1", "status": "pending"},
+    )
+    httpx_mock.add_response(
+        method="GET",
+        url="https://api.example.com/v1/jobs/j1",
+        status_code=200,
+        json={"job_id": "j1", "status": "failed", "error": "boom"},
+    )
+    client = PolyLingo("k", base_url="https://api.example.com/v1")
+    with pytest.raises(JobFailedError) as ei:
+        client.jobs.translate(content="x", targets=["de"], poll_interval=0.01, timeout=5.0)
+    assert ei.value.job_id == "j1"

polylingo-0.1.0/tests/test_translate.py

@@ -0,0 +1,39 @@
+import pytest
+
+
+def test_translate_posts_json(httpx_mock):
+    httpx_mock.add_response(
+        method="POST",
+        url="https://api.example.com/v1/translate",
+        status_code=200,
+        json={
+            "translations": {"es": "Hola"},
+            "usage": {"total_tokens": 3, "input_tokens": 1, "output_tokens": 2},
+        },
+    )
+    from polylingo import PolyLingo
+
+    client = PolyLingo("secret", base_url="https://api.example.com/v1")
+    r = client.translate(content="Hi", targets=["es"], format="plain")
+    assert r["translations"]["es"] == "Hola"
+    req = httpx_mock.get_request()
+    assert req.headers["Authorization"] == "Bearer secret"
+    import json
+
+    body = json.loads(req.content.decode())
+    assert body == {"content": "Hi", "targets": ["es"], "format": "plain"}
+
+
+@pytest.mark.asyncio
+async def test_async_translate(httpx_mock):
+    httpx_mock.add_response(
+        method="POST",
+        url="https://api.example.com/v1/translate",
+        status_code=200,
+        json={"translations": {"de": "Ja"}, "usage": {"total_tokens": 1, "input_tokens": 0, "output_tokens": 1}},
+    )
+    from polylingo import AsyncPolyLingo
+
+    async with AsyncPolyLingo("x", base_url="https://api.example.com/v1") as c:
+        r = await c.translate(content="Yes", targets=["de"])
+    assert r["translations"]["de"] == "Ja"