Metadata-Version: 2.5
Name: officepdf
Version: 1.0.0
Summary: OfficePDF — high-fidelity Word to PDF conversion (cloud API and on-premise server)
Project-URL: Homepage, https://getofficepdf.com
Project-URL: Documentation, https://getofficepdf.com/en/docs
Author-email: OfficePDF <support@getofficepdf.com>
License: MIT
License-File: LICENSE
Keywords: conversion,docx,officepdf,pdf,word
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Office Suites
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: fastapi>=0.115; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: python-multipart>=0.0.9; extra == 'dev'
Requires-Dist: uvicorn>=0.30; extra == 'dev'
Description-Content-Type: text/markdown

# 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.

```bash
pip install officepdf
```

No third-party dependencies.

## Quick start

```python
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.

```python
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:

```python
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.

```python
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

```python
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

```python
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:

```python
client.convert("big.docx", on_progress=lambda r: print(r.status, r.pages))
```

## Listing

```python
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

```python
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

```bash
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.
