pdfbridge-python

The official Python SDK for the PDFBridge API. Generate pixel-perfect PDFs from HTML or URLs.

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

pip install pdfbridge-python

Quick Start

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.

# 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.

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.

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.

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)}")