medalbot-render 0.1.1__py3-none-any.whl

medalbot_render/__init__.py

@@ -0,0 +1,23 @@
+from .client import RenderClient
+from .models import (
+    CompletedRender,
+    FailedRender,
+    Format,
+    Images,
+    PendingRender,
+    Render,
+    RenderError,
+    View,
+)
+
+__all__ = [
+    "CompletedRender",
+    "FailedRender",
+    "Format",
+    "Images",
+    "PendingRender",
+    "Render",
+    "RenderError",
+    "RenderClient",
+    "View",
+]

medalbot_render/client.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+import asyncio
+import math
+import random
+import re
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from types import TracebackType
+from typing import Self, TypeVar
+from uuid import uuid4
+
+import httpx
+from pydantic import ValidationError
+
+from .models import (
+    CompletedRender,
+    FailedRender,
+    Format,
+    Images,
+    Render,
+    RenderError,
+    RenderResponse,
+    View,
+)
+
+T = TypeVar("T")
+_VIEWS: tuple[View, ...] = ("preview", "front", "back")
+_RENDER_ID = re.compile(r"rnd_(?:[0-7][0-9A-HJKMNP-TV-Z]{25}|[a-f0-9]{32})\Z")
+
+
+@dataclass
+class _Context:
+    render_id: str | None = None
+    idempotency_key: str | None = None
+    request_id: str | None = None
+
+
+def _validate_id(render_id: str) -> None:
+    if not _RENDER_ID.fullmatch(render_id):
+        raise ValueError("render_id must be a prefixed ULID or an existing render ID")
+
+
+def _views(views: Sequence[View] | None) -> tuple[View, ...]:
+    result = tuple(views) if views is not None else _VIEWS
+    if not result or any(view not in _VIEWS for view in result):
+        raise ValueError("views must contain preview, front, or back")
+    if len(set(result)) != len(result):
+        raise ValueError("views must be unique")
+    return result
+
+
+def _submission(
+    inspect_url: str,
+    views: Sequence[View] | None,
+    format: Format,
+    idempotency_key: str | None,
+) -> tuple[dict[str, object], _Context, tuple[View, ...]]:
+    if not isinstance(inspect_url, str) or not 1 <= len(inspect_url) <= 32768:
+        raise ValueError("inspect_url must contain 1 to 32768 characters")
+    requested = _views(views)
+    if format not in ("webp", "png"):
+        raise ValueError("format must be webp or png")
+    key = str(uuid4()) if idempotency_key is None else idempotency_key
+    if not re.fullmatch(r"[\x21-\x7e]{1,128}", key):
+        raise ValueError(
+            "idempotency_key must contain 1 to 128 visible ASCII characters"
+        )
+    return (
+        {"inspectUrl": inspect_url, "views": list(requested), "format": format},
+        _Context(idempotency_key=key),
+        requested,
+    )
+
+
+def _retry_delay(response: httpx.Response | None, attempt: int) -> float:
+    retry_after = 0.0
+    if response is not None:
+        value = response.headers.get("Retry-After", "")
+        try:
+            retry_after = float(value)
+        except ValueError:
+            try:
+                date = parsedate_to_datetime(value)
+                if date.tzinfo is None:
+                    date = date.replace(tzinfo=UTC)
+                retry_after = (date - datetime.now(UTC)).total_seconds()
+            except (ValueError, TypeError, OverflowError):
+                pass
+    if not math.isfinite(retry_after):
+        retry_after = 0.0
+    return min(10.0, max(0.2 * math.pow(2, attempt), retry_after)) + random.uniform(
+        0, 0.1
+    )
+
+
+def _text(value: object) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+class RenderClient:
+    """Async render client. Owns its HTTP connection pool; close after use."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = "https://render.medalbot.cc",
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not api_key.strip():
+            raise ValueError("api_key must not be empty")
+        self._http = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Accept": "application/json",
+            },
+            transport=transport,
+            timeout=httpx.Timeout(30, connect=10),
+            follow_redirects=False,
+        )
+        self.renders = Renders(self)
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _bounded(
+        self,
+        operation: Callable[[], Awaitable[T]],
+        timeout: float,
+        context: _Context,
+    ) -> T:
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("timeout must be a positive, finite number of seconds")
+        deadline = asyncio.timeout(timeout)
+        try:
+            async with deadline:
+                return await operation()
+        except TimeoutError:
+            if not deadline.expired():
+                raise
+            raise RenderError(
+                "wait_timeout",
+                "Render continues; resume with renders.wait(render_id)"
+                if context.render_id
+                else "Submission timed out; retry with the same idempotency key",
+                render_id=context.render_id,
+                request_id=context.request_id,
+                idempotency_key=context.idempotency_key,
+            ) from None
+        except RenderError as error:
+            error.render_id = error.render_id or context.render_id
+            error.idempotency_key = error.idempotency_key or context.idempotency_key
+            error.request_id = error.request_id or context.request_id
+            raise
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        context: _Context,
+        *,
+        body: dict[str, object] | None = None,
+        wait: bool = False,
+    ) -> Render:
+        headers = {}
+        if context.idempotency_key and method == "POST":
+            headers["Idempotency-Key"] = context.idempotency_key
+        if wait:
+            headers["Prefer"] = "wait=10"
+        for attempt in range(4):
+            try:
+                response = await self._http.request(
+                    method, path, json=body, headers=headers
+                )
+            except httpx.TransportError:
+                if attempt == 3:
+                    raise RenderError(
+                        "transport_error", "API connection failed after four attempts"
+                    ) from None
+                await asyncio.sleep(_retry_delay(None, attempt))
+                continue
+            context.request_id = (
+                response.headers.get("x-request-id") or context.request_id
+            )
+            if response.status_code in (429, 502, 503, 504) and attempt < 3:
+                await asyncio.sleep(_retry_delay(response, attempt))
+                continue
+            try:
+                value = response.json()
+            except ValueError:
+                value = None
+            data = value if isinstance(value, dict) else {}
+            meta = data.get("meta")
+            if isinstance(meta, dict):
+                context.request_id = _text(meta.get("requestId")) or context.request_id
+            if not response.is_success:
+                nested = data.get("error")
+                error = nested if isinstance(nested, dict) else {}
+                raise RenderError(
+                    _text(error.get("code")) or f"http_{response.status_code}",
+                    _text(error.get("detail"))
+                    or _text(error.get("message"))
+                    or f"API returned HTTP {response.status_code}",
+                    request_id=context.request_id,
+                    status_code=response.status_code,
+                )
+            try:
+                envelope = RenderResponse.model_validate(value)
+                context.request_id = envelope.meta.request_id
+                result = envelope.data
+                if context.render_id and result.id != context.render_id:
+                    raise ValueError("Response render ID changed")
+            except (ValidationError, ValueError):
+                raise RenderError(
+                    "invalid_response", "API returned an invalid render response"
+                ) from None
+            context.render_id = result.id
+            return result
+        raise AssertionError("Unreachable retry state")
+
+    async def _poll(
+        self,
+        context: _Context,
+        expected: tuple[View, ...] | None,
+        initial: Render | None = None,
+    ) -> Images:
+        assert context.render_id is not None
+        result = initial or await self._request(
+            "GET", f"/v1/renders/{context.render_id}", context
+        )
+        interval = 0.5
+        while True:
+            if isinstance(result, FailedRender):
+                raise RenderError(result.error.code, result.error.detail)
+            if isinstance(result, CompletedRender):
+                for view in expected or ():
+                    if view not in result.images:
+                        raise RenderError(
+                            "invalid_response", f"Completed render is missing {view}"
+                        )
+                return result.images
+            await asyncio.sleep(interval)
+            result = await self._request(
+                "GET", f"/v1/renders/{context.render_id}", context
+            )
+            interval = min(2.0, interval * 1.5)
+
+    async def render(
+        self,
+        *,
+        inspect_url: str,
+        views: Sequence[View] | None = None,
+        format: Format = "webp",
+        timeout: float = 120,
+        idempotency_key: str | None = None,
+    ) -> Images:
+        """Return finished images, including cached results, within one total deadline."""
+        body, context, requested = _submission(
+            inspect_url, views, format, idempotency_key
+        )
+
+        async def run() -> Images:
+            result = await self._request(
+                "POST", "/v1/renders", context, body=body, wait=True
+            )
+            return await self._poll(context, requested, result)
+
+        return await self._bounded(run, timeout, context)
+
+
+class Renders:
+    """Lower-level admission, status, and resume operations."""
+
+    def __init__(self, client: RenderClient) -> None:
+        self._client = client
+
+    async def create(
+        self,
+        *,
+        inspect_url: str,
+        views: Sequence[View] | None = None,
+        format: Format = "webp",
+        timeout: float = 120,
+        idempotency_key: str | None = None,
+    ) -> Render:
+        body, context, _ = _submission(inspect_url, views, format, idempotency_key)
+        return await self._client._bounded(
+            lambda: self._client._request("POST", "/v1/renders", context, body=body),
+            timeout,
+            context,
+        )
+
+    async def get(self, render_id: str, *, timeout: float = 120) -> Render:
+        _validate_id(render_id)
+        context = _Context(render_id=render_id)
+        return await self._client._bounded(
+            lambda: self._client._request("GET", f"/v1/renders/{render_id}", context),
+            timeout,
+            context,
+        )
+
+    async def wait(
+        self,
+        render_id: str,
+        *,
+        timeout: float = 120,
+        views: Sequence[View] | None = None,
+    ) -> Images:
+        _validate_id(render_id)
+        context = _Context(render_id=render_id)
+        expected = _views(views) if views is not None else None
+        return await self._client._bounded(
+            lambda: self._client._poll(context, expected), timeout, context
+        )

medalbot_render/models.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import (
+    AfterValidator,
+    BaseModel,
+    ConfigDict,
+    Field,
+    HttpUrl,
+    StringConstraints,
+    TypeAdapter,
+)
+
+View = Literal["preview", "front", "back"]
+Format = Literal["png", "webp"]
+RenderId = Annotated[str, StringConstraints(pattern=r"^rnd_(?:[0-7][0-9A-HJKMNP-TV-Z]{25}|[a-f0-9]{32})$")]
+Images = dict[View, str]
+_url = TypeAdapter(HttpUrl)
+
+
+def _validate_url(value: str) -> str:
+    _url.validate_python(value)
+    return value
+
+
+ImageUrl = Annotated[str, AfterValidator(_validate_url)]
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(strict=True, frozen=True, extra="forbid")
+
+
+class Failure(_Model):
+    code: str
+    detail: str
+
+
+class CompletedRender(_Model):
+    id: RenderId
+    images: dict[View, ImageUrl] = Field(min_length=1, max_length=3)
+
+
+class PendingRender(_Model):
+    id: RenderId
+    status: Literal["queued", "rendering", "processing"]
+
+
+class FailedRender(_Model):
+    id: RenderId
+    status: Literal["failed"]
+    error: Failure
+
+
+Render = CompletedRender | PendingRender | FailedRender
+
+
+class _Meta(_Model):
+    request_id: str = Field(alias="requestId", min_length=1)
+
+
+class RenderResponse(_Model):
+    meta: _Meta
+    data: Render
+
+
+class RenderError(Exception):
+    """API, rendering, or local deadline error with resume information."""
+
+    def __init__(
+        self,
+        code: str,
+        detail: str,
+        *,
+        render_id: str | None = None,
+        request_id: str | None = None,
+        idempotency_key: str | None = None,
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(detail)
+        self.code = code
+        self.detail = detail
+        self.render_id = render_id
+        self.request_id = request_id
+        self.idempotency_key = idempotency_key
+        self.status_code = status_code

medalbot_render-0.1.1.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: medalbot-render
+Version: 0.1.1
+Summary: Async Python client for the Medalbot Render API
+Project-URL: Homepage, https://github.com/Flo4604/render-sdks
+Project-URL: Repository, https://github.com/Flo4604/render-sdks
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.10
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.15; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=0.25; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.11; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Python client
+
+Await `client.render()` to get finished image URLs. The SDK handles cached results, retries, and polling.
+
+Install the public wheel:
+
+```bash
+python -m pip install https://github.com/Flo4604/render-sdks/releases/download/v0.1.1/medalbot_render-0.1.1-py3-none-any.whl
+export RENDER_API_KEY="your-api-key"
+```
+
+```python
+import asyncio
+import os
+from medalbot_render import RenderClient
+
+
+async def main():
+    async with RenderClient(api_key=os.environ["RENDER_API_KEY"]) as client:
+        images = await client.render(inspect_url="steam://...")
+        print(images["preview"])
+        print(images["front"])
+        print(images["back"])
+
+
+asyncio.run(main())
+```
+
+Python 3.11 or newer is required. The default API URL is `https://render.medalbot.cc`. Set `base_url` to use another server. The client owns an HTTP connection pool. Use its async context manager or call `await client.aclose()`.
+
+## Request options
+
+```python
+images = await client.render(
+    inspect_url=inspect_url,
+    views=["front"],
+    format="webp",
+    timeout=120,
+    idempotency_key="listing-123-front-v1",
+)
+print(images["front"])
+```
+
+All three views are requested by default. WebP is lossless; PNG is also available. The result is a dictionary of URL strings, such as `{"front": "https://img.medalbot.cc/..."}`. Only requested views are present. Cache hits and fresh renders return the same shape.
+
+The initial request sends `Prefer: wait=10`. If the render is still pending, the SDK polls at intervals from 500 milliseconds to two seconds. The default 120-second deadline covers submission, retry delays, and polling together. Transport failures and HTTP 429, 502, 503, and 504 receive at most four attempts. Retries keep the same idempotency key. Retry delays honor `Retry-After` up to ten seconds.
+
+## Cancellation and resume
+
+Cancel the asyncio task to stop a local wait. Cancellation raises `asyncio.CancelledError`; shared GPU work continues. A local deadline raises `RenderError` with code `wait_timeout`. Other errors include `code`, `detail`, `render_id`, `request_id`, `idempotency_key`, and `status_code` where available.
+
+```python
+from medalbot_render import RenderError
+
+try:
+    images = await client.render(inspect_url=inspect_url, timeout=30)
+except RenderError as error:
+    if error.code != "wait_timeout":
+        raise
+    if error.render_id:
+        images = await client.renders.wait(error.render_id)
+    else:
+        images = await client.render(
+            inspect_url=inspect_url, idempotency_key=error.idempotency_key
+        )
+```
+
+`client.renders.create()` returns the admitted render without waiting for completion. `client.renders.get(id)` returns its current state. Those methods return `CompletedRender`, `PendingRender`, or `FailedRender` models. Completed renders contain `id` and the URL dictionary `images`. Pending renders contain `id` and `status`. Failed renders contain `id`, `status`, and `error`.
+
+`client.renders.wait(id)` resumes a wait and returns the URL dictionary. Each method accepts a total `timeout` in seconds. Pass `views` to `wait` when you also want to check the original requested views. The SDK unwraps the HTTP response envelope `meta` and `data` for callers. Error request IDs come from `meta.requestId`.
+
+## Development
+
+Run these commands from the repository root:
+
+```bash
+uv run --project packages/sdk-python --extra dev pytest packages/sdk-python/tests
+uv run --project packages/sdk-python --extra dev mypy --strict packages/sdk-python/src
+uv build --project packages/sdk-python
+```

medalbot_render-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+medalbot_render/__init__.py,sha256=-vr8e-eqNnOKZROIlPjIB07b1YBoqCCzko3nPAEmC4s,350
+medalbot_render/client.py,sha256=RID_8WHww5VoThL8ZTaLXOPLLG1sGZh9u0m9a2XVmQk,11383
+medalbot_render/models.py,sha256=TlFZ_rhtEn1QuJtX_pLAOgJRuxnme3EiS52KqnOepZ4,1893
+medalbot_render/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+medalbot_render-0.1.1.dist-info/METADATA,sha256=ho6yV6dgL3SFLZlfcH3eUgzY6lrv7fzzmSjv2_g_ahY,4176
+medalbot_render-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+medalbot_render-0.1.1.dist-info/licenses/LICENSE,sha256=YK3WELFQ2yA0AgKS-kX3XdPGPJkcbCl8axQNu1uHeQo,1070
+medalbot_render-0.1.1.dist-info/RECORD,,

medalbot_render-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

medalbot_render-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Eikel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.