Skip to main content

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)

Source distribution for officepdf 1.0.0
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)

Table of built distributions (wheels) for officepdf 1.0.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.0.0 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