Metadata-Version: 2.4
Name: pdfbridge-python
Version: 1.0.0
Summary: The official Python SDK for the PDFBridge API. Generate pixel-perfect PDFs from HTML/URLs.
Project-URL: Homepage, https://pdfbridge.xyz
Project-URL: Bug Tracker, https://github.com/techhspyder/pdfbridge-python/issues
Author-email: TechhSpyder <hello@techhspyder.com>
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.25.1
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: responses>=0.23.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">
  <img src="https://assets.pdfbridge.xyz/logo.svg" alt="PDFBridge Logo" width="200"/>
  <h1>pdfbridge-python</h1>
  <p>The official Python SDK for the <a href="https://pdfbridge.xyz">PDFBridge API</a>. Generate pixel-perfect PDFs from HTML or URLs.</p>
</div>

[![PyPI version](https://badge.fury.io/py/pdfbridge-python.svg)](https://badge.fury.io/py/pdfbridge-python)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python Support](https://img.shields.io/pypi/pyversions/pdfbridge-python.svg)](https://pypi.org/project/pdfbridge-python/)

## Features

- **Typed Inputs & Outputs**: Fully powered by Pydantic V2 for strict runtime validation and autocomplete.
- **Convenient Sync Methods**: Out-of-the-box `generate_and_wait` blocking wrapper so you don't have to write your own pollers.
- **Ghost Mode Native**: Fetch raw PDF bytes directly into memory. No intermediate storage or URLs.
- **Bulk Conversions**: Convert up to 1,000 documents simultaneously.

---

## Installation

```bash
pip install pdfbridge-python
```

## Quick Start

```python
import os
from pdfbridge import PDFBridge

# Initialize with your secret API key
# Can also be picked up automatically via the PDFBRIDGE_API_KEY environment variable.
client = PDFBridge(api_key="pk_live_your_key_here")

# Generate and wait for completion (blocks execution until PDF is ready)
status = client.generate_and_wait(
    url="https://github.com",
    filename="github_page.pdf",
    options={
        "format": "A4",
        "printBackground": True
    }
)

print(f"Success! Download PDF from: {status.pdfUrl}")
```

## Advanced Usage

### 👻 Ghost Mode (Memory-Native)

Ghost Mode returns the direct `bytes` of the generated PDF without saving it to Cloud Storage. This is perfect for securely piping documents to your own S3 bucket or streaming directly to users.

```python
# Returns raw bytes natively
pdf_bytes = client.generate(
    html="<h1>Highly Confidential Financial Data</h1>",
    ghostMode=True,
    options={
        "format": "Letter",
        "margin": "1in"
    }
)

with open("secure_report.pdf", "wb") as f:
    f.write(pdf_bytes)
```

### 🚀 Bulk Generation

Queue up to 1,000 PDF generation jobs natively in a single API call.

```python
bulk_job = client.generate_bulk(
    webhookUrl="https://api.yourdomain.com/webhooks/pdfbridge",
    jobs=[
        {"url": "https://example.com/invoice/123", "filename": "INV-123.pdf"},
        {"url": "https://example.com/invoice/124", "filename": "INV-124.pdf"},
        {"url": "https://example.com/invoice/125", "filename": "INV-125.pdf"}
    ]
)

print(f"Queued {len(bulk_job.jobs)} items.")
```

### 🧠 Templates & Variables

Pass dynamic data into your saved HTML templates.

```python
client.generate_and_wait(
    templateId="tmpl_987654321",
    variables={
        "customer_name": "Jane Doe",
        "total_amount": "$45.00"
    }
)
```

## Error Handling

The SDK raises `PDFBridgeError` on any HTTP failures, authentication issues, or data malformations.

```python
from pdfbridge import PDFBridgeError

try:
    client.generate(url="invalid-url")
except PDFBridgeError as e:
    print(f"API Failed with status {e.status_code}: {str(e)}")
```
