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

curstate()¶

Return the current State object

Returns:	the current default State object
Return type:	state

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

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

Does not change the current Document from curdoc(). File, server, and notebook output may be active at the same time, so this does not clear the effects of output_server() or output_notebook().

Parameters:

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: `'cdn'`) 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

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: 'cdn') 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(resources=None, verbose=False, hide_banner=False, load_timeout=5000)¶

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

If output_server() has also been called, the notebook cells are loaded from the configured server; otherwise, Bokeh pushes HTML to the notebook directly.

Parameters:	resources (Resource, optional) – How and where to load BokehJS from (default: CDN) verbose (bool, optional) – whether to display detailed BokehJS banner (default: False) hide_banner (bool, optional) – whether to hide the Bokeh banner (default: False) load_timeout (int, optional) – Timeout in milliseconds when plots assume load timed out (default: 5000)
Returns:	None

Note

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

output_server(session_id='default', url='default', app_path='/', autopush=False)¶

Configure the default output state to push its document to a session on a Bokeh server.

Sessions are in-memory and not persisted to disk; in a typical production deployment, you would have a fresh session ID for each browser tab. If different users share the same session ID, it will create security and scalability problems.

output_server() defaults to always using the session_id "default", which is useful for running local demos or notebooks. However, if you are creating production sessions, you’ll need to set session_id to None (to generate a fresh ID) or to a session ID generated elsewhere.

File, server, and notebook output may be active at the same time, so output_server() does not clear the effects of output_file() or output_notebook(). output_server() changes the behavior of output_notebook(), so the notebook will load output cells from the server rather than receiving them as inline HTML.

Parameters:

Parameters:	session_id (str, optional) – Name of session to push on Bokeh server (default: “default”) Any existing session with the same name will be overwritten. url (str, optional) – base URL of the Bokeh server (default: “default”) If “default” use the default localhost URL. app_path (str, optional) – relative path of the app on the Bokeh server (default: “/”) autopush (bool, optional) – whether to automatically push (default: False) If True, then Bokeh plotting APIs may opt to automatically push the document more frequently (e.g., after any plotting command). If False, then the document is only pushed upon calling `show()` or `push()`.
Returns:	None

session_id (str, optional) – Name of session to push on Bokeh server (default: “default”) Any existing session with the same name will be overwritten.
url (str, optional) – base URL of the Bokeh server (default: “default”) If “default” use the default localhost URL.
app_path (str, optional) – relative path of the app on the Bokeh server (default: “/”)
autopush (bool, optional) – whether to automatically push (default: False) If True, then Bokeh plotting APIs may opt to automatically push the document more frequently (e.g., after any plotting command). If False, then the document is only pushed upon calling show() or push().

Returns:

None

Warning

Calling this function will replace any existing server-side document in the named session.

push(session_id=None, url=None, app_path=None, document=None, state=None, io_loop=None, validate=True)¶

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_id, url, app_path, or document if they are not provided.

Parameters:

Parameters:	session_id (str, optional) – a Bokeh server session ID to push objects to url (str, optional) – a Bokeh server URL to push objects to app_path (str, optional) – Relative application path to push objects to document (Document, optional) – A `bokeh.document.Document` to use state (State, optional) – A state to use for any output_server() configuration of session or url io_loop (tornado.ioloop.IOLoop, optional) – Tornado IOLoop to use for connecting to server validate (bool, optional) – True to check integrity of the document we are pushing
Returns:	None

session_id (str, optional) – a Bokeh server session ID to push objects to
url (str, optional) – a Bokeh server URL to push objects to
app_path (str, optional) – Relative application path to push objects to
document (Document, optional) – A bokeh.document.Document to use
state (State, optional) – A state to use for any output_server() configuration of session or url
io_loop (tornado.ioloop.IOLoop, optional) – Tornado IOLoop to use for connecting to server
validate (bool, optional) – True to check integrity of the document we are pushing

Returns:

None

push_notebook(document=None, state=None, handle=None)¶

Update Bokeh plots in a Jupyter notebook output cells with new data or property values.

When working the the notebook, the show function can be passed the argument notebook_handle=True, which will cause it to return a handle object that can be used to update the Bokeh output later. When push_notebook is called, any property updates (e.g. plot titles or data source values, etc.) since the last call to push_notebook or the original show call are applied to the Bokeh output in the previously rendered Jupyter output cell.

Several example notebooks can be found in the GitHub repository in the examples/howto/notebook_comms directory.

Parameters:	document (Document, optional) – A `Document` to push from. If None, uses `curdoc()`. state (State, optional) – A Bokeh State object
Returns:	None

Examples

Typical usage is typically similar to this:

from bokeh.plotting import figure
from bokeh.io import output_notebook, push_notebook, show

output_notebook()

plot = figure()
plot.circle([1,2,3], [4,6,5])

handle = show(plot, notebook_handle=True)

# Update the plot title in the earlier cell
plot.title = "New Title"
push_notebook(handle)

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. If the filename is not given and not provided via output state, it is derived from the script name (e.g. /foo/myplot.py will create /foo/myplot.html)

Parameters:	obj (Document or model 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” validate (bool, optional) – True to check integrity of the models
Returns:	filename – the filename where the HTML file is saved.
Return type:	str
Raises:	`RuntimeError`

set_curdoc(doc)¶

Configure the current document (returned by curdoc()).

This is the document we will save or push according to output_file(), output_server(), etc. configuration.

Parameters:	doc (Document) – Document we will output.
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 document.

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:

Parameters:	obj (LayoutDOM object) – a Layout (Row/Column), Plot or Widget 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. notebook_handle (bool, optional) – create notebook interaction handle (default: False) For notebook output, toggles whether a handle which can be used with `push_notebook` is returned.
Returns:	when in a jupyter notebook (with `output_notebook` enabled) and `notebook_handle=True`, returns a handle that can be used by `push_notebook`, None otherwise.

obj (LayoutDOM object) – a Layout (Row/Column), Plot or Widget 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.
notebook_handle (bool, optional) – create notebook interaction handle (default: False) For notebook output, toggles whether a handle which can be used with push_notebook is returned.

Returns:

when in a jupyter notebook (with output_notebook enabled) and notebook_handle=True, returns a handle that can be used by push_notebook, None otherwise.

Note

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