Source code for bokeh.io.export

#-----------------------------------------------------------------------------
# Copyright (c) 2012 - 2024, Anaconda, Inc., and Bokeh Contributors.
# All rights reserved.
#
# The full license is in the file LICENSE.txt, distributed with this software.
#-----------------------------------------------------------------------------
'''

'''

#-----------------------------------------------------------------------------
# Boilerplate
#-----------------------------------------------------------------------------
from __future__ import annotations

import logging # isort:skip
log = logging.getLogger(__name__)

#-----------------------------------------------------------------------------
# Imports
#-----------------------------------------------------------------------------

# Standard library imports
import io
import os
from contextlib import contextmanager
from os.path import abspath, expanduser, splitext
from tempfile import mkstemp
from typing import (
    TYPE_CHECKING,
    Any,
    Iterator,
    cast,
)

if TYPE_CHECKING:
    from selenium.webdriver.remote.webdriver import WebDriver

# Bokeh imports
from ..core.types import PathLike
from ..document import Document
from ..embed import file_html
from ..resources import INLINE, Resources
from ..themes import Theme
from ..util.warnings import warn
from .state import State, curstate
from .util import default_filename

if TYPE_CHECKING:
    from PIL import Image

    from ..models.plots import Plot
    from ..models.ui import UIElement

#-----------------------------------------------------------------------------
# Globals and constants
#-----------------------------------------------------------------------------

__all__ = (
    'export_png',
    'export_svg',
    'export_svgs',
    'get_layout_html',
    'get_screenshot_as_png',
    'get_svgs',
)

#-----------------------------------------------------------------------------
# General API
#-----------------------------------------------------------------------------

[docs] def export_png(obj: UIElement | Document, *, filename: PathLike | None = None, width: int | None = None, height: int | None = None, scale_factor: float = 1, webdriver: WebDriver | None = None, timeout: int = 5, state: State | None = None) -> str: ''' Export the ``UIElement`` object or document as a PNG. If the filename is not given, it is derived from the script name (e.g. ``/foo/myplot.py`` will create ``/foo/myplot.png``) Args: obj (UIElement or Document) : a Layout (Row/Column), Plot or Widget object or Document to export. filename (PathLike, e.g. str, Path, optional) : filename to save document under (default: None) If None, infer from the filename. width (int) : the desired width of the exported layout obj only if it's a Plot instance. Otherwise the width kwarg is ignored. height (int) : the desired height of the exported layout obj only if it's a Plot instance. Otherwise the height kwarg is ignored. scale_factor (float, optional) : A factor to scale the output PNG by, providing a higher resolution while maintaining element relative scales. webdriver (selenium.webdriver) : a selenium webdriver instance to use to export the image. timeout (int) : the maximum amount of time (in seconds) to wait for Bokeh to initialize (default: 5) (Added in 1.1.1). state (State, optional) : A :class:`State` object. If None, then the current default implicit state is used. (default: None). Returns: filename (str) : the filename where the static file is saved. If you would like to access an Image object directly, rather than save a file to disk, use the lower-level :func:`~bokeh.io.export.get_screenshot_as_png` function. .. warning:: Responsive sizing_modes may generate layouts with unexpected size and aspect ratios. It is recommended to use the default ``fixed`` sizing mode. ''' image = get_screenshot_as_png(obj, width=width, height=height, scale_factor=scale_factor, driver=webdriver, timeout=timeout, state=state) if filename is None: filename = default_filename("png") if image.width == 0 or image.height == 0: raise ValueError("unable to save an empty image") filename = os.fspath(filename) # XXX: Image.save() doesn't fully support PathLike image.save(filename) return abspath(expanduser(filename))
[docs] def export_svg(obj: UIElement | Document, *, filename: PathLike | None = None, width: int | None = None, height: int | None = None, webdriver: WebDriver | None = None, timeout: int = 5, state: State | None = None) -> list[str]: ''' Export a layout as SVG file or a document as a set of SVG files. If the filename is not given, it is derived from the script name (e.g. ``/foo/myplot.py`` will create ``/foo/myplot.svg``) Args: obj (UIElement object) : a Layout (Row/Column), Plot or Widget object to display filename (PathLike, e.g. str, Path, optional) : filename to save document under (default: None) If None, infer from the filename. width (int) : the desired width of the exported layout obj only if it's a Plot instance. Otherwise the width kwarg is ignored. height (int) : the desired height of the exported layout obj only if it's a Plot instance. Otherwise the height kwarg is ignored. webdriver (selenium.webdriver) : a selenium webdriver instance to use to export the image. timeout (int) : the maximum amount of time (in seconds) to wait for Bokeh to initialize (default: 5) state (State, optional) : A :class:`State` object. If None, then the current default implicit state is used. (default: None). Returns: filenames (list(str)) : the list of filenames where the SVGs files are saved. .. warning:: Responsive sizing_modes may generate layouts with unexpected size and aspect ratios. It is recommended to use the default ``fixed`` sizing mode. ''' svgs = get_svg(obj, width=width, height=height, driver=webdriver, timeout=timeout, state=state) return _write_collection(svgs, filename, "svg")
[docs] def export_svgs(obj: UIElement | Document, *, filename: str | None = None, width: int | None = None, height: int | None = None, webdriver: WebDriver | None = None, timeout: int = 5, state: State | None = None) -> list[str]: ''' Export the SVG-enabled plots within a layout. Each plot will result in a distinct SVG file. If the filename is not given, it is derived from the script name (e.g. ``/foo/myplot.py`` will create ``/foo/myplot.svg``) Args: obj (UIElement object) : a Layout (Row/Column), Plot or Widget object to display filename (str, optional) : filename to save document under (default: None) If None, infer from the filename. width (int) : the desired width of the exported layout obj only if it's a Plot instance. Otherwise the width kwarg is ignored. height (int) : the desired height of the exported layout obj only if it's a Plot instance. Otherwise the height kwarg is ignored. webdriver (selenium.webdriver) : a selenium webdriver instance to use to export the image. timeout (int) : the maximum amount of time (in seconds) to wait for Bokeh to initialize (default: 5) (Added in 1.1.1). state (State, optional) : A :class:`State` object. If None, then the current default implicit state is used. (default: None). Returns: filenames (list(str)) : the list of filenames where the SVGs files are saved. .. warning:: Responsive sizing_modes may generate layouts with unexpected size and aspect ratios. It is recommended to use the default ``fixed`` sizing mode. ''' svgs = get_svgs(obj, width=width, height=height, driver=webdriver, timeout=timeout, state=state) if len(svgs) == 0: log.warning("No SVG Plots were found.") return [] return _write_collection(svgs, filename, "svg")
#----------------------------------------------------------------------------- # Dev API #-----------------------------------------------------------------------------
[docs] def get_screenshot_as_png(obj: UIElement | Document, *, driver: WebDriver | None = None, timeout: int = 5, resources: Resources = INLINE, width: int | None = None, height: int | None = None, scale_factor: float = 1, state: State | None = None) -> Image.Image: ''' Get a screenshot of a ``UIElement`` object. Args: obj (UIElement or Document) : a Layout (Row/Column), Plot or Widget object or Document to export. driver (selenium.webdriver) : a selenium webdriver instance to use to export the image. timeout (int) : the maximum amount of time to wait for initialization. It will be used as a timeout for loading Bokeh, then when waiting for the layout to be rendered. scale_factor (float, optional) : A factor to scale the output PNG by, providing a higher resolution while maintaining element relative scales. state (State, optional) : A :class:`State` object. If None, then the current default implicit state is used. (default: None). Returns: image (PIL.Image.Image) : a pillow image loaded from PNG. .. warning:: Responsive sizing_modes may generate layouts with unexpected size and aspect ratios. It is recommended to use the default ``fixed`` sizing mode. ''' from .webdriver import get_web_driver_device_pixel_ratio, scale_factor_less_than_web_driver_device_pixel_ratio, webdriver_control with _tmp_html() as tmp: theme = (state or curstate()).document.theme html = get_layout_html(obj, resources=resources, width=width, height=height, theme=theme) with open(tmp.path, mode="w", encoding="utf-8") as file: file.write(html) if driver is not None: web_driver = driver if not scale_factor_less_than_web_driver_device_pixel_ratio(scale_factor, web_driver): device_pixel_ratio = get_web_driver_device_pixel_ratio(web_driver) raise ValueError(f'Expected the web driver to have a device pixel ratio greater than {scale_factor}. ' f'Was given a web driver with a device pixel ratio of {device_pixel_ratio}.') else: web_driver = webdriver_control.get(scale_factor=scale_factor) web_driver.maximize_window() web_driver.get(f"file://{tmp.path}") wait_until_render_complete(web_driver, timeout) [width, height, dpr] = _maximize_viewport(web_driver) png = web_driver.get_screenshot_as_png() from PIL import Image return (Image.open(io.BytesIO(png)) .convert("RGBA") .crop((0, 0, width*dpr, height*dpr)) .resize((int(width*scale_factor), int(height*scale_factor))))
def get_svg(obj: UIElement | Document, *, driver: WebDriver | None = None, timeout: int = 5, resources: Resources = INLINE, width: int | None = None, height: int | None = None, state: State | None = None) -> list[str]: from .webdriver import webdriver_control with _tmp_html() as tmp: theme = (state or curstate()).document.theme html = get_layout_html(obj, resources=resources, width=width, height=height, theme=theme) with open(tmp.path, mode="w", encoding="utf-8") as file: file.write(html) web_driver = driver if driver is not None else webdriver_control.get() web_driver.get(f"file://{tmp.path}") wait_until_render_complete(web_driver, timeout) svgs = cast(list[str], web_driver.execute_script(_SVG_SCRIPT)) return svgs def get_svgs(obj: UIElement | Document, *, driver: WebDriver | None = None, timeout: int = 5, resources: Resources = INLINE, width: int | None = None, height: int | None = None, state: State | None = None) -> list[str]: from .webdriver import webdriver_control with _tmp_html() as tmp: theme = (state or curstate()).document.theme html = get_layout_html(obj, resources=resources, width=width, height=height, theme=theme) with open(tmp.path, mode="w", encoding="utf-8") as file: file.write(html) web_driver = driver if driver is not None else webdriver_control.get() web_driver.get(f"file://{tmp.path}") wait_until_render_complete(web_driver, timeout) svgs = cast(list[str], web_driver.execute_script(_SVGS_SCRIPT)) return svgs
[docs] def get_layout_html(obj: UIElement | Document, *, resources: Resources = INLINE, width: int | None = None, height: int | None = None, theme: Theme | None = None) -> str: ''' ''' template = r"""\ {% block preamble %} <style> html, body { box-sizing: border-box; width: 100%; height: 100%; margin: 0; border: 0; padding: 0; overflow: hidden; } </style> {% endblock %} """ def html() -> str: return file_html( obj, resources=resources, title="", template=template, theme=theme, suppress_callback_warning=True, _always_new=True, ) if width is not None or height is not None: # Defer this import, it is expensive from ..models.plots import Plot if not isinstance(obj, Plot): warn("Export method called with width or height argument on a non-Plot model. The size values will be ignored.") else: with _resized(obj, width, height): return html() return html()
def wait_until_render_complete(driver: WebDriver, timeout: int) -> None: ''' ''' from selenium.common.exceptions import TimeoutException from selenium.webdriver.support.wait import WebDriverWait def is_bokeh_loaded(driver: WebDriver) -> bool: return cast(bool, driver.execute_script(''' return typeof Bokeh !== "undefined" && Bokeh.documents != null && Bokeh.documents.length != 0 ''')) try: WebDriverWait(driver, timeout, poll_frequency=0.1).until(is_bokeh_loaded) except TimeoutException as e: _log_console(driver) raise RuntimeError('Bokeh was not loaded in time. Something may have gone wrong.') from e driver.execute_script(_WAIT_SCRIPT) def is_bokeh_render_complete(driver: WebDriver) -> bool: return cast(bool, driver.execute_script('return window._bokeh_render_complete;')) try: WebDriverWait(driver, timeout, poll_frequency=0.1).until(is_bokeh_render_complete) except TimeoutException: log.warning("The webdriver raised a TimeoutException while waiting for " "a 'bokeh:idle' event to signify that the layout has rendered. " "Something may have gone wrong.") finally: _log_console(driver) #----------------------------------------------------------------------------- # Private API #----------------------------------------------------------------------------- @contextmanager def _resized(obj: Plot, width: int | None, height: int | None) -> Iterator[None]: old_width = obj.width old_height = obj.height if width is not None: obj.width = width if height is not None: obj.height = height yield obj.width = old_width obj.height = old_height def _write_collection(items: list[str], filename: PathLike | None, ext: str) -> list[str]: if filename is None: filename = default_filename(ext) filename = os.fspath(filename) filenames: list[str] = [] def _indexed(name: str, i: int) -> str: basename, ext = splitext(name) return f"{basename}_{i}{ext}" for i, item in enumerate(items): fname = filename if i == 0 else _indexed(filename, i) with open(fname, mode="w", encoding="utf-8") as f: f.write(item) filenames.append(fname) return filenames def _log_console(driver: WebDriver) -> None: levels = {'WARNING', 'ERROR', 'SEVERE'} try: logs = driver.get_log('browser') except Exception: return messages = [ log.get("message") for log in logs if log.get('level') in levels ] if len(messages) > 0: log.warning("There were browser warnings and/or errors that may have affected your export") for message in messages: log.warning(message) def _maximize_viewport(web_driver: WebDriver) -> tuple[int, int, int]: calculate_viewport_size = """\ const root_view = Bokeh.index.roots[0] const {width, height} = root_view.el.getBoundingClientRect() return [Math.round(width), Math.round(height), window.devicePixelRatio] """ viewport_size: tuple[int, int, int] = web_driver.execute_script(calculate_viewport_size) calculate_window_size = """\ const [width, height, dpr] = arguments return [ // XXX: outer{Width,Height} can be 0 in headless mode under certain window managers Math.round(Math.max(0, window.outerWidth - window.innerWidth) + width*dpr), Math.round(Math.max(0, window.outerHeight - window.innerHeight) + height*dpr), ] """ [width, height] = web_driver.execute_script(calculate_window_size, *viewport_size) eps = 100 # XXX: can't set window size exactly in certain window managers, crop it to size later web_driver.set_window_size(width + eps, height + eps) return viewport_size # TODO: consider UIElement like Pane _SVGS_SCRIPT = """ const {LayoutDOMView} = Bokeh.require("models/layouts/layout_dom") const {PlotView} = Bokeh.require("models/plots/plot") function* collect_svgs(views) { for (const view of views) { if (view instanceof LayoutDOMView) { yield* collect_svgs(view.child_views.values()) } if (view instanceof PlotView && view.model.output_backend == "svg") { const {ctx} = view.canvas_view.compose() yield ctx.get_serialized_svg(true) } } } return [...collect_svgs(Bokeh.index)] """ _SVG_SCRIPT = """\ function* export_svgs(views) { for (const view of views) { // TODO: use to_blob() API in future const {ctx} = view.export("svg") yield ctx.get_serialized_svg(true) } } return [...export_svgs(Bokeh.index)] """ _WAIT_SCRIPT = """ // add private window prop to check that render is complete window._bokeh_render_complete = false; function done() { window._bokeh_render_complete = true; } const doc = Bokeh.documents[0]; if (doc.is_idle) done(); else doc.idle.connect(done); """ class _TempFile: _closed: bool = False fd: int path: str def __init__(self, *, prefix: str = "tmp", suffix: str = "") -> None: # XXX: selenium has issues with /tmp directory (or equivalent), so try using the # current directory first, if writable, and otherwise fall back to the system # default tmp directory. try: self.fd, self.path = mkstemp(prefix=prefix, suffix=suffix, dir=os.getcwd()) except OSError: self.fd, self.path = mkstemp(prefix=prefix, suffix=suffix) def __enter__(self) -> _TempFile: return self def __exit__(self, exc: Any, value: Any, tb: Any) -> None: self.close() def __del__(self) -> None: self.close() def close(self) -> None: if self._closed: return try: os.close(self.fd) except OSError: pass try: os.unlink(self.path) except OSError: pass self._closed = True def _tmp_html() -> _TempFile: return _TempFile(prefix="bokeh", suffix=".html") #----------------------------------------------------------------------------- # Code #-----------------------------------------------------------------------------