switchfile-sdk 0.1.0__py3-none-any.whl

switchfile/__init__.py

@@ -0,0 +1,178 @@
+"""switchfile: Python-SDK für die switchfile-API.
+
+Schnittstelle wie das CloudConvert-SDK::
+
+    import switchfile
+    switchfile.configure(api_key="...", sandbox=False)
+    job = switchfile.Job.create(payload={"tasks": {...}})
+    job = switchfile.Job.wait(id=job["id"])
+
+Dazu ``switchfile.convert(file, to, options)`` für /v1 und ``switchfile.Client`` für mehrere Keys.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from .client import (_UNSET, DEFAULT_BASE_URL, MULTIPART_LIMIT, NO_STORE_LIMIT, NO_STORE_TIMEOUT, Client, Jobs,
+                     NoStoreResult, Webhooks)
+from .errors import ConversionFailedError, SwitchfileError
+from .version import __version__
+
+__all__ = [
+    "Account", "Client", "Conversion", "ConversionFailedError", "DEFAULT_BASE_URL", "Job", "MULTIPART_LIMIT",
+    "NO_STORE_LIMIT", "NO_STORE_TIMEOUT", "NoStoreResult", "SwitchfileError", "Task", "User", "Webhook", "__version__",
+    "configure", "convert", "convert_without_storage", "default", "download", "formats",
+]
+
+_client: Client | None = None
+
+
+def configure(**config: Any) -> Client:
+    """Standard-Client einstellen: api_key, sandbox, base_url, sandbox_base_url, timeout, max_retries, poll_interval,
+    user_agent. Gibt den Client zurück."""
+    global _client
+    _client = Client(**config)
+    return _client
+
+
+def default() -> Client:
+    """Standard-Client aus der Umgebung (SWITCHFILE_API_KEY, SWITCHFILE_API_URL, SWITCHFILE_SANDBOX=true)."""
+    return configure(sandbox=os.environ.get("SWITCHFILE_SANDBOX", "false").lower() == "true")
+
+
+def _c() -> Client:
+    return _client if _client is not None else default()
+
+
+class Job:
+    """Jobs (/v2), Methoden wie cloudconvert.Job."""
+
+    @staticmethod
+    def create(payload: dict | None = None) -> dict:
+        return _c().jobs.create(payload)
+
+    @staticmethod
+    def find(id: str) -> dict:
+        return _c().jobs.find(id)
+
+    @staticmethod
+    def show(id: str) -> dict:
+        return _c().jobs.find(id)
+
+    @staticmethod
+    def wait(id: str, timeout: float | None = None) -> dict:
+        return _c().jobs.wait(id, timeout=timeout)
+
+    @staticmethod
+    def all(params: dict | None = None) -> list:
+        return _c().jobs.all(params)
+
+    @staticmethod
+    def delete(id: str) -> bool:
+        return _c().jobs.delete(id)
+
+    @staticmethod
+    def get_export_urls(job: dict) -> list:
+        return Jobs.get_export_urls(job)
+
+
+class Task:
+    """Tasks (/v2), Methoden wie cloudconvert.Task."""
+
+    @staticmethod
+    def find(id: str, include: str | None = None) -> dict:
+        return _c().tasks.find(id, include)
+
+    @staticmethod
+    def show(id: str, include: str | None = None) -> dict:
+        return _c().tasks.find(id, include)
+
+    @staticmethod
+    def wait(id: str, timeout: float | None = None) -> dict:
+        return _c().tasks.wait(id, timeout=timeout)
+
+    @staticmethod
+    def all(params: dict | None = None) -> list:
+        return _c().tasks.all(params)
+
+    @staticmethod
+    def cancel(id: str) -> bool:
+        return _c().tasks.cancel(id)
+
+    @staticmethod
+    def retry(id: str) -> dict:
+        return _c().tasks.retry(id)
+
+    @staticmethod
+    def upload(file_name: Any, task: dict, filename: str | None = None) -> bool:
+        return _c().tasks.upload(file_name, task, filename)
+
+
+class User:
+    @staticmethod
+    def me() -> dict:
+        return _c().users.me()
+
+
+class Webhook:
+    """Webhook-Signaturen, wie cloudconvert.Webhook.verify."""
+
+    @staticmethod
+    def verify(payload_string: str | bytes, signature: str | None, signature_secret: str) -> bool:
+        return Webhooks.verify(payload_string, signature, signature_secret)
+
+    @staticmethod
+    def construct_event(payload_string: str | bytes, signature: str | None, signature_secret: str) -> dict:
+        return Webhooks.construct_event(payload_string, signature, signature_secret)
+
+
+class Conversion:
+    """Umwandlungen (/v1)."""
+
+    @staticmethod
+    def find(id: str, wait: float | None = None) -> dict:
+        return _c().conversions.find(id, wait)
+
+    @staticmethod
+    def wait(id: str, timeout: float | None = None) -> dict:
+        return _c().conversions.wait(id, timeout)
+
+    @staticmethod
+    def list(ids: list[str]) -> list:
+        return _c().conversions.list(ids)
+
+    @staticmethod
+    def delete(id: str) -> bool:
+        return _c().conversions.delete(id)
+
+
+class Account:
+    """Konto (/v1): Credits, Gratis-Kontingent, Webhook-URL und Signing-Secret."""
+
+    @staticmethod
+    def get() -> dict:
+        return _c().account.get()
+
+    @staticmethod
+    def update(webhook_url: Any = _UNSET, *, no_store: bool | None = None) -> dict:
+        return _c().account.update(webhook_url, no_store=no_store)
+
+
+def convert(file: Any, to: str | None = None, options: dict | None = None, **kwargs: Any) -> dict:
+    """Datei umwandeln (/v1) und auf das Ergebnis warten. Siehe Client.convert."""
+    return _c().convert(file, to, options, **kwargs)
+
+
+def convert_without_storage(file: Any, to: str | None = None, options: dict | None = None, **kwargs: Any) -> NoStoreResult:
+    """Datei ohne Speicherung umwandeln, Ergebnis in der Antwort. Siehe Client.convert_without_storage."""
+    return _c().convert_without_storage(file, to, options, **kwargs)
+
+
+def formats(input: str | None = None) -> dict:
+    return _c().formats(input)
+
+
+def download(url: Any = None, filename: str | os.PathLike | None = None) -> bytes | str:
+    """Datei von einer signierten URL laden; mit filename in die Datei schreiben (wie cloudconvert.download)."""
+    return _c().download(url, filename)

switchfile/_http.py

@@ -0,0 +1,314 @@
+"""HTTP-Kern mit urllib (keine Abhängigkeiten). Der API-Key geht nur an die Basis-URL der API, nie an signierte
+Upload- und Download-URLs. Uploads und Downloads werden gestreamt, nicht im Speicher gepuffert."""
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import os
+import random
+import re
+import secrets
+import shutil
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, BinaryIO, Callable, Iterable
+
+from .errors import SwitchfileError, error_from_response
+
+_SAFE_HEADER = re.compile(r"^[A-Za-z0-9-]{1,64}$")
+_UNSAFE_VALUE = re.compile(r"[\r\n\x00]")
+_BLOCKED_HEADER = re.compile(r"^(authorization|host|content-length|transfer-encoding|connection|cookie)$", re.I)
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):  # Redirects der API nicht folgen (Key bliebe sonst im Header)
+        return None
+
+
+_api_opener = urllib.request.build_opener(_NoRedirect)
+_plain_opener = urllib.request.build_opener()
+
+
+def redirect_error(status: int, location: str | None, url: str) -> SwitchfileError:
+    """Fehler für eine 3xx-Antwort der API."""
+    host = urllib.parse.urlsplit(url).netloc
+    target = f" to {location}" if location else ""
+    return SwitchfileError(
+        "UNEXPECTED_REDIRECT",
+        f"The switchfile API at {host} answered with a redirect (HTTP {status}{target}). "
+        "Check the base URL; it should be https://api.switchfile.io.",
+        status=status,
+    )
+
+
+class Transport:
+    def __init__(self, api_key: str, base_url: str, timeout: float, max_retries: int, user_agent: str,
+                 opener: urllib.request.OpenerDirector | None = None):
+        self.api_key = api_key
+        self.base_url = base_url
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.user_agent = user_agent
+        self._opener = opener or _api_opener
+
+    # ---------- API ----------
+    def request(self, method: str, path: str, *, query: dict | None = None, json_body: Any = None,
+                body_factory: Callable[[], tuple[Any, dict]] | None = None, auth: bool = True,
+                idempotency_key: str | None = None, timeout: float | None = None, retry: bool | None = None,
+                headers: dict | None = None, binary: bool = False) -> Any:
+        """JSON-Request an die API. Gibt den geparsten Body zurück (None bei 204). binary: (Bytes, Header) der
+        Erfolgsantwort, z. B. die Datei einer Umwandlung ohne Speicherung."""
+        url = self.base_url + path
+        q = {k: v for k, v in (query or {}).items() if v is not None}
+        if q:
+            url += "?" + urllib.parse.urlencode({k: (str(v).lower() if isinstance(v, bool) else v) for k, v in q.items()})
+        headers = {"Accept": "application/json", "User-Agent": self.user_agent, **(headers or {})}
+        if auth:
+            if not self.api_key:
+                raise SwitchfileError("MISSING_API_KEY", "No API key. Pass api_key or set SWITCHFILE_API_KEY.")
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        retry_server = retry if retry is not None else (method in ("GET", "DELETE") or bool(idempotency_key))
+
+        attempt = 0
+        while True:
+            data: Any = None
+            extra: dict = {}
+            if json_body is not None:
+                data = json.dumps(json_body).encode()
+                extra = {"Content-Type": "application/json"}
+            elif body_factory is not None:
+                data, extra = body_factory()
+            req = urllib.request.Request(url, data=data, method=method, headers={**headers, **extra})
+            try:
+                with _closing(data), self._opener.open(req, timeout=timeout or self.timeout) as res:
+                    raw = res.read()
+                    if binary:
+                        return raw, res.headers
+                    return _parse(raw) if res.status != 204 else None
+            except urllib.error.HTTPError as e:
+                raw = e.read() if e.fp else b""
+                if 300 <= e.code < 400:
+                    # Weiterleitungen nie folgen und nicht als Erfolg werten: meist ist die Basis-URL falsch.
+                    raise redirect_error(e.code, e.headers.get("Location"), url) from None
+                err = error_from_response(e.code, _parse(raw), e.headers.get("Retry-After"))
+                again = ((e.code == 429 and err.code == "RATE_LIMIT_EXCEEDED")
+                         or (e.code == 409 and err.code == "IDEMPOTENCY_KEY_IN_USE")
+                         # Ohne Speicherung: ausgelastet oder belegt, die API hat nichts umgewandelt und nichts berechnet.
+                         or (e.code == 429 and err.code == "CONCURRENCY_LIMIT")
+                         or (e.code == 503 and err.code in ("SERVER_BUSY", "NO_STORE_UNAVAILABLE"))
+                         or (retry_server and e.code in (500, 502, 503, 504)))
+                if again and attempt < self.max_retries:
+                    wait = err.retry_after if err.retry_after is not None else _backoff(attempt)
+                    if wait <= 60:
+                        time.sleep(wait)
+                        attempt += 1
+                        continue
+                raise err from None
+            except (urllib.error.URLError, ConnectionError, socket.timeout, TimeoutError) as e:
+                if retry_server and attempt < self.max_retries:
+                    time.sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                host = urllib.parse.urlsplit(url).netloc
+                reason = getattr(e, "reason", e)
+                if isinstance(reason, (socket.timeout, TimeoutError)):
+                    raise SwitchfileError("TIMEOUT", f"The switchfile API ({host}) did not answer in time.") from e
+                raise SwitchfileError("NETWORK_ERROR", f"Could not reach the switchfile API at {host}.") from e
+
+    # ---------- signierte URLs ----------
+    def send_signed(self, method: str, url: str, body_factory: Callable[[], tuple[Any, dict]]) -> Any:
+        """Upload an eine signierte URL, ohne Key. Gibt den JSON-Body zurück (falls vorhanden)."""
+        target = self.resolve_signed(url)
+        data, headers = body_factory()
+        req = urllib.request.Request(target, data=data, method=method, headers={"User-Agent": self.user_agent, **headers})
+        try:
+            with _closing(data), _plain_opener.open(req, timeout=max(self.timeout, 300)) as res:
+                return _parse(res.read())
+        except urllib.error.HTTPError as e:
+            raw = e.read() if e.fp else b""
+            raise error_from_response(e.code, _parse(raw), e.headers.get("Retry-After")) from None
+        except (urllib.error.URLError, ConnectionError, socket.timeout, TimeoutError) as e:
+            host = urllib.parse.urlsplit(target).netloc
+            raise SwitchfileError("NETWORK_ERROR", f"The upload to {host} failed.") from e
+
+    def download(self, url: str, filename: str | os.PathLike | None = None) -> bytes | str:
+        """Signierte URL laden (ohne Key). Mit filename in die Datei schreiben und den Pfad zurückgeben."""
+        target = self.resolve_signed(url)
+        host = urllib.parse.urlsplit(target).netloc
+        req = urllib.request.Request(target, headers={"User-Agent": self.user_agent})
+        for attempt in range(self.max_retries + 1):
+            try:
+                with _plain_opener.open(req, timeout=max(self.timeout, 300)) as res:
+                    if filename is None:
+                        return res.read()
+                    path = os.fspath(filename)
+                    tmp = f"{path}.part-{os.getpid()}-{secrets.token_hex(4)}"
+                    try:
+                        with open(tmp, "wb") as out:
+                            shutil.copyfileobj(res, out, 1024 * 1024)
+                        os.replace(tmp, path)
+                    except BaseException:
+                        try:
+                            os.remove(tmp)
+                        except OSError:
+                            pass
+                        raise
+                    return path
+            except urllib.error.HTTPError as e:
+                if e.code >= 500 and attempt < self.max_retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                raw = e.read() if e.fp else b""
+                raise error_from_response(e.code, _parse(raw), e.headers.get("Retry-After")) from None
+            except (urllib.error.URLError, ConnectionError, socket.timeout, TimeoutError) as e:
+                if attempt < self.max_retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise SwitchfileError("NETWORK_ERROR", f"The download from {host} failed.") from e
+        raise SwitchfileError("NETWORK_ERROR", f"The download from {host} failed.")
+
+    def resolve_signed(self, url: str) -> str:
+        full = urllib.parse.urljoin(self.base_url + "/", url)
+        p = urllib.parse.urlsplit(full)
+        if p.scheme not in ("http", "https") or p.username or p.password:
+            raise SwitchfileError("BAD_RESPONSE", "The switchfile API returned a file URL that is not allowed.")
+        return full
+
+
+# ---------- Dateien ----------
+class PreparedFile:
+    """Datei aus Pfad, Bytes oder Datei-Objekt mit Name und Größe. open() liefert jedes Mal einen frischen Stream."""
+
+    def __init__(self, source: Any, filename: str | None = None):
+        self._path: str | None = None
+        self._bytes: bytes | None = None
+        self._fileobj: BinaryIO | None = None
+        self._start = 0
+        if isinstance(source, (str, os.PathLike)):
+            path = os.fspath(source)
+            if not os.path.isfile(path):
+                raise SwitchfileError("READ_FAILED", f"Could not read {path}: not a file.")
+            self._path = path
+            self.size = os.path.getsize(path)
+            self.filename = filename or os.path.basename(path)
+        elif isinstance(source, (bytes, bytearray, memoryview)):
+            self._bytes = bytes(source)
+            self.size = len(self._bytes)
+            self.filename = filename
+        elif hasattr(source, "read"):
+            name = getattr(source, "name", None)
+            self.filename = filename or (os.path.basename(name) if isinstance(name, str) else None)
+            try:  # Datei mit bekannter Größe: von der aktuellen Position an streamen
+                self._start = source.tell()
+                source.seek(0, io.SEEK_END)
+                self.size = source.tell() - self._start
+                source.seek(self._start)
+                self._fileobj = source
+            except (AttributeError, OSError, io.UnsupportedOperation):
+                self._bytes = source.read()
+                self.size = len(self._bytes)
+        else:
+            raise SwitchfileError("INVALID_SOURCE", "Unsupported file source. Pass a path, bytes or a file object.")
+
+    def open(self) -> BinaryIO:
+        if self._path is not None:
+            return open(self._path, "rb")
+        if self._fileobj is not None:
+            self._fileobj.seek(self._start)
+            return _NoClose(self._fileobj)
+        return io.BytesIO(self._bytes or b"")
+
+
+class _NoClose(io.RawIOBase):
+    """Datei-Objekt des Aufrufers lesen, ohne es zu schließen."""
+
+    def __init__(self, f: BinaryIO):
+        self._f = f
+
+    def readable(self) -> bool:
+        return True
+
+    def read(self, n: int = -1) -> bytes:
+        return self._f.read(n)
+
+
+class MultipartBody(io.RawIOBase):
+    """multipart/form-data als Stream mit bekannter Länge (die Datei wird beim Senden gelesen)."""
+
+    def __init__(self, fields: Iterable[tuple[str, str]], file_field: str, file: PreparedFile, filename: str):
+        self.boundary = "----switchfile" + uuid.uuid4().hex
+        pre = b""
+        for k, v in fields:
+            pre += (f"--{self.boundary}\r\nContent-Disposition: form-data; name=\"{_q(k)}\"\r\n\r\n").encode() + v.encode() + b"\r\n"
+        pre += (f"--{self.boundary}\r\nContent-Disposition: form-data; name=\"{_q(file_field)}\"; filename=\"{_q(filename)}\"\r\n"
+                f"Content-Type: application/octet-stream\r\n\r\n").encode()
+        post = f"\r\n--{self.boundary}--\r\n".encode()
+        self.length = len(pre) + file.size + len(post)
+        self._parts: list[Any] = [io.BytesIO(pre), file.open(), io.BytesIO(post)]
+
+    def close(self) -> None:
+        # Auch nach einem abgebrochenen Senden: die Datei nicht offen lassen (_NoClose schließt die des Aufrufers nicht).
+        for part in self._parts:
+            part.close()
+        self._parts = []
+        super().close()
+
+    @property
+    def content_type(self) -> str:
+        return f"multipart/form-data; boundary={self.boundary}"
+
+    def readable(self) -> bool:
+        return True
+
+    def read(self, n: int = -1) -> bytes:
+        out = b""
+        while self._parts and (n < 0 or len(out) < n):
+            chunk = self._parts[0].read(-1 if n < 0 else n - len(out))
+            if not chunk:
+                part = self._parts.pop(0)
+                part.close()
+                continue
+            out += chunk
+        return out
+
+
+@contextlib.contextmanager
+def _closing(data: Any):
+    """Body (Datei, MultipartBody) nach dem Request schließen, auch bei Fehlern; Bytes bleiben unberührt."""
+    try:
+        yield data
+    finally:
+        if hasattr(data, "close"):
+            data.close()
+
+
+def safe_upload_headers(h: dict | None) -> dict:
+    """Header der API für den PUT: ohne Authorization, Host, Längen; Werte mit CR, LF oder NUL werden verworfen
+    (wie integrations/shared/http-common.ts), sonst würfe urllib einen ValueError."""
+    return {k: str(v) for k, v in (h or {}).items()
+            if v is not None and isinstance(k, str) and _SAFE_HEADER.match(k) and not _BLOCKED_HEADER.match(k)
+            and not _UNSAFE_VALUE.search(str(v))}
+
+
+def _q(s: str) -> str:
+    return s.replace("\\", "\\\\").replace('"', "%22").replace("\r", "").replace("\n", "")
+
+
+def _parse(raw: bytes) -> Any:
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except ValueError:
+        return None
+
+
+def _backoff(attempt: int) -> float:
+    return min(8.0, 0.5 * 2 ** attempt) + random.random() * 0.25

switchfile/client.py

@@ -0,0 +1,434 @@
+"""Client mit allen Ressourcen. ``Client`` für mehrere Keys oder Basis-URLs; die Modul-Funktionen und -Klassen
+(``switchfile.Job.create`` …) nutzen einen Standard-Client wie das CloudConvert-SDK."""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import re
+import time
+import urllib.parse
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+from ._http import MultipartBody, PreparedFile, Transport, safe_upload_headers
+from .errors import ConversionFailedError, SwitchfileError
+from .version import __version__
+
+DEFAULT_BASE_URL = "https://api.switchfile.io"
+#: Dateien bis zu dieser Größe gehen im Request mit (multipart), größere über POST /v1/uploads.
+MULTIPART_LIMIT = 50 * 1024 * 1024
+#: Größte Datei ohne Speicherung (die API lehnt größere mit FILE_TOO_LARGE ab).
+NO_STORE_LIMIT = 50 * 1024 * 1024
+# Zeitlimit eines Requests ohne Speicherung (s): so lang, wie die API ihm lässt (Hochladen 120 s, Umwandeln 90 s,
+# Senden der Antwort 180 s). Ein längeres Zeitlimit des Clients gilt.
+NO_STORE_TIMEOUT = 390
+_WAIT_SECONDS = 30
+_LIVE_KEY = re.compile(r"^(sf_live_|ac_live_)")
+
+
+_UNSET: Any = object()
+
+
+def _q(s: str) -> str:
+    return urllib.parse.quote(str(s), safe="")
+
+
+def _poll(load, done, timeout: float | None, interval: float) -> dict:
+    deadline = None if timeout is None else time.monotonic() + timeout
+    while True:
+        item = load()
+        if done(item.get("status")):
+            return item
+        if deadline is not None:
+            left = deadline - time.monotonic()
+            if left <= 0:
+                raise SwitchfileError("TIMEOUT", f"Still {item.get('status')} after waiting {timeout} seconds.", body=item)
+            time.sleep(min(interval, left))
+        else:
+            time.sleep(interval)
+        interval = min(5.0, interval * 1.5)
+
+
+def _job_done(s: Any) -> bool:
+    return s in ("finished", "error")
+
+
+def _conv_done(s: Any) -> bool:
+    return s in ("finished", "failed")
+
+
+class Jobs:
+    def __init__(self, t: Transport, poll: float):
+        self._t, self._poll = t, poll
+
+    def create(self, payload: dict | None = None) -> dict:
+        """Job anlegen (POST /v2/jobs). Gibt den Job mit allen Tasks zurück. Mit "store": False läuft er ohne
+        Speicherung über /sync/v2/jobs und kommt fertig zurück (Dateien als base64 in result.files[].content)."""
+        payload = payload or {}
+        if payload.get("store") is False:
+            # Der Header hebt die Grenze des JSON-Bodys auf die Dateigrenze ohne Speicherung (base64 von 50 MB).
+            return self._t.request("POST", "/sync/v2/jobs", json_body=payload, retry=False,
+                                   headers={"Switchfile-Store": "false"}, timeout=max(self._t.timeout, NO_STORE_TIMEOUT))["data"]
+        return self._t.request("POST", "/v2/jobs", json_body=payload, retry=False)["data"]
+
+    def find(self, id: str) -> dict:
+        return self._t.request("GET", f"/v2/jobs/{_q(id)}")["data"]
+
+    show = find
+
+    def wait(self, id: str, timeout: float | None = None) -> dict:
+        """Wartet, bis der Job finished oder error ist. Wirft bei error nicht."""
+        return _poll(lambda: self.find(id), _job_done, timeout, self._poll)
+
+    def all(self, params: dict | None = None) -> list:
+        return self._t.request("GET", "/v2/jobs", query=params)["data"]
+
+    def delete(self, id: str) -> bool:
+        self._t.request("DELETE", f"/v2/jobs/{_q(id)}")
+        return True
+
+    @staticmethod
+    def get_export_urls(job: dict) -> list:
+        """Alle Dateien der fertigen export/url-Tasks."""
+        return [f for t in job.get("tasks") or [] if t.get("operation") == "export/url" and t.get("status") == "finished"
+                for f in ((t.get("result") or {}).get("files") or [])]
+
+
+class Tasks:
+    def __init__(self, t: Transport, poll: float):
+        self._t, self._poll = t, poll
+
+    def find(self, id: str, include: str | None = None) -> dict:
+        return self._t.request("GET", f"/v2/tasks/{_q(id)}", query={"include": include})["data"]
+
+    show = find
+
+    def wait(self, id: str, timeout: float | None = None) -> dict:
+        return _poll(lambda: self.find(id), _job_done, timeout, self._poll)
+
+    def all(self, params: dict | None = None) -> list:
+        return self._t.request("GET", "/v2/tasks", query=params)["data"]
+
+    def cancel(self, id: str) -> bool:
+        data = self._t.request("POST", f"/v2/tasks/{_q(id)}/cancel", retry=True)["data"]
+        return data.get("status") == "error"
+
+    def retry(self, id: str) -> dict:
+        return self._t.request("POST", f"/v2/tasks/{_q(id)}/retry", retry=False)["data"]
+
+    def upload(self, file_name: Any, task: dict, filename: str | None = None) -> bool:
+        """Datei für einen import/upload-Task hochladen. file_name: Pfad, Bytes oder Datei-Objekt.
+
+        Nutzt den direkten Upload (result.upload: PUT, danach upload-complete), sonst das Formular (result.form).
+        Gibt True zurück, wenn der Task danach fertig ist.
+        """
+        if task.get("operation") != "import/upload":
+            raise SwitchfileError("INVALID_TASK", f"Task {task.get('name') or task.get('id')} is not an import/upload task.")
+        file = PreparedFile(file_name, filename)
+        result = task.get("result") or {}
+        direct, form = result.get("upload"), result.get("form")
+        if direct and direct.get("url"):
+            headers = {"Content-Type": "application/octet-stream", **safe_upload_headers(direct.get("headers")),
+                       "Content-Length": str(file.size)}
+            with file.open() as fh:
+                self._t.send_signed("PUT", direct["url"], lambda: (fh, headers))
+            body = {"filename": file.filename} if file.filename else {}
+            data = self._t.request("POST", f"/v2/tasks/{_q(task['id'])}/upload-complete", json_body=body, retry=True)["data"]
+            return data.get("status") == "finished"
+        if form and form.get("url"):
+            fields = [(k, str(v)) for k, v in (form.get("parameters") or {}).items()]
+
+            def body():
+                mp = MultipartBody(fields, "file", file, file.filename or "file")
+                return mp, {"Content-Type": mp.content_type, "Content-Length": str(mp.length)}
+
+            res = self._t.send_signed("POST", form["url"], body)
+            data = (res or {}).get("data") if isinstance(res, dict) else None
+            return (data or self.find(task["id"])).get("status") == "finished"
+        raise SwitchfileError("INVALID_TASK", f"Task {task.get('name') or task.get('id')} has no upload URL. "
+                                              "Pass the task from the job returned by Job.create().")
+
+
+class Users:
+    def __init__(self, t: Transport):
+        self._t = t
+
+    def me(self) -> dict:
+        return self._t.request("GET", "/v2/users/me")["data"]
+
+
+class Webhooks:
+    @staticmethod
+    def verify(payload: str | bytes, signature: str | None, signing_secret: str) -> bool:
+        """True, wenn die Signatur (Header CloudConvert-Signature bzw. Switchfile-Signature) zum rohen Body passt."""
+        if not signature or not signing_secret:
+            return False
+        raw = payload.encode() if isinstance(payload, str) else bytes(payload)
+        expected = hmac.new(signing_secret.encode(), raw, hashlib.sha256).hexdigest()
+        # Als Bytes vergleichen: compare_digest wirft bei str mit Nicht-ASCII-Zeichen TypeError statt False.
+        given = signature.strip().lower().encode("utf-8", "replace")
+        return hmac.compare_digest(expected.encode("ascii"), given)
+
+    @classmethod
+    def construct_event(cls, payload: str | bytes, signature: str | None, signing_secret: str) -> dict:
+        """Signatur prüfen und das Ereignis parsen. Wirft SwitchfileError INVALID_SIGNATURE bzw. INVALID_PAYLOAD."""
+        if not cls.verify(payload, signature, signing_secret):
+            raise SwitchfileError("INVALID_SIGNATURE", "The webhook signature does not match the payload.")
+        try:
+            event = json.loads(payload)
+        except ValueError as e:
+            raise SwitchfileError("INVALID_PAYLOAD", "The webhook payload is not valid JSON.") from e
+        if not isinstance(event, dict) or not isinstance(event.get("event"), str):
+            raise SwitchfileError("INVALID_PAYLOAD", "The webhook payload has no event name.")
+        return event
+
+
+class Conversions:
+    def __init__(self, t: Transport, poll: float):
+        self._t, self._poll = t, poll
+
+    def find(self, id: str, wait: float | None = None) -> dict:
+        """Umwandlung lesen. wait: bis zu so vielen Sekunden auf das Ende warten (höchstens 30)."""
+        w = min(_WAIT_SECONDS, int(wait + 0.999)) if wait and wait > 0 else None
+        return self._t.request("GET", f"/v1/conversions/{_q(id)}", query={"wait": w},
+                               timeout=self._t.timeout + (w or 0))
+
+    show = find
+
+    def list(self, ids: list[str]) -> list:
+        return self._t.request("GET", "/v1/conversions", query={"ids": ",".join(ids)})["data"]
+
+    def wait(self, id: str, timeout: float | None = None) -> dict:
+        """Wartet, bis die Umwandlung fertig ist. Wirft ConversionFailedError, wenn sie scheitert."""
+        c = _poll(lambda: self.find(id, wait=_WAIT_SECONDS), _conv_done, timeout, self._poll)
+        return _assert_finished(c)
+
+    def delete(self, id: str) -> bool:
+        self._t.request("DELETE", f"/v1/conversions/{_q(id)}")
+        return True
+
+
+class Account:
+    def __init__(self, t: Transport):
+        self._t = t
+
+    def get(self) -> dict:
+        return self._t.request("GET", "/v1/account")
+
+    def update(self, webhook_url: Any = _UNSET, *, no_store: bool | None = None) -> dict:
+        """Webhook-URL setzen (None entfernt sie) und/oder no_store=True für „immer ohne Speicherung“."""
+        body: dict[str, Any] = {}
+        if webhook_url is not _UNSET:
+            body["webhook_url"] = webhook_url
+        if no_store is not None:
+            body["no_store"] = bool(no_store)
+        if not body:
+            raise SwitchfileError("INVALID_DATA", "Pass webhook_url or no_store.")
+        return self._t.request("PATCH", "/v1/account", json_body=body, retry=True)
+
+
+@dataclass
+class NoStoreResult:
+    """Ergebnis einer Umwandlung ohne Speicherung. Gespeichert ist nichts davon, nur der Eintrag im Nutzungsverlauf."""
+
+    #: Die Datei; mehrere Ergebnisse kommen als ein ZIP.
+    data: bytes
+    filename: str | None
+    content_type: str
+    #: ID des Eintrags im Nutzungsverlauf (GET /v1/conversions/{id} kennt sie nicht).
+    conversion_id: str | None
+    credits: int | None
+
+
+def _assert_finished(c: dict) -> dict:
+    if c.get("status") == "failed":
+        err = c.get("error") or {}
+        raise ConversionFailedError(err.get("code") or "CONVERSION_FAILED", err.get("message") or "The conversion failed.", c)
+    return c
+
+
+class Client:
+    """switchfile-Client.
+
+    ``Client(api_key=None, sandbox=False, base_url=None, ...)``. Ohne api_key gilt SWITCHFILE_API_KEY, ohne base_url
+    SWITCHFILE_API_URL bzw. https://api.switchfile.io. Mit ``sandbox=True`` werden Live-Keys abgelehnt (bei
+    switchfile entscheidet der Key: ``sf_test_…`` kostet keine Credits).
+    """
+
+    def __init__(self, api_key: str | None = None, sandbox: bool = False, base_url: str | None = None,
+                 sandbox_base_url: str | None = None, timeout: float = 60.0, max_retries: int = 3,
+                 poll_interval: float = 1.0, user_agent: str | None = None, **_ignored: Any):
+        self.api_key = (api_key if api_key is not None else os.environ.get("SWITCHFILE_API_KEY", "")).strip()
+        self.sandbox = bool(sandbox)
+        base = base_url or os.environ.get("SWITCHFILE_API_URL") or DEFAULT_BASE_URL
+        self.base_url = _normalize_base(sandbox_base_url or base if self.sandbox else base)
+        if self.sandbox and _LIVE_KEY.match(self.api_key):
+            raise SwitchfileError("SANDBOX_KEY_REQUIRED",
+                                  "Sandbox mode needs a sandbox key (sf_test_...). Create one in the dashboard under API keys.")
+        ua = f"switchfile-python/{__version__}" + (f" {user_agent}" if user_agent else "")
+        self._t = Transport(self.api_key, self.base_url, timeout, max_retries, ua)
+        self.jobs = Jobs(self._t, poll_interval)
+        self.tasks = Tasks(self._t, poll_interval)
+        self.users = Users(self._t)
+        self.webhooks = Webhooks()
+        self.conversions = Conversions(self._t, poll_interval)
+        self.account = Account(self._t)
+
+    # ---------- /v1 ----------
+    def convert(self, file: Any, to: str | None = None, options: dict | None = None, *, filename: str | None = None,
+                input_format: str | None = None, webhook_url: str | None = None, wait: bool = True,
+                timeout: float = 1800, idempotency_key: str | None = None, multipart_limit: int = MULTIPART_LIMIT,
+                preset: str | None = None) -> dict:
+        """Datei umwandeln und (Standard) bis zum Ende warten.
+
+        file: Pfad, Bytes, Datei-Objekt, eine http(s)-URL als String oder {"url": ...}, {"upload_id": ...},
+        {"from": conversion_id}. preset: ID oder Name eines Presets aus dem Dashboard (setzt Zielformat und
+        Einstellungen; to darf dann fehlen, options überschreiben einzelne Werte). Wirft ConversionFailedError, wenn die
+        Umwandlung scheitert.
+        """
+        if (not to or not isinstance(to, str)) and not preset:
+            raise SwitchfileError("INVALID_DATA", "The target format (to) is missing. Pass a format or a preset.")
+        key = idempotency_key or str(uuid.uuid4())
+        fields: dict[str, Any] = {}
+        if to:
+            fields["to"] = to
+        if preset:
+            fields["preset"] = preset
+        if options:
+            fields["options"] = options
+        if input_format:
+            fields["input_format"] = input_format
+        if webhook_url:
+            fields["webhook_url"] = webhook_url
+        query = {"wait": _WAIT_SECONDS if wait else None}
+        req_timeout = self._t.timeout + (_WAIT_SECONDS if wait else 0)
+
+        src = _json_source(file)
+        if src is not None:
+            body = {**src, **fields, **({"filename": filename} if filename else {})}
+            conv = self._t.request("POST", "/v1/convert", json_body=body, query=query, idempotency_key=key, timeout=req_timeout)
+        else:
+            pf = PreparedFile(file, filename)
+            name = pf.filename
+            if pf.size <= multipart_limit:
+                form = [("to", to)] if to else []
+                if preset:
+                    form.append(("preset", preset))
+                if options:
+                    form.append(("options", json.dumps(options)))
+                if input_format:
+                    form.append(("input_format", input_format))
+                if webhook_url:
+                    form.append(("webhook_url", webhook_url))
+                if name:
+                    form.append(("filename", name))
+
+                def body_factory():
+                    mp = MultipartBody(form, "file", pf, name or "file")
+                    return mp, {"Content-Type": mp.content_type, "Content-Length": str(mp.length)}
+
+                conv = self._t.request("POST", "/v1/convert", body_factory=body_factory, query=query,
+                                       idempotency_key=key, timeout=max(req_timeout, 1800))
+            else:
+                up = self._t.request("POST", "/v1/uploads", json_body={**({"filename": name} if name else {}), "size": pf.size},
+                                     idempotency_key=f"{key}:upload")
+                headers = {"Content-Type": "application/octet-stream", **safe_upload_headers(up.get("headers")),
+                           "Content-Length": str(pf.size)}
+                with pf.open() as fh:
+                    self._t.send_signed("PUT", up["url"], lambda: (fh, headers))
+                body = {"upload_id": up["upload_id"], **fields, **({"filename": name} if name else {})}
+                conv = self._t.request("POST", "/v1/convert", json_body=body, query=query, idempotency_key=key, timeout=req_timeout)
+        if not wait:
+            return conv
+        if _conv_done(conv.get("status")):
+            return _assert_finished(conv)
+        return self.conversions.wait(conv["id"], timeout=timeout)
+
+    def convert_without_storage(self, file: Any, to: str | None = None, options: dict | None = None, *,
+                                filename: str | None = None, input_format: str | None = None,
+                                preset: str | None = None, timeout: float | None = None) -> NoStoreResult:
+        """Datei ohne Speicherung umwandeln (POST /v1/convert?store=false): Datei im Request, Ergebnis in der Antwort,
+        weder Eingabe noch Ergebnis bleiben bei switchfile. file: Pfad, Bytes oder Datei-Objekt bis 50 MB. Ohne
+        Idempotency-Key, weil die API das Ergebnis nicht behält; wiederholt wird nur, wenn sie nichts umgewandelt hat.
+        timeout: Standard NO_STORE_TIMEOUT (390 s) oder das längere Zeitlimit des Clients."""
+        if (not to or not isinstance(to, str)) and not preset:
+            raise SwitchfileError("INVALID_DATA", "The target format (to) is missing. Pass a format or a preset.")
+        if isinstance(file, dict) or (isinstance(file, str) and re.match(r"^https?://", file, re.I)):
+            raise SwitchfileError("INVALID_DATA", "Without storage, send the file itself. A URL or an ID needs storage.")
+        pf = PreparedFile(file, filename)
+        if pf.size > NO_STORE_LIMIT:
+            raise SwitchfileError("FILE_TOO_LARGE", f"Without storage, files can be at most {NO_STORE_LIMIT // 1024 // 1024} MB.")
+        name = pf.filename
+        form = [("to", to)] if to else []
+        if preset:
+            form.append(("preset", preset))
+        if options:
+            form.append(("options", json.dumps(options)))
+        if input_format:
+            form.append(("input_format", input_format))
+        if name:
+            form.append(("filename", name))
+
+        def body_factory():
+            mp = MultipartBody(form, "file", pf, name or "file")
+            return mp, {"Content-Type": mp.content_type, "Content-Length": str(mp.length)}
+
+        data, headers = self._t.request("POST", "/v1/convert", body_factory=body_factory, query={"store": "false"},
+                                        headers={"Switchfile-Store": "false"}, binary=True,
+                                        timeout=timeout or max(self._t.timeout, NO_STORE_TIMEOUT))
+        credits = headers.get("X-Credits")
+        return NoStoreResult(
+            data=data,
+            filename=_filename_of(headers.get("Content-Disposition")),
+            content_type=headers.get("Content-Type") or "application/octet-stream",
+            conversion_id=headers.get("X-Conversion-Id"),
+            credits=int(credits) if credits and credits.isdigit() else None,
+        )
+
+    def formats(self, input: str | None = None) -> dict:
+        """Alle Formate mit Zielen und Vorschlägen (ohne Key)."""
+        return self._t.request("GET", "/v1/formats", query={"input": input}, auth=False)
+
+    def download(self, url: Any = None, filename: str | os.PathLike | None = None) -> bytes | str:
+        """Ergebnis laden: URL, Datei aus result.files oder fertige Umwandlung (erste Datei). Mit filename in die Datei
+        schreiben (Rückgabe: Pfad), sonst kommen die Bytes zurück."""
+        if isinstance(url, dict):
+            url = url.get("download_url") or url.get("url")
+        if not url:
+            raise SwitchfileError("NO_FILE", "Nothing to download: the conversion has no result file yet.")
+        return self._t.download(url, filename)
+
+
+def _filename_of(header: str | None) -> str | None:
+    """Dateiname aus Content-Disposition (filename* vor filename)."""
+    if not header:
+        return None
+    star = re.search(r"filename\*=UTF-8''([^;]+)", header, re.I)
+    if star:
+        try:
+            return urllib.parse.unquote(star.group(1).strip(), errors="strict")
+        except UnicodeDecodeError:
+            pass
+    plain = re.search(r'filename="([^"]*)"', header, re.I) or re.search(r"filename=([^;]+)", header, re.I)
+    return plain.group(1).strip() if plain else None
+
+
+def _json_source(file: Any) -> dict | None:
+    if isinstance(file, str) and re.match(r"^https?://", file, re.I):
+        return {"url": file}
+    if isinstance(file, dict):
+        for k in ("url", "upload_id", "from"):
+            if isinstance(file.get(k), str):
+                return {k: file[k]}
+        raise SwitchfileError("INVALID_SOURCE", "Pass {'url': ...}, {'upload_id': ...} or {'from': ...}.")
+    return None
+
+
+def _normalize_base(raw: str) -> str:
+    p = urllib.parse.urlsplit(raw)
+    if p.scheme not in ("http", "https") or not p.netloc:
+        raise SwitchfileError("INVALID_BASE_URL", f"Invalid base URL: {raw}")
+    return raw.rstrip("/")

switchfile/errors.py

@@ -0,0 +1,59 @@
+"""Fehler des SDKs. /v1 antwortet mit application/problem+json (code, detail), /v2 im CloudConvert-Format
+(code, message). Beides wird zu SwitchfileError mit stabilem ``code``."""
+from __future__ import annotations
+
+from typing import Any
+
+
+class SwitchfileError(Exception):
+    """Fehler der API oder des Clients.
+
+    Attribute: ``code`` (z. B. INVALID_DATA, UNAUTHENTICATED, NOT_FOUND, RATE_LIMIT_EXCEEDED, NETWORK_ERROR),
+    ``status`` (HTTP-Status oder None), ``errors`` (Fehler je Feld), ``retry_after`` (Sekunden), ``body``.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        status: int | None = None,
+        errors: dict[str, list[str]] | None = None,
+        retry_after: float | None = None,
+        body: Any = None,
+    ):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.errors = errors
+        self.retry_after = retry_after
+        self.body = body
+
+    def __repr__(self) -> str:
+        return f"SwitchfileError(code={self.code!r}, status={self.status!r}, message={self.message!r})"
+
+
+class ConversionFailedError(SwitchfileError):
+    """Eine Umwandlung (/v1) ist gescheitert. ``conversion`` enthält das ganze Objekt."""
+
+    def __init__(self, code: str, message: str, conversion: dict):
+        super().__init__(code, message, body=conversion)
+        self.conversion = conversion
+
+
+_FALLBACK = {401: "UNAUTHENTICATED", 403: "FORBIDDEN", 404: "NOT_FOUND", 413: "FILE_TOO_LARGE", 422: "INVALID_DATA",
+             429: "RATE_LIMIT_EXCEEDED"}
+
+
+def error_from_response(status: int, body: Any, retry_after: str | None) -> SwitchfileError:
+    b = body if isinstance(body, dict) else {}
+    code = b.get("code") if isinstance(b.get("code"), str) and b.get("code") else (
+        "INTERNAL_ERROR" if status >= 500 else _FALLBACK.get(status, "HTTP_ERROR"))
+    message = next((b[k] for k in ("detail", "message", "title") if isinstance(b.get(k), str) and b.get(k)),
+                   f"The switchfile API answered with HTTP {status}.")
+    errors = b.get("errors") if isinstance(b.get("errors"), dict) else None
+    try:
+        ra = float(retry_after) if retry_after is not None else None
+    except ValueError:
+        ra = None
+    return SwitchfileError(code, message, status=status, errors=errors, retry_after=ra, body=body)

switchfile/version.py

@@ -0,0 +1,2 @@
+# Gleich der Version in pyproject.toml (tests/test_client.py prüft das).
+__version__ = "0.1.0"

switchfile_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: switchfile-sdk
+Version: 0.1.0
+Summary: Python SDK for the switchfile file conversion API. Drop-in replacement for the CloudConvert v2 SDK, plus a one-call convert() helper.
+Author-email: "Aura UG (haftungsbeschränkt)" <hello@switchfile.io>
+License-Expression: MIT
+Project-URL: Homepage, https://switchfile.io/developers#sdks
+Project-URL: Documentation, https://switchfile.io/developers
+Keywords: switchfile,file conversion,converter,cloudconvert,api,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# switchfile for Python
+
+The official Python SDK for the [switchfile](https://switchfile.io) file conversion API.
+
+- The same functions and return values as the CloudConvert Python SDK (`Job.create`, `Job.wait`, `Task.upload`,
+  `Webhook.verify`, `download` and more), so existing code keeps working after you change the import.
+- `convert()` for the simple API: one call with a file and a target format, and you get the finished conversion back.
+- No dependencies. Python 3.10 or newer.
+
+```bash
+pip install switchfile-sdk
+```
+
+## Moving from CloudConvert
+
+Change the import and the configuration. Everything else stays the same.
+
+```diff
+- import cloudconvert
+- cloudconvert.configure(api_key=os.environ["CLOUDCONVERT_API_KEY"], sandbox=False)
++ import switchfile as cloudconvert
++ cloudconvert.configure(api_key=os.environ["SWITCHFILE_API_KEY"], sandbox=False)
+```
+
+Create an API key in the [dashboard](https://switchfile.io/dashboard/keys). Keys starting with `sf_test_` are
+sandbox keys: they never use credits.
+
+What is different:
+
+| CloudConvert | switchfile |
+|---|---|
+| `sandbox=True` uses a separate sandbox server | The key decides: `sf_test_` keys are sandbox keys. `sandbox=True` refuses live keys, so tests cannot use credits by mistake |
+| `cloudconvert.default()` reads `CLOUDCONVERT_API_KEY` | `switchfile.default()` reads `SWITCHFILE_API_KEY`, `SWITCHFILE_API_URL` and `SWITCHFILE_SANDBOX` |
+| Operations such as `optimize`, `merge`, `capture-website`, `import/s3` | Tasks: `import/url`, `import/upload`, `import/base64`, `convert`, `export/url` |
+| `SignedUrl.sign()` | Not available |
+| `Task.create()`, `Task.delete()` | Not available; create tasks inside a job with `Job.create()` |
+| Errors from `cloudconvert.exceptions` | `switchfile.SwitchfileError` with `code`, `status` and `errors` |
+
+## Convert a file in one call
+
+```python
+import switchfile
+
+switchfile.configure(api_key=os.environ["SWITCHFILE_API_KEY"])
+
+conversion = switchfile.convert("talk.mkv", "mp4")
+switchfile.download(conversion, "talk.mp4")
+```
+
+`convert(file, to, options)` takes a file path, `bytes`, an open file, a public URL as a string
+(`"https://..."`) or `{"url": ...}`, `{"upload_id": ...}` for a file sent through `/v1/uploads`, or
+`{"from": conversion_id}` to convert an earlier input again.
+
+Files up to 50 MB are sent with the request, larger files (up to your plan's limit) go through an upload URL and are
+read from disk while they upload. The call waits until the conversion is done and raises `ConversionFailedError` if
+it fails.
+
+```python
+conversion = switchfile.convert(
+    data,                                   # bytes
+    "jpg",
+    {"quality": 80},                        # settings for the conversion
+    filename="photo.heic",                  # name of the input (needed for bytes)
+    webhook_url="https://example.com/hooks/switchfile",
+    wait=True,                              # False: return right away with status queued
+    timeout=600,                            # stop waiting after 10 minutes
+)
+
+for f in conversion["result"]["files"]:     # e.g. one image per page
+    switchfile.download(f["url"], f["filename"])
+data = switchfile.download(conversion)       # bytes without a file name
+```
+
+A preset from your dashboard sets the target format and its settings. Leave out `to` and pass the ID or name;
+settings in `options` override single values of the preset:
+
+```python
+switchfile.convert("photo.heic", preset="Web images")
+switchfile.convert("photo.heic", options={"quality": 90}, preset="Web images")
+```
+
+### Without storage
+
+`convert_without_storage` sends the file with the request and gets the result back in the response. switchfile keeps
+neither of them, only an entry in the usage history without the file name. Files can be up to 50 MB, several result
+files come back as one ZIP.
+
+```python
+result = switchfile.convert_without_storage("invoice.docx", "pdf")
+with open(result.filename or "invoice.pdf", "wb") as f:
+    f.write(result.data)
+result.conversion_id   # the entry in the usage history
+result.credits         # credits used
+```
+
+For jobs, pass `"store": False` to `Job.create` with three tasks, one of each: `import/base64`, `convert` and
+`export/url`. The job comes back finished, and each file of the export task has its bytes as base64 in `content`.
+`client.account.update(no_store=True)` makes the account refuse every request that would store a file. Keep using
+`convert_without_storage` and `"store": False` after that: the other calls expect a stored conversion and are rejected.
+Details are in the [guide](https://switchfile.io/docs/no-store).
+
+More calls for the simple API:
+
+```python
+switchfile.Conversion.find(id)              # status and result
+switchfile.Conversion.wait(id)              # until finished
+switchfile.Conversion.list([id1, id2])      # up to 50 at once
+switchfile.Conversion.delete(id)            # delete input and result now
+switchfile.formats("heic")                  # targets for one input format (no key needed)
+switchfile.Account.get()                    # credits, free quota, webhook signing secret
+switchfile.Account.update("https://example.com/hooks/switchfile")
+```
+
+## Jobs and tasks
+
+```python
+job = switchfile.Job.create(payload={
+    "tasks": {
+        "import-my-file": {"operation": "import/url", "url": "https://example.com/report.docx"},
+        "convert-my-file": {"operation": "convert", "input": "import-my-file", "output_format": "pdf"},
+        "export-my-file": {"operation": "export/url", "input": "convert-my-file"},
+    },
+    "tag": "order-1234",
+})
+
+job = switchfile.Job.wait(id=job["id"])
+for file in switchfile.Job.get_export_urls(job):
+    switchfile.download(filename=file["filename"], url=file["url"])
+```
+
+`Job.wait()` returns the job when it is `finished` or `error`; it does not raise for a failed job. Check
+`job["status"]` and the `code` and `message` of each task.
+
+### Uploading files
+
+```python
+job = switchfile.Job.create(payload={
+    "tasks": {
+        "upload-my-file": {"operation": "import/upload"},
+        "convert-my-file": {"operation": "convert", "input": "upload-my-file", "output_format": "pdf"},
+        "export-my-file": {"operation": "export/url", "input": "convert-my-file"},
+    }
+})
+
+upload_task = [t for t in job["tasks"] if t["name"] == "upload-my-file"][0]
+switchfile.Task.upload(file_name="path/to/report.docx", task=upload_task)
+```
+
+`Task.upload()` also takes `bytes` or an open file (pass `filename=` for bytes).
+
+### All functions
+
+| Function | Returns |
+|---|---|
+| `Job.create(payload)` | job `dict` |
+| `Job.find(id)`, `Job.show(id)` | job `dict` |
+| `Job.wait(id, timeout=None)` | job `dict` once it is `finished` or `error` |
+| `Job.all(params)` | `list` of jobs, filters such as `{"filter[tag]": "..."}` |
+| `Job.delete(id)` | `True` |
+| `Job.get_export_urls(job)` | files of all finished `export/url` tasks |
+| `Task.find(id)`, `Task.show(id)` | task `dict` |
+| `Task.wait(id)` | task `dict` |
+| `Task.all(params)` | `list` of tasks |
+| `Task.cancel(id)` | `True` if the task is cancelled |
+| `Task.retry(id)` | the new task |
+| `Task.upload(file_name, task)` | `True` if the upload finished the task |
+| `User.me()` | account with credits and today's free quota |
+| `Webhook.verify(payload, signature, secret)` | `bool` |
+| `Webhook.construct_event(payload, signature, secret)` | the parsed event, raises if the signature is wrong |
+| `download(url, filename)` | the path, or `bytes` without a file name |
+
+### Several keys
+
+The functions above use one client for the whole program. For several keys or servers, create clients:
+
+```python
+client = switchfile.Client(api_key="sf_live_...", timeout=60, max_retries=3)
+job = client.jobs.create({...})
+client.tasks.upload("report.docx", upload_task)
+conversion = client.convert("report.docx", "pdf")
+```
+
+## Webhooks
+
+```python
+from flask import Flask, request
+
+app = Flask(__name__)
+
+@app.post("/hooks/switchfile")
+def hook():
+    signature = request.headers.get("CloudConvert-Signature") or request.headers.get("Switchfile-Signature")
+    if not switchfile.Webhook.verify(request.get_data(), signature, os.environ["SWITCHFILE_WEBHOOK_SECRET"]):
+        return "", 400
+    event = request.get_json()
+    # job.finished / job.failed: event["job"]
+    # conversion.finished / conversion.failed: event["data"]
+    return "", 200
+```
+
+Jobs send `job.finished` and `job.failed` with the header `CloudConvert-Signature`. Conversions from `convert()` send
+`conversion.finished` and `conversion.failed` with `Switchfile-Signature`. Both are signed the same way. The signing
+secret is `webhook_signing_secret` from `switchfile.Account.get()` and in the dashboard.
+
+## Settings
+
+```python
+switchfile.configure(
+    api_key="sf_test_...",                  # default: SWITCHFILE_API_KEY
+    base_url="https://api.switchfile.io",   # default: SWITCHFILE_API_URL or https://api.switchfile.io
+    sandbox=True,                           # only accept sandbox keys (sf_test_)
+    timeout=60,                             # per request, in seconds
+    max_retries=3,                          # network errors, 429 and 5xx
+    user_agent="my-app/1.0",                # added to the User-Agent header
+)
+```
+
+Requests are repeated after network errors, `429 RATE_LIMIT_EXCEEDED` (after `Retry-After`) and server errors.
+`convert()` sends an `Idempotency-Key`, so a repeated request never creates a second conversion.
+
+## Errors
+
+Every error is a `switchfile.SwitchfileError` with a stable `code` (for example `UNAUTHENTICATED`, `INVALID_DATA`,
+`UNSUPPORTED_PAIR`, `CREDITS_EXCEEDED`, `RATE_LIMIT_EXCEEDED`), the HTTP `status` and, for `INVALID_DATA`, `errors`
+per field. A failed conversion from `convert()` raises `switchfile.ConversionFailedError` with the conversion in
+`conversion`.
+
+```python
+try:
+    switchfile.convert("notes.txt", "mp4")
+except switchfile.ConversionFailedError as e:
+    print("failed:", e.code, e.conversion["id"])
+except switchfile.SwitchfileError as e:
+    print(e.status, e.code, e.message)
+```
+
+## Links
+
+- [API documentation](https://switchfile.io/developers)
+- [Supported formats](https://switchfile.io/convert)
+
+License: MIT, Aura UG (haftungsbeschränkt).

switchfile_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+switchfile/__init__.py,sha256=3AczTZcCrHv8ylL7i2G_ZPxuz9WcL5uh_lOvGCOZAsU,5587
+switchfile/_http.py,sha256=XpMymdstFxEv6t8V9FCveMKr1-UOlt8ODsy7lqoPWYU,14428
+switchfile/client.py,sha256=GGwblbTftSBVbxiW3yYTHli_bES2bAzBxynEHz0_SDs,20953
+switchfile/errors.py,sha256=r18diL07b_x0MgRgwwM7I4gdyKdHCqVXxHYEPwBHBxs,2370
+switchfile/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+switchfile/version.py,sha256=2TCbceqWBqs1r8sSPqT5Nh4zssuVNt_IRWnYhjwBH8U,96
+switchfile_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=f8v80ahpE8MC3QdDx4mCs_hyx1t0SP2_lIqN-kwRxaI,1086
+switchfile_sdk-0.1.0.dist-info/METADATA,sha256=jN0hyMZ_x6-HtihBywtoM01LEU2ElulAmvoIEXG-k2I,11189
+switchfile_sdk-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+switchfile_sdk-0.1.0.dist-info/top_level.txt,sha256=LN05KxK9SPIjXw8WvaGIYG1ELsAtVueorHJlfB7U8ws,11
+switchfile_sdk-0.1.0.dist-info/RECORD,,

switchfile_sdk-0.1.0.dist-info/WHEEL

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

switchfile_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aura UG (haftungsbeschränkt)
+
+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.

switchfile_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+switchfile