Skip to main content

libreserv-client

Python client for libreserv, the LibreOffice document-conversion service. Convert documents (docx → pdf, xlsx → csv, pptx → pdf, …) through a libreserv server with one call — synchronously or asynchronously.

  • Python ≥ 3.9, one dependency (httpx)
  • Sync and async client with identical APIs
  • Typed models, a precise exception hierarchy, webhook signature verification

Installation

pip install libreserv-client

Quick start

from libreserv_client import LibreservClient

client = LibreservClient(
    "https://convert.example.com",   # your libreserv server
    api_key="lsv_...",               # issued by a libreserv admin, per app
)

# one call: upload, convert, download
client.convert("report.docx", "pdf", output="report.pdf")

# or work with bytes in memory
pdf_bytes = client.convert("report.docx", "pdf")

convert() uses the server's synchronous endpoint and transparently falls back to polling when a conversion outlasts the server-side wait — you always get the finished document back (or a precise exception).

Use the client as a context manager in scripts, or keep one long-lived instance per process in services (it pools connections):

with LibreservClient(url, api_key=key) as client:
    client.convert("in.xlsx", "csv", output="out.csv")

Async

AsyncLibreservClient mirrors the sync client method-for-method:

import asyncio
from libreserv_client import AsyncLibreservClient

async def main():
    async with AsyncLibreservClient("https://convert.example.com", api_key="lsv_...") as client:
        pdf = await client.convert("report.docx", "pdf")

asyncio.run(main())

The job workflow (async jobs, webhooks)

For long conversions or fire-and-forget submission, use the job API:

job = client.submit_job(
    "big-presentation.pptx", "pdf",
    webhook_url="https://myapp.example.com/hooks/libreserv",  # optional
)
print(job.id, job.status)          # -> "…-uuid-…", "queued"

job = client.wait_for_job(job.id)  # polls until terminal
if job.succeeded:
    client.download_result(job.id, output="deck.pdf")
else:
    print(job.error_code, job.error_msg)

client.job_log(job.id)             # full server-side conversion log (str)
client.download_source(job.id)     # the original upload, while retained
client.cancel_job(job.id)          # cancel queued/running jobs
client.list_jobs(status="failed")  # your app's job history

Documents can be given as a path, raw bytes, an open binary file, or an explicit ("filename.docx", payload) pair — the filename determines both LibreOffice's import format detection and the result's download name.

Verifying webhooks

When a job with a webhook_url finishes, the server POSTs a JSON body signed with your app's webhook secret (client.me().webhook_secret). In your handler, verify and parse it with the raw request bytes — verification is built into parse_webhook and cannot be skipped, since a webhook endpoint is reachable by anyone on the network:

from libreserv_client import parse_webhook, SignatureVerificationError

def hook(request):
    try:
        event = parse_webhook(
            request.body,
            secret=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; HTTP errors map to precise subclasses of APIError:

Exception When
AuthenticationError 401 — bad/revoked key, deactivated app
PermissionDeniedError 403 — admin-only endpoint, or your app's source/Referer restrictions rejected the request
NotFoundError 404 — unknown job (or another app's job)
ConflictError 409 — e.g. downloading a result that isn't ready
GoneError 410 — artifacts expired (retention)
FileTooLargeError 413 — upload over your app's size limit
InvalidRequestError 422 — unsupported target format, bad fields
ConversionFailedError the document itself cannot be converted; .error_code says why (load_failed, no_filter, …)
QuotaExceededError 429 — jobs/day, jobs/minute, or concurrency quota
ServiceUnavailableError 503/507 — queue down or server out of disk
ServerError any 5xx
TransportError the server could not be reached (DNS, connection, TLS, timeout) — the underlying httpx error is its __cause__
WaitTimeout client-side wait expired; the job keeps running server-side
SignatureVerificationError a webhook's signature is missing or wrong
WebhookPayloadError a correctly signed webhook body is not the expected JSON
from libreserv_client import ConversionFailedError, QuotaExceededError

try:
    client.convert("input.docx", "pdf", output="out.pdf")
except ConversionFailedError as error:
    print(f"unconvertible document: {error.error_code} — {error}")
except QuotaExceededError:
    retry_later()

Identify your application

The client sends libreserv-client-python/<version> as its User-Agent, and the server records it per API key for diagnostics. Add your own identifier so operators can tell your app's traffic apart:

client = LibreservClient(url, api_key=key, app_identifier="invoice-service/2.3")

TLS and private CAs

Certificates are verified against the system CA bundle by default. For a self-hosted server with an internal CA, pass the bundle (or an ssl.SSLContext) — never disable verification in production:

client = LibreservClient(url, api_key=key, verify="/etc/ssl/corp-ca.pem")

Typing

The package ships a py.typed marker and passes mypy --strict; all models are frozen dataclasses, so your type checker sees every field and return type.

Account helpers

client.me()        # AppInfo: your quotas, restrictions, webhook secret
client.usage(date_from="2026-08-01", date_to="2026-08-31")  # daily rows + totals
client.formats()   # {"pdf": "pdf", "docx": "docx", ...}

Versioning

This library follows Semantic Versioning; see CHANGELOG.md. The current version is available as libreserv_client.__version__.

Development

uv sync
uv run pytest
uv run ruff check src tests
uv run mypy --strict src

Contributing

Issues and pull requests are welcome on GitHub. Development happens in our GitLab, which mirrors master to GitHub — see CONTRIBUTING.md for how PRs land (squash-merged, with attribution preserved) and SECURITY.md for reporting vulnerabilities privately.

License

MIT

Metadata

Release files for libreserv-client 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for libreserv-client 1.0.1
File Size Uploaded Provenance Actions
libreserv_client-1.0.1.tar.gz 20.1 kB Without provenance Details for libreserv_client-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for libreserv-client 1.0.1
File Interpreter ABI Platform Actions
libreserv_client-1.0.1-py3-none-any.whl Python 3 none any Details for libreserv_client-1.0.1-py3-none-any.whl

Total release size: 40.9 kB

Release files / libreserv_client-1.0.1.tar.gz

Download URL libreserv_client-1.0.1.tar.gz
Size 20.1 kB
Tags Source
SHA-256 checksum
How to use checksums
f2f8f113bb39ab392bbc3c21a0e3b659ad39e5d3d84647c1cc7b956ad257bfe9
BLAKE2b-256 checksum
How to use checksums
ff8cfad0265cd1d924a65d39e5197ee0654e03e3d359c757c0e8c53ec42ab353
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / libreserv_client-1.0.1-py3-none-any.whl

Download URL libreserv_client-1.0.1-py3-none-any.whl
Size 20.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f0151c9215647dc2b311621f0a40a7fe5bef00ae6a38759ae397bfcde1e8b73f
BLAKE2b-256 checksum
How to use checksums
d8666d5c018a6047d266aede519a40b2c997a154e549f9b435af66417f095d2f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for libreserv-client 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page