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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.