OfficePDF Python SDK
High-fidelity Word to PDF conversion. Works against the OfficePDF cloud API and against an on-premise server with the same code.
pip install officepdf
No third-party dependencies.
Quick start
from officepdf import OfficePDF
client = OfficePDF(api_key="opk_...")
result = client.convert("contract.docx") # uploads, polls, returns
if result.succeeded:
result.save("contract.pdf")
Cloud or on-premise
The same interface; only the base URL changes.
client = OfficePDF(api_key="opk_...") # cloud
client = OfficePDF(base_url="http://localhost:8080") # on-premise
OFFICEPDF_API_KEY and OFFICEPDF_BASE_URL are read from the environment when
not passed explicitly.
Strict mode: rejection is a result, not an error
In strict mode (the default) the engine refuses documents it cannot render correctly rather than producing a PDF that merely looks right. That is a normal outcome, so it does not raise:
result = client.convert("contract.docx", mode="strict")
if result.rejected:
print("Not converted:", result.error.code, result.error.message)
for d in result.diagnostics.errors:
print(d) # p4 error unsupported_equation: ...
elif result.needs_review: # succeeded, but something fell back
result.save("contract.pdf")
for d in result.diagnostics.warnings:
print(d) # p2 warning font_substituted: ...
else:
result.save("contract.pdf")
Use mode="preview" to always get a PDF, with fallbacks recorded in the
diagnostics and degraded set to True.
Diagnostics
Every diagnostic carries the page it happened on.
result.diagnostics # all of them (up to 50 on the job)
result.diagnostics.errors # severity == "error"
result.diagnostics.warnings # severity == "warning"
result.diagnostics.on_page(3) # just page 3
result.diagnostics.with_code("font_substituted")
if result.has_more_diagnostics: # more than 50
everything = result.all_diagnostics() # fetches the full report
The complete engine report — font manifest, hashes, every diagnostic — is
available with result.report().
Outcomes
| Property | Meaning |
|---|---|
result.succeeded |
A PDF was produced |
result.degraded |
Produced, but something fell back |
result.needs_review |
succeeded and degraded — worth a human look |
result.rejected |
Strict mode refused it; result.error says why |
result.failed |
The conversion failed (corrupt file, engine error) |
result.cancelled |
Cancelled by client.cancel(id) |
Saving
result.save("out.pdf") # atomic; creates parent directories
data = result.download() # bytes
client.convert_to("in.docx", "out.pdf") # convert and save in one call
Without blocking
job = client.create_conversion("contract.docx") # returns immediately
...
result = client.wait(job.id, timeout=600) # polls with backoff
Pass on_progress to convert or wait to observe each poll:
client.convert("big.docx", on_progress=lambda r: print(r.status, r.pages))
Listing
page = client.list_conversions(limit=20, status="succeeded")
for result in page:
print(result.id, result.pages)
for result in client.iter_conversions(): # follows cursors
...
Errors
from officepdf import (APIError, AuthenticationError, QuotaExhaustedError,
RateLimitError, UnsupportedFormatError, FileTooLargeError,
OutputExpiredError, TimeoutError_, ConnectionError_)
Every API error carries .status, .code and .message; branch on .code.
Transient failures (429, 5xx, network) are retried automatically with jittered
backoff — max_retries=3 by default.
Tests
pip install -e ".[dev]"
pytest
The suite runs a real on-premise server with a stubbed engine, so multipart uploads, polling, error envelopes and file writes are genuinely exercised.
Metadata
Release files for officepdf 1.0.0
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 |
|---|---|---|---|---|
| officepdf-1.0.0.tar.gz | 10.1 kB | Without provenance | Details for officepdf-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| officepdf-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for officepdf-1.0.0-py3-none-any.whl |
Total release size: 22.1 kB
Release files / officepdf-1.0.0.tar.gz
| Download URL | officepdf-1.0.0.tar.gz |
|---|---|
| Size | 10.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
286fb6cbb9481668bff0b90338504fc5a76e50257793c524f0d46c7fa0399153
|
|
BLAKE2b-256 checksum How to use checksums |
5797fa8bfd1ecaea65d0a6c0c477b789e6e196328836a312a84f4b16f4df9004
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.8
|
Release files / officepdf-1.0.0-py3-none-any.whl
| Download URL | officepdf-1.0.0-py3-none-any.whl |
|---|---|
| Size | 12.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dd41c6683575f6cd00ce33e763cab38ab78fc351ec3d919be6045d82df9fe016
|
|
BLAKE2b-256 checksum How to use checksums |
55a31c1ef8b46320025c0f2480ee710dff2a35c630da4ef77b29105cfe50d60a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.8
|
Security for officepdf 1.0.0
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.