# DocFast Python SDK

Official Python client for the [DocFast](https://docfast.dev) HTML-to-PDF API.

## Install

```bash
pip install docfast
```

Requires Python 3.8+.

## Quick Start

```python
from docfast import DocFast

client = DocFast("df_pro_your_api_key")

# HTML to PDF
pdf = client.html("<h1>Hello World</h1>")
with open("output.pdf", "wb") as f:
    f.write(pdf)

# Markdown to PDF
pdf = client.markdown("# Hello\n\nThis is **bold**.")

# URL to PDF
pdf = client.url("https://example.com")
```

## Async Usage

```python
from docfast import AsyncDocFast

async with AsyncDocFast("df_pro_your_api_key") as client:
    pdf = await client.html("<h1>Hello</h1>")
```

## API

### `DocFast(api_key, *, base_url=None)`

Create a synchronous client. Use as a context manager or call `client.close()`.

### `AsyncDocFast(api_key, *, base_url=None)`

Create an async client. Use as an async context manager.

### Conversion Methods

All methods return PDF bytes and accept optional keyword arguments:

| Method | Input | Description |
|--------|-------|-------------|
| `client.html(html, **opts)` | HTML string | Convert HTML to PDF |
| `client.markdown(markdown, **opts)` | Markdown string | Convert Markdown to PDF |
| `client.url(url, **opts)` | URL string | Convert webpage to PDF |
| `client.templates()` | — | List available templates |
| `client.render_template(id, data, **opts)` | Template ID + data dict | Render template to PDF |

### PDF Options

Pass as keyword arguments to any conversion method:

```python
pdf = client.html(
    "<h1>Report</h1>",
    format="A4",
    landscape=True,
    margin={"top": "20mm", "bottom": "20mm"},
    print_background=True,
)
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `format` | str | `"A4"` | Page size: A4, Letter, Legal, A3, A5, Tabloid |
| `landscape` | bool | `False` | Landscape orientation |
| `margin` | dict | — | `{top, bottom, left, right}` in CSS units |
| `header` | dict | — | `{content, height}` for page header |
| `footer` | dict | — | `{content, height}` for page footer |
| `scale` | float | `1.0` | Render scale |
| `print_background` | bool | `False` | Include background colors/images |

## Error Handling

```python
from docfast import DocFast, DocFastError

client = DocFast("df_pro_your_api_key")

try:
    pdf = client.html("<h1>Test</h1>")
except DocFastError as e:
    print(e)          # "Invalid API key"
    print(e.status)   # 403
```

## License

MIT