render_to_file

render_to_file(client: PoliPage, input: RenderInput, path: str | os.PathLike[str]) -> None

Render a PDF and write it to disk (sync).

Parameters

Name	Type	Required	Description
client	PoliPage	required	A `PoliPage` instance.
input	RenderInput	required	Render input. Same shape as `render.pdf`.
path	str | os.PathLike[str]	required	Destination path. Parent directories are created automatically.

Returns

None — None. The PDF is streamed to disk at path.

Errors

Code	When
PROJECT_REQUIRED_FOR_DOCUMENT	Input without a `project`. Rejected locally before the HTTP call.
VALIDATION_ERROR	The request body failed validation.
INVALID_API_KEY	The API key is malformed or revoked.
PROJECT_NOT_FOUND	No project with this slug in the organization.
PROJECT_NOT_IN_ENVIRONMENT	The project is not published in the key's environment.
TEMPLATE_NOT_FOUND	The template is not in the project's copy published in the key's environment.
TEMPLATE_ERROR	The engine rejected the template or its data.
TEMPLATE_UNSAFE	The template, a partial or an SVG asset holds an injection attempt; `detail` names it.
EMPTY_DOCUMENT	The render produced zero pages.
RENDER_BODY_TOO_LARGE	The request body is over the API's size limit (413).
DOCUMENT_TOO_LARGE	The document exceeds an engine cap (413).
QUOTA_EXCEEDED	Monthly quota reached (429). Not retried: it lasts until the monthly reset.
OVERAGE_CAP_EXCEEDED	Overage cap reached on a paid tier (429). Not retried: it lasts until the monthly reset.
RATE_LIMIT_EXCEEDED	Per-key render rate limit reached. Retryable.
PUBLISH_IN_PROGRESS	The project is being published into this environment (503 with `Retry-After`). Retryable.
RENDER_TIMEOUT	The engine's time budget expired (504). Retryable.
timeout	Request exceeded the configured `timeout`. Retryable.
network_error	TCP/TLS-level failure reaching the API. Retryable.
STORAGE_ACCESS_DENIED	The organization's own storage bucket refuses access (502). Not retried: restore the bucket role, then call again.
INTERNAL_ERROR	The API returned 5xx. Retryable.
DOWNLOAD_FAILED	The S3 second-hop download for the rendered PDF failed.

Example

# Demonstrates: render_to_file(client, input, path) from poli_page.fs.
from poli_page import PoliPage
from poli_page.fs import render_to_file

client = PoliPage()

render_to_file(
    client,
    {
        "project": "billing",
        "template": "invoice",
        "data": {"invoiceNumber": "INV-001", "total": 1280},
    },
    "./invoices/INV-001.pdf",
)

# Streams response bytes directly to disk with bounded memory.
# Parent directories are created automatically.
print("Wrote ./invoices/INV-001.pdf")

See also

• Errors
• Configuration