thumbrella-client 0.5.0__tar.gz

thumbrella_client-0.5.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+recursive-include examples *.py
+recursive-include src/thumbrella *.jpeg

thumbrella_client-0.5.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: thumbrella-client
+Version: 0.5.0
+Summary: Python client for the Thumbrella thumbnail API — typed results, async streaming, pluggable caching
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://thumbrella.dev
+Project-URL: Repository, https://github.com/thumbrella-dev/clients
+Project-URL: Issues, https://github.com/thumbrella-dev/clients/issues
+Project-URL: Documentation, https://thumbrella.dev/docs/client
+Keywords: thumbrella,thumbnail,thumbnails,image,media,streaming
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.32.0
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.9.0; extra == "async"
+
+# thumbrella-client
+
+Python client for [Thumbrella](https://thumbrella.dev) — a fast thumbnail API
+for images, video, documents, and more.
+
+[![PyPI version](https://img.shields.io/pypi/v/thumbrella-client)](https://pypi.org/project/thumbrella-client/)
+[![Python](https://img.shields.io/pypi/pyversions/thumbrella-client)](https://pypi.org/project/thumbrella-client/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](https://github.com/thumbrella-dev/clients/blob/main/LICENSE)
+
+## Install
+
+```bash
+pip install thumbrella-client
+```
+
+Or with uv:
+
+```bash
+uv add thumbrella-client
+```
+
+Async streaming needs `aiohttp`:
+
+```bash
+pip install "thumbrella-client[async]"
+```
+
+## Quickstart
+
+```python
+import thumbrella
+
+tbr = thumbrella.Client().verify()
+result = tbr.thumb("https://example.com/photo.jpg")
+
+print(result.status, len(result.media.thumbnail), "bytes")
+
+# Use with Pillow
+from PIL import Image
+img = Image.open(result.media.thumbnail.io)
+```
+
+
+
+## How It Works
+
+Create a `Client`, call `verify()` to check connectivity, then use `thumb()`,
+`batch()`, or `stream()` to generate thumbnails.
+
+The client reads `$TBR_CONNECT` for server config. Override it with a connect
+string:
+
+```python
+tbr = thumbrella.Client("http://localhost:3114")                  # local dev
+tbr = thumbrella.Client("https://cloud.thumbrella.dev,tbr_s_...")  # cloud token
+```
+
+Every URL gets a `Result` — failures get a placeholder image too. Use
+`result.verify()` to raise on failure, or check `result.is_success()` for inline
+handling. See the [client docs](https://thumbrella.dev/docs/client/) for the
+full `Result` and `Media` field reference.
+
+### Errors
+
+```python
+from thumbrella import ThumbError, ConnectionError, TimeoutError, VerifyError
+```
+
+All errors extend `ThumbError`. `Client.verify()` raises `VerifyError` on bad
+config. Network issues raise `ConnectionError` or `TimeoutError`. Per-result
+failures return a `Result` with a failure status — call `result.verify()` to
+convert to an exception.
+
+### Caching
+
+Each `Client` defaults to an in-memory LRU cache (256 entries). Disable with
+`caches=[]` or layer custom backends:
+
+```python
+tbr = thumbrella.Client(caches=[])                      # no caching
+tbr = thumbrella.Client(caches=[thumbrella.MemoryCache(max_items=1000)])
+```
+
+Implement `thumbrella.Cache` to add persistent storage (SQLite, S3, etc.).
+
+
+## Examples
+
+```bash
+# Download one thumbnail to disk (with PIL inspection)
+python examples/basic.py https://demo.thumbrella.dev/media/raw-canon.cr2 cam.jpeg
+
+# Stream batch progress
+python examples/stream.py https://example.com/a.jpg https://example.com/b.png
+
+# Build a collage grid from streamed thumbnails
+python examples/collage.py urls.txt
+
+# Batch download with persistent caching
+python examples/gallery.py https://example.com/a.jpg https://example.com/b.png
+```
+
+See [`examples/`](./examples) for full source.
+
+
+## Next Steps
+
+- **[Client docs](https://thumbrella.dev/docs/client/)** — full API reference and examples
+- **[Thumbrella](https://thumbrella.dev)** — main site
+- **[GitHub](https://github.com/thumbrella-dev/clients)** — source and issues
+
+## License
+
+Apache-2.0. See [LICENSE](https://github.com/thumbrella-dev/clients/blob/main/LICENSE).
+
+

thumbrella_client-0.5.0/README.md

@@ -0,0 +1,116 @@
+# thumbrella-client
+
+Python client for [Thumbrella](https://thumbrella.dev) — a fast thumbnail API
+for images, video, documents, and more.
+
+[![PyPI version](https://img.shields.io/pypi/v/thumbrella-client)](https://pypi.org/project/thumbrella-client/)
+[![Python](https://img.shields.io/pypi/pyversions/thumbrella-client)](https://pypi.org/project/thumbrella-client/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](https://github.com/thumbrella-dev/clients/blob/main/LICENSE)
+
+## Install
+
+```bash
+pip install thumbrella-client
+```
+
+Or with uv:
+
+```bash
+uv add thumbrella-client
+```
+
+Async streaming needs `aiohttp`:
+
+```bash
+pip install "thumbrella-client[async]"
+```
+
+## Quickstart
+
+```python
+import thumbrella
+
+tbr = thumbrella.Client().verify()
+result = tbr.thumb("https://example.com/photo.jpg")
+
+print(result.status, len(result.media.thumbnail), "bytes")
+
+# Use with Pillow
+from PIL import Image
+img = Image.open(result.media.thumbnail.io)
+```
+
+
+
+## How It Works
+
+Create a `Client`, call `verify()` to check connectivity, then use `thumb()`,
+`batch()`, or `stream()` to generate thumbnails.
+
+The client reads `$TBR_CONNECT` for server config. Override it with a connect
+string:
+
+```python
+tbr = thumbrella.Client("http://localhost:3114")                  # local dev
+tbr = thumbrella.Client("https://cloud.thumbrella.dev,tbr_s_...")  # cloud token
+```
+
+Every URL gets a `Result` — failures get a placeholder image too. Use
+`result.verify()` to raise on failure, or check `result.is_success()` for inline
+handling. See the [client docs](https://thumbrella.dev/docs/client/) for the
+full `Result` and `Media` field reference.
+
+### Errors
+
+```python
+from thumbrella import ThumbError, ConnectionError, TimeoutError, VerifyError
+```
+
+All errors extend `ThumbError`. `Client.verify()` raises `VerifyError` on bad
+config. Network issues raise `ConnectionError` or `TimeoutError`. Per-result
+failures return a `Result` with a failure status — call `result.verify()` to
+convert to an exception.
+
+### Caching
+
+Each `Client` defaults to an in-memory LRU cache (256 entries). Disable with
+`caches=[]` or layer custom backends:
+
+```python
+tbr = thumbrella.Client(caches=[])                      # no caching
+tbr = thumbrella.Client(caches=[thumbrella.MemoryCache(max_items=1000)])
+```
+
+Implement `thumbrella.Cache` to add persistent storage (SQLite, S3, etc.).
+
+
+## Examples
+
+```bash
+# Download one thumbnail to disk (with PIL inspection)
+python examples/basic.py https://demo.thumbrella.dev/media/raw-canon.cr2 cam.jpeg
+
+# Stream batch progress
+python examples/stream.py https://example.com/a.jpg https://example.com/b.png
+
+# Build a collage grid from streamed thumbnails
+python examples/collage.py urls.txt
+
+# Batch download with persistent caching
+python examples/gallery.py https://example.com/a.jpg https://example.com/b.png
+```
+
+See [`examples/`](./examples) for full source.
+
+
+## Next Steps
+
+- **[Client docs](https://thumbrella.dev/docs/client/)** — full API reference and examples
+- **[Thumbrella](https://thumbrella.dev)** — main site
+- **[GitHub](https://github.com/thumbrella-dev/clients)** — source and issues
+
+## License
+
+Apache-2.0. See [LICENSE](https://github.com/thumbrella-dev/clients/blob/main/LICENSE).
+
+

thumbrella_client-0.5.0/examples/basic.py

@@ -0,0 +1,57 @@
+"""basic.py - download one thumbnail to a file.
+
+Usage:
+    python basic.py https://www.python.org/static/img/python-logo.png thumb.jpeg
+
+Gets a generated thumbnail for any URL. If there are problems connecting
+to Thumbrella or accessing the media URL this will fail with an explanation.
+"""
+
+import argparse
+from pathlib import Path
+
+import thumbrella
+
+
+def thumbnail(url: str, path: Path):
+    """Generate thumbnail for url and save to disk."""
+    tbr = thumbrella.Client().verify()
+    result = tbr.thumb(url)
+
+    m = result.media
+    if m is None:
+        print("Thumbnail did not succeed:", result.status)
+
+    # Simple result metadata
+    print(
+        f"{m.kind if m else '?'} {m.file_size if m else '?':,} bytes ->  "
+        f"{len(m.thumbnail) if m else 0:,} bytes {path}"
+    )
+
+    # Load thumbnail into PIL and process
+    try:
+        from PIL import Image
+        img = Image.open(m.thumbnail.io)
+        print("mode:", img.mode, "width:", img.width, "height:", img.height)
+        pixel = img.getpixel((img.width // 2, img.height // 2))
+        print("center pixel:", pixel)
+    except ImportError:
+        pass
+
+    # Write image to disk
+    path.write_bytes(m.thumbnail.bytes if m else b"")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="download a thumbnail")
+    parser.add_argument("url", help="media URL to thumbnail")
+    parser.add_argument("path", type=Path, help="output jpeg path")
+    args = parser.parse_args()
+    try:
+        thumbnail(args.url, args.path)
+    except thumbrella.ThumbError as err:
+        raise SystemExit(err)
+
+
+if __name__ == "__main__":
+    main()

thumbrella_client-0.5.0/examples/collage.py

@@ -0,0 +1,112 @@
+"""collage.py — stream thumbnails into a grid collage.
+
+Usage:
+    python collage.py urls.txt collage.jpg
+
+urls.txt should contain one URL per line (# comments and blank lines ok).
+
+Streams results live and reports timing + cache status.  Thumbnails are
+arranged on a 6-column grid (3 columns when fewer than 8 items).
+"""
+
+import argparse
+import asyncio
+import time
+from pathlib import Path
+
+import thumbrella
+
+THUMB_W, THUMB_H = 250, 200
+SPACING = 4
+COLS = 6
+COLS_SMALL = 3
+
+
+async def collage(urls_file: Path, out_path: Path) -> None:
+    urls = [
+        line.strip()
+        for line in urls_file.read_text().splitlines()
+        if line.strip() and not line.startswith("#")
+    ]
+
+    # Client reads TBR_CONNECT env var for server URL or cloud token.
+    tbr = thumbrella.Client().verify()
+
+    placed: list[thumbrella.Result] = []
+    placeholders = 0
+    t0 = time.monotonic()
+
+    async for result in tbr.stream(urls):
+        elapsed = time.monotonic() - t0
+
+        # Intermediate result — tier1 delegating to a renderer.
+        if result.status == "intermediate":
+            placeholders += 1
+            print(f"  ...      {result.url}")
+            continue
+
+        if result.is_success():
+            placed.append(result)
+            tag = _cache_tag(result)
+            print(
+                f"  {tag:6s}  {result.duration:>5.0f}ms  "
+                f"{result.kind:8s}  {result.mime or '':20s}  {result.url}"
+            )
+        else:
+            print(f"  FAIL     {result.status:16s}  {result.url}")
+
+    if not placed:
+        raise SystemExit("no thumbnails to collage")
+
+    # Build collage grid.
+    cols = COLS_SMALL if len(placed) < 8 else COLS
+    rows = (len(placed) + cols - 1) // cols
+    cw, ch = THUMB_W + SPACING, THUMB_H + SPACING
+    canvas_w = cols * cw + SPACING
+    canvas_h = rows * ch + SPACING
+
+    from PIL import Image
+
+    grid = Image.new("RGB", (canvas_w, canvas_h), (255, 255, 255))
+
+    for i, r in enumerate(placed):
+        col, row = i % cols, i // cols
+        x, y = SPACING + col * cw, SPACING + row * ch
+        img = Image.open(r.thumbnail.io)
+        img.load()
+        grid.paste(img, (x, y))
+
+    grid.save(out_path, quality=85)
+    print(
+        f"\n{len(placed)} thumbnails  "
+        f"{rows}x{cols}  "
+        f"{grid.size[0]}x{grid.size[1]} px  "
+        f"{placeholders} placeholders  ->  {out_path}"
+    )
+
+
+def _cache_tag(result: thumbrella.Result) -> str:
+    """Short label for how this thumbnail was produced."""
+    src = result.source
+    if src == thumbrella.Source.CLIENT:
+        return "client"
+    if src == thumbrella.Source.CACHE:
+        return "cached"
+    if src == thumbrella.Source.SHORTCUT:
+        return "embed"
+    return "render"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="stream thumbnails into a collage")
+    parser.add_argument("urls", type=Path, help="file with one media URL per line")
+    parser.add_argument("out", type=Path, help="output collage JPEG path")
+    args = parser.parse_args()
+    try:
+        asyncio.run(collage(args.urls, args.out))
+    except thumbrella.ThumbError as err:
+        raise SystemExit(err)
+
+
+if __name__ == "__main__":
+    main()

thumbrella_client-0.5.0/examples/gallery.py

@@ -0,0 +1,113 @@
+"""gallery.py — stream a batch of URLs with live progress and local caching.
+
+Usage:
+    python gallery.py urls.txt thumbs/
+
+urls.txt should contain one URL per line (# comments and blank lines ok).
+
+Re-running with the same output directory skips unchanged thumbnails by
+persisting cache tokens in thumbs/.thumbrella_cache.json.
+
+"""
+
+import argparse
+import asyncio
+import json
+from pathlib import Path
+
+import thumbrella
+
+
+async def gallery(urls_file: Path, out_dir: Path) -> None:
+    """Stream thumbnails for urls in *urls_file*, save to *out_dir*."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+    urls = [
+        line.strip()
+        for line in urls_file.read_text().splitlines()
+        if line.strip() and not line.startswith("#")
+    ]
+
+    # Restore persistent cache tokens from last run.
+    cache_path = out_dir / ".thumbrella_cache.json"
+    prev_cache: dict[str, str] = {}
+    try:
+        prev_cache = json.loads(cache_path.read_text())
+    except (FileNotFoundError, json.JSONDecodeError):
+        pass
+
+    # Client reads TBR_CONNECT env var for server URL or cloud token.
+    tbr = thumbrella.Client().verify()
+    image_loader = await _ensure_pil()
+
+    image_cache: dict[int, object] = {}  # key → PIL Image
+    new_cache: dict[str, str] = {}
+    new_count, unchanged, failed = 0, 0, 0
+
+    async for result in tbr.stream(urls):
+        # Restore cache token so the server can 304 on unchanged media.
+        if result.url in prev_cache:
+            result.cache = prev_cache[result.url]
+
+        if result.is_success():
+            if result.is_fresh():
+                unchanged += 1
+            else:
+                new_count += 1
+
+            if result.cache:
+                new_cache[result.url] = result.cache
+
+            # Decode with PIL, deduplicated by thumbnail content key.
+            img = image_cache.get(result.thumbnail.key)
+            if img is None and image_loader is not None:
+                img = image_loader(result.thumbnail.io)
+                image_cache[result.thumbnail.key] = img
+
+            # Save thumbnail.
+            stem = result.url.rstrip("/").split("/")[-1] or "thumb"
+            safe = "".join(c if c.isalnum() or c in "._-" else "_" for c in stem)
+            path = out_dir / f"{safe}.jpg"
+            path.write_bytes(result.thumbnail.bytes)
+
+            w, h = img.size if img else (0, 0)
+            tag = "(cached)" if result.is_fresh() else ""
+            print(f"  {tag:9s}{result.kind:8s} {w:>4d}x{h:<4d}  {result.mime:20s}  {result.url}")
+        else:
+            failed += 1
+            print(f"  FAIL    {result.status:16s}  {result.url}")
+
+    if new_cache:
+        cache_path.write_text(json.dumps(new_cache, indent=2))
+
+    print(f"\n{new_count} new, {unchanged} unchanged, {failed} failed")
+
+
+async def _ensure_pil():
+    """Return an image loader function, or None if Pillow is missing."""
+    try:
+        from PIL import Image
+    except ImportError:
+        print("(install Pillow for image dimensions)")
+        return None
+
+    def load(io) -> object:
+        img = Image.open(io)
+        img.load()
+        return img
+
+    return load
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="stream thumbnails from a URL list")
+    parser.add_argument("urls", type=Path, help="file with one media URL per line")
+    parser.add_argument("out_dir", type=Path, help="directory for output JPEGs")
+    args = parser.parse_args()
+    try:
+        asyncio.run(gallery(args.urls, args.out_dir))
+    except thumbrella.ThumbError as err:
+        raise SystemExit(err)
+
+
+if __name__ == "__main__":
+    main()

thumbrella_client-0.5.0/examples/stream.py

@@ -0,0 +1,71 @@
+"""stream.py - show progress on async thumbnail rendering.
+
+Usage:
+    python stream.py https://www.python.org/static/img/python-logo.png https://www.pygame.org/docs/_images/pygame_powered.png https://pypi.org/unknown.jpg
+
+Gets a generated thumbnail for any URL. If there are problems connecting
+to Thumbrella or accessing the media URL this will fail with an explanation.
+"""
+
+import asyncio
+import argparse
+import time
+
+import thumbrella
+
+
+
+def main():
+    parser = argparse.ArgumentParser(description="monitor streamed results")
+    parser.add_argument("urls", nargs="+", help="media URLs to stream")
+    parser.add_argument("--batch", action="store_true", help="use sync back instead")
+    args = parser.parse_args()
+
+    tbr = thumbrella.Client().verify()
+    try:
+        if args.batch:
+            batched(tbr, args.urls)
+        else:
+            asyncio.run(streamed(tbr, args.urls))
+    except thumbrella.ThumbError as err:
+        raise SystemExit(err)
+
+
+async def streamed(tbr: thumbrella.Client, urls: list[str]):
+    """Monitor streamed results."""
+    # async with thumbrella.Client() as tbr:
+    #     tbr.verify()
+    async with tbr:
+        indices = _index(urls)
+        start = time.time()
+        stream = tbr.stream(urls)
+        async for result in stream:
+            _report(start, indices.get(result.url, "XXX"), result)
+
+
+def batched(tbr: thumbrella.Client, urls: list[str]):
+    """Get all results in one single call"""
+    indices = _index(urls)
+    start = time.time()
+    batch = tbr.batch(urls)
+    for result in batch:
+        _report(start, indices.get(result.url, "XXX"), result)
+
+
+def _index(urls: list[str]):
+    """Assign report index to each url"""
+    indices = {u: f"{i:03d}" for i, u in enumerate(urls, 1)}
+    for u, i in indices.items():
+        print(f"{i}: {u}")
+    return indices
+
+def _report(start: float, idx: str, result: thumbrella.Result):
+    """One line report for each result"""
+    kind = f"{result.media.kind}({result.media.extension})" if result.media else "<nomedia>"
+    print(
+        f"{(time.time() - start) * 1000:,.0f}ms {idx}"
+        f" - {result.status} {kind} {result.source} {result.message or ''}"
+    )
+
+if __name__ == "__main__":
+    main()

thumbrella_client-0.5.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "thumbrella-client"
+version = "0.5.0"
+description = "Python client for the Thumbrella thumbnail API — typed results, async streaming, pluggable caching"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+keywords = ["thumbrella", "thumbnail", "thumbnails", "image", "media", "streaming"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Multimedia :: Graphics",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+
+dependencies = [
+  "requests>=2.32.0",
+]
+
+[project.optional-dependencies]
+async = ["aiohttp>=3.9.0"]
+
+[project.urls]
+Homepage = "https://thumbrella.dev"
+Repository = "https://github.com/thumbrella-dev/clients"
+Issues = "https://github.com/thumbrella-dev/clients/issues"
+Documentation = "https://thumbrella.dev/docs/client"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+thumbrella = ["*.jpg"]
+

thumbrella_client-0.5.0/setup.cfg

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