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).


