django-poli-page

Render Poli Page documents as Django HTTP responses.

About

django-poli-page is a reusable Django app around the official poli-page Python SDK. You add it to INSTALLED_APPS, declare a POLI_PAGE settings dict, and you return PDFs, streamed PDFs, stored-document HTML previews, and presigned-URL redirects from your views with one helper call each. The app validates configuration at startup, exposes a lazy PoliPage singleton, and bridges the SDK's retry and error hooks onto Django signals.

When to use this:

• You render invoices, contracts, statements or reports from Django views and want the right Content-Disposition, Cache-Control and Content-Type without rewriting them on each route.
• You want SDK retries and terminal errors observable through django.dispatch instead of bespoke callbacks.
• You want manage.py to fail loudly when your POLI_PAGE settings are wrong.

When not to:

• You need a templatetag library, a class-based view mixin, or a database model for documents — this app deliberately does not ship those.

Requirements

• Python 3.11+
• Django 4.2 LTS, 5.0, 5.1, 5.2 LTS, or 6.0
• The poli-page Python SDK 0.13.x (installed with the app, poli-page>=0.13,<0.14)
• A Poli Page API key (pp_{environment}_…, see API keys)

Install

pip install django-poli-page

This installs the poli-page SDK 0.13.x with it.

Add the app to INSTALLED_APPS and export your key:

# settings.py
INSTALLED_APPS = [
    # ...
    "django_poli_page",
]

POLI_PAGE = {
    "API_KEY": os.environ["POLI_PAGE_API_KEY"],
}

export POLI_PAGE_API_KEY=pp_sandbox_your_key_here

You get a key from the dashboard at app.poli.page under Settings → API Keys. Smoke-test the wiring from the command line:

python manage.py poli_page_render \
    --project=getting-started \
    --template=welcome \
    --data='{"name":"World"}' \
    --output=welcome.pdf

API keys

A key belongs to one environment of your organization and reads pp_{environment}_{32 hex characters}. The environment selects which published copy of a project a render uses, so a render input names a project and a template, never a version.

"Counted" means the render counts toward the organization's monthly PDF quota.

Quick start

# views.py
from django_poli_page import client
from django_poli_page.http import pdf_response


def invoice_view(request, invoice_id):
    pdf = client.render.pdf({
        "project": "invoices",
        "template": "default",
        "data": {"invoice_id": invoice_id},
    })
    return pdf_response(pdf, f"invoice-{invoice_id}.pdf")

Configuration

You configure everything through a single POLI_PAGE dict in your settings module. AppConfig.ready() validates the dict at startup and surfaces problems through manage.py check.

# settings.py
POLI_PAGE = {
    "API_KEY": os.environ["POLI_PAGE_API_KEY"],
    "TIMEOUT": 30,
    "RETRIES": {"MAX_ATTEMPTS": 3, "DELAY_SECONDS": 0.5},
}

When ON_RETRY or ON_ERROR is unset, the SDK hooks dispatch through Django signals instead (see API at a glance).

API at a glance

Errors

Error handler (on by default)

When the app starts, it appends django_poli_page.middleware.PoliPageErrorMiddleware to MIDDLEWARE. A PoliPageError that a view does not catch is answered as JSON:

• the body is the SDK's error.to_payload(), exactly {"code", "message", "status", "requestId"};
• the HTTP status is that payload's status: the API's status for an API error, 503 for network_error, 504 for timeout, 502 for invalid_response (a 2xx whose body is not JSON, usually from a proxy), and 500 when the error has none, as for invalid_options and io_error (the body's status is then null);
• Content-Type: application/json.

{
  "code": "TEMPLATE_NOT_FOUND",
  "message": "Template 'does-not-exist' not found in project 'getting-started'.",
  "status": 404,
  "requestId": "req_..."
}

Other exceptions go on to Django's own handling. The handler is the innermost middleware, so it answers before any other middleware's process_exception. To handle errors yourself, turn it off:

POLI_PAGE = {
    "API_KEY": os.environ["POLI_PAGE_API_KEY"],
    "ERROR_HANDLER": False,
}

The app adds the middleware once, at startup; listing it yourself in MIDDLEWARE places it where you want it, and it is not added a second time. A later replacement of MIDDLEWARE, such as override_settings(MIDDLEWARE=[...]) or pytest-django's settings.MIDDLEWARE = [...] in a test, drops the handler unless the new list includes "django_poli_page.middleware.PoliPageErrorMiddleware".

For a streamed PDF, hand the SDK stream to pdf_stream_response instead of opening it inside a generator: an error raised once the body is streaming comes after the 200 is sent, and no handler can answer it.

Error types

The response helpers do not catch SDK exceptions. Every SDK error is a PoliPageError, which carries code, status, message, and request_id; the main families you can catch in a view are exported from poli_page:

• API status — APIStatusError and its per-status subclasses, such as BadRequestError (400), AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), RateLimitError (429) and InternalServerError (5xx). The API answered with an error status.
• Network / transport — APIConnectionError, and its subclass APITimeoutError. No answer arrived in time.
• Invalid response — InvalidResponseError, code invalid_response. A 2xx whose body is not JSON, usually from a proxy or a captive portal; its status is that 2xx.
• Local and download — a PoliPageError with code invalid_options (bad input or settings), io_error (render_to_file() could not write the file) or DOWNLOAD_FAILED (the PDF download from its presigned URL failed or timed out).

Catch one in the view when a route needs its own answer:

# views.py
from poli_page import NotFoundError

from django_poli_page import client
from django_poli_page.http import pdf_response


def invoice_view(request, invoice_id):
    try:
        pdf = client.render.pdf({
            "project": "invoices",
            "template": "default",
            "data": {"invoice_id": invoice_id},
        })
    except NotFoundError:
        pdf = client.render.pdf({"project": "invoices", "template": "fallback", "data": {}})
    return pdf_response(pdf, f"invoice-{invoice_id}.pdf")

Example app

A runnable Django 5 project under example-app/ covers every public method of the SDK through django-poli-page, with one route per demo step and an interactive dashboard at /. See example-app/README.md for the route map.

cd example-app
uv sync
export POLI_PAGE_API_KEY=pp_sandbox_your_key
uv run python manage.py runserver

Going further

• Streaming large PDFs through pdf_stream_response — forthcoming in docs/streaming.md.
• Document workflow: create, fetch, thumbnails, presigned-URL redirects — forthcoming in docs/documents.md.
• Signals: wiring poli_page_retry and poli_page_error into logging or metrics — forthcoming in docs/signals.md.
• Swapping the underlying httpx.Client for connection-pool tuning or instrumentation — forthcoming in docs/http-client.md.

Compatibility

The package shares its major.minor with the Poli Page API and requires the poli-page SDK of the same minor (see RELEASING.md). It follows the Django supported-versions policy; releases drop a Django row when upstream marks it end-of-life.

Contributing

Run the checks CI runs from the repository root: uv sync --all-extras, then uv run ruff check ., uv run ruff format --check ., uv run mypy src tests example-app/tests scripts and uv run pytest tests/unit.

Contract tests

example-app/tests/test_contract.py runs the integration cases (kind: "impl") of the Poli Page API contract against the example app: a local server plays the API, the app's SDK points at it through POLI_PAGE["BASE_URL"], and Django's test client checks each answer. CI runs them against the contract version pinned in .github/workflows/ci.yml. Locally:

cd example-app
uv sync
POLI_CONTRACT=<path to contract.json> uv run pytest

Without POLI_CONTRACT the test is skipped (in CI it fails). example-app/tests/contract-skip.json lists the cases allowed to fail, each with its reason.

License

Released under the MIT License.