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)
Return type:session
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.

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-concatenated JS using requirejs
  • 'relative' configure to load relative to the given directory
  • 'relative-dev' same as relative but supports non-concatenated JS using requirejs
  • 'absolute' configure to load from the installed Bokeh library static directory
  • 'absolute-dev' same as absolute but supports non-concatenated JS using requirejs

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:

(js, tag) : JavaScript code to be saved at script_path and a <script> tag to load it
Raises:

ValueError –
components(plot_object, resources)

Return HTML components to embed a Bokeh plot.

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

Note

The returned components assume that BokehJS resources are already loaded.

Parameters:
  • plot_object (PlotObject) – Bokeh object to render typically a Plot or PlotContext
  • resources (Resources, optional) – BokehJS resources config
Returns:

(script, div) : UTF-8 encoded
file_html(plot_object, resources, title, template=<Template memory:2b9b05ab2940>)

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
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.

RESOURCES

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

param css_files:
 a list of URIs for CSS files to include
type css_files:list[str]
param js_files:a list of URIs for JS files to include
type js_files:list[str]
param css_raw:a list of raw CSS snippets to put between <style> tags
type css_raw:list[str]
param js_raw:a list of raw JS snippets to put between <style> tags
type js_raw:list[str]
PLOT_DIV

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

param elementid:
 a unique identifier for the div a PLOT_JS template should be configured with the same elementid
type elementid:str
PLOT_JS

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

param modelid:The Bokeh model id for the object to render typically for a Plot, PlotContext, etc.
type modelid:str
param modeltype:
 the type of the model to render used to reference the appropriate Backbone collection
type modeltype:str
param elementid:
 the id of the div to render the plot into
type elementid:str
PLOT_SCRIPT

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

param plot_js:raw JavaScript code to include
type plot_js:str
FILE

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

param title:a value for <title> tags
type title:str
param plot_resources:
 typically the output of RESOURCES
type plot_resources:
 str
param plot_script:
 typically the output of PLOT_SCRIPT
type plot_script:
 str
param plot_div:typically the output of PLOT_DIV
type plot_div:str
param Users can customize the file output by providing their own template with these parameters.:
 
NOTEBOOK_LOAD

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

param plot_resources:
 typically the output of RESOURCES
type plot_resources:
 str
param log_url:URL to Bokeh logo to dispay
type log_url:str
param verbose:whether to display verbose info about BokehJS configuration, etc
type verbose:bool
param bokeh_version:
 the current version of Bokeh
type bokeh_version:
 str
param js_info:information about the location, version, etc. of BokehJS code
type js_info:str
param css_info:information about the location, version, etc. of BokehJS css
type css_info:str
param warnings:list of warnings to display to user
type warnings:list[str]
NOTEBOOK_DIV

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

param plot_script:
 typically the output of PLOT_SCRIPT
type plot_script:
 str
param plot_div:typically the output of PLOT_DIV
type plot_div:str
AUTOLOAD

This template is for creating a sidecar JS file that will automatically and asynchronously load BokehJS (if necessary) and then replaces the script tag that loads it (with appropriate attributes) with a 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

param src_path:path to AUTOLOAD script
type src_path:str
param elementid:
 the a unique id for the script tag
type elementid:str
param modelid:The Bokeh model id for the object to render typically for a Plot, PlotContext, etc.
type modelid:str
param root_url:root URL of the Bokeh Server
type root_url:str
param docid:document ID for the document on the server to load
type docid:str
param docapikey:
 API key for the document
type docapikey:str
AUTOLOAD_STATIC

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

param src_path:path to AUTOLOAD script
type src_path:str
param elementid:
 the a unique id for the script tag
type elementid:str
param modelid:The Bokeh model id for the object to render typically for a Plot, PlotContext, etc.
type modelid:str
param modeltype:
 the type of the model to render used to reference the appropriate Backbone collection
type modeltype:str

Note

This script injects a <div> in place, so must be placed under <body>.