Skip to content
Poli Page Python SDK

Migration

This page tracks breaking changes between versions of poli-page. For the full per-release diff, see the changelog.

From 0.11.0 to 0.13.0

Section titled “From 0.11.0 to 0.13.0”

The SDK now shares its major.minor with the Poli Page API, so there is no 0.12. This release follows the Poli Page API contract v0.13.0. The full guide is in MIGRATION.md in the repo.

  • A 2xx answer whose body is not JSON raises InvalidResponseError (code invalid_response, the real 2xx as status, not retried) instead of a raw json.JSONDecodeError. See Errors.
  • render_to_file and async_render_to_file raise io_error (Failed to write PDF: <target>: <reason>, the OSError as __cause__) instead of the OSError itself, and leave the target as it was when anything fails.
  • The PDF download is bounded by timeout: the whole download for render.pdf and download_pdf(), an idle timeout for render.pdf_stream. Past it, DOWNLOAD_FAILED with Failed to download PDF: timeout.
  • render.pdf_stream raises DOWNLOAD_FAILED from the chunk iterator, not an httpx exception.

From 0.10.0 to 0.11.0

Section titled “From 0.10.0 to 0.11.0”

The SDK now follows the retry policy and the error messages of the Poli Page API contract. The full guide is in MIGRATION.md in the repo.

  • QUOTA_EXCEEDED and OVERAGE_CAP_EXCEEDED (429) and STORAGE_ACCESS_DENIED (502) are no longer retried, and is_retryable() returns False for them. A queue that requeues on is_retryable() now drops these errors at once: handle them by code. See Retries and idempotency.
  • An explicit empty api_key="" raises invalid_options, even when POLI_PAGE_API_KEY is set; the variable is read only when api_key is omitted or None.
  • Retry-After-Ms is ignored: only Retry-After sets the delay before a retry.
  • The SDK-side messages are the specification’s exact texts (Network request failed, Request timed out after <ms>ms, Failed to download PDF: HTTP <status>, Failed to download PDF: network error, HTTP <status> for a non-JSON error body, apiKey is required, project is required). Match err.code, not the message. See Errors.

From 0.9.x to 0.10.0

Section titled “From 0.9.x to 0.10.0”

0.10.0 moves the SDK to the environments contract. It is a breaking change with no deprecation window; while the SDK is on 0.x, a breaking change bumps the minor version. The full guide, with before/after code, is in MIGRATION.md in the repo.

Short version:

  • An API key belongs to one environment and names it: pp_{env}_… (pp_sandbox_…, pp_live_…, pp_staging_…). The old test-mode and service-account prefixes are gone: standard and service keys share this one format. See Authentication.
  • There is no version input any more: a render uses the project’s copy published in the key’s environment. DocumentDescriptor.version is gone too.
  • The template-preview method and inline-HTML rendering are removed, with their types; previews live in the playground at play.poli.page. documents.preview(id), the stored HTML of a rendered document, stays.
  • ProjectModeInput is renamed RenderInput, the only render input type. See Render input.
  • Removed error codes: VERSION_NOT_FOUND, INVALID_VERSION_FORMAT, VERSION_REQUIRED, INVALID_VERSION_FOR_KEY_ENV, MISSING_PROJECT_OR_TEMPLATE, GONE (now DOCUMENT_GONE) and PAYMENT_REQUIRED (now ORGANIZATION_PAYMENT_GRACE). See Errors.

0.9.0

Section titled “0.9.0”

The first public release. Its surface and how it maps to the Node SDK are documented in MIGRATION.md in the repo.

See also

Section titled “See also”