Metadata-Version: 2.4
Name: imagecompressor
Version: 1.0.0
Summary: Client for the ImageCompressor.si image API: compress, convert, resize, remove backgrounds, upscale, OCR, pipelines and jobs.
License: MIT
Project-URL: Homepage, https://imagecompressor.si/developers
Project-URL: Documentation, https://imagecompressor.si/developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# imagecompressor (Python)

Client for the [ImageCompressor.si](https://imagecompressor.si/developers) image API. Standard library only; Python 3.8+.

```python
import os
from imagecompressor import ImageCompressor

client = ImageCompressor(os.environ["IMAGECOMPRESSOR_API_KEY"])

# Compress to WebP, at most 1600 px wide, letting smart mode pick the quality.
with open("photo.jpg", "rb") as handle:
    result = client.compress(handle.read(), format="webp", mode="smart", max_width=1600)
result.save("photo.webp")
print(result.width, result.height, result.bytes, result.warnings)
```

Options are keyword arguments named like the API's parameters. An image is `bytes`, or `{"url": "https://..."}`.

| Method | Does |
|---|---|
| `compress(image, **options)` | compress, convert, resize, crop, rotate, edit, watermark |
| `convert(image, format, **options)` | change format |
| `remove_background(image, **options)` | cut out the subject |
| `id_photo(image, preset="35x45")` | an ID or passport photo at an exact size, DPI and KB range; `sheet=True` for a 4×6 print sheet |
| `upscale(image)` | double the size with the AI upscaler |
| `inspect(image)` | format, size, metadata, GPS position, fingerprints |
| `ocr(image, languages=[...])` | the text in the image |
| `pipeline(image, pipeline=... or preset=...)` / `dry_run(...)` | several steps on one image (Pro plan) |
| `create_job / get_job / cancel_job / wait_for_job` | a pipeline over many images, in the background (Pro plan) |
| `list_pipelines / save_pipeline / get_pipeline / delete_pipeline` | saved pipelines |
| `optimize_site / get_site_job` | the website optimizer |
| `usage()`, `capabilities()`, `download(url)` | account and discovery |

Errors are `ImageCompressorError` with `code`, `status`, `request_id` and, for a failed pipeline, `steps`. A `429` or `503` is retried after the wait the API names.

## Webhooks

```python
from imagecompressor import verify_webhook

# body must be the raw request body, exactly as received.
event = verify_webhook(os.environ["IMAGECOMPRESSOR_WEBHOOK_SECRET"], body, headers)
if event["type"] == "job.finished":
    print(event["data"]["id"], event["data"]["status"])
```

Run the tests with `python -m unittest discover -s tests`.
