Client library
libreserv-client
is the official Python client. Python ≥ 3.9, one dependency
(httpx), MIT license.
pip install libreserv-clientSynchronous
from libreserv_client import LibreservClient
with LibreservClient("https://convert.example.com", api_key="lsv_...") as client:
# one call: upload, convert, download
client.convert("report.docx", "pdf", output="report.pdf")
# or keep the result in memory
pdf_bytes = client.convert("report.docx", "pdf")
Asynchronous
AsyncLibreservClient mirrors the sync client method for method:
from libreserv_client import AsyncLibreservClient
async with AsyncLibreservClient(url, api_key=key) as client:
pdf = await client.convert("report.docx", "pdf")
The job workflow
job = client.submit_job(
"big-presentation.pptx", "pdf",
webhook_url="https://myapp.example.com/hooks/libreserv", # optional
)
job = client.wait_for_job(job.id) # or rely on the webhook
if job.succeeded:
client.download_result(job.id, output="deck.pdf")
else:
print(job.error_code, job.error_msg)
client.job_log(job.id) # the server-side conversion log
client.download_source(job.id) # the original upload
client.list_jobs(status="failed") # your app's history
Documents can be a path, raw bytes, an open binary file, or a
("filename.docx", payload) pair — the filename drives format
detection and the result's download name.
Verifying webhooks
from libreserv_client import parse_webhook, SignatureVerificationError
def hook(request):
try:
event = parse_webhook(
request.body, # raw bytes!
secret=WEBHOOK_SECRET, # client.me().webhook_secret
signature_header=request.headers["X-Libreserv-Signature"],
)
except SignatureVerificationError:
return 403
if event.succeeded:
queue_download(event.job_id)
return 200
Error handling
Everything the library raises derives from LibreservError —
network failures included — so one except is exhaustive:
AuthenticationError | 401 — bad or revoked key, deactivated app |
PermissionDeniedError | 403 — admin endpoint, or source/Referer restrictions |
NotFoundError / GoneError | 404 / 410 — unknown job, or artifacts expired |
FileTooLargeError | 413 — upload over the app's size limit |
InvalidRequestError | 422 — unsupported format, bad fields |
ConversionFailedError | the document itself cannot be converted; .error_code says why |
QuotaExceededError | 429 — daily / per-minute / concurrency quota |
ServiceUnavailableError / ServerError | 503/507 / any 5xx |
TransportError | network failure — DNS, connection, TLS, timeout |
WaitTimeout | client-side wait expired; the job keeps running server-side |
Identify your application
client = LibreservClient(url, api_key=key, app_identifier="invoice-service/2.3")
The server records each key's User-Agent, so operators can tell your app's traffic apart when diagnosing issues.