pdfapi-client 0.1.3
Python client for pdfapi.dev - HTML to PDF conversion service
Requires Python: >=3.7
Keywords: pdf conversion html api client

# Python Client for pdfapi.dev

<img src="logo.svg" alt="pdfapi.dev logo" width="200"/>

A Python client library for [pdfapi.dev](https://pdfapi.dev) - HTML to PDF conversion service that supports:
- CSS styling
- Custom headers and footers
- Images and other assets
- Multiple page formats
- Configurable margins and scaling

## Installation

```bash
pip install pdfapi-client
```

## Quick Start

```python
from pdfapi_client import PDFApiClient, ConversionConfig, PageFormat

# Initialize the client
client = PDFApiClient(api_key="your-api-key")

# Convert HTML to PDF
pdf_bytes = client.convert_html(
    html="<h1>Hello World</h1>",
    config=ConversionConfig(format=PageFormat.A4)
)

# Save to file
with open("output.pdf", "wb") as f:
    f.write(pdf_bytes)
```

## Examples

### HTML with CSS

```python
html = """
<html>
    <head>
        <link rel="stylesheet" href="style.css">
    </head>
    <body>
        <h1>Styled Document</h1>
        <p>This is a styled paragraph.</p>
    </body>
</html>
"""

css = "h1 { color: navy; } p { color: gray; }"

pdf_bytes = client.convert_html(
    html=html,
    assets={"style.css": css},
    config=ConversionConfig(format=PageFormat.A4)
)
```

### With Header and Footer

```python
from pathlib import Path

config = ConversionConfig(
    format=PageFormat.A4,
    margin=Margin(top=40, bottom=40, left=20, right=20),
    header_file="<div style='text-align: center'>My Document</div>",
    footer_file="<div style='text-align: right'>Page {page} of {pages}</div>"
)

pdf_bytes = client.convert_html(
    html=Path("document.html"),  # Can also load from file
    config=config
)
```

### With Images

```python
html = """
<html>
    <body>
        <h1>Document with Image</h1>
        <img src="image.png" alt="My Image">
    </body>
</html>
"""

pdf_bytes = client.convert_html(
    html=html,
    assets={"image.png": Path("path/to/image.png")},
    config=ConversionConfig(format=PageFormat.A4)
)
```

## Configuration Options

### Page Formats

Available page formats:
- `PageFormat.A4` (default)
- `PageFormat.A3`
- `PageFormat.LETTER`
- `PageFormat.LEGAL`
- And more...

### Margins

Margins can be specified in pixels:

```python
config = ConversionConfig(
    margin=Margin(
        top=20,
        bottom=20,
        left=20,
        right=20
    )
)
```

### Other Options

- `scale`: Scale factor for the output (default: 1.0)
- `landscape`: Whether to use landscape orientation (default: False)

## Input Types

The library accepts various input types:
- Strings (for direct content)
- Path objects (for file paths)
- File-like objects (for open files)
- Bytes (for binary content)

This applies to HTML content, CSS, images, and header/footer files.

## Error Handling

```python
from pdfapi_client import PDFApiClient, ConversionError

try:
    pdf_bytes = client.convert_html(html="<h1>Test</h1>")
except ConversionError as e:
    print(f"Conversion failed: {e}")
```

## License

Copyright 2024 pdfapi.dev

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.