createrington-skin-api 1.0.0__tar.gz

createrington_skin_api-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+.coverage
+htmlcov/

createrington_skin_api-1.0.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# createrington-skin-api (Python)
+
+This changelog tracks the Python SDK only. It is versioned and released
+independently of the rest of the repo, via `sdk-py-v<version>` git tags.
+
+## v1.0.0
+
+Initial release on PyPI.
+
+### Surface
+
+- `SkinApiClient` (sync) and `AsyncSkinApiClient` (async), both backed by
+  `httpx` and usable as context managers.
+- `render(pose, *, uuid | username | skin_url | skin_base64 | png, slim,
+  width, height)` returning PNG `bytes`. Exactly one skin source is required.
+- `api_key` falls back to the `SKIN_API_KEY` environment variable; `base_url`
+  defaults to `https://api.createrington.com`.
+- `KNOWN_POSES` tuple + `KnownPose` literal type generated from the server's
+  pose data; `render` still accepts any pose string.
+- Single `SkinApiError` carrying `code`, `status`, and `retry_after_ms`.
+  Server `UPPER_SNAKE` codes are normalized to the documented lowercase form.
+- Retries `429`/`502`/`503`/`504` and network errors with exponential
+  backoff, honouring `retryAfterMs` on `429`.
+- Ships `py.typed` for full mypy/pyright inference.

createrington_skin_api-1.0.0/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2026 Matej Hozlar. All Rights Reserved.
+
+This software and its accompanying source code, documentation, assets, and any
+related materials (the "Software") are the proprietary and confidential
+property of Matej Hozlar ("the Author") and are protected by copyright law and
+international treaties.
+
+NO LICENSE IS GRANTED.
+
+No part of the Software may be copied, reproduced, modified, merged,
+published, distributed, sublicensed, sold, leased, rented, publicly displayed,
+publicly performed, transmitted, reverse engineered, decompiled, disassembled,
+or otherwise exploited in any form or by any means, in whole or in part,
+without the prior express written permission of the Author.
+
+Access to the Software, including via source repositories, build artifacts, or
+deployed services, does not grant any license or right of use beyond what has
+been explicitly authorized in writing by the Author.
+
+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
+AUTHOR 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.
+
+All rights not expressly granted herein are reserved by the Author.

createrington_skin_api-1.0.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: createrington-skin-api
+Version: 1.0.0
+Summary: Official Python client for the Createrington Skin API.
+Project-URL: Homepage, https://api.createrington.com
+Project-URL: Repository, https://gitea.matejhoz.com/matejhozlar/skin-api
+Author: Matej Hozlar
+License: Copyright (c) 2026 Matej Hozlar. All Rights Reserved.
+        
+        This software and its accompanying source code, documentation, assets, and any
+        related materials (the "Software") are the proprietary and confidential
+        property of Matej Hozlar ("the Author") and are protected by copyright law and
+        international treaties.
+        
+        NO LICENSE IS GRANTED.
+        
+        No part of the Software may be copied, reproduced, modified, merged,
+        published, distributed, sublicensed, sold, leased, rented, publicly displayed,
+        publicly performed, transmitted, reverse engineered, decompiled, disassembled,
+        or otherwise exploited in any form or by any means, in whole or in part,
+        without the prior express written permission of the Author.
+        
+        Access to the Software, including via source repositories, build artifacts, or
+        deployed services, does not grant any license or right of use beyond what has
+        been explicitly authorized in writing by the Author.
+        
+        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
+        AUTHOR 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.
+        
+        All rights not expressly granted herein are reserved by the Author.
+License-File: LICENSE
+Keywords: api-client,createrington,minecraft,render,skin
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: Implementation :: CPython
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# createrington-skin-api
+
+Official Python client for the Createrington Skin API. Renders Minecraft
+player skins into named poses and returns PNG bytes. Sync and async clients,
+fully typed.
+
+```sh
+pip install createrington-skin-api
+```
+
+> Access is invite-only. Request an API key at https://api.createrington.com.
+
+## Quickstart
+
+```python
+from createrington_skin_api import SkinApiClient
+
+client = SkinApiClient(api_key="sk_...")  # or set SKIN_API_KEY
+
+# Render a known pose for a Minecraft account by UUID.
+png = client.render("wave", uuid="069a79f444e94726a5befca90e38aaf5")
+
+# `png` is `bytes` of a PNG image.
+with open("notch-waving.png", "wb") as f:
+    f.write(png)
+```
+
+### Async
+
+```python
+import asyncio
+from createrington_skin_api import AsyncSkinApiClient
+
+
+async def main() -> None:
+    async with AsyncSkinApiClient(api_key="sk_...") as client:
+        png = await client.render("wave", username="Notch", slim=True)
+        with open("notch-waving.png", "wb") as f:
+            f.write(png)
+
+
+asyncio.run(main())
+```
+
+## Client
+
+```python
+SkinApiClient(
+    api_key=None,          # required; falls back to the SKIN_API_KEY env var
+    base_url="https://api.createrington.com",
+    timeout=30.0,          # seconds
+    retries=2,             # retries 429/502/503/504 and network errors
+    user_agent="createrington-skin-api",
+)
+```
+
+`AsyncSkinApiClient` takes the same arguments. Both are usable as context
+managers (`with` / `async with`) and expose `close()` / `aclose()` for
+explicit cleanup of the underlying connection pool.
+
+## `render`
+
+```python
+client.render(
+    pose,                  # a KNOWN_POSES name (e.g. "wave"), or any pose string
+    *,
+    # exactly one skin source:
+    uuid=None,             # Mojang UUID, resolved server-side
+    username=None,         # Mojang username, resolved server-side
+    skin_url=None,         # public URL to a 64x64 PNG
+    skin_base64=None,      # base64-encoded 64x64 PNG (data URL prefix optional)
+    png=None,              # raw 64x64 PNG bytes, sent as multipart/form-data
+    # options:
+    slim=None,             # override slim/Alex arm geometry; default uses skin metadata
+    width=None,            # default 400 (64..2048)
+    height=None,           # default 600 (64..2048)
+) -> bytes
+```
+
+Exactly one skin source must be supplied; passing none or more than one
+raises `ValueError`.
+
+`pose` accepts any string, so server-side poses added after this release work
+without an SDK upgrade. The bundled `KNOWN_POSES` tuple and `KnownPose` type
+cover the poses known at publish time; fetch `GET /v1/poses` directly if you
+need the live catalogue with descriptions.
+
+```python
+from createrington_skin_api import KNOWN_POSES, KnownPose
+```
+
+## Errors
+
+Every non-2xx response (and network/timeout failures) raises `SkinApiError`:
+
+```python
+from createrington_skin_api import SkinApiError
+
+try:
+    client.render("wave", uuid="bad-uuid")
+except SkinApiError as err:
+    print(err.code, err.status, err)
+    if err.code == "rate_limited" and err.retry_after_ms:
+        ...  # back off and retry
+```
+
+`err.code` is one of `"bad_request"`, `"unauthorized"`, `"forbidden"`,
+`"not_found"`, `"conflict"`, `"unsupported_media_type"`, `"rate_limited"`,
+`"internal"`, `"render_failed"`, `"upstream_unavailable"`, `"timeout"`,
+`"aborted"`, `"network_error"`, `"unknown"`. `err.status` is the HTTP status
+(or `0` for network/timeout failures). `err.retry_after_ms` is populated on
+`429` responses when the server reports it.
+
+The client retries `429`, `502`, `503`, `504`, and network errors up to
+`retries` times with exponential backoff; `429` responses honour the server's
+`retryAfterMs` when present.
+
+## License
+
+UNLICENSED. See repository for terms.

createrington_skin_api-1.0.0/README.md

@@ -0,0 +1,120 @@
+# createrington-skin-api
+
+Official Python client for the Createrington Skin API. Renders Minecraft
+player skins into named poses and returns PNG bytes. Sync and async clients,
+fully typed.
+
+```sh
+pip install createrington-skin-api
+```
+
+> Access is invite-only. Request an API key at https://api.createrington.com.
+
+## Quickstart
+
+```python
+from createrington_skin_api import SkinApiClient
+
+client = SkinApiClient(api_key="sk_...")  # or set SKIN_API_KEY
+
+# Render a known pose for a Minecraft account by UUID.
+png = client.render("wave", uuid="069a79f444e94726a5befca90e38aaf5")
+
+# `png` is `bytes` of a PNG image.
+with open("notch-waving.png", "wb") as f:
+    f.write(png)
+```
+
+### Async
+
+```python
+import asyncio
+from createrington_skin_api import AsyncSkinApiClient
+
+
+async def main() -> None:
+    async with AsyncSkinApiClient(api_key="sk_...") as client:
+        png = await client.render("wave", username="Notch", slim=True)
+        with open("notch-waving.png", "wb") as f:
+            f.write(png)
+
+
+asyncio.run(main())
+```
+
+## Client
+
+```python
+SkinApiClient(
+    api_key=None,          # required; falls back to the SKIN_API_KEY env var
+    base_url="https://api.createrington.com",
+    timeout=30.0,          # seconds
+    retries=2,             # retries 429/502/503/504 and network errors
+    user_agent="createrington-skin-api",
+)
+```
+
+`AsyncSkinApiClient` takes the same arguments. Both are usable as context
+managers (`with` / `async with`) and expose `close()` / `aclose()` for
+explicit cleanup of the underlying connection pool.
+
+## `render`
+
+```python
+client.render(
+    pose,                  # a KNOWN_POSES name (e.g. "wave"), or any pose string
+    *,
+    # exactly one skin source:
+    uuid=None,             # Mojang UUID, resolved server-side
+    username=None,         # Mojang username, resolved server-side
+    skin_url=None,         # public URL to a 64x64 PNG
+    skin_base64=None,      # base64-encoded 64x64 PNG (data URL prefix optional)
+    png=None,              # raw 64x64 PNG bytes, sent as multipart/form-data
+    # options:
+    slim=None,             # override slim/Alex arm geometry; default uses skin metadata
+    width=None,            # default 400 (64..2048)
+    height=None,           # default 600 (64..2048)
+) -> bytes
+```
+
+Exactly one skin source must be supplied; passing none or more than one
+raises `ValueError`.
+
+`pose` accepts any string, so server-side poses added after this release work
+without an SDK upgrade. The bundled `KNOWN_POSES` tuple and `KnownPose` type
+cover the poses known at publish time; fetch `GET /v1/poses` directly if you
+need the live catalogue with descriptions.
+
+```python
+from createrington_skin_api import KNOWN_POSES, KnownPose
+```
+
+## Errors
+
+Every non-2xx response (and network/timeout failures) raises `SkinApiError`:
+
+```python
+from createrington_skin_api import SkinApiError
+
+try:
+    client.render("wave", uuid="bad-uuid")
+except SkinApiError as err:
+    print(err.code, err.status, err)
+    if err.code == "rate_limited" and err.retry_after_ms:
+        ...  # back off and retry
+```
+
+`err.code` is one of `"bad_request"`, `"unauthorized"`, `"forbidden"`,
+`"not_found"`, `"conflict"`, `"unsupported_media_type"`, `"rate_limited"`,
+`"internal"`, `"render_failed"`, `"upstream_unavailable"`, `"timeout"`,
+`"aborted"`, `"network_error"`, `"unknown"`. `err.status` is the HTTP status
+(or `0` for network/timeout failures). `err.retry_after_ms` is populated on
+`429` responses when the server reports it.
+
+The client retries `429`, `502`, `503`, `504`, and network errors up to
+`retries` times with exponential backoff; `429` responses honour the server's
+`retryAfterMs` when present.
+
+## License
+
+UNLICENSED. See repository for terms.

createrington_skin_api-1.0.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "createrington-skin-api"
+dynamic = ["version"]
+description = "Official Python client for the Createrington Skin API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Matej Hozlar" }]
+keywords = ["minecraft", "skin", "render", "createrington", "api-client"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://api.createrington.com"
+Repository = "https://gitea.matejhoz.com/matejhozlar/skin-api"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "mypy>=1.8",
+]
+
+[tool.hatch.version]
+path = "src/createrington_skin_api/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/createrington_skin_api"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "scripts", "tests", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src", "scripts"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

createrington_skin_api-1.0.0/scripts/generate_poses.py

@@ -0,0 +1,50 @@
+"""Regenerate src/createrington_skin_api/_poses.py from the renderer pose data.
+
+The pose JSON files in packages/renderer/data/poses/ are the source of truth.
+Run this after that data changes:
+
+    python scripts/generate_poses.py
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+SDK_ROOT = SCRIPT_DIR.parent
+REPO_ROOT = SDK_ROOT.parent.parent
+POSES_DIR = REPO_ROOT / "packages" / "renderer" / "data" / "poses"
+OUT_FILE = SDK_ROOT / "src" / "createrington_skin_api" / "_poses.py"
+
+
+def _entries(names: list[str]) -> str:
+    return "\n".join(f'    "{name}",' for name in names)
+
+
+def main() -> int:
+    if not POSES_DIR.is_dir():
+        sys.stderr.write(f"pose data directory not found: {POSES_DIR}\n")
+        return 1
+
+    names = sorted(p.stem for p in POSES_DIR.glob("*.json"))
+    if not names:
+        sys.stderr.write(f"no pose JSON files found in {POSES_DIR}\n")
+        return 1
+
+    body = (
+        "# AUTO-GENERATED by scripts/generate_poses.py\n"
+        "# Do not edit by hand. Regenerated from packages/renderer/data/poses/.\n"
+        "from __future__ import annotations\n\n"
+        "from typing import Literal, Tuple\n\n"
+        f"KNOWN_POSES: Tuple[str, ...] = (\n{_entries(names)}\n)\n\n"
+        f"KnownPose = Literal[\n{_entries(names)}\n]\n"
+    )
+
+    OUT_FILE.write_text(body, encoding="utf-8")
+    sys.stdout.write(f"generated {OUT_FILE} ({len(names)} poses)\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

createrington_skin_api-1.0.0/src/createrington_skin_api/__init__.py

@@ -0,0 +1,22 @@
+"""Official Python client for the Createrington Skin API."""
+
+from __future__ import annotations
+
+from ._core import DEFAULT_BASE_URL
+from ._poses import KNOWN_POSES, KnownPose
+from .async_client import AsyncSkinApiClient
+from .client import SkinApiClient
+from .errors import SkinApiError, SkinApiErrorCode
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AsyncSkinApiClient",
+    "SkinApiClient",
+    "SkinApiError",
+    "SkinApiErrorCode",
+    "KNOWN_POSES",
+    "KnownPose",
+    "DEFAULT_BASE_URL",
+    "__version__",
+]

createrington_skin_api-1.0.0/src/createrington_skin_api/_core.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+from typing import Tuple
+
+DEFAULT_BASE_URL = "https://api.createrington.com"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_RETRIES = 2
+DEFAULT_USER_AGENT = "createrington-skin-api"
+API_KEY_ENV = "SKIN_API_KEY"
+
+_BACKOFF_BASE_MS = 200
+_BACKOFF_MAX_MS = 5_000
+_RETRYABLE_STATUSES = frozenset({429, 502, 503, 504})
+
+# render() keyword name -> JSON body field name. png is multipart, not JSON.
+_JSON_SOURCE_FIELDS: dict[str, str] = {
+    "uuid": "uuid",
+    "username": "username",
+    "skin_url": "skinUrl",
+    "skin_base64": "skinBase64",
+}
+
+
+@dataclass(frozen=True)
+class PreparedRender:
+    url: str
+    params: dict[str, str]
+    json: dict[str, str] | None = None
+    files: dict[str, Tuple[str, bytes, str]] | None = None
+
+
+def _select_source(
+    *,
+    uuid: str | None,
+    username: str | None,
+    skin_url: str | None,
+    skin_base64: str | None,
+    png: bytes | bytearray | memoryview | None,
+) -> str:
+    given = [
+        name
+        for name, value in (
+            ("uuid", uuid),
+            ("username", username),
+            ("skin_url", skin_url),
+            ("skin_base64", skin_base64),
+            ("png", png),
+        )
+        if value is not None
+    ]
+
+    if not given:
+        raise ValueError(
+            "render() requires exactly one skin source: pass one of "
+            "uuid, username, skin_url, skin_base64, or png"
+        )
+    if len(given) > 1:
+        raise ValueError(
+            "render() accepts exactly one skin source, but several were given: "
+            + ", ".join(given)
+        )
+    return given[0]
+
+
+def prepare_render(
+    base_url: str,
+    pose: str,
+    *,
+    uuid: str | None,
+    username: str | None,
+    skin_url: str | None,
+    skin_base64: str | None,
+    png: bytes | bytearray | memoryview | None,
+    slim: bool | None,
+    width: int | None,
+    height: int | None,
+) -> PreparedRender:
+    name = _select_source(
+        uuid=uuid,
+        username=username,
+        skin_url=skin_url,
+        skin_base64=skin_base64,
+        png=png,
+    )
+
+    params: dict[str, str] = {"pose": pose}
+    if slim is not None:
+        params["slim"] = "1" if slim else "0"
+    if width is not None:
+        params["width"] = str(width)
+    if height is not None:
+        params["height"] = str(height)
+
+    url = f"{base_url}/v1/render"
+
+    if name == "png":
+        assert png is not None
+        return PreparedRender(
+            url=url,
+            params=params,
+            files={"skin": ("skin.png", bytes(png), "image/png")},
+        )
+
+    value = {
+        "uuid": uuid,
+        "username": username,
+        "skin_url": skin_url,
+        "skin_base64": skin_base64,
+    }[name]
+    assert value is not None
+    return PreparedRender(
+        url=url,
+        params=params,
+        json={_JSON_SOURCE_FIELDS[name]: value},
+    )
+
+
+def is_retryable_status(status: int) -> bool:
+    return status in _RETRYABLE_STATUSES
+
+
+def _backoff_seconds(attempt: int) -> float:
+    capped = min(_BACKOFF_BASE_MS * (1 << attempt), _BACKOFF_MAX_MS)
+    jitter = capped * 0.25 * random.random()
+    return (capped + jitter) / 1000.0
+
+
+def retry_delay_seconds(status: int, body: object, attempt: int) -> float:
+    if status == 429 and isinstance(body, dict):
+        info = body.get("error")
+        if isinstance(info, dict):
+            retry_after = info.get("retryAfterMs")
+            if isinstance(retry_after, (int, float)) and not isinstance(
+                retry_after, bool
+            ):
+                return float(retry_after) / 1000.0
+    return _backoff_seconds(attempt)

createrington_skin_api-1.0.0/src/createrington_skin_api/_http.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import httpx
+
+
+def safe_json(response: httpx.Response) -> object:
+    """Parse a response body as JSON, returning None when it is not JSON."""
+    try:
+        return response.json()
+    except ValueError:
+        return None
+
+
+def default_headers(api_key: str, user_agent: str) -> dict[str, str]:
+    return {
+        "authorization": f"Bearer {api_key}",
+        "user-agent": user_agent,
+    }
+
+
+def resolve_api_key(api_key: str | None, env_value: str | None) -> str:
+    key = api_key if api_key is not None else env_value
+    if not key:
+        raise ValueError(
+            "api_key is required: pass api_key=... or set the "
+            "SKIN_API_KEY environment variable"
+        )
+    return key