imagecompressor 1.0.0__py3-none-any.whl

imagecompressor/__init__.py

@@ -0,0 +1,20 @@
+"""Client for the ImageCompressor.si image API.
+
+Uses only the Python standard library.
+
+    from imagecompressor import ImageCompressor
+
+    client = ImageCompressor("ic_live_...")
+    result = client.compress(open("photo.jpg", "rb").read(), format="webp", mode="smart")
+    open("photo.webp", "wb").write(result.data)
+"""
+
+from .client import (
+    ImageCompressor,
+    ImageCompressorError,
+    ImageResult,
+    verify_webhook,
+)
+
+__all__ = ["ImageCompressor", "ImageCompressorError", "ImageResult", "verify_webhook"]
+__version__ = "1.0.0"

imagecompressor/client.py

@@ -0,0 +1,325 @@
+"""The ImageCompressor API client. Standard library only (urllib)."""
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+
+# An image is its bytes, or the address to fetch it from: {"url": "https://..."}.
+ImageInput = Union[bytes, bytearray, Dict[str, str]]
+
+
+class ImageCompressorError(Exception):
+    """An error answered by the API, or a failure to reach it (code "network")."""
+
+    def __init__(self, code, message, status=0, request_id=None, retry_after=None, steps=None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.request_id = request_id
+        self.retry_after = retry_after
+        # For a failed pipeline: how far it got.
+        self.steps = steps
+
+
+@dataclass
+class ImageResult:
+    """A processed image and the facts the API reported about it."""
+
+    data: bytes
+    content_type: str
+    format: str
+    width: int
+    height: int
+    original_bytes: int
+    bytes: int
+    outcome: str
+    warnings: List[str] = field(default_factory=list)
+    duration_ms: int = 0
+    fingerprint: Optional[str] = None
+    similarity: Optional[float] = None
+    filename: Optional[str] = None
+    request_id: str = ""
+    steps: List[str] = field(default_factory=list)
+
+    def save(self, path: str) -> None:
+        with open(path, "wb") as handle:
+            handle.write(self.data)
+
+
+def _query(options: Dict[str, Any]) -> str:
+    """Options as the API's query string. True/False become true/false; None is left out."""
+    pairs = []
+    for name, value in options.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            value = "true" if value else "false"
+        elif isinstance(value, (list, tuple)):
+            value = ",".join(str(part) for part in value)
+        pairs.append((name, str(value)))
+    return ("?" + urllib.parse.urlencode(pairs)) if pairs else ""
+
+
+class ImageCompressor:
+    """Calls the API with one API key.
+
+    Options are keyword arguments named like the API's query parameters,
+    for example ``client.compress(data, format="webp", max_width=1600)``.
+    """
+
+    def __init__(self, api_key: str, base_url: str = "https://imagecompressor.si", max_retries: int = 3, timeout: float = 180.0):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+
+    # ---- One image in, one image out ----
+
+    def compress(self, image: ImageInput, **options: Any) -> ImageResult:
+        """Compress, convert, resize, crop, rotate, edit or watermark."""
+        return self._image("/api/v1/compress", image, options)
+
+    def convert(self, image: ImageInput, format: str, **options: Any) -> ImageResult:
+        return self._image("/api/v1/compress", image, dict(options, format=format))
+
+    def remove_background(self, image: ImageInput, **options: Any) -> ImageResult:
+        return self._image("/api/v1/remove-background", image, options)
+
+    def id_photo(self, image: ImageInput, **options: Any) -> ImageResult:
+        """Makes an ID or passport photo at an exact size: preset, or width_mm and height_mm, or width
+        and height in pixels; dpi, crop, min_bytes, max_bytes, background, remove_background, sheet."""
+        return self._image("/api/v1/id-photo", image, options)
+
+    def upscale(self, image: ImageInput, **options: Any) -> ImageResult:
+        """Doubles the width and height with a super-resolution model."""
+        return self._image("/api/v1/upscale", image, options)
+
+    def pipeline(self, image: ImageInput, pipeline: Optional[dict] = None, preset: Optional[str] = None,
+                 version: Optional[int] = None, name: Optional[str] = None) -> ImageResult:
+        """Runs a pipeline (inline, or a saved or built-in preset by name) on one image."""
+        query = _query({"pipeline": json.dumps(pipeline) if pipeline else None, "preset": preset, "version": version, "name": name})
+        return self._read_image(self._send("POST", "/api/v1/pipeline" + query, image=image))
+
+    def dry_run(self, image: ImageInput, pipeline: Optional[dict] = None, preset: Optional[str] = None,
+                version: Optional[int] = None, name: Optional[str] = None) -> dict:
+        """What a pipeline would do to this image, without doing it."""
+        query = _query({"pipeline": json.dumps(pipeline) if pipeline else None, "preset": preset, "version": version,
+                        "name": name, "dry_run": True})
+        return self._json("POST", "/api/v1/pipeline" + query, image=image)
+
+    # ---- One image in, an answer out ----
+
+    def inspect(self, image: ImageInput) -> dict:
+        """Format, size, metadata, GPS position and fingerprints."""
+        return self._json("POST", "/api/v1/inspect", image=image)
+
+    def ocr(self, image: ImageInput, languages: Optional[List[str]] = None) -> dict:
+        """The text in the image. languages: "eng", "slv" or both."""
+        return self._json("POST", "/api/v1/ocr" + _query({"lang": languages}), image=image)
+
+    # ---- Background jobs ----
+
+    def create_job(self, inputs: List[Union[str, dict]], pipeline: Optional[dict] = None, preset: Optional[str] = None,
+                   version: Optional[int] = None, webhook_url: Optional[str] = None,
+                   idempotency_key: Optional[str] = None) -> dict:
+        """Starts a pipeline over several images. idempotency_key makes the call safe to repeat."""
+        body = {"inputs": [{"url": item} if isinstance(item, str) else item for item in inputs]}
+        for name, value in (("pipeline", pipeline), ("preset", preset), ("version", version), ("webhook_url", webhook_url)):
+            if value is not None:
+                body[name] = value
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
+        return self._json("POST", "/api/v1/jobs", body=body, headers=headers)
+
+    def get_job(self, job_id: str) -> dict:
+        return self._json("GET", "/api/v1/jobs/" + urllib.parse.quote(job_id, safe=""))
+
+    def cancel_job(self, job_id: str) -> dict:
+        return self._json("DELETE", "/api/v1/jobs/" + urllib.parse.quote(job_id, safe=""))
+
+    def wait_for_job(self, job_id: str, interval: float = 1.0, timeout: float = 600.0) -> dict:
+        """Polls until the job is finished, failed or cancelled."""
+        deadline = time.time() + timeout
+        while True:
+            job = self.get_job(job_id)
+            if job["status"] not in ("queued", "running"):
+                return job
+            if time.time() > deadline:
+                raise ImageCompressorError("timeout", "The job did not finish in time.")
+            time.sleep(interval)
+
+    # ---- Saved pipelines ----
+
+    def list_pipelines(self) -> dict:
+        return self._json("GET", "/api/v1/pipelines")
+
+    def save_pipeline(self, name: str, pipeline: dict) -> dict:
+        """Saving under an existing name adds a version."""
+        return self._json("POST", "/api/v1/pipelines", body={"name": name, "pipeline": pipeline})
+
+    def get_pipeline(self, name: str, version: Optional[int] = None) -> dict:
+        return self._json("GET", "/api/v1/pipelines/" + urllib.parse.quote(name, safe="") + _query({"version": version}))
+
+    def delete_pipeline(self, name: str) -> dict:
+        return self._json("DELETE", "/api/v1/pipelines/" + urllib.parse.quote(name, safe=""))
+
+    # ---- Asset index ----
+
+    def index_assets(self, project: str, assets: List[dict]) -> dict:
+        """Replaces one project's entries in the asset index. Facts only: no image data is sent."""
+        return self._json("POST", "/api/v1/assets", body={"project": project, "assets": assets})
+
+    def search_assets(self, q: Optional[str] = None, project: Optional[str] = None, limit: Optional[int] = None) -> dict:
+        return self._json("GET", "/api/v1/assets" + _query({"q": q, "project": project, "limit": limit}))
+
+    def duplicate_assets(self) -> dict:
+        """Identical files that appear more than once across your projects."""
+        return self._json("GET", "/api/v1/assets/duplicates")
+
+    def remove_asset_project(self, project: str) -> dict:
+        return self._json("DELETE", "/api/v1/assets" + _query({"project": project}))
+
+    # ---- Website optimizer, account, discovery ----
+
+    def optimize_site(self, url: str, quality: Optional[int] = None, max_pages: Optional[int] = None) -> dict:
+        body = {"url": url}
+        if quality is not None:
+            body["quality"] = quality
+        if max_pages is not None:
+            body["max_pages"] = max_pages
+        return self._json("POST", "/api/v1/sites/optimize", body=body)
+
+    def get_site_job(self, job_id: str) -> dict:
+        return self._json("GET", "/api/v1/sites/optimize/" + urllib.parse.quote(job_id, safe=""))
+
+    def usage(self) -> dict:
+        return self._json("GET", "/api/v1/usage")
+
+    def capabilities(self) -> dict:
+        return self._json("GET", "/api/v1/capabilities")
+
+    def download(self, url: str) -> bytes:
+        """Downloads a stored result (a url from a job or an output="json" call)."""
+        path = urllib.parse.urlparse(url).path if url.startswith("http") else url
+        return self._send("GET", path)["body"]
+
+    # ---- Plumbing ----
+
+    def _image(self, path: str, image: ImageInput, options: Dict[str, Any]) -> ImageResult:
+        return self._read_image(self._send("POST", path + _query(dict(options, output="binary")), image=image))
+
+    @staticmethod
+    def _read_image(response: dict) -> ImageResult:
+        headers = response["headers"]
+
+        def number(name: str) -> int:
+            return int(headers.get(name) or 0)
+
+        disposition = headers.get("content-disposition") or ""
+        filename = disposition.split('filename="')[1].split('"')[0] if 'filename="' in disposition else None
+        similarity = headers.get("x-ic-similarity")
+        return ImageResult(
+            data=response["body"],
+            content_type=headers.get("content-type") or "application/octet-stream",
+            format=headers.get("x-ic-format") or "",
+            width=number("x-ic-width"),
+            height=number("x-ic-height"),
+            original_bytes=number("x-ic-original-bytes"),
+            bytes=len(response["body"]),
+            outcome=headers.get("x-ic-outcome") or "done",
+            warnings=[w for w in (headers.get("x-ic-warnings") or "").split(",") if w],
+            duration_ms=number("x-ic-duration-ms"),
+            fingerprint=headers.get("x-ic-fingerprint"),
+            similarity=float(similarity) if similarity is not None else None,
+            filename=filename,
+            request_id=headers.get("x-request-id") or "",
+            steps=json.loads(headers.get("x-ic-steps") or "[]"),
+        )
+
+    def _json(self, method: str, path: str, image: Optional[ImageInput] = None, body: Any = None,
+              headers: Optional[Dict[str, str]] = None) -> Any:
+        return json.loads(self._send(method, path, image=image, body=body, headers=headers)["body"].decode("utf-8"))
+
+    def _send(self, method: str, path: str, image: Optional[ImageInput] = None, body: Any = None,
+              headers: Optional[Dict[str, str]] = None) -> dict:
+        request_headers = {"Authorization": "Bearer " + self.api_key, "User-Agent": "imagecompressor-python/1.0.0"}
+        request_headers.update(headers or {})
+        data = None
+        if image is not None:
+            if isinstance(image, (bytes, bytearray)):
+                data = bytes(image)
+                request_headers["Content-Type"] = "application/octet-stream"
+            else:
+                data = json.dumps({"url": image["url"]}).encode("utf-8")
+                request_headers["Content-Type"] = "application/json"
+        elif body is not None:
+            data = json.dumps(body).encode("utf-8")
+            request_headers["Content-Type"] = "application/json"
+
+        attempt = 0
+        while True:
+            request = urllib.request.Request(self.base_url + path, data=data, method=method, headers=request_headers)
+            try:
+                with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                    return {"body": response.read(), "headers": {k.lower(): v for k, v in response.headers.items()}}
+            except urllib.error.HTTPError as error:
+                error_headers = {k.lower(): v for k, v in error.headers.items()}
+                retry_after = int(error_headers.get("retry-after") or 0) or None
+                if error.code in (429, 503) and attempt < self.max_retries and retry_after and retry_after <= 60:
+                    attempt += 1
+                    time.sleep(retry_after)
+                    continue
+                try:
+                    parsed = json.loads(error.read().decode("utf-8"))
+                except ValueError:
+                    parsed = {}
+                detail = parsed.get("error") or {}
+                raise ImageCompressorError(
+                    detail.get("code", "internal"),
+                    detail.get("message", "The API answered with status %d." % error.code),
+                    status=error.code,
+                    request_id=detail.get("request_id") or error_headers.get("x-request-id"),
+                    retry_after=retry_after,
+                    steps=parsed.get("steps"),
+                ) from None
+            except urllib.error.URLError as error:
+                raise ImageCompressorError("network", str(error.reason)) from None
+
+
+def verify_webhook(secret: str, body: Union[str, bytes], headers: Dict[str, str], tolerance: int = 300) -> dict:
+    """Checks that a webhook really came from ImageCompressor and returns its parsed body.
+
+    secret is the signing secret from your account page (whsec_...), body the
+    raw request body exactly as received, headers the request's headers.
+    Raises ValueError when the signature does not match or the message is
+    older than tolerance seconds. Signatures follow the Standard Webhooks
+    specification.
+    """
+    lowered = {name.lower(): value for name, value in headers.items()}
+    message_id = lowered.get("webhook-id")
+    timestamp = lowered.get("webhook-timestamp")
+    signatures = lowered.get("webhook-signature")
+    if not message_id or not timestamp or not signatures:
+        raise ValueError("missing webhook headers")
+    if abs(time.time() - int(timestamp)) > tolerance:
+        raise ValueError("the message is too old")
+    text = body.decode("utf-8") if isinstance(body, bytes) else body
+    key = base64.b64decode(secret[len("whsec_"):] if secret.startswith("whsec_") else secret)
+    expected = base64.b64encode(
+        hmac.new(key, ("%s.%s.%s" % (message_id, timestamp, text)).encode("utf-8"), hashlib.sha256).digest()
+    ).decode("ascii")
+    # The header may carry several space-separated "v1,<signature>" entries.
+    for entry in signatures.split(" "):
+        version, _, signature = entry.partition(",")
+        if version == "v1" and hmac.compare_digest(signature, expected):
+            return json.loads(text)
+    raise ValueError("the signature does not match")

imagecompressor-1.0.0.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: imagecompressor
+Version: 1.0.0
+Summary: Client for the ImageCompressor.si image API: compress, convert, resize, remove backgrounds, upscale, OCR, pipelines and jobs.
+License: MIT
+Project-URL: Homepage, https://imagecompressor.si/developers
+Project-URL: Documentation, https://imagecompressor.si/developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# imagecompressor (Python)
+
+Client for the [ImageCompressor.si](https://imagecompressor.si/developers) image API. Standard library only; Python 3.8+.
+
+```python
+import os
+from imagecompressor import ImageCompressor
+
+client = ImageCompressor(os.environ["IMAGECOMPRESSOR_API_KEY"])
+
+# Compress to WebP, at most 1600 px wide, letting smart mode pick the quality.
+with open("photo.jpg", "rb") as handle:
+    result = client.compress(handle.read(), format="webp", mode="smart", max_width=1600)
+result.save("photo.webp")
+print(result.width, result.height, result.bytes, result.warnings)
+```
+
+Options are keyword arguments named like the API's parameters. An image is `bytes`, or `{"url": "https://..."}`.
+
+| Method | Does |
+|---|---|
+| `compress(image, **options)` | compress, convert, resize, crop, rotate, edit, watermark |
+| `convert(image, format, **options)` | change format |
+| `remove_background(image, **options)` | cut out the subject |
+| `id_photo(image, preset="35x45")` | an ID or passport photo at an exact size, DPI and KB range; `sheet=True` for a 4×6 print sheet |
+| `upscale(image)` | double the size with the AI upscaler |
+| `inspect(image)` | format, size, metadata, GPS position, fingerprints |
+| `ocr(image, languages=[...])` | the text in the image |
+| `pipeline(image, pipeline=... or preset=...)` / `dry_run(...)` | several steps on one image (Pro plan) |
+| `create_job / get_job / cancel_job / wait_for_job` | a pipeline over many images, in the background (Pro plan) |
+| `list_pipelines / save_pipeline / get_pipeline / delete_pipeline` | saved pipelines |
+| `optimize_site / get_site_job` | the website optimizer |
+| `usage()`, `capabilities()`, `download(url)` | account and discovery |
+
+Errors are `ImageCompressorError` with `code`, `status`, `request_id` and, for a failed pipeline, `steps`. A `429` or `503` is retried after the wait the API names.
+
+## Webhooks
+
+```python
+from imagecompressor import verify_webhook
+
+# body must be the raw request body, exactly as received.
+event = verify_webhook(os.environ["IMAGECOMPRESSOR_WEBHOOK_SECRET"], body, headers)
+if event["type"] == "job.finished":
+    print(event["data"]["id"], event["data"]["status"])
+```
+
+Run the tests with `python -m unittest discover -s tests`.

imagecompressor-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+imagecompressor/__init__.py,sha256=zuaMdWDoaE43ZjomdmvjjfYVxO61hzD3zEkfRfqUndM,543
+imagecompressor/client.py,sha256=shJ8H1mdz73TxcRw5Wicyt_JwcoIj7c49czY4l46nDc,15361
+imagecompressor-1.0.0.dist-info/METADATA,sha256=DsNWH0Q-gvcvOJX1ooxuIr30s9iyQeuAoZkE7TCwQWM,2640
+imagecompressor-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+imagecompressor-1.0.0.dist-info/top_level.txt,sha256=h8S09EWPVZ-A_EqHhIwNyepIZqGpvg2V2LZjKGQoanc,16
+imagecompressor-1.0.0.dist-info/RECORD,,

imagecompressor-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

imagecompressor-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+imagecompressor