html2pdf-smart 0.1.1

Intelligent HTML-to-PDF conversion with layout pre-processing

html2pdf-smart

Intelligent HTML-to-PDF conversion with layout pre-processing.

Uses a hybrid architecture: a custom DOM analysis layer handles page break logic, font/margin adjustment, and layout optimization before Playwright (Chromium) renders the final PDF. Supports three interfaces: Python library, CLI, and REST API.

Installation

pip install html2pdf-smart
playwright install chromium

For CLI support:

pip install "html2pdf-smart[cli]"

For the REST API:

pip install "html2pdf-smart[api]"

Quickstart — Library

from html2pdf import convert, PDFConfig

# Convert an HTML string to PDF bytes
pdf_bytes = convert("<h1>Hello</h1><p>World</p>")

# With configuration overrides
pdf_bytes = convert(html, page_size="Letter", landscape=True, margin_top="25mm")

# Convert a file
from html2pdf import convert_file
output_path = convert_file("report.html", "report.pdf")

# Batch conversion (single browser instance — much faster)
from html2pdf import convert_batch
results = convert_batch([
    ("<h1>Doc 1</h1>", "doc1.pdf"),
    ("<h1>Doc 2</h1>", "doc2.pdf"),
])
for label, pdf_bytes, error in results:
    if error:
        print(f"{label}: FAILED — {error}")
    else:
        print(f"{label}: {len(pdf_bytes)} bytes")

Async

import asyncio
from html2pdf import async_convert, async_convert_batch

pdf = asyncio.run(async_convert("<h1>Async</h1>"))

Quickstart — CLI

# Single file
html2pdf convert report.html -o report.pdf

# Batch convert a directory
html2pdf convert *.html --output-dir ./pdfs/

# From stdin
cat page.html | html2pdf convert - -o page.pdf

# With options
html2pdf convert doc.html -o doc.pdf --format Letter --landscape --margin-top 25mm

Quickstart — REST API

# Start the server
uvicorn html2pdf.api.app:app --host 0.0.0.0 --port 8000

# Convert HTML
curl -X POST http://localhost:8000/convert/html \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>"}' \
  --output result.pdf

# Health check
curl http://localhost:8000/health

Configuration

PDFConfig fields (all have sensible defaults):

Field	Default	Description
page_size	"A4"	A0–A6, Letter, Legal, Tabloid, Ledger
margin_top	"20mm"	Top margin
margin_bottom	"20mm"	Bottom margin
margin_left	"15mm"	Left margin
margin_right	"15mm"	Right margin
break_strategy	"smart"	"smart", "css-only", or "none"
font_adjustment	True	Enable font normalization
print_background	True	Include background colors/images
scale	1.0	Page scale factor
landscape	False	Landscape orientation
header_template	None	Custom header HTML
footer_template	None	Custom footer HTML

Config resolution order: function kwargs → config file → HTML2PDF_* env vars → frozen defaults.

Config file locations (first found wins): explicit path → ./html2pdf.toml → pyproject.toml [tool.html2pdf] → ~/.config/html2pdf/config.toml.

Requirements

• Python 3.10+
• Playwright with Chromium (playwright install chromium)

License

MIT — see LICENSE.