webpninja 1.0.0__tar.gz

webpninja-1.0.0/.gitignore

@@ -0,0 +1,39 @@
+# build output
+dist/
+
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# Not committed: this project bundles native-binary optional deps
+# (lightningcss, sharp, esbuild) whose platform-specific packages have a
+# known npm bug where a lockfile generated on one OS causes `npm install`
+# to skip the correct binary on another OS/Docker build. Letting each
+# environment resolve its own lockfile avoids that class of failure.
+package-lock.json
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# environment variables
+.env
+.env.production
+api/.env
+
+# macOS-specific files
+.DS_Store
+
+# jetbrains setting folder
+.idea/
+
+# Python SDK build/test artifacts
+__pycache__/
+*.egg-info/
+.pytest_cache/
+sdks/python/dist/
+sdks/python/build/

webpninja-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WebP Ninja
+
+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.

webpninja-1.0.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: webpninja
+Version: 1.0.0
+Summary: Official Python client for the WebP Ninja image compression API
+Project-URL: Homepage, https://webpninja.com
+Project-URL: Documentation, https://webpninja.com/docs
+Project-URL: Repository, https://github.com/yantrixlab/WebPNinja
+Author: WebP Ninja
+License-Expression: MIT
+License-File: LICENSE
+Keywords: avif,image-compression,jpeg,png,webp
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.25
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Requires-Dist: responses>=0.23; extra == 'test'
+Description-Content-Type: text/markdown
+
+# webpninja
+
+Official Python client for the [WebP Ninja](https://webpninja.com) Developer API — server-side
+image compression for WebP, JPEG, PNG, and AVIF.
+
+## Install
+
+```bash
+pip install webpninja
+```
+
+Requires Python 3.8 or later.
+
+## Usage
+
+```python
+from webpninja import WebPNinja
+
+client = WebPNinja("webpninja_live_your_key")
+# or: client = WebPNinja()  # reads WEBPNINJA_API_KEY from the environment
+
+client.compress_to_file("photo.png", "photo.webp", format="webp", quality=75)
+```
+
+Or get the compressed bytes directly:
+
+```python
+data = client.compress("photo.png", format="webp", quality=75)
+```
+
+`input` can be a file path or raw bytes.
+
+## Error handling
+
+```python
+from webpninja import WebPNinja, RateLimitError, AuthenticationError
+
+try:
+    client.compress("photo.png", format="webp")
+except RateLimitError as err:
+    print(f"Quota: {err.used}/{err.quota}")
+except AuthenticationError:
+    print("Check your API key.")
+```
+
+All errors extend `WebPNinjaError` and carry `.status` (the HTTP status code) and `.message`.
+See [webpninja.com/docs](https://webpninja.com/docs) for the full error reference.
+
+## License
+
+MIT

webpninja-1.0.0/README.md

@@ -0,0 +1,51 @@
+# webpninja
+
+Official Python client for the [WebP Ninja](https://webpninja.com) Developer API — server-side
+image compression for WebP, JPEG, PNG, and AVIF.
+
+## Install
+
+```bash
+pip install webpninja
+```
+
+Requires Python 3.8 or later.
+
+## Usage
+
+```python
+from webpninja import WebPNinja
+
+client = WebPNinja("webpninja_live_your_key")
+# or: client = WebPNinja()  # reads WEBPNINJA_API_KEY from the environment
+
+client.compress_to_file("photo.png", "photo.webp", format="webp", quality=75)
+```
+
+Or get the compressed bytes directly:
+
+```python
+data = client.compress("photo.png", format="webp", quality=75)
+```
+
+`input` can be a file path or raw bytes.
+
+## Error handling
+
+```python
+from webpninja import WebPNinja, RateLimitError, AuthenticationError
+
+try:
+    client.compress("photo.png", format="webp")
+except RateLimitError as err:
+    print(f"Quota: {err.used}/{err.quota}")
+except AuthenticationError:
+    print("Check your API key.")
+```
+
+All errors extend `WebPNinjaError` and carry `.status` (the HTTP status code) and `.message`.
+See [webpninja.com/docs](https://webpninja.com/docs) for the full error reference.
+
+## License
+
+MIT

webpninja-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "webpninja"
+version = "1.0.0"
+description = "Official Python client for the WebP Ninja image compression API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+dependencies = ["requests>=2.25"]
+authors = [{ name = "WebP Ninja" }]
+keywords = ["webp", "image-compression", "png", "jpeg", "avif"]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "responses>=0.23"]
+
+[project.urls]
+Homepage = "https://webpninja.com"
+Documentation = "https://webpninja.com/docs"
+Repository = "https://github.com/yantrixlab/WebPNinja"
+
+[tool.hatch.build.targets.wheel]
+packages = ["webpninja"]

webpninja-1.0.0/tests/test_client.py

@@ -0,0 +1,121 @@
+import pytest
+import responses
+
+from webpninja import (
+    WebPNinja,
+    AuthenticationError,
+    ValidationError,
+    PayloadTooLargeError,
+    RateLimitError,
+)
+
+COMPRESS_URL = "https://api.webpninja.com/api/v1/compress"
+
+
+@responses.activate
+def test_compress_success(tmp_path):
+    responses.add(
+        responses.POST,
+        COMPRESS_URL,
+        body=b"fake-webp-bytes",
+        status=200,
+        content_type="image/webp",
+    )
+
+    photo = tmp_path / "photo.png"
+    photo.write_bytes(b"fake-png-bytes")
+
+    client = WebPNinja(api_key="webpninja_live_test")
+    result = client.compress(str(photo), format="webp", quality=75)
+
+    assert result == b"fake-webp-bytes"
+    sent = responses.calls[0].request
+    assert sent.headers["Authorization"] == "Bearer webpninja_live_test"
+
+
+@responses.activate
+def test_compress_accepts_raw_bytes():
+    responses.add(responses.POST, COMPRESS_URL, body=b"ok", status=200)
+
+    client = WebPNinja(api_key="webpninja_live_test")
+    result = client.compress(b"raw-bytes", format="png")
+
+    assert result == b"ok"
+
+
+def test_compress_rejects_bad_input_type():
+    client = WebPNinja(api_key="webpninja_live_test")
+    with pytest.raises(TypeError):
+        client.compress(12345, format="webp")
+
+
+@responses.activate
+def test_compress_maps_401_to_authentication_error():
+    responses.add(
+        responses.POST,
+        COMPRESS_URL,
+        json={"error": "Invalid or revoked API key"},
+        status=401,
+    )
+
+    client = WebPNinja(api_key="webpninja_live_bad")
+    with pytest.raises(AuthenticationError):
+        client.compress(b"bytes", format="webp")
+
+
+@responses.activate
+def test_compress_maps_400_to_validation_error():
+    responses.add(
+        responses.POST,
+        COMPRESS_URL,
+        json={"error": "format must be one of: webp, jpeg, png, avif"},
+        status=400,
+    )
+
+    client = WebPNinja(api_key="webpninja_live_test")
+    with pytest.raises(ValidationError):
+        client.compress(b"bytes", format="bogus")
+
+
+@responses.activate
+def test_compress_maps_413_with_plan_fields():
+    responses.add(
+        responses.POST,
+        COMPRESS_URL,
+        json={
+            "error": "File exceeds your plan's upload limit",
+            "maxUploadMb": 15,
+            "fileSizeMb": 20,
+        },
+        status=413,
+    )
+
+    client = WebPNinja(api_key="webpninja_live_test")
+    with pytest.raises(PayloadTooLargeError) as exc_info:
+        client.compress(b"bytes", format="webp")
+
+    assert exc_info.value.max_upload_mb == 15
+    assert exc_info.value.file_size_mb == 20
+
+
+@responses.activate
+def test_compress_maps_429_with_quota_fields():
+    responses.add(
+        responses.POST,
+        COMPRESS_URL,
+        json={"error": "Daily quota exceeded", "quota": 15, "used": 15},
+        status=429,
+    )
+
+    client = WebPNinja(api_key="webpninja_live_test")
+    with pytest.raises(RateLimitError) as exc_info:
+        client.compress(b"bytes", format="webp")
+
+    assert exc_info.value.quota == 15
+    assert exc_info.value.used == 15
+
+
+def test_missing_api_key(monkeypatch):
+    monkeypatch.delenv("WEBPNINJA_API_KEY", raising=False)
+    with pytest.raises(ValueError):
+        WebPNinja()

webpninja-1.0.0/webpninja/__init__.py

@@ -0,0 +1,19 @@
+from .client import WebPNinja
+from .errors import (
+    WebPNinjaError,
+    ValidationError,
+    AuthenticationError,
+    PayloadTooLargeError,
+    CompressionError,
+    RateLimitError,
+)
+
+__all__ = [
+    "WebPNinja",
+    "WebPNinjaError",
+    "ValidationError",
+    "AuthenticationError",
+    "PayloadTooLargeError",
+    "CompressionError",
+    "RateLimitError",
+]

webpninja-1.0.0/webpninja/client.py

@@ -0,0 +1,51 @@
+import os
+from pathlib import Path
+
+import requests
+
+from .errors import error_from_response
+
+DEFAULT_BASE_URL = "https://api.webpninja.com"
+
+
+class WebPNinja:
+    def __init__(self, api_key=None, base_url=DEFAULT_BASE_URL):
+        self.api_key = api_key or os.environ.get("WEBPNINJA_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "Missing API key: pass one to WebPNinja(api_key) or set WEBPNINJA_API_KEY"
+            )
+        self.base_url = base_url
+
+    def compress(self, input, format, quality=80, filename="image"):
+        data, name = self._resolve_input(input, filename)
+
+        response = requests.post(
+            f"{self.base_url}/api/v1/compress",
+            headers={"Authorization": f"Bearer {self.api_key}"},
+            files={"file": (name, data)},
+            data={"format": format, "quality": str(quality)},
+        )
+
+        if not response.ok:
+            try:
+                body = response.json()
+            except ValueError:
+                body = None
+            raise error_from_response(response.status_code, body)
+
+        return response.content
+
+    def compress_to_file(self, input, output_path, format, quality=80):
+        result = self.compress(input, format=format, quality=quality)
+        Path(output_path).write_bytes(result)
+        return result
+
+    @staticmethod
+    def _resolve_input(input, default_filename):
+        if isinstance(input, (str, os.PathLike)):
+            path = Path(input)
+            return path.read_bytes(), path.name
+        if isinstance(input, (bytes, bytearray)):
+            return bytes(input), default_filename
+        raise TypeError("input must be a file path or bytes")

webpninja-1.0.0/webpninja/errors.py

@@ -0,0 +1,53 @@
+class WebPNinjaError(Exception):
+    """Base error for all WebP Ninja API failures."""
+
+    def __init__(self, message, status=None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+
+
+class ValidationError(WebPNinjaError):
+    def __init__(self, message):
+        super().__init__(message, 400)
+
+
+class AuthenticationError(WebPNinjaError):
+    def __init__(self, message):
+        super().__init__(message, 401)
+
+
+class PayloadTooLargeError(WebPNinjaError):
+    def __init__(self, message, max_upload_mb=None, file_size_mb=None):
+        super().__init__(message, 413)
+        self.max_upload_mb = max_upload_mb
+        self.file_size_mb = file_size_mb
+
+
+class CompressionError(WebPNinjaError):
+    def __init__(self, message):
+        super().__init__(message, 422)
+
+
+class RateLimitError(WebPNinjaError):
+    def __init__(self, message, quota=None, used=None):
+        super().__init__(message, 429)
+        self.quota = quota
+        self.used = used
+
+
+def error_from_response(status, body):
+    body = body or {}
+    message = body.get("error") or f"Request failed with status {status}"
+
+    if status == 400:
+        return ValidationError(message)
+    if status == 401:
+        return AuthenticationError(message)
+    if status == 413:
+        return PayloadTooLargeError(message, body.get("maxUploadMb"), body.get("fileSizeMb"))
+    if status == 422:
+        return CompressionError(message)
+    if status == 429:
+        return RateLimitError(message, body.get("quota"), body.get("used"))
+    return WebPNinjaError(message, status)