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
|
Split an animated GIF into one PNG per frame. |
|
Print an HTML page to PDF. |
|
Build a Chromium page-footer template with page numbers. |
|
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_CSSplus 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=inhtml_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
.htmlfile.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_pathif given, otherwise the PDF bytes.- Return type:
str | bytes
- Raises:
RuntimeError – No browser could be found or the print failed.