Metadata-Version: 2.5
Name: comprestack
Version: 0.1.0
Summary: Official Python SDK for the Comprestack image optimization API
Project-URL: Homepage, https://www.comprestack.com/docs
Project-URL: Documentation, https://www.comprestack.com/docs#sdk
Project-URL: Repository, https://github.com/MichaelGenesisII/Comprestack-API/tree/main/sdk/python
Project-URL: OpenAPI, https://api.comprestack.com/openapi.yaml
Author: Comprestack
License-Expression: MIT
Keywords: avif,compression,comprestack,image,sdk,webp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Multimedia :: Graphics
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# comprestack

Official Python SDK for the [Comprestack](https://www.comprestack.com) image optimization API.

Compress or convert images from scripts, Django, FastAPI, and workers with a small typed client. Same REST surface as the [API docs](https://www.comprestack.com/docs) and [OpenAPI](https://api.comprestack.com/openapi.yaml).

[![PyPI version](https://img.shields.io/pypi/v/comprestack.svg)](https://pypi.org/project/comprestack/)
[![Python](https://img.shields.io/pypi/pyversions/comprestack.svg)](https://pypi.org/project/comprestack/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

---

## Install

```bash
pip install comprestack
```

**Requirements:** Python 3.9+ (uses [httpx](https://www.python-httpx.org/)).

Create an API key in the [dashboard](https://www.comprestack.com/dashboard?section=api), then set:

```bash
export COMPRESTACK_API_KEY=csk_live_…
```

### Security

API keys must stay on the **server**. Do not put them in browsers, mobile apps, or public repositories.

---

## Quick start

```python
import os
from pathlib import Path

from comprestack import Comprestack

client = Comprestack(api_key=os.environ["COMPRESTACK_API_KEY"])

job = client.convert(
    ["photo.jpg"],
    format="webp",
    quality="balanced",
    maxWidth=1600,
)

Path("photo.webp").write_bytes(client.download(job))
print(f"Saved {job['files'][0]['saved_percent']}% · {job['usage']['remaining']} left")
```

Compress without changing format:

```python
job = client.compress(["hero.png"], quality="high")
```

Use as a context manager to close the HTTP client:

```python
with Comprestack(api_key=os.environ["COMPRESTACK_API_KEY"]) as client:
    job = client.compress([b"..."])
```

---

## What you can do

| Goal | Method |
|------|--------|
| Shrink, keep format | `compress(files, …)` |
| Change format + shrink | `convert(files, format=…, …)` |
| Re-fetch job metadata | `get_job(id)` |
| Download ZIP / result | `download(job)` or `download(download_url)` |
| Download one file in a batch | `download_file(job_id, index)` |
| Check quota | `usage()` |
| White-label billing report | `room_report(room_id)` |

Jobs finish in the same request. Results expire after about one hour.

---

## Inputs

| Input | Example |
|-------|---------|
| File path | `"photo.jpg"` or `Path("photo.jpg")` |
| Bytes | `b"…"`, `bytearray`, `memoryview` |
| File object | `open("photo.jpg", "rb")` |
| Named bytes | `("hero.png", data)` or `{"data": data, "filename": "hero.png"}` |

---

## Options

Available on both `compress` and `convert`:

| Option | Description |
|--------|-------------|
| `quality` | `"balanced"` (default), `"high"`, `"smallest"`, or `1–100` on Pro/Business |
| `format` | **convert only** — `webp`, `avif`, `jpeg`, `png`, `gif`, `tiff`, `bmp`, `ico` |
| `maxWidth` / `maxHeight` | Downscale to fit (never enlarges) |
| `target_kb` | Aim for a max file size (Pro/Business) |
| `lossless` | Pixel-perfect where the codec allows (Pro/Business) |
| `keep_metadata` | Keep EXIF / color profile (default strips metadata, including GPS) |

---

## Client configuration

```python
client = Comprestack(
    api_key=os.environ["COMPRESTACK_API_KEY"],
    # base_url="https://api.comprestack.com/api/v1",
    # timeout=300,
    # max_retries=2,  # extra tries on 429 / 503 (honours Retry-After)
    # on_progress=lambda e: print(e["phase"], e["path"], e["attempt"]),
    # headers={"X-Request-Id": "order-4417"},
)
```

---

## Errors

Failed requests raise `ComprestackError`:

```python
from comprestack import Comprestack, ComprestackError

try:
    client.compress(["huge.tiff"])
except ComprestackError as err:
    print(err.status, err.code, err.message)
    # err.retry_after — seconds, when the API sent Retry-After
    raise
```

Common codes: `unauthorized`, `limit_reached`, `file_too_large`, `rate_limited`, `busy`, `plan_required`.

---

## Links

- [API reference](https://www.comprestack.com/docs)
- [OpenAPI 3.1](https://api.comprestack.com/openapi.yaml)
- [Dashboard — API keys](https://www.comprestack.com/dashboard?section=api)
- [TypeScript SDK](https://www.npmjs.com/package/comprestack)
- [Source](https://github.com/MichaelGenesisII/Comprestack-API/tree/main/sdk/python)

---

## License

MIT © Comprestack
