runconvert 0.1.0__tar.gz

runconvert-0.1.0/LICENSE

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

runconvert-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: runconvert
+Version: 0.1.0
+Summary: Official RunConvert SDK for Python: convert files between 240+ formats
+License-Expression: MIT
+Project-URL: Homepage, https://www.runconvert.com
+Project-URL: Documentation, https://www.runconvert.com/docs
+Project-URL: Source, https://github.com/runconvert/runconvert-python
+Keywords: runconvert,file converter,convert,pdf,video,image,api,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# RunConvert SDK for Python
+
+Convert files between 240+ formats (3,000+ conversions) with the [RunConvert API](https://www.runconvert.com/docs):
+documents, images, video, audio, ebooks, archives, fonts and CAD. Python 3.10+, no dependencies.
+
+```bash
+pip install runconvert
+```
+
+```python
+from runconvert import RunConvert
+
+rc = RunConvert()  # reads RUNCONVERT_API_KEY
+
+# One call: upload, convert, wait, download.
+result = rc.convert("report.docx", "pdf", out_dir="out")
+print(result.saved)  # ['out/report.pdf']
+```
+
+Get an API key in **Dashboard → API Keys** on [runconvert.com](https://www.runconvert.com). Keep keys on the server.
+
+## Convert
+
+```python
+# From a URL (imported by RunConvert, nothing to upload)
+rc.convert("https://example.com/talk.mp4", "mp3", options={"audioBitrate": "192k"})
+
+# From bytes or a file object: give a filename (or from_)
+rc.convert(data, "jpg", filename="photo.heic", out_dir="out")
+
+# Progress and a time limit (seconds)
+rc.convert("movie.mov", "mp4", out_dir="out", on_update=lambda job: print(job["status"]), timeout=600)
+```
+
+`convert` returns `ConvertResult(job, files, saved)`. Options for a conversion come from
+`rc.operations.for_pair("mp4", "mp3")`.
+
+## Jobs with your own tasks
+
+```python
+from runconvert import Jobs
+
+# Merge three PDFs into one
+job = rc.jobs.create({
+    "a": {"operation": "import/url", "source_url": "https://example.com/cover.pdf"},
+    "b": {"operation": "import/url", "source_url": "https://example.com/body.pdf"},
+    "merge": {"operation": "convert", "input": ["a", "b"], "input_format": "pdf", "output_format": "pdf"},
+    "export": {"operation": "export/url", "input": "merge"},
+}, tag="merge")
+done = rc.jobs.wait(job["id"])
+for f in Jobs.exported_files(done):
+    rc.files.download(f, "out")
+
+# Upload your own file
+job = rc.jobs.create({
+    "upload": {"operation": "import/direct/upload"},
+    "convert": {"operation": "convert", "input": "upload", "input_format": "png", "output_format": "webp", "image_quality": 80},
+    "export": {"operation": "export/url", "input": "convert"},
+})
+upload_task = next(t for t in job["tasks"] if t["name"] == "upload")
+rc.files.upload(upload_task, "image.png")
+```
+
+| Method | What it does |
+|---|---|
+| `rc.jobs.create(tasks, tag=, metadata=)` | Create a job (returned with its tasks) |
+| `rc.jobs.get(id)` / `rc.jobs.list(status=, tag=, page=, per_page=)` | A job / one page `{"data", "meta"}` |
+| `rc.jobs.all(...)` | Every job: `for job in rc.jobs.all()` |
+| `rc.jobs.wait(id, timeout=, on_update=, raise_on_error=)` | Poll until `finished` or `error` |
+| `rc.jobs.cancel(id)` / `rc.jobs.delete(id)` | Stop pending tasks / delete |
+| `rc.files.upload(task, file)` / `rc.files.download(file, dir)` | Upload to a task / save a result |
+| `rc.operations.list(category=)` / `for_input("mp4")` / `for_pair("mp4", "mp3")` | Formats, targets, engines (no key needed) |
+| `rc.me()` | Account, team and credit balance |
+
+## Webhooks
+
+```python
+from runconvert import construct_event
+
+@app.post("/webhooks/runconvert")  # Flask
+def runconvert_webhook():
+    try:
+        event = construct_event(request.get_data(), request.headers.get("X-RunConvert-Signature"), os.environ["RUNCONVERT_WEBHOOK_SECRET"])
+    except ValueError:
+        return "", 400
+    if event["event"] == "job.finished":
+        print("done", event["job"]["id"])
+    return "", 200
+```
+
+## Errors
+
+| Error | When |
+|---|---|
+| `RunConvertError` | The API said no: `.status`, `.code` (e.g. `BILLING_INSUFFICIENT_CREDITS`), `.message` |
+| `JobFailedError` | The job ended in `error`; `.task` has `code`, `reason`, `message` |
+| `WaitTimeoutError` | `wait` ran past its `timeout` |
+
+Network errors, `429` and `5xx` are retried twice with backoff (`max_retries`). Creating a job is only
+retried when the request never reached the API, so a job is never created twice.
+
+## Development
+
+```bash
+PYTHONPATH=src python3 -m unittest tests.test_unit                          # no network
+RUNCONVERT_API_KEY=rc_live_… PYTHONPATH=src python3 -m unittest tests.test_live  # real API, about 2 credits
+```
+
+## License
+
+MIT

runconvert-0.1.0/README.md

@@ -0,0 +1,111 @@
+# RunConvert SDK for Python
+
+Convert files between 240+ formats (3,000+ conversions) with the [RunConvert API](https://www.runconvert.com/docs):
+documents, images, video, audio, ebooks, archives, fonts and CAD. Python 3.10+, no dependencies.
+
+```bash
+pip install runconvert
+```
+
+```python
+from runconvert import RunConvert
+
+rc = RunConvert()  # reads RUNCONVERT_API_KEY
+
+# One call: upload, convert, wait, download.
+result = rc.convert("report.docx", "pdf", out_dir="out")
+print(result.saved)  # ['out/report.pdf']
+```
+
+Get an API key in **Dashboard → API Keys** on [runconvert.com](https://www.runconvert.com). Keep keys on the server.
+
+## Convert
+
+```python
+# From a URL (imported by RunConvert, nothing to upload)
+rc.convert("https://example.com/talk.mp4", "mp3", options={"audioBitrate": "192k"})
+
+# From bytes or a file object: give a filename (or from_)
+rc.convert(data, "jpg", filename="photo.heic", out_dir="out")
+
+# Progress and a time limit (seconds)
+rc.convert("movie.mov", "mp4", out_dir="out", on_update=lambda job: print(job["status"]), timeout=600)
+```
+
+`convert` returns `ConvertResult(job, files, saved)`. Options for a conversion come from
+`rc.operations.for_pair("mp4", "mp3")`.
+
+## Jobs with your own tasks
+
+```python
+from runconvert import Jobs
+
+# Merge three PDFs into one
+job = rc.jobs.create({
+    "a": {"operation": "import/url", "source_url": "https://example.com/cover.pdf"},
+    "b": {"operation": "import/url", "source_url": "https://example.com/body.pdf"},
+    "merge": {"operation": "convert", "input": ["a", "b"], "input_format": "pdf", "output_format": "pdf"},
+    "export": {"operation": "export/url", "input": "merge"},
+}, tag="merge")
+done = rc.jobs.wait(job["id"])
+for f in Jobs.exported_files(done):
+    rc.files.download(f, "out")
+
+# Upload your own file
+job = rc.jobs.create({
+    "upload": {"operation": "import/direct/upload"},
+    "convert": {"operation": "convert", "input": "upload", "input_format": "png", "output_format": "webp", "image_quality": 80},
+    "export": {"operation": "export/url", "input": "convert"},
+})
+upload_task = next(t for t in job["tasks"] if t["name"] == "upload")
+rc.files.upload(upload_task, "image.png")
+```
+
+| Method | What it does |
+|---|---|
+| `rc.jobs.create(tasks, tag=, metadata=)` | Create a job (returned with its tasks) |
+| `rc.jobs.get(id)` / `rc.jobs.list(status=, tag=, page=, per_page=)` | A job / one page `{"data", "meta"}` |
+| `rc.jobs.all(...)` | Every job: `for job in rc.jobs.all()` |
+| `rc.jobs.wait(id, timeout=, on_update=, raise_on_error=)` | Poll until `finished` or `error` |
+| `rc.jobs.cancel(id)` / `rc.jobs.delete(id)` | Stop pending tasks / delete |
+| `rc.files.upload(task, file)` / `rc.files.download(file, dir)` | Upload to a task / save a result |
+| `rc.operations.list(category=)` / `for_input("mp4")` / `for_pair("mp4", "mp3")` | Formats, targets, engines (no key needed) |
+| `rc.me()` | Account, team and credit balance |
+
+## Webhooks
+
+```python
+from runconvert import construct_event
+
+@app.post("/webhooks/runconvert")  # Flask
+def runconvert_webhook():
+    try:
+        event = construct_event(request.get_data(), request.headers.get("X-RunConvert-Signature"), os.environ["RUNCONVERT_WEBHOOK_SECRET"])
+    except ValueError:
+        return "", 400
+    if event["event"] == "job.finished":
+        print("done", event["job"]["id"])
+    return "", 200
+```
+
+## Errors
+
+| Error | When |
+|---|---|
+| `RunConvertError` | The API said no: `.status`, `.code` (e.g. `BILLING_INSUFFICIENT_CREDITS`), `.message` |
+| `JobFailedError` | The job ended in `error`; `.task` has `code`, `reason`, `message` |
+| `WaitTimeoutError` | `wait` ran past its `timeout` |
+
+Network errors, `429` and `5xx` are retried twice with backoff (`max_retries`). Creating a job is only
+retried when the request never reached the API, so a job is never created twice.
+
+## Development
+
+```bash
+PYTHONPATH=src python3 -m unittest tests.test_unit                          # no network
+RUNCONVERT_API_KEY=rc_live_… PYTHONPATH=src python3 -m unittest tests.test_live  # real API, about 2 credits
+```
+
+## License
+
+MIT

runconvert-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "runconvert"
+version = "0.1.0"
+description = "Official RunConvert SDK for Python: convert files between 240+ formats"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["runconvert", "file converter", "convert", "pdf", "video", "image", "api", "sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://www.runconvert.com"
+Documentation = "https://www.runconvert.com/docs"
+Source = "https://github.com/runconvert/runconvert-python"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+runconvert = ["py.typed"]

runconvert-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

runconvert-0.1.0/src/runconvert/__init__.py

@@ -0,0 +1,19 @@
+"""Official RunConvert SDK for Python: convert files between 240+ formats."""
+
+from .client import ConvertResult, Files, Jobs, Operations, RunConvert, __version__
+from .errors import JobFailedError, RunConvertError, WaitTimeoutError
+from .webhooks import construct_event, verify_signature
+
+__all__ = [
+    "RunConvert",
+    "Jobs",
+    "Operations",
+    "Files",
+    "ConvertResult",
+    "RunConvertError",
+    "JobFailedError",
+    "WaitTimeoutError",
+    "verify_signature",
+    "construct_event",
+    "__version__",
+]

runconvert-0.1.0/src/runconvert/client.py

@@ -0,0 +1,344 @@
+"""The RunConvert API client (v3). Standard library only."""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import random
+import shutil
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, BinaryIO, Callable, Dict, Iterator, List, Optional, Union
+
+from . import webhooks as _webhooks
+from .errors import JobFailedError, RunConvertError, WaitTimeoutError
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://api.runconvert.com/v3"
+_RETRY_STATUS = {408, 425, 429, 500, 502, 503, 504}
+FileInput = Union[str, "os.PathLike[str]", bytes, BinaryIO]
+
+
+@dataclass
+class HTTPResponse:
+    status: int
+    headers: Dict[str, str]
+    body: bytes = b""
+
+
+@dataclass
+class ConvertResult:
+    #: The finished job, with its tasks.
+    job: dict
+    #: The converted files, each with ``filename``, ``url`` (temporary) and ``size``.
+    files: List[dict]
+    #: Local paths, when ``out_dir`` was given.
+    saved: List[str] = field(default_factory=list)
+
+
+class RunConvert:
+    """The RunConvert API client.
+
+    >>> rc = RunConvert()  # reads RUNCONVERT_API_KEY
+    >>> rc.convert("report.docx", to="pdf", out_dir="out").saved
+    ['out/report.pdf']
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+    ) -> None:
+        self.api_key = api_key if api_key is not None else os.environ.get("RUNCONVERT_API_KEY", "")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.user_agent = f"runconvert-python/{__version__} python/{platform.python_version()}"
+        self.jobs = Jobs(self)
+        self.operations = Operations(self)
+        self.files = Files(self)
+        self.webhooks = Webhooks()
+
+    # ---- high level ----
+
+    def me(self) -> dict:
+        """The account, team and credit balance behind the API key."""
+        return self.request("GET", "/me")
+
+    def convert(
+        self,
+        file: FileInput,
+        to: str,
+        *,
+        from_: Optional[str] = None,
+        options: Optional[Dict[str, Any]] = None,
+        out_dir: Optional[str] = None,
+        filename: Optional[str] = None,
+        tag: Optional[str] = None,
+        on_update: Optional[Callable[[dict], None]] = None,
+        timeout: Optional[float] = None,
+    ) -> ConvertResult:
+        """Converts one file in one call: upload (or import a URL), convert, wait, download.
+
+        ``file`` is a path, an ``http(s)://`` URL, bytes or a binary file object. ``from_`` is
+        read from the name when left out. Engine options (e.g. ``{"audioBitrate": "192k"}``)
+        go in ``options``.
+        """
+        is_url = isinstance(file, str) and file.lower().startswith(("http://", "https://"))
+        if filename:
+            name = filename
+        elif is_url:
+            name = urllib.parse.urlparse(str(file)).path
+        elif isinstance(file, (str, os.PathLike)):
+            name = os.fspath(file)
+        else:
+            name = getattr(file, "name", "") or ""
+        source = (from_ or os.path.splitext(str(name))[1].lstrip(".")).lower()
+        if not source:
+            raise ValueError('Can\'t tell the source format: pass from_="mp4" or filename="video.mp4".')
+        target = to.lower().lstrip(".")
+        import_task = {"operation": "import/url", "source_url": file} if is_url else {"operation": "import/direct/upload"}
+        convert_task = dict(options or {})
+        convert_task.update({"operation": "convert", "input": "import-1", "input_format": source, "output_format": target})
+        job = self.jobs.create(
+            {"import-1": import_task, "convert-1": convert_task, "export-1": {"operation": "export/url", "input": "convert-1"}},
+            tag=tag,
+        )
+        if not is_url:
+            task = next((t for t in job.get("tasks") or [] if t.get("name") == "import-1"), None)
+            if not task or not task.get("upload_url"):
+                raise RunConvertError("The job has no upload URL", body=job)
+            self.files.upload(task, file, filename=os.path.basename(str(name)) if name else None)
+        job = self.jobs.wait(job["id"], on_update=on_update, timeout=timeout)
+        files = Jobs.exported_files(job)
+        saved = [self.files.download(f, out_dir) for f in files] if out_dir else []
+        return ConvertResult(job=job, files=files, saved=saved)
+
+    # ---- HTTP ----
+
+    def request(self, method: str, path: str, body: Any = None, query: Optional[Dict[str, Any]] = None) -> Any:
+        """Sends a request and returns ``data`` from ``{"success": true, "data": …}``."""
+        return self.request_raw(method, path, body, query)[0]
+
+    def request_raw(self, method: str, path: str, body: Any = None, query: Optional[Dict[str, Any]] = None):
+        """Like :meth:`request`, returning ``(data, meta)``."""
+        params = {k: v for k, v in (query or {}).items() if v is not None and v != ""}
+        url = self.base_url + path + ("?" + urllib.parse.urlencode(params) if params else "")
+        headers = {"Accept": "application/json", "User-Agent": self.user_agent}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        # POST /jobs is only repeated when it never reached the server, so a job is never created twice.
+        idempotent = method != "POST" or path.endswith("/cancel")
+        attempt = 0
+        while True:
+            try:
+                res = self._send(method, url, headers, data, self.timeout)
+            except (urllib.error.URLError, OSError) as err:
+                reached = isinstance(err, TimeoutError) or "timed out" in str(err)
+                if attempt < self.max_retries and (idempotent or not reached):
+                    attempt += 1
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise RunConvertError(f"Request to RunConvert failed: {err}") from err
+            if res.status in _RETRY_STATUS and attempt < self.max_retries and (idempotent or res.status == 429):
+                attempt += 1
+                time.sleep(_retry_after(res) or _backoff(attempt))
+                continue
+            if res.status == 204:
+                return None, {}
+            try:
+                payload = json.loads(res.body.decode("utf-8")) if res.body else None
+            except ValueError:
+                payload = None
+            if res.status >= 400 or (isinstance(payload, dict) and payload.get("success") is False):
+                err = (payload or {}).get("error") or {} if isinstance(payload, dict) else {}
+                raise RunConvertError(err.get("message") or f"RunConvert API error (HTTP {res.status})", res.status, err.get("code", ""), payload if payload is not None else res.body)
+            payload = payload or {}
+            return payload.get("data"), payload.get("meta") or {}
+
+    def _send(self, method: str, url: str, headers: Dict[str, str], data: Any, timeout: Optional[float]) -> HTTPResponse:
+        """One HTTP exchange. Overridden in tests."""
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as r:
+                return HTTPResponse(r.status, dict(r.headers), r.read())
+        except urllib.error.HTTPError as e:
+            return HTTPResponse(e.code, dict(e.headers or {}), e.read() or b"")
+
+    def _stream_to(self, url: str, dest: str) -> int:
+        """Downloads ``url`` to ``dest``; returns the status. Overridden in tests."""
+        req = urllib.request.Request(url, headers={"User-Agent": self.user_agent})
+        try:
+            with urllib.request.urlopen(req) as r, open(dest, "wb") as out:
+                shutil.copyfileobj(r, out, 1 << 20)
+                return r.status
+        except urllib.error.HTTPError as e:
+            return e.code
+
+
+def _backoff(attempt: int) -> float:
+    return min(8.0, 0.5 * 2 ** (attempt - 1)) * (0.75 + random.random() / 2)
+
+
+def _retry_after(res: HTTPResponse) -> Optional[float]:
+    value = {k.lower(): v for k, v in res.headers.items()}.get("retry-after")
+    try:
+        seconds = float(value) if value else 0
+    except ValueError:
+        return None
+    return min(seconds, 30.0) if seconds > 0 else None
+
+
+class Jobs:
+    """Create, read, wait for and stop jobs."""
+
+    def __init__(self, client: RunConvert) -> None:
+        self._c = client
+
+    def create(self, tasks: Dict[str, dict], *, tag: Optional[str] = None, metadata: Optional[dict] = None) -> dict:
+        """Creates a job from named tasks. Returned with its tasks (an upload task carries ``upload_url``)."""
+        body: Dict[str, Any] = {"tasks": tasks}
+        if tag:
+            body["tag"] = tag
+        if metadata:
+            body["metadata"] = metadata
+        return self._c.request("POST", "/jobs", body, {"include": "tasks"})
+
+    def get(self, job_id: str) -> dict:
+        """A job with its tasks."""
+        return self._c.request("GET", f"/jobs/{urllib.parse.quote(job_id, safe='')}", query={"include": "tasks"})
+
+    def list(self, *, status: Optional[str] = None, tag: Optional[str] = None, page: Optional[int] = None,
+             per_page: Optional[int] = None, include_tasks: bool = False) -> Dict[str, Any]:
+        """One page of jobs, newest first: ``{"data": [...], "meta": {...}}``."""
+        data, meta = self._c.request_raw("GET", "/jobs", query={
+            "filter[status]": status, "filter[tag]": tag, "page": page, "per_page": per_page,
+            "include": "tasks" if include_tasks else None,
+        })
+        return {"data": data or [], "meta": meta}
+
+    def all(self, **filters: Any) -> Iterator[dict]:
+        """Every job, page by page: ``for job in rc.jobs.all(status="finished")``."""
+        page = 1
+        while True:
+            result = self.list(page=page, **filters)
+            yield from result["data"]
+            total_pages = result["meta"].get("total_pages")
+            if not result["data"] or (total_pages is not None and page >= total_pages):
+                return
+            page += 1
+
+    def cancel(self, job_id: str) -> dict:
+        """Cancels pending tasks; credits for unfinished tasks are refunded."""
+        return self._c.request("POST", f"/jobs/{urllib.parse.quote(job_id, safe='')}/cancel")
+
+    def delete(self, job_id: str) -> None:
+        """Deletes a job."""
+        self._c.request("DELETE", f"/jobs/{urllib.parse.quote(job_id, safe='')}")
+
+    def wait(self, job_id: str, *, timeout: Optional[float] = None, on_update: Optional[Callable[[dict], None]] = None,
+             raise_on_error: bool = True) -> dict:
+        """Polls until ``finished`` or ``error`` (0.7 s, slowing to 3 s). Raises JobFailedError for a failed job."""
+        started = time.monotonic()
+        delay = 0.7
+        while True:
+            job = self.get(job_id)
+            if on_update:
+                on_update(job)
+            if job.get("status") == "finished":
+                return job
+            if job.get("status") == "error":
+                if not raise_on_error:
+                    return job
+                failed = next((t for t in job.get("tasks") or [] if t.get("status") == "error"), None)
+                raise JobFailedError(job, failed)
+            if timeout is not None and time.monotonic() - started + delay > timeout:
+                raise WaitTimeoutError(job, timeout)
+            time.sleep(delay)
+            delay = min(delay + 0.3, 3.0)
+
+    @staticmethod
+    def exported_files(job: dict) -> List[dict]:
+        """The files produced by the job's ``export/url`` tasks."""
+        return [f for t in job.get("tasks") or [] if t.get("operation") == "export/url" for f in (t.get("result") or {}).get("files") or []]
+
+
+class Operations:
+    """Supported formats, targets, engines and options. Public: no key needed."""
+
+    def __init__(self, client: RunConvert) -> None:
+        self._c = client
+
+    def list(self, *, category: Optional[str] = None) -> dict:
+        """Every input format with its targets: ``{"categories": [...], "formats": [...]}``."""
+        return self._c.request("GET", "/operations", query={"category": category})
+
+    def for_input(self, input_format: str) -> dict:
+        """What one format converts to, with credit costs."""
+        return self._c.request("GET", "/operations", query={"input": input_format.lower()})
+
+    def for_pair(self, input_format: str, output_format: str) -> dict:
+        """Engines for one conversion and the options a convert task accepts."""
+        return self._c.request("GET", "/operations", query={"input": input_format.lower(), "output": output_format.lower()})
+
+
+class Files:
+    """Uploads to ``import/direct/upload`` tasks and downloads of results."""
+
+    def __init__(self, client: RunConvert) -> None:
+        self._c = client
+
+    def upload(self, task: Union[dict, str], file: FileInput, *, filename: Optional[str] = None) -> None:
+        """PUTs a path, bytes or binary file object to the task's ``upload_url`` before its deadline."""
+        upload_url = task if isinstance(task, str) else task.get("upload_url")
+        if not upload_url:
+            raise ValueError("This task has no upload_url (is it an import/direct/upload task?)")
+        if filename is None and isinstance(file, (str, os.PathLike)):
+            filename = os.path.basename(os.fspath(file))
+        url = _with_query(upload_url, {"filename": filename} if filename else {})
+        headers = {"Content-Type": "application/octet-stream", "User-Agent": self._c.user_agent}
+        if isinstance(file, (str, os.PathLike)):
+            headers["Content-Length"] = str(os.path.getsize(file))
+            with open(file, "rb") as fh:
+                res = self._c._send("PUT", url, headers, fh, None)
+        else:
+            res = self._c._send("PUT", url, headers, file, None)
+        if res.status >= 300:
+            raise RunConvertError(f"Upload failed (HTTP {res.status}): {res.body[:300].decode('utf-8', 'replace')}", res.status)
+
+    def download(self, file: Union[dict, str], out_dir: str, filename: Optional[str] = None) -> str:
+        """Saves a result file (or a URL) into ``out_dir`` keeping its name; returns the path."""
+        url = file if isinstance(file, str) else file["url"]
+        name = filename or (os.path.basename(urllib.parse.urlparse(url).path) if isinstance(file, str) else file["filename"])
+        os.makedirs(out_dir, exist_ok=True)
+        dest = os.path.join(out_dir, os.path.basename(name))
+        status = self._c._stream_to(url, dest)
+        if status >= 300:
+            raise RunConvertError(f"Download failed (HTTP {status})", status)
+        return dest
+
+
+class Webhooks:
+    """``verify`` and ``construct_event`` for webhook deliveries."""
+
+    verify = staticmethod(_webhooks.verify_signature)
+    construct_event = staticmethod(_webhooks.construct_event)
+
+
+def _with_query(url: str, extra: Dict[str, str]) -> str:
+    parts = urllib.parse.urlsplit(url)
+    query = dict(urllib.parse.parse_qsl(parts.query, keep_blank_values=True))
+    query.update(extra)
+    return urllib.parse.urlunsplit(parts._replace(query=urllib.parse.urlencode(query)))

runconvert-0.1.0/src/runconvert/errors.py

@@ -0,0 +1,41 @@
+"""Errors raised by the RunConvert client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class RunConvertError(Exception):
+    """The API said no: ``{"success": false, "error": {"code", "message"}}``.
+
+    ``code`` is machine-readable (e.g. ``BILLING_INSUFFICIENT_CREDITS``). New codes can
+    appear, so branch on ``status`` for anything you don't recognise.
+    """
+
+    def __init__(self, message: str, status: int = 0, code: str = "", body: Any = None) -> None:
+        super().__init__(message)
+        self.message = message
+        #: HTTP status, or 0 when the request never got a response.
+        self.status = status
+        #: API error code, empty when the API sent none.
+        self.code = code
+        #: The raw response body, when there was one.
+        self.body = body
+
+
+class JobFailedError(RunConvertError):
+    """The job ended with status ``error``. ``task`` is the first failed task (code, reason, message)."""
+
+    def __init__(self, job: dict, task: Optional[dict] = None) -> None:
+        message = (task or {}).get("message") or f"Job {job.get('id')} failed"
+        super().__init__(message, 0, (task or {}).get("code", ""), job)
+        self.job = job
+        self.task = task
+
+
+class WaitTimeoutError(RunConvertError):
+    """``jobs.wait`` gave up before the job reached ``finished`` or ``error``."""
+
+    def __init__(self, job: dict, timeout: float) -> None:
+        super().__init__(f"Job {job.get('id')} still {job.get('status')} after {round(timeout)}s", 0, "WAIT_TIMEOUT", job)
+        self.job = job

runconvert-0.1.0/src/runconvert/webhooks.py

@@ -0,0 +1,37 @@
+"""Webhook signature checks.
+
+Every delivery has an ``X-RunConvert-Signature`` header: ``sha256=`` followed by the hex
+HMAC-SHA256 of the **raw** request body, keyed with the endpoint's secret.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+from typing import Optional, Union
+
+_HEX64 = re.compile(r"^[0-9a-f]{64}$")
+
+
+def verify_signature(raw_body: Union[str, bytes], signature: Optional[str], secret: str) -> bool:
+    """True when ``signature`` matches the body. Pass the body exactly as received."""
+    if not signature or not secret:
+        return False
+    given = signature.strip()
+    if given.lower().startswith("sha256="):
+        given = given[7:]
+    given = given.lower()
+    if not _HEX64.match(given):
+        return False
+    body = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+    expected = hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, given)
+
+
+def construct_event(raw_body: Union[str, bytes], signature: Optional[str], secret: str) -> dict:
+    """Verifies the signature, then parses the event. Raises ``ValueError`` if it doesn't match."""
+    if not verify_signature(raw_body, signature, secret):
+        raise ValueError("Invalid RunConvert webhook signature")
+    return json.loads(raw_body)

runconvert-0.1.0/src/runconvert.egg-info/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: runconvert
+Version: 0.1.0
+Summary: Official RunConvert SDK for Python: convert files between 240+ formats
+License-Expression: MIT
+Project-URL: Homepage, https://www.runconvert.com
+Project-URL: Documentation, https://www.runconvert.com/docs
+Project-URL: Source, https://github.com/runconvert/runconvert-python
+Keywords: runconvert,file converter,convert,pdf,video,image,api,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# RunConvert SDK for Python
+
+Convert files between 240+ formats (3,000+ conversions) with the [RunConvert API](https://www.runconvert.com/docs):
+documents, images, video, audio, ebooks, archives, fonts and CAD. Python 3.10+, no dependencies.
+
+```bash
+pip install runconvert
+```
+
+```python
+from runconvert import RunConvert
+
+rc = RunConvert()  # reads RUNCONVERT_API_KEY
+
+# One call: upload, convert, wait, download.
+result = rc.convert("report.docx", "pdf", out_dir="out")
+print(result.saved)  # ['out/report.pdf']
+```
+
+Get an API key in **Dashboard → API Keys** on [runconvert.com](https://www.runconvert.com). Keep keys on the server.
+
+## Convert
+
+```python
+# From a URL (imported by RunConvert, nothing to upload)
+rc.convert("https://example.com/talk.mp4", "mp3", options={"audioBitrate": "192k"})
+
+# From bytes or a file object: give a filename (or from_)
+rc.convert(data, "jpg", filename="photo.heic", out_dir="out")
+
+# Progress and a time limit (seconds)
+rc.convert("movie.mov", "mp4", out_dir="out", on_update=lambda job: print(job["status"]), timeout=600)
+```
+
+`convert` returns `ConvertResult(job, files, saved)`. Options for a conversion come from
+`rc.operations.for_pair("mp4", "mp3")`.
+
+## Jobs with your own tasks
+
+```python
+from runconvert import Jobs
+
+# Merge three PDFs into one
+job = rc.jobs.create({
+    "a": {"operation": "import/url", "source_url": "https://example.com/cover.pdf"},
+    "b": {"operation": "import/url", "source_url": "https://example.com/body.pdf"},
+    "merge": {"operation": "convert", "input": ["a", "b"], "input_format": "pdf", "output_format": "pdf"},
+    "export": {"operation": "export/url", "input": "merge"},
+}, tag="merge")
+done = rc.jobs.wait(job["id"])
+for f in Jobs.exported_files(done):
+    rc.files.download(f, "out")
+
+# Upload your own file
+job = rc.jobs.create({
+    "upload": {"operation": "import/direct/upload"},
+    "convert": {"operation": "convert", "input": "upload", "input_format": "png", "output_format": "webp", "image_quality": 80},
+    "export": {"operation": "export/url", "input": "convert"},
+})
+upload_task = next(t for t in job["tasks"] if t["name"] == "upload")
+rc.files.upload(upload_task, "image.png")
+```
+
+| Method | What it does |
+|---|---|
+| `rc.jobs.create(tasks, tag=, metadata=)` | Create a job (returned with its tasks) |
+| `rc.jobs.get(id)` / `rc.jobs.list(status=, tag=, page=, per_page=)` | A job / one page `{"data", "meta"}` |
+| `rc.jobs.all(...)` | Every job: `for job in rc.jobs.all()` |
+| `rc.jobs.wait(id, timeout=, on_update=, raise_on_error=)` | Poll until `finished` or `error` |
+| `rc.jobs.cancel(id)` / `rc.jobs.delete(id)` | Stop pending tasks / delete |
+| `rc.files.upload(task, file)` / `rc.files.download(file, dir)` | Upload to a task / save a result |
+| `rc.operations.list(category=)` / `for_input("mp4")` / `for_pair("mp4", "mp3")` | Formats, targets, engines (no key needed) |
+| `rc.me()` | Account, team and credit balance |
+
+## Webhooks
+
+```python
+from runconvert import construct_event
+
+@app.post("/webhooks/runconvert")  # Flask
+def runconvert_webhook():
+    try:
+        event = construct_event(request.get_data(), request.headers.get("X-RunConvert-Signature"), os.environ["RUNCONVERT_WEBHOOK_SECRET"])
+    except ValueError:
+        return "", 400
+    if event["event"] == "job.finished":
+        print("done", event["job"]["id"])
+    return "", 200
+```
+
+## Errors
+
+| Error | When |
+|---|---|
+| `RunConvertError` | The API said no: `.status`, `.code` (e.g. `BILLING_INSUFFICIENT_CREDITS`), `.message` |
+| `JobFailedError` | The job ended in `error`; `.task` has `code`, `reason`, `message` |
+| `WaitTimeoutError` | `wait` ran past its `timeout` |
+
+Network errors, `429` and `5xx` are retried twice with backoff (`max_retries`). Creating a job is only
+retried when the request never reached the API, so a job is never created twice.
+
+## Development
+
+```bash
+PYTHONPATH=src python3 -m unittest tests.test_unit                          # no network
+RUNCONVERT_API_KEY=rc_live_… PYTHONPATH=src python3 -m unittest tests.test_live  # real API, about 2 credits
+```
+
+## License
+
+MIT

runconvert-0.1.0/src/runconvert.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/runconvert/__init__.py
+src/runconvert/client.py
+src/runconvert/errors.py
+src/runconvert/py.typed
+src/runconvert/webhooks.py
+src/runconvert.egg-info/PKG-INFO
+src/runconvert.egg-info/SOURCES.txt
+src/runconvert.egg-info/dependency_links.txt
+src/runconvert.egg-info/top_level.txt
+tests/test_live.py
+tests/test_unit.py

runconvert-0.1.0/src/runconvert.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

runconvert-0.1.0/src/runconvert.egg-info/top_level.txt

@@ -0,0 +1 @@
+runconvert

runconvert-0.1.0/tests/test_live.py

@@ -0,0 +1,44 @@
+"""Live tests against the real API. Needs RUNCONVERT_API_KEY; converts one small text file (about 2 credits)."""
+import os
+import tempfile
+import unittest
+
+from runconvert import RunConvert, RunConvertError
+
+KEY = os.environ.get("RUNCONVERT_API_KEY")
+
+
+@unittest.skipUnless(KEY, "set RUNCONVERT_API_KEY to run live tests")
+class LiveTests(unittest.TestCase):
+    def test_me(self):
+        me = RunConvert().me()
+        self.assertTrue(me.get("credits"))
+
+    def test_operations(self):
+        rc = RunConvert(api_key="")
+        self.assertTrue(any(f["format"] == "txt" for f in rc.operations.list(category="document")["formats"]))
+        self.assertTrue(any(o["format"] == "pdf" for o in rc.operations.for_input("TXT")["outputs"]))
+        self.assertTrue(rc.operations.for_pair("mp4", "mp3")["engines"])
+
+    def test_convert_text_to_pdf(self):
+        rc = RunConvert()
+        with tempfile.TemporaryDirectory() as d:
+            src = os.path.join(d, "sdk-live-test.txt")
+            with open(src, "w", encoding="utf-8") as f:
+                f.write("RunConvert Python SDK live test\nLine two\n\nCafé – 你好 – Привет\n")
+            seen = []
+            res = rc.convert(src, "pdf", out_dir=os.path.join(d, "out"), tag="sdk-python-live-test", on_update=lambda j: seen.append(j["status"]), timeout=150)
+            self.assertEqual(res.job["status"], "finished")
+            with open(res.saved[0], "rb") as f:
+                pdf = f.read()
+            self.assertEqual(pdf[:5], b"%PDF-")
+            print(f"\n  job {res.job['id']}: {' → '.join(dict.fromkeys(seen))}, {res.job.get('credits_used')} credit(s), {len(pdf)} bytes")
+
+    def test_bad_key(self):
+        with self.assertRaises(RunConvertError) as cm:
+            RunConvert(api_key="rc_live_invalid", max_retries=0).me()
+        self.assertEqual(cm.exception.status, 401)
+
+
+if __name__ == "__main__":
+    unittest.main()

runconvert-0.1.0/tests/test_unit.py

@@ -0,0 +1,165 @@
+import hashlib
+import hmac
+import json
+import os
+import tempfile
+import unittest
+import urllib.parse
+
+from runconvert import JobFailedError, RunConvert, RunConvertError, WaitTimeoutError, construct_event, verify_signature
+from runconvert.client import HTTPResponse
+
+
+def ok(data, meta=None):
+    body = {"success": True, "data": data}
+    if meta:
+        body["meta"] = meta
+    return HTTPResponse(200, {}, json.dumps(body).encode())
+
+
+def fail(status, code, message, headers=None):
+    return HTTPResponse(status, headers or {}, json.dumps({"success": False, "error": {"code": code, "message": message}}).encode())
+
+
+class Fake(RunConvert):
+    """A client whose HTTP goes to ``handler(call, n)`` instead of the network."""
+
+    def __init__(self, handler, **kw):
+        super().__init__("rc_live_test", base_url="https://api.example/v3", max_retries=2, **kw)
+        self.handler = handler
+        self.calls = []
+        self.downloads = {}
+
+    def _send(self, method, url, headers, data, timeout):
+        u = urllib.parse.urlsplit(url)
+        body = data.read() if hasattr(data, "read") else data
+        call = {"method": method, "path": u.path.replace("/v3", "", 1), "query": dict(urllib.parse.parse_qsl(u.query)), "headers": headers, "body": body}
+        self.calls.append(call)
+        return self.handler(call, len(self.calls))
+
+    def _stream_to(self, url, dest):
+        with open(dest, "wb") as f:
+            f.write(self.downloads.get(url, b""))
+        return 200 if url in self.downloads else 404
+
+
+class ClientTests(unittest.TestCase):
+    def setUp(self):
+        import runconvert.client as c
+        self._sleep = c.time.sleep
+        c.time.sleep = lambda s: None  # no real waiting in tests
+
+    def tearDown(self):
+        import runconvert.client as c
+        c.time.sleep = self._sleep
+
+    def test_key_and_envelope(self):
+        rc = Fake(lambda call, n: ok({"credits": {"total_remaining": 42}}))
+        self.assertEqual(rc.me()["credits"]["total_remaining"], 42)
+        self.assertEqual(rc.calls[0]["headers"]["Authorization"], "Bearer rc_live_test")
+        self.assertTrue(rc.calls[0]["headers"]["User-Agent"].startswith("runconvert-python/"))
+
+    def test_api_error(self):
+        rc = Fake(lambda call, n: fail(422, "BILLING_INSUFFICIENT_CREDITS", "Insufficient credits."))
+        with self.assertRaises(RunConvertError) as cm:
+            rc.jobs.get("job_1")
+        self.assertEqual((cm.exception.status, cm.exception.code, str(cm.exception)), (422, "BILLING_INSUFFICIENT_CREDITS", "Insufficient credits."))
+
+    def test_get_retries_503(self):
+        rc = Fake(lambda call, n: HTTPResponse(503, {}, b"busy") if n < 3 else ok({"id": "job_1", "status": "finished"}))
+        self.assertEqual(rc.jobs.get("job_1")["status"], "finished")
+        self.assertEqual(len(rc.calls), 3)
+
+    def test_create_not_retried_after_500(self):
+        rc = Fake(lambda call, n: fail(500, "INTERNAL", "boom"))
+        with self.assertRaises(RunConvertError):
+            rc.jobs.create({})
+        self.assertEqual(len(rc.calls), 1)
+
+    def test_create_retried_on_429(self):
+        rc = Fake(lambda call, n: fail(429, "ACTIVE_JOB_LIMIT_REACHED", "x", {"Retry-After": "0"}) if n == 1 else ok({"id": "job_1", "status": "waiting", "tasks": []}))
+        self.assertEqual(rc.jobs.create({})["id"], "job_1")
+        self.assertEqual(len(rc.calls), 2)
+        self.assertEqual(rc.calls[1]["query"]["include"], "tasks")
+
+    def test_list_and_all(self):
+        rc = Fake(lambda call, n: ok([{"id": "job_p" + call["query"]["page"], "status": "finished"}], {"page": int(call["query"]["page"]), "total_pages": 2}))
+        page = rc.jobs.list(status="finished", tag="x", page=1, per_page=1)
+        self.assertEqual(page["meta"]["total_pages"], 2)
+        self.assertEqual(rc.calls[0]["query"]["filter[status]"], "finished")
+        self.assertEqual([j["id"] for j in rc.jobs.all(per_page=1)], ["job_p1", "job_p2"])
+
+    def test_wait(self):
+        states = ["waiting", "processing", "finished"]
+        rc = Fake(lambda call, n: ok({"id": "job_1", "status": states[min(n - 1, 2)], "tasks": []}))
+        seen = []
+        self.assertEqual(rc.jobs.wait("job_1", on_update=lambda j: seen.append(j["status"]))["status"], "finished")
+        self.assertEqual(seen, states)
+
+    def test_wait_failed_and_timeout(self):
+        failed = {"id": "job_1", "status": "error", "tasks": [{"name": "c", "operation": "convert", "status": "error", "code": "INVALID_DATA", "reason": "INPUT_EMPTY", "message": "The file is empty."}]}
+        rc = Fake(lambda call, n: ok(failed))
+        with self.assertRaises(JobFailedError) as cm:
+            rc.jobs.wait("job_1")
+        self.assertEqual((cm.exception.task["reason"], str(cm.exception)), ("INPUT_EMPTY", "The file is empty."))
+        self.assertEqual(rc.jobs.wait("job_1", raise_on_error=False)["status"], "error")
+        rc2 = Fake(lambda call, n: ok({"id": "job_1", "status": "processing", "tasks": []}))
+        with self.assertRaises(WaitTimeoutError):
+            rc2.jobs.wait("job_1", timeout=0.001)
+
+    def test_delete_204_and_operations(self):
+        rc = Fake(lambda call, n: HTTPResponse(204, {}) if call["method"] == "DELETE" else ok({"engines": []}))
+        self.assertIsNone(rc.jobs.delete("job_1"))
+        rc.operations.for_pair("MP4", "MP3")
+        self.assertEqual(rc.calls[1]["query"], {"input": "mp4", "output": "mp3"})
+
+    def test_webhooks(self):
+        body = json.dumps({"event": "job.finished", "job": {"id": "job_1"}})
+        sig = "sha256=" + hmac.new(b"whsec_x", body.encode(), hashlib.sha256).hexdigest()
+        self.assertTrue(verify_signature(body, sig, "whsec_x"))
+        self.assertTrue(verify_signature(body.encode(), sig, "whsec_x"))
+        self.assertFalse(verify_signature(body + " ", sig, "whsec_x"))
+        self.assertFalse(verify_signature(body, sig, "other"))
+        self.assertFalse(verify_signature(body, "sha256=nothex", "whsec_x"))
+        self.assertFalse(verify_signature(body, None, "whsec_x"))
+        self.assertEqual(construct_event(body, sig, "whsec_x")["job"]["id"], "job_1")
+        with self.assertRaises(ValueError):
+            construct_event(body, "sha256=" + "0" * 64, "whsec_x")
+
+    def test_convert_upload_wait_download(self):
+        polls = {"n": 0}
+
+        def handler(call, n):
+            if call["method"] == "POST" and call["path"] == "/jobs":
+                return ok({"id": "job_1", "status": "waiting", "tasks": [{"name": "import-1", "operation": "import/direct/upload", "status": "waiting", "upload_url": "https://up.example/u/1?token=t"}]})
+            if call["method"] == "PUT":
+                return HTTPResponse(200, {}, b"")
+            polls["n"] += 1
+            return ok({"id": "job_1", "status": "finished" if polls["n"] > 1 else "processing", "tasks": [{"name": "export-1", "operation": "export/url", "status": "finished", "result": {"files": [{"filename": "notes.pdf", "url": "https://dl.example/notes.pdf"}]}}]})
+
+        rc = Fake(handler)
+        rc.downloads["https://dl.example/notes.pdf"] = b"PDF"
+        with tempfile.TemporaryDirectory() as d:
+            src = os.path.join(d, "notes.txt")
+            with open(src, "w") as f:
+                f.write("hello")
+            res = rc.convert(src, "pdf", out_dir=os.path.join(d, "out"), options={"page_size": "a4"})
+            created = json.loads(rc.calls[0]["body"])
+            self.assertEqual(created["tasks"]["convert-1"], {"page_size": "a4", "operation": "convert", "input": "import-1", "input_format": "txt", "output_format": "pdf"})
+            put = next(c for c in rc.calls if c["method"] == "PUT")
+            self.assertEqual((put["query"]["filename"], put["query"]["token"], put["body"]), ("notes.txt", "t", b"hello"))
+            with open(res.saved[0], "rb") as f:
+                self.assertEqual(f.read(), b"PDF")
+
+    def test_convert_url_and_bytes(self):
+        rc = Fake(lambda call, n: ok({"id": "job_2", "status": "finished" if call["method"] == "GET" else "waiting", "tasks": []}))
+        rc.convert("https://example.com/a/talk.MP4?x=1", "mp3")
+        tasks = json.loads(rc.calls[0]["body"])["tasks"]
+        self.assertEqual(tasks["import-1"], {"operation": "import/url", "source_url": "https://example.com/a/talk.MP4?x=1"})
+        self.assertEqual(tasks["convert-1"]["input_format"], "mp4")
+        with self.assertRaises(ValueError):
+            rc.convert(b"x", "pdf")
+
+
+if __name__ == "__main__":
+    unittest.main()