Metadata-Version: 2.4
Name: iterationlayer
Version: 2.0.5
Summary: Official Python SDK for the Iteration Layer API
Project-URL: Homepage, https://iterationlayer.com
Project-URL: Documentation, https://iterationlayer.com/docs
Project-URL: Repository, https://github.com/iterationlayer/sdk-python
Project-URL: Issues, https://github.com/iterationlayer/issues
Author: Iteration Layer
License-Expression: MIT
License-File: LICENSE
Keywords: api,document-extraction,document-generation,image-generation,image-transformation,iteration-layer,sdk
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.28.1
Provides-Extra: dev
Requires-Dist: mypy>=2.1.0; extra == 'dev'
Requires-Dist: pytest<9,>=8.4.2; extra == 'dev'
Requires-Dist: respx>=0.23.1; extra == 'dev'
Requires-Dist: ruff>=0.15.12; extra == 'dev'
Description-Content-Type: text/markdown

# Iteration Layer Python SDK

Official Python SDK for the [Iteration Layer API](https://iterationlayer.com).

## Installation

```sh
pip install iterationlayer
```

## Usage

```python
from iterationlayer import IterationLayer

client = IterationLayer(api_key="il_your_api_key")
```

### Document Extraction

Extract structured data from documents using AI.

```python
result = client.extract_document(
    files=[{"type": "url", "name": "invoice.pdf", "url": "https://example.com/invoice.pdf"}],
    schema={
        "fields": [
            {"type": "TEXT", "name": "company_name", "description": "The company name"},
            {"type": "CURRENCY_AMOUNT", "name": "total", "description": "The invoice total"},
        ]
    },
)

print(result["company_name"]["value"])       # "Acme Corp"
print(result["company_name"]["confidence"])  # 0.95
```

### Website Extraction

Extract structured data from public website pages. Static fetching is used by default; set `should_render_javascript` when a page needs browser rendering.

```python
result = client.extract_website(
    file={
        "type": "url",
        "url": "https://example.com/pricing",
        "fetch_options": {"should_render_javascript": True},
    },
    schema={
        "fields": [
            {"type": "TEXT", "name": "plan_name", "description": "The pricing plan name"},
            {"type": "CURRENCY_AMOUNT", "name": "price", "description": "The monthly price"},
        ]
    },
)

print(result["plan_name"]["value"])  # "Pro"
```

### Image Transformation

Resize, crop, convert, and apply effects to images.

```python
result = client.transform_image(
    file={"type": "url", "name": "photo.jpg", "url": "https://example.com/photo.jpg"},
    operations=[
        {"type": "resize", "width_in_px": 800, "height_in_px": 600, "fit": "cover"},
        {"type": "convert", "format": "webp", "quality": 85},
    ],
)

import base64
image_bytes = base64.b64decode(result["buffer"])
```

### Image Generation

Compose images from layer definitions.

```python
result = client.generate_image(
    dimensions={"width_in_px": 1200, "height_in_px": 630},
    layers=[
        {"type": "solid-color", "index": 0, "hex_color": "#1a1a2e"},
        {
            "type": "text",
            "index": 1,
            "text": "Hello World",
            "font_name": "Inter",
            "font_size_in_px": 48,
            "text_color": "#ffffff",
            "position": {"x_in_px": 50, "y_in_px": 50},
            "dimensions": {"width_in_px": 1100, "height_in_px": 530},
        },
    ],
    output_format="png",
)

import base64
image_bytes = base64.b64decode(result["buffer"])
```

### Document Generation

Generate PDF, DOCX, EPUB, or PPTX from structured data.

```python
result = client.generate_document(
    format="pdf",
    document={
        "metadata": {"title": "Invoice #123"},
        "page": {
            "size": {"preset": "A4"},
            "margins": {"top_in_pt": 36, "bottom_in_pt": 36, "left_in_pt": 36, "right_in_pt": 36},
        },
        "styles": {
            "text": {"font_family": "Helvetica", "font_size_in_pt": 12, "line_height": 1.5, "color": "#000000"},
            "headline": {"font_family": "Helvetica", "font_size_in_pt": 24, "color": "#000000", "spacing_before_in_pt": 12, "spacing_after_in_pt": 6},
            "link": {"color": "#0066cc"},
            "list": {"indent_in_pt": 18, "spacing_between_items_in_pt": 4},
            "table": {
                "header": {"background_color": "#f0f0f0", "font_family": "Helvetica", "font_size_in_pt": 12, "color": "#000000", "padding_in_pt": 6},
                "body": {"font_family": "Helvetica", "font_size_in_pt": 12, "color": "#000000", "padding_in_pt": 6},
            },
            "grid": {"gap_in_pt": 12},
            "separator": {"color": "#cccccc", "thickness_in_pt": 1, "margin_top_in_pt": 12, "margin_bottom_in_pt": 12},
            "image": {"alignment": "center", "margin_top_in_pt": 8, "margin_bottom_in_pt": 8},
        },
        "content": [
            {"type": "headline", "level": "h1", "text": "Invoice #123"},
            {"type": "paragraph", "markdown": "Thank you for your business."},
        ],
    },
)

import base64
pdf_bytes = base64.b64decode(result["buffer"])
```

### Sheet Generation

Generate CSV, Markdown, or XLSX spreadsheets from structured data.

```python
result = client.generate_sheet(
    format="xlsx",
    sheets=[
        {
            "name": "Invoices",
            "columns": [
                {"name": "Company", "width": 20},
                {"name": "Total", "width": 15},
            ],
            "rows": [
                [
                    {"value": "Acme Corp"},
                    {"value": 1500.50, "format": "currency", "currency_code": "EUR"},
                ],
            ],
        },
    ],
)

import base64
sheet_bytes = base64.b64decode(result["buffer"])
```

### Webhooks (Async)

Use the `*_async` methods to receive results via webhook instead of waiting for the response.

```python
result = client.extract_document_async(
    files=[{"type": "url", "name": "invoice.pdf", "url": "https://example.com/invoice.pdf"}],
    schema={
        "fields": [
            {"type": "CURRENCY_AMOUNT", "name": "total", "description": "The invoice total"},
        ]
    },
    webhook_url="https://your-app.com/webhooks/extraction",
)
```

### Context Manager

The client can be used as a context manager to ensure the underlying HTTP connection is closed.

```python
with IterationLayer(api_key="il_your_api_key") as client:
    result = client.extract_document(...)
```

### Error Handling

```python
from iterationlayer import IterationLayerError

try:
    result = client.extract_document(...)
except IterationLayerError as e:
    print(e.status_code)     # 422
    print(e.error_message)   # "Validation error: ..."
```

## Documentation

Full documentation is available at [https://iterationlayer.com/docs](https://iterationlayer.com/docs).

## Issues & Feedback

Please report bugs and request features in the [issues repository](https://github.com/iterationlayer/issues).
