bokeh.embed

Provide functions to embed Bokeh models (e.g., plots, widget, layouts) in various different ways.

There are a number of different combinations of options when embedding Bokeh plots. The data for the plot can be contained in the document, or on a Bokeh server, or in a sidecar JavaScript file. Likewise, BokehJS may be inlined in the document, or loaded from CDN or a Bokeh server.

The functions in bokeh.embed provide functionality to embed in all these different cases.

autoload_server(model, app_path='/', session_id=None, url='default')

Return a script tag that embeds the given model (or entire Document) from a Bokeh server session.

In a typical deployment, each browser tab connecting to a Bokeh application will have its own unique session ID. The session ID identifies a unique Document instance for each session (so the state of the Document can be different in every tab).

If you call autoload_server(model=None), you’ll embed the entire Document for a freshly-generated session ID. Typically, you should call autoload_server() again for each page load so that every new browser tab gets its own session.

Sometimes when doodling around on a local machine, it’s fine to set session_id to something human-readable such as "default". That way you can easily reload the same session each time and keep your state. But don’t do this in production!

In some applications, you may want to “set up” the session before you embed it. For example, you might session = bokeh.client.pull_session() to load up a session, modify session.document in some way (perhaps adding per-user data?), and then call autoload_server(model=None, session_id=session.id). The session ID obtained from pull_session() can be passed to autoload_server().

Parameters:
  • model (Model) – the object to render from the session, or None for entire document
  • app_path (str, optional) – the server path to the app we want to load
  • session_id (str, optional) – server session ID (default: None) If None, let the server autogenerate a random session ID. If you supply a specific model to render, you must also supply the session ID containing that model, though.
  • url (str, optional) – server root URL (where static resources live, not where a specific app lives)
Returns:

a <script> tag that will execute an autoload script loaded from the Bokeh Server

Return type:

tag

Note

It is a very bad idea to use the same session_id for every page load; you are likely to create scalability and security problems. So autoload_server() should be called again on each page load.

autoload_static(model, resources, script_path)

Return JavaScript code and a script tag that can be used to embed Bokeh Plots.

The data for the plot is stored directly in the returned JavaScript code.

Parameters:
  • model (Model or Document) –
  • resources (Resources) –
  • script_path (str) –
Returns:

JavaScript code to be saved at script_path and a <script> tag to load it

Return type:

(js, tag)

Raises:

ValueError

components(models, resources=None, wrap_script=True, wrap_plot_info=True)

Return HTML components to embed a Bokeh plot. The data for the plot is stored directly in the returned HTML.

An example can be found in examples/embed/embed_multiple.py

Note

The returned components assume that BokehJS resources are already loaded.

Parameters:
  • models (Model|list|dict|tuple) – A single Model, a list/tuple of Models, or a dictionary of keys and Models.
  • resources – Deprecated argument
  • wrap_script (boolean, optional) – If True, the returned javascript is wrapped in a script tag. (default: True)
  • wrap_plot_info (boolean, optional) –

    If True, returns <div> strings. Otherwise, return dicts that can be used to build your own divs. (default: True)

    If False, the returned dictionary contains the following information:

    {
        'modelid':  'The model ID, used with Document.get_model_by_id',
        'elementid': 'The css identifier the BokehJS will look for to target the plot',
        'docid': 'Used by Bokeh to find the doc embedded in the returned script',
    }
    
Returns:

UTF-8 encoded (script, div[s]) or (raw_script, plot_info[s])

Examples

With default wrapping parameter values:

components(plot)
# => (script, plot_div)

components((plot1, plot2))
# => (script, (plot1_div, plot2_div))

components({"Plot 1": plot1, "Plot 2": plot2})
# => (script, {"Plot 1": plot1_div, "Plot 2": plot2_div})

Examples

With wrapping parameters set to False:

components(plot, wrap_script=False, wrap_plot_info=False)
# => (javascript, plot_dict)

components((plot1, plot2), wrap_script=False, wrap_plot_info=False)
# => (javascript, (plot1_dict, plot2_dict))

components({"Plot 1": plot1, "Plot 2": plot2}, wrap_script=False, wrap_plot_info=False)
# => (javascript, {"Plot 1": plot1_dict, "Plot 2": plot2_dict})
file_html(models, resources, title=None, template=<Template 'file.html'>, template_variables={})

Return an HTML document that embeds Bokeh Model or Document objects.

The data for the plot is stored directly in the returned HTML.

This is an alias for standalone_html_page_for_models() which supports customizing the JS/CSS resources independently and customizing the jinja2 template.

Parameters:
  • models (Model or Document or list) – Bokeh object or objects to render typically a Model or Document
  • resources (Resources or tuple(JSResources or None, CSSResources or None)) – a resource configuration for Bokeh JS & CSS assets.
  • title (str, optional) – a title for the HTML document <title> tags or None. (default: None) If None, attempt to automatically find the Document title from the given plot objects.
  • template (Template, optional) – HTML document template (default: FILE) A Jinja2 Template, see bokeh.core.templates.FILE for the required template parameters
  • template_variables (dict, optional) – variables to be used in the Jinja2 template. If used, the following variable names will be overwritten: title, bokeh_js, bokeh_css, plot_script, plot_div
Returns:

UTF-8 encoded HTML

notebook_div(model, notebook_comms_target=None)

Return HTML for a div that will display a Bokeh plot in an IPython Notebook

The data for the plot is stored directly in the returned HTML.

Parameters:
  • model (Model) – Bokeh object to render
  • notebook_comms_target (str, optional) – A target name for a Jupyter Comms object that can update the document that is rendered to this notebook div
Returns:

UTF-8 encoded HTML text for a <div>

Note

Assumes load_notebook() or the equivalent has already been executed.

standalone_html_page_for_models(models, resources, title)

Return an HTML document that renders zero or more Bokeh documents or models.

The document for each model will be embedded directly in the HTML, so the resulting HTML file is standalone (does not require a server). Depending on the provided resources, the HTML file may be completely self-contained or may have to load JS and CSS from different files.

Parameters:
  • models (Model or Document) – Bokeh object to render typically a Model or a Document
  • resources (Resources) – a resource configuration for BokehJS assets
  • title (str) – a title for the HTML document <title> tags or None to use the document title
Returns:

UTF-8 encoded HTML