Browser PDF export#

Serverless browser-PDF export is available with ADR 27.1 and later. It stages an offline report bundle, opens that bundle with the Chromium package shipped with ADR, and prints the browser-rendered report to PDF.

ADR 26.1 remains supported by PyDynamicReporting 1.x, but it does not contain the required browser package. Serverless PDF rendering is therefore unavailable with ADR 26.1.

Configure static assets#

Set a local ADR 27.1 installation and a static_directory, then collect the product’s static files during setup:

from ansys.dynamicreporting.core.serverless import ADR, PDFPageSize

adr = ADR(
    ansys_installation=r"C:\Program Files\ANSYS Inc\v271",
    db_directory=r"C:\reports\database",
    media_directory=r"C:\reports\media",
    static_directory=r"C:\reports\static",
)
adr.setup(collect_static=True)

Both static_directory and collect_static=True are required so the offline bundle contains the report’s styles, scripts, fonts, and other static assets.

Render PDF bytes#

Use render_report_as_browser_pdf() when another API or storage layer needs the PDF as bytes:

pdf_bytes = adr.render_report_as_browser_pdf(
    name="Simulation Summary",
    context={"project": "wing"},
    item_filter="A|i_tags|cont|project=wing;",
    dark_mode=True,
    landscape=True,
    page_size=PDFPageSize.A3,
    margins={
        "top": "12mm",
        "right": "12mm",
        "bottom": "12mm",
        "left": "12mm",
    },
    render_timeout=45,
)

with open("simulation-summary.pdf", "wb") as pdf_file:
    pdf_file.write(pdf_bytes)

Write a PDF file#

Use export_report_as_browser_pdf() to write the report directly:

adr.export_report_as_browser_pdf(
    filename="simulation-summary.pdf",
    name="Simulation Summary",
    context={"project": "wing"},
    item_filter="A|i_tags|cont|project=wing;",
    dark_mode=True,
    page_size=PDFPageSize.A3,
)

If filename is omitted, the export uses the report template GUID with a .pdf suffix. Both methods require at least one template lookup argument, such as name or guid.

Page sizes#

Browser-PDF export defaults to PDFPageSize.A3. The following fixed formats are available: PDFPageSize.LETTER, PDFPageSize.LEGAL, PDFPageSize.TABLOID, PDFPageSize.LEDGER, and PDFPageSize.A0 through PDFPageSize.A6.

For a custom page, set page_size=None and provide both width and height:

pdf_bytes = adr.render_report_as_browser_pdf(
    name="Simulation Summary",
    page_size=None,
    width="320mm",
    height="450mm",
)

Each custom dimension can be a positive number, interpreted as CSS pixels, or a string using px, in, cm, or mm. Supplying only one dimension raises ADRException. If page_size is None and neither dimension is provided, the export falls back to A3.

page_size takes precedence over width and height whenever it is not None. Set it to None to activate custom dimensions. Setting landscape=True swaps the selected width and height for either fixed or custom sizing. Content wider than the printable area is clipped and never expands the page.

Diagnosing failures#

Unlike the service-mode export_browser_pdf(), which returns False on failure for backward compatibility, both serverless methods raise ADRException when the export fails, for example when a readiness signal such as Plotly charts does not finish within render_timeout. Catch that exception to see the specific reason:

from ansys.dynamicreporting.core.exceptions import ADRException

try:
    adr.export_report_as_browser_pdf(
        filename="simulation-summary.pdf", name="Simulation Summary"
    )
except ADRException as exc:
    raise RuntimeError(f"Browser PDF export failed: {exc}") from exc

Options#

  • context supplies template rendering values.

  • item_filter limits report items with an ADR query expression.

  • dark_mode selects the report’s dark presentation.

  • landscape defaults to portrait output. When enabled, it swaps the selected page width and height.

  • margins must contain exactly top, right, bottom, and left. Values can use pixels, inches, centimeters, or millimeters. A unitless value is treated as pixels. The default is 10 mm on every side.

  • page_size selects a fixed PDFPageSize and defaults to A3.

  • width and height define a custom page when page_size=None. Both dimensions are required.

  • render_timeout is one shared browser-side budget for browser launch, navigation, readiness checks, and print preparation. It defaults to 30 seconds. Server-side template rendering and offline asset staging occur before that budget starts.

Offline rendering behavior#

The renderer waits for ADR web components, fonts, MathJax, Plotly, images, and videos. Print styling keeps headings with the following content and preserves the report canvas used by responsive charts. Browser layout and pagination use the selected printable page dimensions.

The staged report blocks external network requests. All content needed by the PDF must therefore be present in the offline bundle. Custom asynchronous JavaScript in raw HTML items or layout HTML does not have its own readiness signal and can still be captured before it finishes.

Browser and process requirements#

PyDynamicReporting uses the Chromium package from the configured ADR 27.1 installation; it does not use a machine-wide Playwright browser cache. A missing or incomplete product browser package raises an ADR-owned error.

During rendering, PyDynamicReporting temporarily points PLAYWRIGHT_BROWSERS_PATH at the product browser and restores the caller’s original value afterward. Because this environment variable is process-wide, do not run browser-PDF exports concurrently in the same process.

Temporary offline bundles are removed after the operation. Cleanup failures are retained for debug logging and do not mask a successful PDF or the primary rendering error.