Metadata-Version: 2.5
Name: abyssale
Version: 1.2.0
Summary: Official Python SDK for the Abyssale API — image, video and PDF generation.
Project-URL: Homepage, https://www.abyssale.com
Project-URL: Documentation, https://developers.abyssale.com/sdks/python
Project-URL: API Reference, https://developers.abyssale.com/api-reference/
Project-URL: Repository, https://github.com/getabyssale/abyssale-python-sdk
Project-URL: Issues, https://github.com/getabyssale/abyssale-python-sdk/issues
Project-URL: Changelog, https://github.com/getabyssale/abyssale-python-sdk/blob/main/CHANGELOG.md
Author: Abyssale
License: MIT License
        
        Copyright (c) 2025 Abyssale
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: abyssale,api,banner,image-generation,pdf,sdk,video
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Provides-Extra: codegen
Requires-Dist: datamodel-code-generator>=0.25; extra == 'codegen'
Requires-Dist: pyyaml>=6; extra == 'codegen'
Provides-Extra: dev
Requires-Dist: anyio>=4; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# Abyssale Python SDK

Official Python client for the [Abyssale API](https://developers.abyssale.com) — generate images,
videos, HTML5 banners and print-ready PDFs from your designs.

**📖 Full reference: [developers.abyssale.com/sdks/python](https://developers.abyssale.com/sdks/python)**
— every method, configuration, error handling, retry behaviour and the polling helpers.

## Install

```bash
pip install abyssale
```

Requires Python 3.10+. This release models API version **`v2026-09-02`** — see
[CHANGELOG.md](https://github.com/getabyssale/abyssale-python-sdk/blob/main/CHANGELOG.md) for the
SDK-to-API version pairing, and `abyssale.__api_version__` to read it at runtime.

## Quick start

```python
from abyssale import Abyssale

with Abyssale() as client:                      # reads ABYSSALE_API_KEY
    design = client.get_design("64238d01-d402-474b-8c2d-fbc957e9d290")

    banner = client.generate_image(design.id, {
        "elements": {"text_title": {"payload": "Summer sale — 40% off"}},
        "template_format_name": "facebook-feed",
    })
    print(banner.file.cdn_url)
```

Async is the same surface:

```python
import asyncio
from abyssale import AsyncAbyssale

async def main():
    async with AsyncAbyssale() as client:
        accepted = await client.generate_multi_format_media(design_id, {
            "elements": {"text_title": {"payload": "Summer sale — 40% off"}},
            "template_format_names": ["facebook-feed", "instagram-post"],
        })
        result = await client.wait_for_generation_request(accepted.generation_request_id)
        for banner in result.banners:
            print(banner.file.cdn_url)

asyncio.run(main())
```

Methods return the result and **raise** on failure. Branch on the API's machine-readable `id`, never
on the message:

```python
from abyssale import AbyssaleAPIError

try:
    client.generate_image(design_id, {...})
except AbyssaleAPIError as err:
    print(err.status, err.id, err.message, err.errors)
```

## What you get

- **22 methods, sync and async**, one per API operation, named after its `operationId` snake_cased,
  plus two `wait_for_*` polling helpers —
  [every method](https://developers.abyssale.com/sdks/python#every-method)
- **Typed responses, permissive request bodies** — responses are pydantic models that never fail a
  `200`, request bodies pass through untouched —
  [request bodies and responses](https://developers.abyssale.com/sdks/python#request-bodies-and-responses)
- **A typed exception hierarchy** carrying the API's `id`, `errors` and `retry_after` —
  [errors](https://developers.abyssale.com/sdks/python#errors)
- **Narrow retries and a per-attempt timeout**, configurable per client or by environment
  (`ABYSSALE_API_KEY`, `ABYSSALE_TIMEOUT_MS`, `ABYSSALE_MAX_RETRIES`,
  `ABYSSALE_MAX_RETRY_WAIT_MS`) —
  [configuration](https://developers.abyssale.com/sdks/python#configuration) ·
  [what is retried, and what is not](https://developers.abyssale.com/sdks/python#retries-and-timeouts)
- **Webhook signature verification** in `abyssale.webhooks`, which imports only the standard library
  — no client and no API key needed in a receiver process —
  [signature verification](https://developers.abyssale.com/webhooks/signature-verification)

## Examples

Runnable scripts are in [`examples/`](https://github.com/getabyssale/abyssale-python-sdk/blob/main/examples),
including a complete webhook receiver. Each one names its own command:

```bash
ABYSSALE_API_KEY=your-key python examples/generate_image.py
```

## Contributing

See [AGENTS.md](https://github.com/getabyssale/abyssale-python-sdk/blob/main/AGENTS.md) for the
architecture, how to regenerate the models from the OpenAPI spec, and how to add an endpoint.

## Links

- [Abyssale](https://www.abyssale.com) — the product this SDK talks to
- [Documentation](https://developers.abyssale.com/sdks/python)
- [API reference](https://developers.abyssale.com/api-reference/)
- [OpenAPI spec](https://developers.abyssale.com/api.yaml) — the contract this SDK is generated from
- [Source](https://github.com/getabyssale/abyssale-python-sdk)
