very-good-ffmpeg 0.1.0__tar.gz

very_good_ffmpeg-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# env
+.env.test
+.env
+
+# python
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+
+# editors
+.vscode/
+.idea/
+*.swp
+.claude
+

very_good_ffmpeg-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: very-good-ffmpeg
+Version: 0.1.0
+Summary: Python SDK for the Very Good FFmpeg API
+Project-URL: Homepage, https://verygoodffmpeg.com
+Requires-Python: >=3.10

very_good_ffmpeg-0.1.0/README.md

@@ -0,0 +1,142 @@
+# very-good-ffmpeg
+
+Python SDK for the Very Good FFmpeg API — run FFmpeg jobs in the cloud.
+
+[![PyPI](https://img.shields.io/pypi/v/very-good-ffmpeg)](https://pypi.org/project/very-good-ffmpeg/)
+
+[Homepage](https://verygoodffmpeg.com) · [API Docs](https://verygoodffmpeg.com/docs)
+
+## Installation
+
+```
+pip install very-good-ffmpeg
+```
+
+## Usage
+
+```python
+import os
+from very_good_ffmpeg import VGF
+
+client = VGF(os.environ["VGFFMPEG_API_KEY"])
+
+# Create a job and wait for it to complete
+job = client.run(
+    input_files={"input": "https://example.com/input.mp4"},
+    output_files=["output.mp4"],
+    ffmpeg_commands=["-i {{input}} -vf scale=1280:720 {{output.mp4}}"],
+    wait=True,
+)
+
+print(job.status)       # "succeeded"
+print(job.output_files) # {"output.mp4": "https://..."}
+```
+
+Async is also supported — use `arun`, `jobs.aget`, `jobs.alist`, `jobs.acancel`, `files.aupload`, etc.
+
+```python
+import asyncio, os
+from very_good_ffmpeg import VGF
+
+async def main():
+    client = VGF(os.environ["VGFFMPEG_API_KEY"])
+    job = await client.arun(
+        input_files={"input": "https://example.com/input.mp4"},
+        output_files=["output.mp4"],
+        ffmpeg_commands=["-i {{input}} -vf scale=1280:720 {{output.mp4}}"],
+        wait=True,
+    )
+    print(job.status)
+
+asyncio.run(main())
+```
+
+## Reference
+
+### Create a job — `client.run(...)` / `client.arun(...)`
+
+Submits an FFmpeg job. Pass `wait=True` to block until the job reaches a terminal state.
+
+```python
+job = client.run(
+    input_files={"input": "https://example.com/input.mp4"},
+    output_files=["output.mp4"],
+    ffmpeg_commands=["-i {{input}} -c:v libx264 {{output.mp4}}"],
+    webhook_url="https://example.com/webhook",  # optional
+    machine="nvidia",  # optional: "cpu" | "nvidia"
+    wait=True,
+)
+```
+
+### Get a job — `client.jobs.get(id)` / `client.jobs.aget(id)`
+
+```python
+job = client.jobs.get("job_abc123")
+print(job.status)  # "queued" | "running" | "succeeded" | "failed" | "cancelled"
+```
+
+### List jobs — `client.jobs.list(...)` / `client.jobs.alist(...)`
+
+Returns a `JobList` with `data` (list of jobs) and `paging_params`.
+
+```python
+result = client.jobs.list(limit=20, offset=0)
+print(result.data)          # list[Job]
+print(result.paging_params) # PagingParams(limit=20, offset=0, total=100, has_more=True)
+```
+
+### Cancel a job — `client.jobs.cancel(id)` / `client.jobs.acancel(id)`
+
+```python
+job = client.jobs.cancel("job_abc123")
+print(job.status)  # "cancelled"
+```
+
+### Poll until done — `job.wait(...)` / `job.async_wait(...)`
+
+```python
+job = client.run(input_files=..., output_files=..., ffmpeg_commands=...)
+job.wait(timeout=120)
+print(job.status)
+```
+
+### Upload a file — `client.files.upload(data, content_type?)` / `client.files.aupload(...)`
+
+Upload bytes or a file path to temporary storage and get back a URL you can use as an `input_files` value.
+
+```python
+with open("input.mp4", "rb") as f:
+    download_url = client.files.upload(f.read(), "video/mp4")
+
+job = client.run(
+    input_files={"input": download_url},
+    output_files=["output.mp4"],
+    ffmpeg_commands=["-i {{input}} -vf scale=1280:720 {{output.mp4}}"],
+)
+```
+
+Pass a file path directly to have the SDK read it for you:
+
+```python
+download_url = client.files.upload("input.mp4")
+```
+
+### Prepare upload — `client.files.prepare()` / `client.files.aprepare()`
+
+Returns a `TmpFile` with `upload_url` and `download_url` if you need to stream a large file yourself.
+
+```python
+tmp = client.files.prepare()
+# PUT your file to tmp.upload_url, then use tmp.download_url as input
+```
+
+## Examples
+
+See the [`examples/`](./examples) folder for minimal runnable scripts:
+
+- [`examples/basic.py`](./examples/basic.py) — sync, list jobs
+- [`examples/async_basic.py`](./examples/async_basic.py) — async, list jobs
+
+## Support
+
+Open an issue at [github.com/verygoodffmpeg/Very-Good-FFmpeg-Python-SDK](https://github.com/verygoodffmpeg/Very-Good-FFmpeg-Python-SDK) or email [please_help@verygoodffmpeg.com](mailto:please_help@verygoodffmpeg.com).

very_good_ffmpeg-0.1.0/examples/async_basic.py

@@ -0,0 +1,21 @@
+"""Async example — list jobs.
+
+Run:
+    python examples/async_basic.py
+
+Requires:
+    VGFFMPEG_API_KEY env var
+"""
+import asyncio
+import os
+
+from very_good_ffmpeg import VGF
+
+
+async def main() -> None:
+    client = VGF(os.environ["VGFFMPEG_API_KEY"])
+    result = await client.jobs.alist()
+    print("Jobs:", result.data)
+
+
+asyncio.run(main())

very_good_ffmpeg-0.1.0/examples/basic.py

@@ -0,0 +1,16 @@
+"""Sync example — list jobs.
+
+Run:
+    python examples/basic.py
+
+Requires:
+    VGFFMPEG_API_KEY env var
+"""
+import os
+
+from very_good_ffmpeg import VGF
+
+client = VGF(os.environ["VGFFMPEG_API_KEY"])
+
+result = client.jobs.list()
+print("Jobs:", result.data)

very_good_ffmpeg-0.1.0/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "very-good-ffmpeg"
+version = "0.1.0"
+description = "Python SDK for the Very Good FFmpeg API"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Homepage = "https://verygoodffmpeg.com"

very_good_ffmpeg-0.1.0/pytest.ini

@@ -0,0 +1,5 @@
+[pytest]
+testpaths = tests
+asyncio_mode = auto
+markers =
+    integration: marks tests as integration tests (require VGFFMPEG_API_KEY)

very_good_ffmpeg-0.1.0/requirements.txt

@@ -0,0 +1,7 @@
+iniconfig==2.3.0
+packaging==26.2
+pluggy==1.6.0
+Pygments==2.20.0
+pytest==9.0.3
+pytest-asyncio==1.3.0
+python-dotenv==1.2.2

very_good_ffmpeg-0.1.0/tests/integration/.env.test.example

@@ -0,0 +1,3 @@
+VGFFMPEG_API_KEY=sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+VGFFMPEG_BASE_URL=https://verygoodffmpeg.com/api
+VGFFMPEG_DEBUG=

very_good_ffmpeg-0.1.0/tests/integration/async/test_cancel.py

@@ -0,0 +1,20 @@
+from very_good_ffmpeg import VGF
+
+INPUT = "https://storage.verygoodffmpeg.com/sample.mp4"
+COMMANDS = ["-i {{input}} -t 60 {{output.mp4}}"]
+OUTPUTS = ["output.mp4"]
+
+
+async def test_cancel(client: VGF):
+    job = await client.arun(
+        input_files={"input": INPUT},
+        output_files=OUTPUTS,
+        ffmpeg_commands=COMMANDS,
+    )
+    assert job.id
+
+    cancelled = await client.jobs.acancel(job.id)
+    assert cancelled.status == "cancelled"
+
+    await job.async_wait(timeout=30)
+    assert job.status == "cancelled"

very_good_ffmpeg-0.1.0/tests/integration/async/test_failure.py

@@ -0,0 +1,27 @@
+from very_good_ffmpeg import VGF
+
+INVALID_INPUT = "https://invalid.example/nope.mp4"
+COMMANDS = ["-i {{input}} {{output.mp4}}"]
+OUTPUTS = ["output.mp4"]
+
+
+async def test_failure_wait(client: VGF):
+    job = await client.arun(
+        input_files={"input": INVALID_INPUT},
+        output_files=OUTPUTS,
+        ffmpeg_commands=COMMANDS,
+        wait=True,
+    )
+    assert job.status == "failed"
+    assert job.error_message
+
+
+async def test_failure_poll(client: VGF):
+    job = await client.arun(
+        input_files={"input": INVALID_INPUT},
+        output_files=OUTPUTS,
+        ffmpeg_commands=COMMANDS,
+    )
+    await job.async_wait(timeout=120)
+    assert job.status == "failed"
+    assert job.error_message

very_good_ffmpeg-0.1.0/tests/integration/async/test_list_jobs.py

@@ -0,0 +1,23 @@
+import asyncio
+
+from very_good_ffmpeg import VGF
+
+
+async def test_list_jobs_offset(client: VGF):
+    page1, page2 = await asyncio.gather(
+        client.jobs.alist(limit=2, offset=0),
+        client.jobs.alist(limit=2, offset=2),
+    )
+
+    assert len(page1.data) <= 2
+    assert len(page2.data) <= 2
+
+    page1_ids = {j.id for j in page1.data}
+    for job in page2.data:
+        assert job.id not in page1_ids
+
+    p = page2.paging_params
+    assert isinstance(p.limit, int)
+    assert isinstance(p.offset, int)
+    assert isinstance(p.total, int)
+    assert isinstance(p.has_more, bool)

very_good_ffmpeg-0.1.0/tests/integration/async/test_success.py

@@ -0,0 +1,29 @@
+from very_good_ffmpeg import VGF
+
+INPUT = "https://storage.verygoodffmpeg.com/sample.mp4"
+COMMANDS = ["-i {{input}} -t 5 {{output.mp4}}"]
+OUTPUTS = ["output.mp4"]
+
+
+async def test_success_wait(client: VGF):
+    job = await client.arun(
+        input_files={"input": INPUT},
+        output_files=OUTPUTS,
+        ffmpeg_commands=COMMANDS,
+        wait=True,
+    )
+    assert job.status == "succeeded"
+    assert job.output_files
+
+
+async def test_success_poll(client: VGF):
+    job = await client.arun(
+        input_files={"input": INPUT},
+        output_files=OUTPUTS,
+        ffmpeg_commands=COMMANDS,
+    )
+    assert job.status in ("queued", "running", "succeeded")
+
+    await job.async_wait(timeout=120)
+    assert job.status == "succeeded"
+    assert job.output_files

very_good_ffmpeg-0.1.0/tests/integration/async/test_tmp_file.py

@@ -0,0 +1,27 @@
+import asyncio
+import urllib.request
+
+from very_good_ffmpeg import VGF
+
+SAMPLE_URL = "https://storage.verygoodffmpeg.com/sample.mp4"
+
+
+async def test_tmp_file_upload_download_and_run(client: VGF):
+    original = await asyncio.to_thread(
+        lambda: urllib.request.urlopen(SAMPLE_URL).read()
+    )
+
+    download_url = await client.files.aupload(original, "video/mp4")
+
+    downloaded = await asyncio.to_thread(
+        lambda: urllib.request.urlopen(download_url).read()
+    )
+    assert downloaded == original
+
+    job = await client.arun(
+        input_files={"input": download_url},
+        output_files=["output.mp4"],
+        ffmpeg_commands=["-i {{input}} -t 2 {{output.mp4}}"],
+        wait=True,
+    )
+    assert job.status == "succeeded"

very_good_ffmpeg-0.1.0/tests/integration/async/test_webhook.py

@@ -0,0 +1,14 @@
+from very_good_ffmpeg import VGF
+
+WEBHOOK_URL = "https://example.com/webhook"
+
+
+async def test_webhook_url_reflected(client: VGF):
+    job = await client.arun(
+        input_files={"input": "https://storage.verygoodffmpeg.com/sample.mp4"},
+        output_files=["output.mp4"],
+        ffmpeg_commands=["-i {{input}} -t 5 {{output.mp4}}"],
+        webhook_url=WEBHOOK_URL,
+        wait=True,
+    )
+    assert job.webhook_url == WEBHOOK_URL

very_good_ffmpeg-0.1.0/tests/integration/conftest.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+import pytest
+from dotenv import load_dotenv
+
+from very_good_ffmpeg import VGF
+
+load_dotenv(Path(__file__).parent / ".env.test")
+
+
+if os.environ.get("VGFFMPEG_DEBUG"):
+    logging.basicConfig(
+        level=logging.DEBUG,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+    logging.getLogger("very_good_ffmpeg").setLevel(logging.DEBUG)
+    logging.debug("Debug logging enabled")
+
+log = logging.getLogger("very_good_ffmpeg.tests")
+
+
+@pytest.fixture(scope="session")
+def client() -> VGF:
+    api_key = os.environ.get("VGFFMPEG_API_KEY")
+    if not api_key:
+        pytest.skip("VGFFMPEG_API_KEY not set")
+    base_url = os.environ.get("VGFFMPEG_BASE_URL", "https://verygoodffmpeg.com/api")
+    log.debug("client base_url=%s", base_url)
+    return VGF(api_key=api_key, base_url=base_url)

very_good_ffmpeg-0.1.0/tests/integration/sync/test_cancel.py

@@ -0,0 +1,20 @@
+from very_good_ffmpeg import VGF
+
+INPUT = "https://storage.verygoodffmpeg.com/sample.mp4"
+COMMANDS = ["-i {{input}} -t 60 {{output.mp4}}"]
+OUTPUTS = ["output.mp4"]
+
+
+def test_cancel(client: VGF):
+    job = client.run(
+        input_files={"input": INPUT},
+        output_files=OUTPUTS,
+        ffmpeg_commands=COMMANDS,
+    )
+    assert job.id
+
+    cancelled = client.jobs.cancel(job.id)
+    assert cancelled.status == "cancelled"
+
+    job.wait(timeout=30)
+    assert job.status == "cancelled"

very_good_ffmpeg-0.1.0/tests/integration/sync/test_failure.py

@@ -0,0 +1,27 @@
+from very_good_ffmpeg import VGF
+
+INVALID_INPUT = "https://invalid.example/nope.mp4"
+COMMANDS = ["-i {{input}} {{output.mp4}}"]
+OUTPUTS = ["output.mp4"]
+
+
+def test_failure_wait(client: VGF):
+    job = client.run(
+        input_files={"input": INVALID_INPUT},
+        output_files=OUTPUTS,
+        ffmpeg_commands=COMMANDS,
+        wait=True,
+    )
+    assert job.status == "failed"
+    assert job.error_message
+
+
+def test_failure_poll(client: VGF):
+    job = client.run(
+        input_files={"input": INVALID_INPUT},
+        output_files=OUTPUTS,
+        ffmpeg_commands=COMMANDS,
+    )
+    job.wait(timeout=120)
+    assert job.status == "failed"
+    assert job.error_message

very_good_ffmpeg-0.1.0/tests/integration/sync/test_list_jobs.py

@@ -0,0 +1,19 @@
+from very_good_ffmpeg import VGF
+
+
+def test_list_jobs_offset(client: VGF):
+    page1 = client.jobs.list(limit=2, offset=0)
+    page2 = client.jobs.list(limit=2, offset=2)
+
+    assert len(page1.data) <= 2
+    assert len(page2.data) <= 2
+
+    page1_ids = {j.id for j in page1.data}
+    for job in page2.data:
+        assert job.id not in page1_ids
+
+    p = page2.paging_params
+    assert isinstance(p.limit, int)
+    assert isinstance(p.offset, int)
+    assert isinstance(p.total, int)
+    assert isinstance(p.has_more, bool)

very_good_ffmpeg-0.1.0/tests/integration/sync/test_success.py

@@ -0,0 +1,29 @@
+from very_good_ffmpeg import VGF
+
+INPUT = "https://storage.verygoodffmpeg.com/sample.mp4"
+COMMANDS = ["-i {{input}} -t 5 {{output.mp4}}"]
+OUTPUTS = ["output.mp4"]
+
+
+def test_success_wait(client: VGF):
+    job = client.run(
+        input_files={"input": INPUT},
+        output_files=OUTPUTS,
+        ffmpeg_commands=COMMANDS,
+        wait=True,
+    )
+    assert job.status == "succeeded"
+    assert job.output_files
+
+
+def test_success_poll(client: VGF):
+    job = client.run(
+        input_files={"input": INPUT},
+        output_files=OUTPUTS,
+        ffmpeg_commands=COMMANDS,
+    )
+    assert job.status in ("queued", "running", "succeeded")
+
+    job.wait(timeout=120)
+    assert job.status == "succeeded"
+    assert job.output_files

very_good_ffmpeg-0.1.0/tests/integration/sync/test_tmp_file.py

@@ -0,0 +1,25 @@
+import urllib.request
+
+from very_good_ffmpeg import VGF
+
+SAMPLE_URL = "https://storage.verygoodffmpeg.com/sample.mp4"
+
+
+def test_tmp_file_upload_download_and_run(client: VGF):
+    with urllib.request.urlopen(SAMPLE_URL) as r:
+        original = r.read()
+
+    download_url = client.files.upload(original, "video/mp4")
+
+    with urllib.request.urlopen(download_url) as r:
+        downloaded = r.read()
+
+    assert downloaded == original
+
+    job = client.run(
+        input_files={"input": download_url},
+        output_files=["output.mp4"],
+        ffmpeg_commands=["-i {{input}} -t 2 {{output.mp4}}"],
+        wait=True,
+    )
+    assert job.status == "succeeded"

very_good_ffmpeg-0.1.0/tests/integration/sync/test_webhook.py

@@ -0,0 +1,14 @@
+from very_good_ffmpeg import VGF
+
+WEBHOOK_URL = "https://example.com/webhook"
+
+
+def test_webhook_url_reflected(client: VGF):
+    job = client.run(
+        input_files={"input": "https://storage.verygoodffmpeg.com/sample.mp4"},
+        output_files=["output.mp4"],
+        ffmpeg_commands=["-i {{input}} -t 5 {{output.mp4}}"],
+        webhook_url=WEBHOOK_URL,
+        wait=True,
+    )
+    assert job.webhook_url == WEBHOOK_URL

very_good_ffmpeg-0.1.0/tests/integration/test_examples.py

@@ -0,0 +1,28 @@
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+EXAMPLES_DIR = Path(__file__).parent.parent.parent / "examples"
+
+
+def _run(script: str) -> str:
+    result = subprocess.run(
+        [sys.executable, script],
+        cwd=EXAMPLES_DIR,
+        env={**os.environ},
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 0, result.stderr
+    return result.stdout
+
+
+def test_basic_example():
+    output = _run("basic.py")
+    assert "Jobs:" in output
+
+
+def test_async_basic_example():
+    output = _run("async_basic.py")
+    assert "Jobs:" in output

very_good_ffmpeg-0.1.0/very_good_ffmpeg/__init__.py

@@ -0,0 +1,6 @@
+from ._client import VGF
+from ._models import Job, JobList, PagingParams, TmpFile
+from ._exceptions import VGFError, VGFAuthError, VGFNotFoundError
+
+__all__ = ["VGF", "Job", "JobList", "PagingParams", "TmpFile", "VGFError", "VGFAuthError", "VGFNotFoundError"]
+__version__ = "0.1.0"

very_good_ffmpeg-0.1.0/very_good_ffmpeg/_client.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from ._exceptions import VGFAuthError, VGFError, VGFNotFoundError
+from ._models import Job, JobList, PagingParams, TmpFile
+
+_BASE_URL = "https://verygoodffmpeg.com/api"
+_DEFAULT_TIMEOUT = 30
+
+log = logging.getLogger("very_good_ffmpeg")
+
+
+def _raise_for_status(status: int, body: bytes, url: str) -> None:
+    if status == 401:
+        raise VGFAuthError("Invalid or missing API key", status_code=status)
+    if status == 404:
+        raise VGFNotFoundError(f"Not found: {url}", status_code=status)
+    if status >= 400:
+        try:
+            msg = json.loads(body).get("message", body.decode())
+        except Exception:
+            msg = body.decode(errors="replace")
+        raise VGFError(msg, status_code=status)
+
+
+def _parse_paging(raw: dict) -> PagingParams:
+    p = raw.get("pagingParams", {})
+    return PagingParams(
+        limit=p.get("limit", 0),
+        offset=p.get("offset", 0),
+        total=p.get("total", 0),
+        has_more=p.get("hasMore", False),
+    )
+
+
+class _JobsResource:
+    def __init__(self, client: VGF):
+        self._c = client
+
+    def get(self, job_id: str) -> Job:
+        data = self._c._request("GET", f"/jobs/{job_id}")
+        return Job._from_dict(data["data"], client=self._c)
+
+    async def aget(self, job_id: str) -> Job:
+        data = await self._c._arequest("GET", f"/jobs/{job_id}")
+        return Job._from_dict(data["data"], client=self._c)
+
+    def list(self, *, limit: int = 50, offset: int = 0) -> JobList:
+        raw = self._c._request("GET", f"/jobs?limit={limit}&offset={offset}")
+        return JobList(
+            data=[Job._from_dict(j, client=self._c) for j in raw["data"]],
+            paging_params=_parse_paging(raw),
+        )
+
+    async def alist(self, *, limit: int = 50, offset: int = 0) -> JobList:
+        raw = await self._c._arequest("GET", f"/jobs?limit={limit}&offset={offset}")
+        return JobList(
+            data=[Job._from_dict(j, client=self._c) for j in raw["data"]],
+            paging_params=_parse_paging(raw),
+        )
+
+    def cancel(self, job_id: str) -> Job:
+        data = self._c._request("POST", f"/jobs/{job_id}/cancel")
+        return Job._from_dict(data["data"], client=self._c)
+
+    async def acancel(self, job_id: str) -> Job:
+        data = await self._c._arequest("POST", f"/jobs/{job_id}/cancel")
+        return Job._from_dict(data["data"], client=self._c)
+
+
+class _FilesResource:
+    def __init__(self, client: VGF):
+        self._c = client
+
+    def prepare(self) -> TmpFile:
+        data = self._c._request("POST", "/tmp-file")
+        return TmpFile(
+            upload_url=data["data"]["upload_url"],
+            download_url=data["data"]["download_url"],
+        )
+
+    async def aprepare(self) -> TmpFile:
+        data = await self._c._arequest("POST", "/tmp-file")
+        return TmpFile(
+            upload_url=data["data"]["upload_url"],
+            download_url=data["data"]["download_url"],
+        )
+
+    def upload(self, data: bytes | str | Path, content_type: str = "application/octet-stream") -> str:
+        tmp = self.prepare()
+        body = data if isinstance(data, bytes) else Path(data).read_bytes()
+        _put(tmp.upload_url, body, content_type)
+        return tmp.download_url
+
+    async def aupload(self, data: bytes | str | Path, content_type: str = "application/octet-stream") -> str:
+        tmp = await self.aprepare()
+        body = data if isinstance(data, bytes) else Path(data).read_bytes()
+        await asyncio.to_thread(_put, tmp.upload_url, body, content_type)
+        return tmp.download_url
+
+
+def _put(url: str, body: bytes, content_type: str = "application/octet-stream") -> None:
+    log.debug("PUT %s (%d bytes)", url, len(body))
+    req = urllib.request.Request(url, data=body, method="PUT")
+    req.add_header("Content-Type", content_type)
+    req.add_header("Content-Length", str(len(body)))
+    try:
+        with urllib.request.urlopen(req, timeout=_DEFAULT_TIMEOUT) as resp:
+            log.debug("PUT response: %s", resp.status)
+            if resp.status not in (200, 204):
+                raise VGFError(f"Upload failed with status {resp.status}")
+    except urllib.error.HTTPError as e:
+        raise VGFError(f"Upload failed: {e}", status_code=e.code) from e
+
+
+class VGF:
+    def __init__(self, api_key: str, base_url: str = _BASE_URL):
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self.jobs = _JobsResource(self)
+        self.files = _FilesResource(self)
+
+    def _request(self, method: str, path: str, body: dict | None = None) -> dict:
+        url = self._base_url + path
+        log.debug("%s %s", method, url)
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(url, data=data, method=method)
+        req.add_header("Authorization", f"Bearer {self._api_key}")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("Accept", "application/json")
+        try:
+            with urllib.request.urlopen(req, timeout=_DEFAULT_TIMEOUT) as resp:
+                result = json.loads(resp.read())
+                log.debug("%s %s -> 200", method, url)
+                return result
+        except urllib.error.HTTPError as e:
+            raw = e.read()
+            log.debug("%s %s -> %s", method, url, e.code)
+            _raise_for_status(e.code, raw, url)
+
+    async def _arequest(self, method: str, path: str, body: dict | None = None) -> dict:
+        return await asyncio.to_thread(self._request, method, path, body)
+
+    def run(
+        self,
+        input_files: dict[str, str],
+        output_files: list[str],
+        ffmpeg_commands: list[str],
+        *,
+        webhook_url: str | None = None,
+        machine: str = "cpu",
+        wait: bool = False,
+    ) -> Job:
+        body: dict = {
+            "input_files": input_files,
+            "output_files": output_files,
+            "ffmpeg_commands": ffmpeg_commands,
+            "machine": machine,
+        }
+        if webhook_url is not None:
+            body["webhook_url"] = webhook_url
+        qs = "?wait=true" if wait else ""
+        data = self._request("POST", f"/ffmpeg{qs}", body)
+        job = Job._from_dict(data["data"], client=self)
+        log.debug("job %s submitted, status=%s", job.id, job.status)
+        return job
+
+    async def arun(
+        self,
+        input_files: dict[str, str],
+        output_files: list[str],
+        ffmpeg_commands: list[str],
+        *,
+        webhook_url: str | None = None,
+        machine: str = "cpu",
+        wait: bool = False,
+    ) -> Job:
+        body: dict = {
+            "input_files": input_files,
+            "output_files": output_files,
+            "ffmpeg_commands": ffmpeg_commands,
+            "machine": machine,
+        }
+        if webhook_url is not None:
+            body["webhook_url"] = webhook_url
+        qs = "?wait=true" if wait else ""
+        data = await self._arequest("POST", f"/ffmpeg{qs}", body)
+        job = Job._from_dict(data["data"], client=self)
+        log.debug("job %s submitted, status=%s", job.id, job.status)
+        return job

very_good_ffmpeg-0.1.0/very_good_ffmpeg/_exceptions.py

@@ -0,0 +1,12 @@
+class VGFError(Exception):
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class VGFNotFoundError(VGFError):
+    pass
+
+
+class VGFAuthError(VGFError):
+    pass

very_good_ffmpeg-0.1.0/very_good_ffmpeg/_models.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._client import VGF
+
+_TERMINAL = {"succeeded", "failed", "cancelled"}
+
+log = logging.getLogger("very_good_ffmpeg")
+
+
+@dataclass
+class Job:
+    id: str
+    status: str
+    queued_at: str
+    started_at: str | None
+    finished_at: str | None
+    created_at: str
+    updated_at: str
+    error_message: str
+    ffmpeg_commands: list[str]
+    input_files: dict[str, str]
+    output_files: dict[str, str]
+    webhook_url: str | None
+    total_input_bytes: int | None
+    total_output_bytes: int | None
+
+    _client: VGF = field(repr=False, compare=False, default=None)
+
+    @classmethod
+    def _from_dict(cls, data: dict, client: VGF = None) -> Job:
+        return cls(
+            id=data["id"],
+            status=data["status"],
+            queued_at=data["queued_at"],
+            started_at=data.get("started_at"),
+            finished_at=data.get("finished_at"),
+            created_at=data["created_at"],
+            updated_at=data["updated_at"],
+            error_message=data.get("error_message", ""),
+            ffmpeg_commands=data.get("ffmpeg_commands", []),
+            input_files=data.get("input_files", {}),
+            output_files=data.get("output_files", {}),
+            webhook_url=data.get("webhook_url"),
+            total_input_bytes=data.get("total_input_bytes"),
+            total_output_bytes=data.get("total_output_bytes"),
+            _client=client,
+        )
+
+    def _apply_update(self, updated: Job) -> None:
+        self.status = updated.status
+        self.started_at = updated.started_at
+        self.finished_at = updated.finished_at
+        self.output_files = updated.output_files
+        self.error_message = updated.error_message
+        self.total_input_bytes = updated.total_input_bytes
+        self.total_output_bytes = updated.total_output_bytes
+        self.updated_at = updated.updated_at
+
+    def wait(self, poll_interval: float = 2.0, timeout: float | None = None) -> Job:
+        deadline = time.monotonic() + timeout if timeout else None
+        while self.status not in _TERMINAL:
+            if deadline and time.monotonic() >= deadline:
+                raise TimeoutError(f"Job {self.id} did not finish within timeout")
+            log.debug("job %s polling, status=%s, sleeping %.1fs", self.id, self.status, poll_interval)
+            time.sleep(poll_interval)
+            self._apply_update(self._client.jobs.get(self.id))
+        log.debug("job %s terminal, status=%s", self.id, self.status)
+        return self
+
+    async def async_wait(self, poll_interval: float = 2.0, timeout: float | None = None) -> Job:
+        deadline = time.monotonic() + timeout if timeout else None
+        while self.status not in _TERMINAL:
+            if deadline and time.monotonic() >= deadline:
+                raise TimeoutError(f"Job {self.id} did not finish within timeout")
+            log.debug("job %s polling, status=%s, sleeping %.1fs", self.id, self.status, poll_interval)
+            await asyncio.sleep(poll_interval)
+            self._apply_update(await self._client.jobs.aget(self.id))
+        log.debug("job %s terminal, status=%s", self.id, self.status)
+        return self
+
+    def cancel(self) -> Job:
+        return self._client.jobs.cancel(self.id)
+
+    async def acancel(self) -> Job:
+        return await self._client.jobs.acancel(self.id)
+
+
+@dataclass
+class PagingParams:
+    limit: int
+    offset: int
+    total: int
+    has_more: bool
+
+
+@dataclass
+class JobList:
+    data: list[Job]
+    paging_params: PagingParams
+
+
+@dataclass
+class TmpFile:
+    upload_url: str
+    download_url: str