Bokeh Menu

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=None, app_path=None, session_id=None, url='default', relative_urls=False)[source]

Return a script tag that embeds content from a Bokeh server session.

Bokeh apps embedded using autoload_server will NOT set the browser window title.

Note

Typically you will not want to save or re-use the output of this function for different or multiple page loads.

Parameters:
  • model (Model, optional) –

    The object to render from the session

    If None an entire document is rendered. (default: None)

    If you supply a specific model to render, you must also supply the session ID containing that model.

    Supplying a model is usually only useful when embedding a specific session that was previously created using the bokeh.client API.

  • session_id (str, optional) –

    A server session ID (default: None)

    If None, let the server auto-generate a random session ID.

    Supplying a session id is usually only useful when embedding a specific session that was previously created using the bokeh.client API.

  • url (str, optional) –

    A URL to a Bokeh application on a Bokeh server

    If None the default URL http://localhost:5006/ will be used.

  • relative_urls (bool, optional) –

    Whether to use relative URLs for resources.

    If True the links generated for resources such a BokehJS JavaScript and CSS will be relative links.

    This should normally be set to False, but must be set to True in situations where only relative URLs will work. E.g. when running the Bokeh behind reverse-proxies under certain configurations
Returns:

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

Examples

In the simplest and most common case, we wish to embed Bokeh server application by providing the URL to where it is located.

Suppose the app is running (perhaps behind Nginx or some other proxy) at http://app.server.org/foo/myapp. We wish to embed this app in a page at mysite.com. The following will provide an HTML script tag to do that, that can be included in mysite.com:

script = autoload_server(url="http://app.server.org/foo/myapp")

Note that in order for this embedding to work, the Bokeh server needs to have been configured to allow connections from the public URL where the embedding happens. In this case, if the autoload script is run from a page located at http://mysite.com/report then the Bokeh server must have been started with an --allow-websocket-origin option specifically allowing websocket connections from pages that originate from mysite.com:

bokeh serve mayapp.py --allow-websocket-origin=mysite.com

If an autoload script runs from an origin that has not been allowed, the Bokeh server will return a 403 error.

It’s also possible to initiate sessions on a Bokeh server from Python, using the functions push_session() and push_session(). This can be useful in advanced situations where you may want to “set up” the session before you embed it. For example, you might to load up a session and modify session.document in some way (perhaps adding per-user data).

In such cases you will pass the session id as an argument as well:

script = autoload_server(session_id="some_session_id",
                         url="http://app.server.org/foo/myapp")

Warning

It is typically a bad idea to re-use the same session_id for every page load. This is likely to create scalability and security problems, and will cause “shared Google doc” behaviour, which is typically not desired.

autoload_static(model, resources, script_path)[source]

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:
Returns:

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

(js, tag)
Raises:

ValueError
components(models, wrap_script=True, wrap_plot_info=True, theme=<class 'bokeh.embed.FromCurdoc'>)[source]

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.
  • 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',
}
  • theme (Theme, optional) – Defaults to the Theme instance in the current document. Setting this to None uses the default theme or the theme already specified in the document. Any other value must be an instance of the Theme class.
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={})[source]

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

The data for the plot is stored directly in the returned HTML, with support for 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, theme=<class 'bokeh.embed.FromCurdoc'>)[source]

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
  • theme (Theme, optional) – Defaults to the Theme instance in the current document. Setting this to None uses the default theme or the theme already specified in the document. Any other value must be an instance of the Theme class.
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)[source]

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