Python reference client
Download the dependency-free Python example for secure direct uploads, HQTools quotes, asynchronous processing and signed downloads.
Python reference implementation#
The reference client implements the complete document-task chain: create a task, obtain a signed upload form, send the PDF directly to storage, seal the upload, request an HQTools quote, submit an explicitly approved task, poll and retrieve a signed download URL. It uses Python's standard library and does not install additional packages.
from pdfhq import PDFHQClient
client = PDFHQClient("YOUR_API_KEY")
task = client.start("compress")
client.upload(task["task_id"], "report.pdf")
quote = client.quote(task["task_id"])
print("Estimated HQ credits:", quote["estimated_hq_credits"])
# Production systems should record approval in their own order flow.
if input("Approve this HQTools credit quote? Type yes: ").strip() != "yes":
raise SystemExit("No credit consumption authorized")
client.process(task["task_id"], {"compression_level": "recommended"})
result = client.wait(task["task_id"])
if result["status"] != "succeeded":
raise RuntimeError(result.get("error_code") or result["status"])
print("Download link available; avoid logging signed URLs")
url = client.download_url(task["task_id"])["url"]Source: sdk/python/pdfhq/client.py in the PDFHQ repository. This is a reference implementation, not a separately published or versioned SDK package. It streams signed multipart uploads with bounded memory and rejects unexpected completion paths.
Billing, credentials and retries#
Never expose the API key in browser JavaScript or send it to the signed storage endpoint. The quote is informational; it does not reserve credits. PDFHQ does not automatically retry uncertain mutations or provider-backed signature requests. Inspect the existing task or envelope before attempting recovery.
Error and retry reference