> ## Documentation Index
> Fetch the complete documentation index at: https://pdfbase.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Auto-generated Python SDK with type hints and async support.

## Installation

```bash theme={null}
pip install pdfbase
```

## Initialization

```python theme={null}
from pdfbase import PDFBase

client = PDFBase(
    api_key="pk_live_xxx",  # or use PDFBASE_API_KEY env var
    timeout=30.0,           # request timeout in seconds
    max_retries=3,          # automatic retries on 5xx/429
)
```

## Generate a PDF

```python theme={null}
pdf = client.pdfs.create(
    html="<h1>Invoice #001</h1><p>Total: $500</p>",
    format="a4",
    output="url",
)

print(pdf.id)    # pdf_x7Kf9m
print(pdf.url)   # https://files.pdfbase.dev/pdf_x7Kf9m.pdf?token=sig_abc
print(pdf.pages) # 1
```

## Async support

```python theme={null}
from pdfbase import AsyncPDFBase

client = AsyncPDFBase(api_key="pk_live_xxx")

pdf = await client.pdfs.create(
    html="<h1>Hello</h1>",
    output="url",
)
```

## Templates

```python theme={null}
template = client.templates.create(
    name="invoice",
    html="<h1>Invoice #{{number}}</h1>...",
    schema={"number": "string", "customer": "string", "total": "string"},
    defaults={"format": "a4", "margin": "20mm"},
)

pdf = client.templates.render(
    template.id,
    data={"number": "INV-001", "customer": "Acme Corp", "total": "$500"},
    output="url",
)
```

## Batch processing

```python theme={null}
batch = client.batches.create(
    items=[
        {"template_id": "tpl_abc123", "data": inv}
        for inv in invoice_data
    ],
    output="individual",
    parallel=10,
)

result = client.batches.poll(
    batch.id,
    interval=2.0,
    timeout=300.0,
)

for item in result.results:
    if item.status == "completed":
        print(f"PDF {item.pdf_id}: {item.url}")
```

## Edit operations

```python theme={null}
# Merge PDFs (Phase 2)
merged = client.pdfs.merge(
    sources=[
        {"pdf_id": "pdf_cover"},
        {"pdf_id": "pdf_report"},
        {"url": "https://legal.example.com/terms.pdf"},
    ],
)

# Split (Phase 2)
parts = client.pdfs.split(
    source={"pdf_id": "pdf_report"},
    ranges=["1-5", "6-10"],
)

# Watermark (Phase 2)
watermarked = client.pdfs.watermark(
    source={"pdf_id": "pdf_contract"},
    text={"content": "DRAFT", "color": "#FF000015"},
)
```

## Extract operations

```python theme={null}
# Extract text (Phase 3)
text = client.extract.text(
    source={"pdf_id": "pdf_report"},
    pages="1-5",
    format="markdown",
)

# OCR (Phase 3)
ocr = client.extract.ocr(
    source={"pdf_id": "pdf_scanned"},
    language="eng",
)

# AI structured extraction (Phase 3)
invoice = client.extract.structured(
    source={"pdf_id": "pdf_invoice"},
    preset="invoice",
)
print(invoice.data["total"])  # 763.00
```

## Convert operations

```python theme={null}
# Office to PDF (Phase 2)
pdf = client.convert.office(
    source={"url": "https://your-app.com/report.xlsx"},
    landscape=True,
)

# PDF to thumbnail (Phase 2)
thumbnail = client.convert.thumbnail(
    source={"pdf_id": "pdf_report"},
    page=1,
)
```

## Error handling

```python theme={null}
from pdfbase import PDFBaseError, RateLimitError, AuthenticationError

try:
    pdf = client.pdfs.create(html="<h1>Test</h1>")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")
except PDFBaseError as e:
    print(f"{e.type}: {e.code} — {e.message}")
```

## Type hints

Full type annotations for IDE autocompletion:

```python theme={null}
from pdfbase.types import PDF, Template, Batch

def generate_invoice(data: dict) -> PDF:
    return client.templates.render("tpl_abc123", data=data)
```

<Note>
  The Python SDK is auto-generated from the PDFBase OpenAPI spec, same as the TypeScript SDK.
</Note>