forge-sdk

Python SDK for the Forge rendering engine. Converts HTML/CSS to PDF, PNG, and other formats via a running Forge server.

Uses httpx for both async and sync HTTP. Supports Python 3.9+.

Installation

pip install forge-sdk

Quick Start

Async

import asyncio
from forge_sdk import ForgeClient, OutputFormat

async def main():
    async with ForgeClient("http://localhost:3000") as client:
        pdf = await client.render_html("<h1>Invoice #1234</h1>") \
            .format(OutputFormat.PDF) \
            .paper("a4") \
            .send()

        with open("invoice.pdf", "wb") as f:
            f.write(pdf)

asyncio.run(main())

Sync

from forge_sdk import ForgeClient, OutputFormat

with ForgeClient("http://localhost:3000") as client:
    pdf = client.render_html("<h1>Invoice #1234</h1>") \
        .format(OutputFormat.PDF) \
        .paper("a4") \
        .send_sync()

    with open("invoice.pdf", "wb") as f:
        f.write(pdf)

Usage

Render HTML to PDF

from forge_sdk import Orientation, Flow

pdf = await client.render_html("<h1>Hello</h1>") \
    .format(OutputFormat.PDF) \
    .paper("a4") \
    .orientation(Orientation.PORTRAIT) \
    .margins("25.4,25.4,25.4,25.4") \
    .flow(Flow.PAGINATE) \
    .send()

Render URL to PNG

png = await client.render_url("https://example.com") \
    .format(OutputFormat.PNG) \
    .width(1280) \
    .height(800) \
    .density(2.0) \
    .send()

Color Quantization

Reduce colors for e-ink displays or limited-palette output.

from forge_sdk import Palette, DitherMethod

eink = await client.render_html("<h1>Dashboard</h1>") \
    .format(OutputFormat.PNG) \
    .palette(Palette.EINK) \
    .dither(DitherMethod.FLOYD_STEINBERG) \
    .send()

Custom Palette

img = await client.render_html("<h1>Brand</h1>") \
    .format(OutputFormat.PNG) \
    .palette(["#000000", "#ffffff", "#ff0000"]) \
    .dither(DitherMethod.ATKINSON) \
    .send()

PDF Metadata

Embed document metadata and enable bookmark/outline generation in PDF output.

pdf = await client.render_html("<h1>Invoice #1234</h1>") \
    .format(OutputFormat.PDF) \
    .paper("a4") \
    .pdf_title("Invoice #1234") \
    .pdf_author("Centrix ERP") \
    .pdf_subject("Monthly billing") \
    .pdf_keywords("invoice,billing,2026") \
    .pdf_creator("forge-sdk-python") \
    .pdf_bookmarks(True) \
    .send()

PDF Watermarks

Add text or image watermarks to each page.

from forge_sdk import WatermarkLayer

pdf = client.render_html("<h1>Draft Report</h1>") \
    .format(OutputFormat.PDF) \
    .pdf_watermark_text("DRAFT") \
    .pdf_watermark_opacity(0.15) \
    .pdf_watermark_rotation(-45) \
    .pdf_watermark_color("#888888") \
    .pdf_watermark_layer(WatermarkLayer.OVER) \
    .send_sync()

PDF/A Compliance & Embedded Files (ZUGFeRD)

Generate PDF/A-3b compliant invoices with embedded XML for e-invoicing standards like ZUGFeRD or Factur-X.

import base64
from forge_sdk import PdfStandard, EmbedRelationship

# Read your ZUGFeRD XML invoice data
with open("zugferd.xml", "rb") as f:
    xml_b64 = base64.b64encode(f.read()).decode()

pdf = await client.render_html("<h1>Invoice #1234</h1>") \
    .format(OutputFormat.PDF) \
    .paper("a4") \
    .pdf_title("Invoice #1234") \
    .pdf_standard(PdfStandard.A3B) \
    .pdf_attach(
        "factur-x.xml",
        xml_b64,
        mime_type="text/xml",
        description="Factur-X/ZUGFeRD invoice data",
        relationship=EmbedRelationship.ALTERNATIVE,
    ) \
    .send()

Health Check

# Async
healthy = await client.health()

# Sync
healthy = client.health_sync()

Resource Management

ForgeClient maintains connection pools internally. Use it as a context manager for automatic cleanup:

# Async context manager
async with ForgeClient("http://localhost:3000") as client:
    pdf = await client.render_html("<h1>Hi</h1>").send()

# Sync context manager
with ForgeClient("http://localhost:3000") as client:
    pdf = client.render_html("<h1>Hi</h1>").send_sync()

# Manual cleanup
client = ForgeClient("http://localhost:3000")
try:
    pdf = client.render_html("<h1>Hi</h1>").send_sync()
finally:
    client.close()

API Reference

ForgeClient(base_url, *, timeout=120.0)

Method	Description
render_html(html)	Start a render request from an HTML string
render_url(url)	Start a render request from a URL
health()	Check server health (async)
health_sync()	Check server health (sync)
close()	Close underlying HTTP connections (sync)
aclose()	Close underlying HTTP connections (async)

Implements both sync (with) and async (async with) context manager protocols.

RenderRequestBuilder

All methods return self for chaining. Call .send() (async) or .send_sync() to execute.

Method	Type	Description
format	OutputFormat	Output format (default: PDF)
width	int	Viewport width in CSS pixels
height	int	Viewport height in CSS pixels
paper	str	Paper size: a3, a4, a5, b4, b5, letter, legal, ledger
orientation	Orientation	PORTRAIT or LANDSCAPE
margins	str	Preset (default, none, narrow) or "T,R,B,L" in mm
flow	Flow	AUTO, PAGINATE, or CONTINUOUS
density	float	Output DPI (default: 96)
background	str	CSS background color (e.g. "#ffffff")
timeout	int	Page load timeout in seconds
colors	int	Quantization color count (2-256)
palette	Palette | list[str]	Color palette preset or list of hex strings
dither	DitherMethod	Dithering algorithm
pdf_title	str	PDF document title metadata
pdf_author	str	PDF document author metadata
pdf_subject	str	PDF document subject metadata
pdf_keywords	str	PDF keywords (comma-separated)
pdf_creator	str	PDF creator tool metadata
pdf_bookmarks	bool	Enable PDF bookmarks/outline generation
pdf_page_numbers	bool	Enable "Page X of Y" footers on each PDF page
pdf_watermark_text	str	Watermark text on each page
pdf_watermark_image	str	Base64-encoded PNG/JPEG watermark image
pdf_watermark_opacity	float	Watermark opacity (0.0-1.0, default: 0.15)
pdf_watermark_rotation	float	Watermark rotation in degrees (default: -45)
pdf_watermark_color	str	Watermark text color as hex (default: #888888)
pdf_watermark_font_size	float	Watermark font size in PDF points (default: auto)
pdf_watermark_scale	float	Watermark image scale (0.0-1.0, default: 0.5)
pdf_watermark_layer	WatermarkLayer	Layer position: OVER or UNDER
pdf_standard(standard)	PdfStandard	PDF standard: NONE, A2B, A3B
pdf_attach(path, data, *, mime_type, description, relationship)		Embed file in PDF (base64 data)
pdf_lang	str	Document language (BCP 47 tag, e.g. "en-US"). Required for PDF/UA-1

Enums

Enum	Values
OutputFormat	PDF, PNG, JPEG, BMP, TGA, QOI, SVG
Orientation	PORTRAIT, LANDSCAPE
Flow	AUTO, PAGINATE, CONTINUOUS
Palette	AUTO, BLACK_WHITE, GRAYSCALE, EINK
DitherMethod	NONE, FLOYD_STEINBERG, ATKINSON, ORDERED
WatermarkLayer	OVER, UNDER
PdfStandard	NONE, A2B, A3B
EmbedRelationship	ALTERNATIVE, SUPPLEMENT, DATA, SOURCE, UNSPECIFIED

Errors

Exception	Description
ForgeError	Base exception for all SDK errors
ForgeServerError	Server returned 4xx/5xx (has .status and .message)
ForgeConnectionError	Network failure (has .cause)

Requirements

• Python 3.9+
• httpx >= 0.24
• A running Forge server

License

MIT