thumbrella-client

Python client for Thumbrella — a fast thumbnail API for images, video, documents, and more.

Install

pip install thumbrella-client

Or with uv:

uv add thumbrella-client

Async streaming needs aiohttp:

pip install "thumbrella-client[async]"

Quickstart

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:

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 for the full Result and Media field reference.

Errors

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:

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

# 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/ for full source.

Next Steps

• Client docs — full API reference and examples
• Thumbrella — main site
• GitHub — source and issues

License

Apache-2.0. See LICENSE.