abyssale 1.0.0__tar.gz

abyssale-1.0.0/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+spec.stripped.json
+.idea/
+.DS_Store

abyssale-1.0.0/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+**Every release names the API version it was generated from.** The API is versioned by release date
+(`vYYYY-MM-DD`) and one version is maintained at a time, so the pairing below tells you which
+contract a given SDK release models. The SDK's own version is independent — regenerating against a
+newer API version is a normal change, and whether it is a patch, minor or major depends on what the
+API changed.
+
+| SDK | API version | |
+|---|---|---|
+| 1.0.0 | `v2026-08-20` | [spec](https://api-reference.abyssale.com/api.yaml) |
+
+## [1.0.0] — 2026-08-20
+
+_Generated from API version **`v2026-08-20`**._
+
+First release. Covers **every operation in that spec** — 18 of them — plus two polling helpers over
+its status endpoints. Response models are generated from its schemas.
+
+### Added
+
+- `Abyssale` and `AsyncAbyssale`, over `httpx`. Both are context managers and both accept a
+  caller-supplied `httpx` client.
+- All 18 endpoints: auth; design list/read/format read; sync and async generation; multipage PDF;
+  generation-request status; file read; fonts; projects list/create; export; dynamic image URL;
+  workspace templates, categories, duplication and duplication status.
+- `wait_for_generation_request` and `wait_for_duplication_request` — exponential backoff with
+  jitter, a 30-minute default deadline, and a budget of three *consecutive* transient failures that
+  resets on any successful poll. Partial success resolves: a finalized request carrying both banners
+  and per-format errors is a result, not an exception. Only a request that finalized with no banners
+  at all and at least one error raises.
+- Retries, following the spec's error contract: 5xx on idempotent methods only
+  (every POST bills credits, and a 504 does not mean the render did not happen); the full ladder for
+  a `429` carrying `Retry-After`; exactly one one-second probe for a bare `429`, because
+  `rate_limit_exceeded` conflates spent credits with the gateway's per-second ceiling;
+  `feature_not_in_plan` never retried, whatever headers the response carries — no window makes a
+  plan restriction clear.
+- `max_retry_wait` (`$ABYSSALE_MAX_RETRY_WAIT_MS`, default 30s) — the longest single `Retry-After`
+  the SDK will sleep through on your behalf. The rate limiter can name a cool-off of ~1700s once a
+  quota is spent, and `max_retries` multiplies it, so honouring it blindly would turn one call into
+  83 minutes of silence with no way to intervene. Past the bound the call fails immediately with
+  `AbyssaleRateLimitError`, `retry_after` carrying the server's figure so the decision is yours.
+  Applies to any server-named wait, including a 5xx that carries `Retry-After` and one absorbed by a
+  `wait_for_*` poll — a 30-minute deadline has room to sleep off a 28-minute cool-off in one go, and
+  the bound is what refuses it. The SDK's own backoff and the bare-`429` probe are unaffected. Pass
+  `math.inf` to wait however long the server asks.
+- An exception hierarchy under `AbyssaleError`, built from the API's single error envelope — the
+  machine-readable `id` is always on the exception, and `errors` holds the per-field problems when
+  the failure was a payload problem.
+- Pydantic response models generated from the spec, with the Alpha design-import surface stripped by
+  `scripts/fetch_spec.py`, since the spec marks that surface Alpha.
+- Seven runnable examples in `examples/`, each exercising a documented operation end to end.
+
+### Notes
+
+- **Request bodies are plain dicts.** The `elements` schema is an `anyOf` of ten deliberately
+  overlapping branches with no discriminator, and the API accepts unknown element names by design,
+  so bodies are passed through untouched rather than modelled.
+- **Parsing never fails a successful response.** Unknown fields are kept, and a field the spec calls
+  required but the response omits does not raise — the spec is hand-maintained and the API is the
+  authority.
+- Requires Python 3.10+.

abyssale-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+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.

abyssale-1.0.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.5
+Name: abyssale
+Version: 1.0.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://api-reference.abyssale.com
+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.
+
+## Install
+
+```bash
+pip install abyssale
+```
+
+Requires Python 3.10+. This release models API version **`v2026-08-20`** — 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": {"title": {"payload": "Hello World"}},
+        "template_format_name": "facebook-post",
+    })
+    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": {"title": {"payload": "Summer Sale"}},
+            "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())
+```
+
+## Errors
+
+Methods return the result and **raise** on failure. Branch on the API's machine-readable `id`, not
+on the message:
+
+```python
+from abyssale import AbyssaleAPIError, AbyssaleRateLimitError
+
+try:
+    client.generate_image(design_id, {...})
+except AbyssaleRateLimitError as err:
+    if err.id == "feature_not_in_plan":
+        ...                                     # your plan excludes this design type
+except AbyssaleAPIError as err:
+    print(err.status, err.id, err.message, err.errors)
+```
+
+`err.errors` holds the per-field problems (`path`, `code`, `message`) when the request body was the
+problem, and is `None` otherwise.
+
+Transient failures are retried for you: 5xx on reads, and `429`s that carry a `Retry-After`. A `429`
+without one gets a single one-second probe, because the status is shared by "out of credits"
+(permanent) and the gateway's per-second ceiling (clears immediately). Writes are never retried on a
+5xx — a timed-out generation may still have been billed.
+
+A `Retry-After` is only waited out up to `max_retry_wait` (30s by default). The rate limiter can name
+a cool-off of half an hour once a quota is spent, and sleeping through that — times `max_retries` —
+turns one call into an hour of silence. Past the bound the call fails immediately instead, with
+`err.retry_after` carrying the server's figure so you can decide what to do with it. Pass
+`max_retry_wait=math.inf` if you do want to wait however long the server asks.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `ABYSSALE_API_KEY` | — | Required, unless you pass `api_key=`. |
+| `ABYSSALE_TIMEOUT_MS` | `30000` | Per-attempt request timeout. |
+| `ABYSSALE_MAX_RETRIES` | `3` | `0` disables retries. |
+| `ABYSSALE_MAX_RETRY_WAIT_MS` | `30000` | Longest `Retry-After` to wait out. `inf` to never give up. |
+
+Every one can be overridden per client: `Abyssale(api_key=..., timeout=60, max_retries=0)`.
+
+## Examples
+
+Runnable scripts are in [`examples/`](https://github.com/getabyssale/abyssale-python-sdk/blob/main/examples). 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://api-reference.abyssale.com)
+- [OpenAPI spec](https://api-reference.abyssale.com/api.yaml) — the contract this SDK is generated from
+- [Source](https://github.com/getabyssale/abyssale-python-sdk)

abyssale-1.0.0/README.md

@@ -0,0 +1,111 @@
+# 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.
+
+## Install
+
+```bash
+pip install abyssale
+```
+
+Requires Python 3.10+. This release models API version **`v2026-08-20`** — 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": {"title": {"payload": "Hello World"}},
+        "template_format_name": "facebook-post",
+    })
+    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": {"title": {"payload": "Summer Sale"}},
+            "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())
+```
+
+## Errors
+
+Methods return the result and **raise** on failure. Branch on the API's machine-readable `id`, not
+on the message:
+
+```python
+from abyssale import AbyssaleAPIError, AbyssaleRateLimitError
+
+try:
+    client.generate_image(design_id, {...})
+except AbyssaleRateLimitError as err:
+    if err.id == "feature_not_in_plan":
+        ...                                     # your plan excludes this design type
+except AbyssaleAPIError as err:
+    print(err.status, err.id, err.message, err.errors)
+```
+
+`err.errors` holds the per-field problems (`path`, `code`, `message`) when the request body was the
+problem, and is `None` otherwise.
+
+Transient failures are retried for you: 5xx on reads, and `429`s that carry a `Retry-After`. A `429`
+without one gets a single one-second probe, because the status is shared by "out of credits"
+(permanent) and the gateway's per-second ceiling (clears immediately). Writes are never retried on a
+5xx — a timed-out generation may still have been billed.
+
+A `Retry-After` is only waited out up to `max_retry_wait` (30s by default). The rate limiter can name
+a cool-off of half an hour once a quota is spent, and sleeping through that — times `max_retries` —
+turns one call into an hour of silence. Past the bound the call fails immediately instead, with
+`err.retry_after` carrying the server's figure so you can decide what to do with it. Pass
+`max_retry_wait=math.inf` if you do want to wait however long the server asks.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `ABYSSALE_API_KEY` | — | Required, unless you pass `api_key=`. |
+| `ABYSSALE_TIMEOUT_MS` | `30000` | Per-attempt request timeout. |
+| `ABYSSALE_MAX_RETRIES` | `3` | `0` disables retries. |
+| `ABYSSALE_MAX_RETRY_WAIT_MS` | `30000` | Longest `Retry-After` to wait out. `inf` to never give up. |
+
+Every one can be overridden per client: `Abyssale(api_key=..., timeout=60, max_retries=0)`.
+
+## Examples
+
+Runnable scripts are in [`examples/`](https://github.com/getabyssale/abyssale-python-sdk/blob/main/examples). 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://api-reference.abyssale.com)
+- [OpenAPI spec](https://api-reference.abyssale.com/api.yaml) — the contract this SDK is generated from
+- [Source](https://github.com/getabyssale/abyssale-python-sdk)

abyssale-1.0.0/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "abyssale"
+version = "1.0.0"
+description = "Official Python SDK for the Abyssale API — image, video and PDF generation."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "Abyssale" }]
+keywords = ["abyssale", "banner", "image-generation", "video", "pdf", "api", "sdk"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+
+[project.urls]
+Homepage = "https://www.abyssale.com"
+Documentation = "https://developers.abyssale.com/sdks/python"
+"API Reference" = "https://api-reference.abyssale.com"
+Repository = "https://github.com/getabyssale/abyssale-python-sdk"
+Issues = "https://github.com/getabyssale/abyssale-python-sdk/issues"
+Changelog = "https://github.com/getabyssale/abyssale-python-sdk/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "anyio>=4",
+    "mypy>=1.10",
+    "ruff>=0.5",
+    "build>=1.2",
+    "twine>=5",
+]
+# Only needed to regenerate `src/abyssale/_generated.py` — not required to use or test the SDK.
+codegen = [
+    "datamodel-code-generator>=0.25",
+    "PyYAML>=6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/abyssale"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/abyssale", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+# The generated models are formatted by the code generator, not by us. Reformatting them here
+# would make every regeneration produce a diff against itself.
+extend-exclude = ["src/abyssale/_generated.py"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/abyssale/_generated.py" = ["ALL"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/abyssale"]
+
+# The generated models are not hand-written and are excluded from strict typing, exactly as
+# `generated.ts` is excluded from review in the Node SDK.
+[[tool.mypy.overrides]]
+module = "abyssale._generated"
+ignore_errors = true

abyssale-1.0.0/src/abyssale/__init__.py

@@ -0,0 +1,102 @@
+"""Official Python SDK for the Abyssale API — image, video and PDF generation.
+
+    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": {"title": {"payload": "Hello World"}},
+            "template_format_name": "facebook-post",
+        })
+        print(banner.file.cdn_url)
+
+Async is the same surface: ``from abyssale import AsyncAbyssale``.
+
+Errors raise. Every failure is an :class:`AbyssaleError`; a non-2xx is an :class:`AbyssaleAPIError`
+carrying the API's machine-readable ``id``, which is what you branch on.
+
+Docs: https://developers.abyssale.com/sdks/python
+"""
+
+from ._async_client import AsyncAbyssale
+from ._client import Abyssale
+from ._errors import (
+    AbyssaleAPIError,
+    AbyssaleAuthError,
+    AbyssaleConfigError,
+    AbyssaleConnectionError,
+    AbyssaleError,
+    AbyssaleNotFoundError,
+    AbyssalePollingError,
+    AbyssaleRateLimitError,
+)
+from ._version import __api_version__, __version__
+from .models import (
+    AuthResult,
+    Banner,
+    Design,
+    DesignAnimation,
+    DesignDetail,
+    DesignElement,
+    DesignFormat,
+    DesignFormatDetail,
+    DesignListItem,
+    DesignPage,
+    DesignPageElement,
+    DuplicatedDesign,
+    DuplicationRequest,
+    DuplicationRequestStatus,
+    DynamicImageResponse,
+    ErrorResponse,
+    ExportAccepted,
+    Font,
+    GenerationRequestAccepted,
+    GenerationRequestStatus,
+    Project,
+    ProjectSummary,
+    TextToImageProperties,
+    WorkspaceTemplate,
+    WorkspaceTemplateCategory,
+)
+
+__all__ = [
+    "Abyssale",
+    "AsyncAbyssale",
+    "__version__",
+    "__api_version__",
+    # Errors
+    "AbyssaleAPIError",
+    "AbyssaleAuthError",
+    "AbyssaleConfigError",
+    "AbyssaleConnectionError",
+    "AbyssaleError",
+    "AbyssaleNotFoundError",
+    "AbyssalePollingError",
+    "AbyssaleRateLimitError",
+    # Models
+    "AuthResult",
+    "Banner",
+    "Design",
+    "DesignAnimation",
+    "DesignDetail",
+    "DesignElement",
+    "DesignFormat",
+    "DesignFormatDetail",
+    "DesignListItem",
+    "DesignPage",
+    "DesignPageElement",
+    "DuplicatedDesign",
+    "DuplicationRequest",
+    "DuplicationRequestStatus",
+    "DynamicImageResponse",
+    "ErrorResponse",
+    "ExportAccepted",
+    "Font",
+    "GenerationRequestAccepted",
+    "GenerationRequestStatus",
+    "Project",
+    "ProjectSummary",
+    "TextToImageProperties",
+    "WorkspaceTemplate",
+    "WorkspaceTemplateCategory",
+]