bokeh.embed

Provide functions for embedding Bokeh standalone and server content in web pages.

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:
  • 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, wrap_script=True, wrap_plot_info=True, theme=<class 'bokeh.embed.util.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

The returned components assume that BokehJS resources are already loaded. The html template in which they will be embedded needs to include the following links and scripts tags. The widgets and tables resources are only necessary if the components make use of widgets and tables.

<link
    href="https://cdn.bokeh.org/bokeh/release/bokeh-x.y.z.min.css"
    rel="stylesheet" type="text/css">
<link
    href="https://cdn.bokeh.org/bokeh/release/bokeh-widgets-x.y.z.min.css"
    rel="stylesheet" type="text/css">
<link
    href="https://cdn.bokeh.org/bokeh/release/bokeh-tables-x.y.z.min.css"
    rel="stylesheet" type="text/css">

<script src="https://cdn.bokeh.org/bokeh/release/bokeh-x.y.z.min.js"></script>
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-widgets-x.y.z.min.js"></script>
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-tables-x.y.z.min.js"></script>

Note that in Jupyter Notebooks, it is not possible to use components and show in the same notebook cell.

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={}, theme=<class 'bokeh.embed.util.FromCurdoc'>, suppress_callback_warning=False)[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 seq[Model]) – 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
  • 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.
  • suppress_callback_warning (bool, optional) – Normally generating standalone HTML from a Bokeh Document that has Python callbacks will result in a warning stating that the callbacks cannot function. However, this warning can be suppressed by setting this value to True (default: False)
Returns:

UTF-8 encoded HTML

json_item(model, target=None, theme=<class 'bokeh.embed.util.FromCurdoc'>)[source]

Return a JSON block that can be used to embed standalone Bokeh conent.

Parameters:
  • model (Model) – The Bokeh object to embed
  • target (string, optional) – A div id to embd the model into. If None, the target id must be supplied in the JavaScript call.
  • 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:

JSON-like

This function returns a JSON block that can be consumed by the BokehJS function Bokeh.embed.embed_item. As an example, a Flask endpoint for /plot might return the following content to embed a Bokeh plot into a div with id “myplot”:

@app.route('/plot')
def plot():
    p = make_plot('petal_width', 'petal_length')
    return json.dumps(json_item(p, "myplot"))

Then a web page can retrieve this JSON and embed the plot by calling Bokeh.embed.embed_item:

<script>
fetch('/plot')
    .then(function(response) { return response.json(); })
    .then(function(item) { Bokeh.embed.embed_item(item); })
</script>

Alternatively, if is more convenient to suppluy the target div id directly in the page source, that is also possible. If target_id is omitted in the call to this function:

return json.dumps(json_item(p))

Then the value passed to embed_item is used:

Bokeh.embed.embed_item(item, "myplot");
server_document(url='default', relative_urls=False, resources='default', arguments=None)[source]

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

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

Parameters:
  • url (str, optional) –

    A URL to a Bokeh application on a Bokeh server (default: “default”)

    If "default" 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

  • resources

    A string specifying what resources need to be loaded along with the document.

    If default then the default JS/CSS bokeh files will be loaded.

    If None then none of the resource files will be loaded. This is useful if you prefer to serve those resource files via other means (e.g. from a caching server). Be careful, however, that the resource files you’ll load separately are of the same version as that of the server’s, otherwise the rendering may not work correctly.

Returns:

A <script> tag that will embed content from a Bokeh Server.

server_session(model=None, session_id=None, url='default', relative_urls=False, resources='default')[source]

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

This function is typically only useful for serving from a a specific session that was previously created using the bokeh.client API.

Bokeh apps embedded using these methods 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 or None, optional) –

    The object to render from the session, or None. (default: None)

    If None, the entire document will be rendered.

  • session_id (str) – A server session ID
  • url (str, optional) –

    A URL to a Bokeh application on a Bokeh server (default: “default”)

    If "default" 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

  • resources (str) –

    A string specifying what resources need to be loaded along with the document.

    If default then the default JS/CSS bokeh files will be loaded.

    If None then none of the resource files will be loaded. This is useful if you prefer to serve those resource files via other means (e.g. from a caching server). Be careful, however, that the resource files you’ll load separately are of the same version as that of the server’s, otherwise the rendering may not work correctly.

Returns:

A <script> tag that will embed content from a Bokeh Server.

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” behavior, which is probably 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:
  • 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, wrap_script=True, wrap_plot_info=True, theme=<class 'bokeh.embed.util.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

The returned components assume that BokehJS resources are already loaded. The html template in which they will be embedded needs to include the following links and scripts tags. The widgets and tables resources are only necessary if the components make use of widgets and tables.

<link
    href="https://cdn.bokeh.org/bokeh/release/bokeh-x.y.z.min.css"
    rel="stylesheet" type="text/css">
<link
    href="https://cdn.bokeh.org/bokeh/release/bokeh-widgets-x.y.z.min.css"
    rel="stylesheet" type="text/css">
<link
    href="https://cdn.bokeh.org/bokeh/release/bokeh-tables-x.y.z.min.css"
    rel="stylesheet" type="text/css">

<script src="https://cdn.bokeh.org/bokeh/release/bokeh-x.y.z.min.js"></script>
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-widgets-x.y.z.min.js"></script>
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-tables-x.y.z.min.js"></script>

Note that in Jupyter Notebooks, it is not possible to use components and show in the same notebook cell.

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={}, theme=<class 'bokeh.embed.util.FromCurdoc'>, suppress_callback_warning=False)[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 seq[Model]) – 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
  • 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.
  • suppress_callback_warning (bool, optional) – Normally generating standalone HTML from a Bokeh Document that has Python callbacks will result in a warning stating that the callbacks cannot function. However, this warning can be suppressed by setting this value to True (default: False)
Returns:

UTF-8 encoded HTML

json_item(model, target=None, theme=<class 'bokeh.embed.util.FromCurdoc'>)[source]

Return a JSON block that can be used to embed standalone Bokeh conent.

Parameters:
  • model (Model) – The Bokeh object to embed
  • target (string, optional) – A div id to embd the model into. If None, the target id must be supplied in the JavaScript call.
  • 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:

JSON-like

This function returns a JSON block that can be consumed by the BokehJS function Bokeh.embed.embed_item. As an example, a Flask endpoint for /plot might return the following content to embed a Bokeh plot into a div with id “myplot”:

@app.route('/plot')
def plot():
    p = make_plot('petal_width', 'petal_length')
    return json.dumps(json_item(p, "myplot"))

Then a web page can retrieve this JSON and embed the plot by calling Bokeh.embed.embed_item:

<script>
fetch('/plot')
    .then(function(response) { return response.json(); })
    .then(function(item) { Bokeh.embed.embed_item(item); })
</script>

Alternatively, if is more convenient to suppluy the target div id directly in the page source, that is also possible. If target_id is omitted in the call to this function:

return json.dumps(json_item(p))

Then the value passed to embed_item is used:

Bokeh.embed.embed_item(item, "myplot");
server_document(url='default', relative_urls=False, resources='default', arguments=None)[source]

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

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

Parameters:
  • url (str, optional) –

    A URL to a Bokeh application on a Bokeh server (default: “default”)

    If "default" 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

  • resources

    A string specifying what resources need to be loaded along with the document.

    If default then the default JS/CSS bokeh files will be loaded.

    If None then none of the resource files will be loaded. This is useful if you prefer to serve those resource files via other means (e.g. from a caching server). Be careful, however, that the resource files you’ll load separately are of the same version as that of the server’s, otherwise the rendering may not work correctly.

Returns:

A <script> tag that will embed content from a Bokeh Server.

server_session(model=None, session_id=None, url='default', relative_urls=False, resources='default')[source]

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

This function is typically only useful for serving from a a specific session that was previously created using the bokeh.client API.

Bokeh apps embedded using these methods 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 or None, optional) –

    The object to render from the session, or None. (default: None)

    If None, the entire document will be rendered.

  • session_id (str) – A server session ID
  • url (str, optional) –

    A URL to a Bokeh application on a Bokeh server (default: “default”)

    If "default" 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

  • resources (str) –

    A string specifying what resources need to be loaded along with the document.

    If default then the default JS/CSS bokeh files will be loaded.

    If None then none of the resource files will be loaded. This is useful if you prefer to serve those resource files via other means (e.g. from a caching server). Be careful, however, that the resource files you’ll load separately are of the same version as that of the server’s, otherwise the rendering may not work correctly.

Returns:

A <script> tag that will embed content from a Bokeh Server.

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” behavior, which is probably not desired.