Resources and Embedding¶

bokeh.state¶

Encapsulate implicit state that is useful for Bokeh plotting APIs.

Generating output for Bokeh plots requires coordinating several things:

Documents

Group together Bokeh models that may be shared between plots (e.g., range or data source objects) into one common namespace.

Resources

Control how JavaScript and CSS for the client library BokehJS are included and used in the generated output.

Sessions

Create and manage persistent connections to a Bokeh server.

It is certainly possible to handle the configuration of these objects manually, and several examples of this can be found in examples/glyphs. When developing sophisticated applications, it may be necessary or desirable to work at this level. However, for general use this would quickly become burdensome. The bokeh.state module provides a State class that encapsulates these objects and ensures their proper configuration.

class State¶

Manage state related to controlling Bokeh output.

document¶

bokeh.document.Document

a default document to use

file¶

dict

default filename, resources, etc. for file output This dictionary has the following form:

{
    'filename'  : # filename to use when saving
    'resources' : # resources configuration
    'autosave'  : # whether to autosave
    'title'     : # a title for the HTML document
}

notebook¶

bool

whether to generate notebook output

session¶

bokeh.session.Session

a default session for Bokeh server output

output_file(filename, title='Bokeh Plot', autosave=False, mode='inline', root_dir=None)¶

Output to a static HTML file.

Parameters:

filename (str) – a filename for saving the HTML document title (str, optional) – a title for the HTML document autosave (bool, optional) – whether to automatically save (default: False) If True, then Bokeh plotting APIs may opt to automatically save the file more frequently (e.g., after any plotting command). If False, then the file is only saved upon calling show() or save(). mode (str, optional) – how to include BokehJS (default: 'inline') One of: 'inline', 'cdn', 'relative(-dev)' or 'absolute(-dev)'. See bokeh.resources.Resources for more details. root_dir (str, optional) – root directory to use for ‘absolute’ resources. (default: None) value is ignored for other resource types, e.g. INLINE or (This) – CDN. –

Warning

This output file will be overwritten on every save, e.g., each time show() or save() is invoked, or any time a Bokeh plotting API causes a save, if autosave is True.

output_notebook(url=None, docname=None, session=None, name=None)¶

Generate output in Jupyter/IPython notebook cells.

Parameters:

url (str, optional) – URL of the Bokeh server (default: “default”) If “default”, then session.DEFAULT_SERVER_URL is used. docname (str) – Name of document to push on Bokeh server Any existing documents with the same name will be overwritten. session (Session, optional) – An explicit session to use (default: None) If None, a new default session is created. name (str, optional) – A name for the session If None, the server URL is used as the name

Returns:

None

output_server(docname, session=None, url='default', name=None, clear=True)¶

Store Bokeh plots and objects on a Bokeh server.

Parameters:

docname (str) – Name of document to push on Bokeh server Any existing documents with the same name will be overwritten. session (Session, optional) – An explicit session to use (default: None) If None, a new default session is created. url (str, optional) – URL of the Bokeh server (default: “default”) If “default”, then session.DEFAULT_SERVER_URL is used. name (str, optional) – A name for the session If None, the server URL is used as the name clear (bool, optional) – Whether to clear the document (default: True) If True, an existing server document will be cleared of any existing objects.

Returns:

None

Warning

Calling this function will replace any existing default session.

reset()¶

Deactivate all currently active output modes.

Subsequent calls to show() will not render until a new output mode is activated.

Returns:	None

bokeh.io¶

Functions for configuring Bokeh output.

curdoc()¶

Return the document for the current default state.

Returns:	the current default document object.
Return type:	doc

Note

When using this API form within the server (e.g. in a Bokeh app), the appropriate document from the request context is returned, rather than the standard default global state. Doing so allows the same code using curdoc() to function correctly whether it is being run inside a server or not.

cursession()¶

Return the session for the current default state, if there is one.

Returns:	the current default Session object (or None)

gridplot(plot_arrangement, **kwargs)¶

Generate a plot that arranges several subplots into a grid.

Parameters:	plot_arrangement (nested list of Plots) – plots to arrange in a grid **kwargs – additional attributes to pass in to GridPlot() constructor

Note

plot_arrangement can be nested, e.g [[p1, p2], [p3, p4]]

Returns:	a new GridPlot
Return type:	grid_plot

hplot(*children, **kwargs)¶

Generate a layout that arranges several subplots horizontally.

output_file(filename, title='Bokeh Plot', autosave=False, mode='inline', root_dir=None)¶

Configure the default output state to generate output saved to a file when show() is called.

Parameters:

filename (str) – a filename for saving the HTML document title (str, optional) – a title for the HTML document (default: “Bokeh Plot”) autosave (bool, optional) – whether to automatically save (default: False) If True, then Bokeh plotting APIs may opt to automatically save the file more frequently (e.g., after any plotting command). If False, then the file is only saved upon calling show() or save(). mode (str, optional) – how to include BokehJS (default: 'inline') One of: 'inline', 'cdn', 'relative(-dev)' or 'absolute(-dev)'. See bokeh.resources.Resources for more details. root_dir (str, optional) – root directory to use for ‘absolute’ resources. (default: None) This value is ignored for other resource types, e.g. INLINE or CDN.

Returns:

None

Note

Generally, this should be called at the beginning of an interactive session or the top of a script.

Warning

This output file will be overwritten on every save, e.g., each time show() or save() is invoked, or any time a Bokeh plotting API causes a save, if autosave is True.

output_notebook(url=None, docname=None, session=None, name=None, resources=None, verbose=False, hide_banner=False)¶

Configure the default output state to generate output in Jupyter/IPython notebook cells when show() is called.

Parameters:

url (str, optional) – URL of the Bokeh server (default: “default”) If “default”, then session.DEFAULT_SERVER_URL is used. docname (str) – Name of document to push on Bokeh server (default: None) Any existing documents with the same name will be overwritten. session (Session, optional) – An explicit session to use (default: None) If None, a new default session is created. name (str, optional) – A name for the session (default: None) If None, the server URL is used as the name resources (Resource, optional) – How and where to load BokehJS from (default: INLINE) verbose (bool, optional) – whether to display detailed BokehJS banner (default: False) hide_banner (bool, optional) – whether to hide the Bokeh banner (default: False)

Returns:

None

Note

Generally, this should be called at the beginning of an interactive session or the top of a script.

output_server(docname, session=None, url='default', name=None, clear=True)¶

Configure the default output state to generate output that gets pushed to a bokeh-server when show() or push() is called.

Parameters:

docname (str) – Name of document to push on Bokeh server Any existing documents with the same name will be overwritten. session (Session, optional) – An explicit session to use (default: None) If None, a new default session is created. url (str, optional) – URL of the Bokeh server (default: “default”) If “default”, then session.DEFAULT_SERVER_URL is used. name (str, optional) – A name for the session (default: None) If None, the server URL is used as the name clear (bool, optional) – Whether to clear the document (default: True) If True, an existing server document will be cleared of any existing objects.

Returns:

None

Note

Generally, this should be called at the beginning of an interactive session or the top of a script.

Warning

Calling this function will replace any existing default session.

push(session=None, document=None, state=None)¶

Update the server with the data for the current document.

Will fall back to the default output state (or an explicitly provided State object) for session or document if they are not provided.

Parameters:	session (Session, optional) – a Bokeh server session to push objects to document (Document, optional) – A bokeh.document.Document to use
Returns:	None

reset_output(state=None)¶

Clear the default state of all output modes.

Returns:	None

save(*args, **kwargs)¶

Save an HTML file with the data for the current document.

Will fall back to the default output state (or an explicitly provided State object) for filename, resources, or title if they are not provided.

Parameters:	obj (Document or Widget/Plot object) – a plot object to save filename (str, optional) – filename to save document under (default: None) If None, use the default state configuration, otherwise raise a RuntimeError. resources (Resources, optional) – A Resources config to use (default: None) If None, use the default state configuration, if there is one. otherwise use resources.INLINE. title (str, optional) – a title for the HTML document (default: None) If None, use the default state title value, if there is one. Otherwise, use “Bokeh Plot”
Returns:	None
Raises:	RuntimeError –

show(obj=None)¶

Immediately display a plot object.

In an IPython/Jupyter notebook, the output is displayed in an output cell. Otherwise, a browser window or tab is autoraised to display the plot object.

If both a server session and notebook output have been configured on the default output state then the notebook output will be generated to load the plot from that server session.

Parameters:

obj (Widget/Plot object) – a plot object to display browser (str, optional) – browser to show with (default: None) For systems that support it, the browser argument allows specifying which browser to display in, e.g. “safari”, “firefox”, “opera”, “windows-default” (see the webbrowser module documentation in the standard lib for more details). new (str, optional) – new file output mode (default: “tab”) For file-based output, opens or raises the browser window showing the current output file. If new is ‘tab’, then opens a new tab. If new is ‘window’, then opens a new window.

Returns:

None

Note

The browser and new parameters are ignored when showing in an IPython/Jupyter notebook.

vform(*children, **kwargs)¶

Generate a layout that arranges several subplots vertically.

vplot(*children, **kwargs)¶

Generate a layout that arranges several subplots vertically.

bokeh.resources¶

The resources module provides the Resources class for easily configuring how BokehJS code and CSS resources should be located, loaded, and embedded in Bokeh documents.

Also provides some pre-configured Resources objects:

CDN¶

load minified BokehJS from CDN

INLINE¶

provide minified BokehJS from library static directory

class Resources(mode='inline', version=None, root_dir=None, minified=True, log_level='info', root_url=None)¶

The Resources class encapsulates information relating to loading or embedding BokehJS code and CSS.

Parameters:

mode (str) – how should BokehJS be included in output See below for descriptions of available modes version (str, optional) – what version of BokejJS to load Only valid with the 'cdn' mode root_dir (str, optional) – root directory for loading BokehJS resources Only valid with 'relative' and 'relative-dev' modes minified (bool, optional) – whether JavaScript and CSS should be minified or not (default: True) root_url (str, optional) – URL and port of Bokeh Server to load resources from Only valid with 'server' and 'server-dev' modes

The following mode values are available for configuring a Resource object:

• 'inline' configure to provide entire BokehJS code and CSS inline
• 'cdn' configure to load BokehJS code and CS from https://cdn.bokeh.org
• 'server' configure to load from a Bokeh Server
• 'server-dev' same as server but supports non-minified JS
• 'relative' configure to load relative to the given directory
• 'relative-dev' same as relative but supports non-minified JS
• 'absolute' configure to load from the installed Bokeh library static directory
• 'absolute-dev' same as absolute but supports non-minified JS

Once configured, a Resource object exposes the following public attributes:

logo_url¶

location of the BokehJS logo image

js_raw¶

any raw JS that needs to be placed inside <script> tags

css_raw¶

any raw CSS that needs to be places inside <style> tags

js_files¶

URLs of any JS files that need to be loaded by <script> tags

css_files¶

URLS od any CSS files that need to be loaed by <link> tags

messages¶

any informational messages concering this configuration

These attributes are often useful as template parameters when embedding Bokeh plots.

bokeh.embed¶

This module provides functions for embedding Bokeh plots 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(plot_object, session, public=False)¶

Return a script tag that can be used to embed Bokeh Plots from a Bokeh Server.

The data for the plot is stored on the Bokeh Server.

Parameters:	plot_object (PlotObject) – session (Session) –
Returns:	a <script> tag that will execute an autoload script loaded from the Bokeh Server
Return type:	tag

autoload_static(plot_object, 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:	plot_object (PlotObject) – 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(plot_objects, 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:	plot_objects – PlotObject|list|dict|tuple A single PlotObject, a list/tuple of PlotObjects, or a dictionary of keys and PlotObjects. 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, then a set of divs are returned. If set to False, then dictionaries are returned that can be used to manually build your own divs. (default: True) If False, the returned dictionary contains the following information: { 'modelid': 'The plots id, which can be used in the Bokeh.index', 'elementid': 'The css identifier the BokehJS will look for to target the plot', 'modeltype': 'The Bokeh model name e.g. Plot, Slider', }
Returns:	UTF-8 encoded The output depends on the input as follows: 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}) (raw_script, plot_info[s]) : UTF-8 encoded The output depends on the input as follows: 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})
Return type:	(script, div[s])

file_html(plot_object, resources, title, js_resources=None, css_resources=None, template=<Template memory:2adf189da510>, template_variables=None)¶

Return an HTML document that embeds a Bokeh plot.

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

Parameters:	plot_object (PlotObject) – Bokeh object to render typically a Plot or PlotContext resources (Resources) – a resource configuration for BokehJS assets title (str) – a title for the HTML document <title> tags template (Template, optional) – HTML document template (default: FILE) A Jinja2 Template, see bokeh.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, js_resources, css_resources, plot_script, plot_div
Returns:	standalone HTML document with embedded plot
Return type:	html

notebook_div(plot_object)¶

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:	plot_object (PlotObject) – Bokeh object to render typically a Plot or PlotContext
Returns:	UTF-8 encoded HTML text
Return type:	div

Note

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

bokeh.templates¶

The templates module contains templates used by Bokeh to enable embedding Bokeh plots in various ways.

JS_RESOURCES¶

This template is for loading BokehJS code and css according to the configuration in a Resources object.

CSS_RESOURCES¶

This template is for loading Bokeh css according to the configuration in a Resources object.

PLOT_DIV¶

This template is for creating a basic plot div (to be used in conjunction with PLOT_JS).

PLOT_JS¶

This template is for creating the JavaScript code snippet that can render a plot into a corresponding PLOT_DIV.

PLOT_SCRIPT¶

This template is for creating a full <script> tag for raw JS code. Useful with the PLOT_JS template.

FILE¶

This template is for rendering Bokeh plots into a basic .html file.

NOTEBOOK_LOAD¶

This template is for loading BokehJS code and CSS into the IPython Notebook according to a resources configuration.

NOTEBOOK_DIV¶

This template is for rendering a Bokeh plot into the IPython Notebook.

AUTOLOAD¶

This template is for creating an “autoload” JS script. The script automatically and asynchronously loads BokehJS (if necessary) and then replaces any suitably constructed <script> tag that loads it with the rendered plot.

AUTOLOAD_SERVER¶

This template is for creating <script> tags that run AUTOLOAD scripts for plots that connect to a Bokeh Server for their data

AUTOLOAD_STATIC¶

This template is for creating <script> tags that run AUTOLOAD scripts for plots that have their data embedded in the AUTOLOAD script