geeViz.outputLib.pdf

Print an HTML page to PDF.

geeViz builds one HTML page per report and prints it; there is no separate PDF layout to keep in step with the HTML. html_to_pdf() takes that page, adapts it for paper, and prints it with headless Chromium through Playwright:

  • Charts stay vector. Plotly runs in the page as it does on screen, so a chart in the PDF is the chart in the HTML, not a PNG of it.

  • Tables break between rows, never through one. The part on the next page starts with a “Continued” label and the header row again. Scroll boxes are opened up so the whole table prints.

  • Animated GIFs become a grid of their frames, one pane per frame. A pane is never split across a page break, and frames carried onto the next page start with a “Continued” label, as tables do.

  • Headings stay with what follows them, and figures are not split.

  • Each report section starts with a horizontal rule.

  • Every page gets a footer with the page number, and a dark page is dark to the paper’s edge.

  • A table too wide for the page shrinks its text to fit.

Why Chromium: it runs the page’s JavaScript, which a report needs for its Plotly charts. WeasyPrint has the better CSS paged-media support but runs no JavaScript at all, and wkhtmltopdf is unmaintained. Playwright drives the browser installed on the machine (Chrome, Edge or Chromium), so nothing extra is downloaded; playwright install chromium is only needed where no browser is installed. Without Playwright the browser’s own --print-to-pdf is used, which prints the same page but without page numbers and with a fixed wait for the charts.

Example:

from geeViz.outputLib import reports as rl

html = report.generate(format="html")
rl.html_to_pdf(html, "report.pdf")

Functions

gif_frames(gif_bytes)

Split an animated GIF into one PNG per frame.

html_to_pdf(html[, output_path, layout, ...])

Print an HTML page to PDF.

page_footer([content_html, color, bg])

Build a Chromium page-footer template with page numbers.

prepare_html_for_pdf(html[, layout, gif_columns])

Adapt an HTML page for printing.

geeViz.outputLib.pdf.gif_frames(gif_bytes)[source]

Split an animated GIF into one PNG per frame.

Parameters:

gif_bytes (bytes) – The GIF file.

Returns:

PNG bytes, one per frame, in order. A still GIF gives one frame.

Return type:

list[bytes]

geeViz.outputLib.pdf.prepare_html_for_pdf(html, layout='report', gif_columns=None)[source]

Adapt an HTML page for printing.

Replaces each embedded animated GIF (data:image/gif;base64) with a grid of its frames and adds the print stylesheet (PRINT_CSS plus the page size). Everything else is left as it is.

Parameters:
  • html (str) – The page.

  • layout (str) – "report" (Letter portrait) or "poster".

  • gif_columns (int, optional) – Frames per row. Defaults to 3 for a report and 4 for a poster.

Returns:

The page, ready to print.

Return type:

str

Build a Chromium page-footer template with page numbers.

Parameters:
  • content_html (str) – What goes on the left of every footer. Images must be data: URIs; the footer cannot load anything.

  • color (str) – Text color.

  • bg (str, optional) – Footer background, for dark pages.

Returns:

The template for footer_template= in html_to_pdf().

Return type:

str

geeViz.outputLib.pdf.html_to_pdf(html, output_path=None, layout='report', footer_template=None, gif_columns=None, timeout=180, allowed_hosts=None)[source]

Print an HTML page to PDF.

The page is adapted for paper first (see prepare_html_for_pdf()): GIFs become grids of frame panes, tables break between rows and repeat their header, and figures and headings are kept whole. Then headless Chromium prints it, with its JavaScript run, so Plotly charts come out as vector graphics.

Parameters:
  • html (str) – The page, or the path to an .html file.

  • output_path (str, optional) – Where to write the PDF. If None, the PDF bytes are returned instead.

  • layout (str) – "report" (Letter portrait, the default) or "poster" (the page size the poster’s own CSS sets).

  • footer_template (str, optional) – Chromium footer template, as made by page_footer(). Defaults to page numbers alone.

  • gif_columns (int, optional) – Frames per row for GIFs.

  • timeout (int) – Seconds to wait for the page and its charts.

  • allowed_hosts (list[str], optional) – Hosts the page may load anything from, for printing HTML you did not write (a server passes REPORT_HOSTS). Without Playwright there is no way to enforce it, so the print fails rather than falling back to the browser’s own unguarded --print-to-pdf. Local files other than the page, and private and loopback addresses, are refused either way.

Returns:

output_path if given, otherwise the PDF bytes.

Return type:

str | bytes

Raises:

RuntimeError – No browser could be found or the print failed.