bokeh.io¶
- curdoc() Document | UnlockedDocumentProxy [source]¶
Return the document for the current default state.
- Returns
the current default document object.
- Return type
- export_png(obj: LayoutDOM | Document, *, filename: PathLike | None = None, width: int | None = None, height: int | None = None, webdriver: WebDriver | None = None, timeout: int = 5) str [source]¶
Export the
LayoutDOM
object or document as a PNG.If the filename is not given, it is derived from the script name (e.g.
/foo/myplot.py
will create/foo/myplot.png
)- Parameters
obj (LayoutDOM or Document) – a Layout (Row/Column), Plot or Widget object or Document to export.
filename (PathLike, e.g. str, Path, optional) – filename to save document under (default: None) If None, infer from the filename.
width (int) – the desired width of the exported layout obj only if it’s a Plot instance. Otherwise the width kwarg is ignored.
height (int) – the desired height of the exported layout obj only if it’s a Plot instance. Otherwise the height kwarg is ignored.
webdriver (selenium.webdriver) – a selenium webdriver instance to use to export the image.
timeout (int) – the maximum amount of time (in seconds) to wait for Bokeh to initialize (default: 5) (Added in 1.1.1).
- Returns
the filename where the static file is saved.
- Return type
filename (str)
If you would like to access an Image object directly, rather than save a file to disk, use the lower-level
get_screenshot_as_png()
function.Warning
Responsive sizing_modes may generate layouts with unexpected size and aspect ratios. It is recommended to use the default
fixed
sizing mode.
- export_svg(obj: LayoutDOM | Document, *, filename: PathLike | None = None, width: int | None = None, height: int | None = None, webdriver: WebDriver | None = None, timeout: int = 5) List[str] [source]¶
Export a layout as SVG file or a document as a set of SVG files.
If the filename is not given, it is derived from the script name (e.g.
/foo/myplot.py
will create/foo/myplot.svg
)- Parameters
obj (LayoutDOM object) – a Layout (Row/Column), Plot or Widget object to display
filename (PathLike, e.g. str, Path, optional) – filename to save document under (default: None) If None, infer from the filename.
width (int) – the desired width of the exported layout obj only if it’s a Plot instance. Otherwise the width kwarg is ignored.
height (int) – the desired height of the exported layout obj only if it’s a Plot instance. Otherwise the height kwarg is ignored.
webdriver (selenium.webdriver) – a selenium webdriver instance to use to export the image.
timeout (int) – the maximum amount of time (in seconds) to wait for Bokeh to initialize (default: 5)
- Returns
the list of filenames where the SVGs files are saved.
- Return type
Warning
Responsive sizing_modes may generate layouts with unexpected size and aspect ratios. It is recommended to use the default
fixed
sizing mode.
- export_svgs(obj: LayoutDOM | Document, *, filename: str | None = None, width: int | None = None, height: int | None = None, webdriver: WebDriver | None = None, timeout: int = 5) List[str] [source]¶
Export the SVG-enabled plots within a layout. Each plot will result in a distinct SVG file.
If the filename is not given, it is derived from the script name (e.g.
/foo/myplot.py
will create/foo/myplot.svg
)- Parameters
obj (LayoutDOM object) – a Layout (Row/Column), Plot or Widget object to display
filename (str, optional) – filename to save document under (default: None) If None, infer from the filename.
width (int) – the desired width of the exported layout obj only if it’s a Plot instance. Otherwise the width kwarg is ignored.
height (int) – the desired height of the exported layout obj only if it’s a Plot instance. Otherwise the height kwarg is ignored.
webdriver (selenium.webdriver) – a selenium webdriver instance to use to export the image.
timeout (int) – the maximum amount of time (in seconds) to wait for Bokeh to initialize (default: 5) (Added in 1.1.1).
- Returns
the list of filenames where the SVGs files are saved.
- Return type
Warning
Responsive sizing_modes may generate layouts with unexpected size and aspect ratios. It is recommended to use the default
fixed
sizing mode.
- install_notebook_hook(notebook_type: typing_extensions.Literal[jupyter, zeppelin], load: bokeh.io.notebook.Load, show_doc: bokeh.io.notebook.ShowDoc, show_app: bokeh.io.notebook.ShowApp, overwrite: bool = False) None [source]¶
Install a new notebook display hook.
Bokeh comes with support for Jupyter notebooks built-in. However, there are other kinds of notebooks in use by different communities. This function provides a mechanism for other projects to instruct Bokeh how to display content in other notebooks.
This function is primarily of use to developers wishing to integrate Bokeh with new notebook types.
- Parameters
notebook_type (str) –
A name for the notebook type, e.e.
'Jupyter'
or'Zeppelin'
If the name has previously been installed, a
RuntimeError
will be raised, unlessoverwrite=True
load (callable) –
A function for loading BokehJS in a notebook type. The function will be called with the following arguments:
load( resources, # A Resources object for how to load BokehJS verbose, # Whether to display verbose loading banner hide_banner, # Whether to hide the output banner entirely load_timeout # Time after which to report a load fail error )
show_doc (callable) –
A function for displaying Bokeh standalone documents in the notebook type. This function will be called with the following arguments:
show_doc( obj, # the Bokeh object to display state, # current bokeh.io "state" notebook_handle # whether a notebook handle was requested )
If the notebook platform is capable of supporting in-place updates to plots then this function may return an opaque notebook handle that can be used for that purpose. The handle will be returned by
show()
, and can be used by as appropriate to update plots, etc. by additional functions in the library that installed the hooks.show_app (callable) –
A function for displaying Bokeh applications in the notebook type. This function will be called with the following arguments:
show_app( app, # the Bokeh Application to display state, # current bokeh.io "state" notebook_url, # URL to the current active notebook page **kw # any backend-specific keywords passed as-is )
overwrite (bool, optional) – Whether to allow an existing hook to be overwritten by a new definition (default: False)
- Returns
None
- Raises
RuntimeError – If
notebook_type
is already installed andoverwrite=False
- output_file(filename: PathLike, title: str = 'Bokeh Plot', mode: ResourcesMode | None = None, root_dir: PathLike | None = None) None [source]¶
Configure the default output state to generate output saved to a file when
show()
is called.Does not change the current
Document
fromcurdoc()
. File and notebook output may be active at the same time, so e.g., this does not clear the effects ofoutput_notebook()
.- Parameters
filename (str) – a filename for saving the HTML document
title (str, optional) – a title for the HTML document (default: “Bokeh Plot”)
mode (str, optional) – how to include BokehJS (default:
'cdn'
) One of:'inline'
,'cdn'
,'relative(-dev)'
or'absolute(-dev)'
. Seebokeh.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
orCDN
.
- Returns
None
Note
Generally, this should be called at the beginning of an interactive session or the top of a script.
- output_notebook(resources: Resources | None = None, verbose: bool = False, hide_banner: bool = False, load_timeout: int = 5000, notebook_type: NotebookType = 'jupyter') None [source]¶
Configure the default output state to generate output in notebook cells when
show()
is called. Note thatshow()
may be called multiple times in a single cell to display multiple objects in the output cell. The objects will be displayed in order.- 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)
notebook_type (string, optional) – Notebook type (default: jupyter)
- Returns
None
Note
Generally, this should be called at the beginning of an interactive session or the top of a script.
- push_notebook(*, document: Document | None = None, state: State | None = None, handle: CommsHandle | None = None) None [source]¶
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 argumentnotebook_handle=True
, which will cause it to return a handle object that can be used to update the Bokeh output later. Whenpush_notebook
is called, any property updates (e.g. plot titles or data source values, etc.) since the last call topush_notebook
or the originalshow
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 usescurdoc()
. (default: None)state (State, optional) – A
State
object. If None, then the current default state (set byoutput_file()
, etc.) is used. (default: None)
- 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.text = "New Title" push_notebook(handle=handle)
- reset_output(state: State | None = None) None [source]¶
Clear the default state of all output modes.
- Returns
None
- save(obj: LayoutDOM, filename: PathLike | None = None, resources: ResourcesLike | None = None, title: str | None = None, template: Template | None = None, state: State | None = None) str [source]¶
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) forfilename
,resources
, ortitle
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 (LayoutDOM object) – a Layout (Row/Column), Plot or Widget object to display
filename (PathLike, e.g. str, Path, optional) – filename to save document under (default: None) If None, use the default state configuration.
resources (Resources or ResourcesMode, 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”
template (Template, optional) – HTML document template (default: FILE) A Jinja2 Template, see bokeh.core.templates.FILE for the required template parameters
state (State, optional) – A
State
object. If None, then the current default implicit state is used. (default: None).
- Returns
the filename where the HTML file is saved.
- Return type
- show(obj: LayoutDOM | Application | ModifyDoc, browser: str | None = None, new: BrowserTarget = 'tab', notebook_handle: bool = False, notebook_url: str = 'localhost:8888', **kwargs: Any) CommsHandle | None [source]¶
Immediately display a Bokeh object or application.
show()
may be called multiple times in a single Jupyter notebook cell to display multiple objects. The objects are displayed in order.- Parameters
obj (LayoutDOM or Application or callable) –
A Bokeh object to display.
Bokeh plots, widgets, layouts (i.e. rows and columns) may be passed to
show
in order to display them. Ifoutput_file()
has been called, the output will be to an HTML file, which is also opened in a new browser window or tab. Ifoutput_notebook()
has been called in a Jupyter notebook, the output will be inline in the associated notebook output cell.In a Jupyter notebook, a Bokeh application or callable may also be passed. A callable will be turned into an Application using a
FunctionHandler
. The application will be run and displayed inline in the associated notebook output cell.browser (str, optional) –
Specify the browser to use to open output files(default: None)
For file output, the browser argument allows for specifying which browser to display in, e.g. “safari”, “firefox”, “opera”, “windows-default”. Not all platforms may support this option, see the documentation for the standard library webbrowser module for more information
new (str, optional) –
Specify the browser mode to use for output files (default: “tab”)
For file 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) –
Whether to create a notebook interaction handle (default: False)
For notebook output, toggles whether a handle which can be used with
push_notebook
is returned. Note that notebook handles only apply to standalone plots, layouts, etc. They do not apply when showing Applications in the notebook.notebook_url (URL, optional) –
Location of the Jupyter notebook page (default: “localhost:8888”)
When showing Bokeh applications, the Bokeh server must be explicitly configured to allow connections originating from different URLs. This parameter defaults to the standard notebook host and port. If you are running on a different location, you will need to supply this value for the application to display properly. If no protocol is supplied in the URL, e.g. if it is of the form “localhost:8888”, then “http” will be used.
notebook_url
can also be a function that takes one int for the bound server port. If the port is provided, the function needs to generate the full public URL to the bokeh server. If None is passed, the function is to generate the origin URL.
Some parameters are only useful when certain output modes are active:
The
browser
andnew
parameters only apply whenoutput_file()
is active.The
notebook_handle
parameter only applies whenoutput_notebook()
is active, and non-Application objects are being shown. It is only supported in Jupyter notebook and raises an exception for other notebook types when it is True.The
notebook_url
parameter only applies when showing Bokeh Applications in a Jupyter notebook.Any additional keyword arguments are passed to
Server
when showing a Bokeh app (added in version 1.1)
- Returns
When in a Jupyter notebook (with
output_notebook()
enabled) andnotebook_handle=True
, returns a handle that can be used bypush_notebook
, None otherwise.
bokeh.io.doc¶
- curdoc() Document | UnlockedDocumentProxy [source]¶
Return the document for the current default state.
- Returns
the current default document object.
- Return type
- patch_curdoc(doc: Document | UnlockedDocumentProxy) Iterator[None] [source]¶
Temporarily override the value of
curdoc()
and then return it to its original state.This context manager is useful for controlling the value of
curdoc()
while invoking functions (e.g. callbacks). The cont- Parameters
doc (Document) – new Document to use for
curdoc()
bokeh.io.export¶
- export_png(obj: LayoutDOM | Document, *, filename: PathLike | None = None, width: int | None = None, height: int | None = None, webdriver: WebDriver | None = None, timeout: int = 5) str [source]¶
Export the
LayoutDOM
object or document as a PNG.If the filename is not given, it is derived from the script name (e.g.
/foo/myplot.py
will create/foo/myplot.png
)- Parameters
obj (LayoutDOM or Document) – a Layout (Row/Column), Plot or Widget object or Document to export.
filename (PathLike, e.g. str, Path, optional) – filename to save document under (default: None) If None, infer from the filename.
width (int) – the desired width of the exported layout obj only if it’s a Plot instance. Otherwise the width kwarg is ignored.
height (int) – the desired height of the exported layout obj only if it’s a Plot instance. Otherwise the height kwarg is ignored.
webdriver (selenium.webdriver) – a selenium webdriver instance to use to export the image.
timeout (int) – the maximum amount of time (in seconds) to wait for Bokeh to initialize (default: 5) (Added in 1.1.1).
- Returns
the filename where the static file is saved.
- Return type
filename (str)
If you would like to access an Image object directly, rather than save a file to disk, use the lower-level
get_screenshot_as_png()
function.Warning
Responsive sizing_modes may generate layouts with unexpected size and aspect ratios. It is recommended to use the default
fixed
sizing mode.
- export_svg(obj: LayoutDOM | Document, *, filename: PathLike | None = None, width: int | None = None, height: int | None = None, webdriver: WebDriver | None = None, timeout: int = 5) List[str] [source]¶
Export a layout as SVG file or a document as a set of SVG files.
If the filename is not given, it is derived from the script name (e.g.
/foo/myplot.py
will create/foo/myplot.svg
)- Parameters
obj (LayoutDOM object) – a Layout (Row/Column), Plot or Widget object to display
filename (PathLike, e.g. str, Path, optional) – filename to save document under (default: None) If None, infer from the filename.
width (int) – the desired width of the exported layout obj only if it’s a Plot instance. Otherwise the width kwarg is ignored.
height (int) – the desired height of the exported layout obj only if it’s a Plot instance. Otherwise the height kwarg is ignored.
webdriver (selenium.webdriver) – a selenium webdriver instance to use to export the image.
timeout (int) – the maximum amount of time (in seconds) to wait for Bokeh to initialize (default: 5)
- Returns
the list of filenames where the SVGs files are saved.
- Return type
Warning
Responsive sizing_modes may generate layouts with unexpected size and aspect ratios. It is recommended to use the default
fixed
sizing mode.
- export_svgs(obj: LayoutDOM | Document, *, filename: str | None = None, width: int | None = None, height: int | None = None, webdriver: WebDriver | None = None, timeout: int = 5) List[str] [source]¶
Export the SVG-enabled plots within a layout. Each plot will result in a distinct SVG file.
If the filename is not given, it is derived from the script name (e.g.
/foo/myplot.py
will create/foo/myplot.svg
)- Parameters
obj (LayoutDOM object) – a Layout (Row/Column), Plot or Widget object to display
filename (str, optional) – filename to save document under (default: None) If None, infer from the filename.
width (int) – the desired width of the exported layout obj only if it’s a Plot instance. Otherwise the width kwarg is ignored.
height (int) – the desired height of the exported layout obj only if it’s a Plot instance. Otherwise the height kwarg is ignored.
webdriver (selenium.webdriver) – a selenium webdriver instance to use to export the image.
timeout (int) – the maximum amount of time (in seconds) to wait for Bokeh to initialize (default: 5) (Added in 1.1.1).
- Returns
the list of filenames where the SVGs files are saved.
- Return type
Warning
Responsive sizing_modes may generate layouts with unexpected size and aspect ratios. It is recommended to use the default
fixed
sizing mode.
- get_layout_html(obj: LayoutDOM | Document, *, resources: Resources = <bokeh.resources.Resources object>, width: int | None = None, height: int | None = None) str [source]¶
- get_screenshot_as_png(obj: LayoutDOM | Document, *, driver: WebDriver | None = None, timeout: int = 5, resources: Resources = <bokeh.resources.Resources object>, width: int | None = None, height: int | None = None) Image.Image [source]¶
Get a screenshot of a
LayoutDOM
object.- Parameters
obj (LayoutDOM or Document) – a Layout (Row/Column), Plot or Widget object or Document to export.
driver (selenium.webdriver) – a selenium webdriver instance to use to export the image.
timeout (int) – the maximum amount of time to wait for initialization. It will be used as a timeout for loading Bokeh, then when waiting for the layout to be rendered.
- Returns
a pillow image loaded from PNG.
- Return type
image (PIL.Image.Image)
Warning
Responsive sizing_modes may generate layouts with unexpected size and aspect ratios. It is recommended to use the default
fixed
sizing mode.
bokeh.io.notebook¶
- destroy_server(server_id: ID) None [source]¶
Given a UUID id of a div removed or replaced in the Jupyter notebook, destroy the corresponding server sessions and stop it.
- get_comms(target_name: str) Comm [source]¶
Create a Jupyter comms object for a specific target, that can be used to update Bokeh documents in the Jupyter notebook.
- Parameters
target_name (str) – the target name the Comms object should connect to
- Returns
Jupyter Comms
- install_notebook_hook(notebook_type: typing_extensions.Literal[jupyter, zeppelin], load: bokeh.io.notebook.Load, show_doc: bokeh.io.notebook.ShowDoc, show_app: bokeh.io.notebook.ShowApp, overwrite: bool = False) None [source]¶
Install a new notebook display hook.
Bokeh comes with support for Jupyter notebooks built-in. However, there are other kinds of notebooks in use by different communities. This function provides a mechanism for other projects to instruct Bokeh how to display content in other notebooks.
This function is primarily of use to developers wishing to integrate Bokeh with new notebook types.
- Parameters
notebook_type (str) –
A name for the notebook type, e.e.
'Jupyter'
or'Zeppelin'
If the name has previously been installed, a
RuntimeError
will be raised, unlessoverwrite=True
load (callable) –
A function for loading BokehJS in a notebook type. The function will be called with the following arguments:
load( resources, # A Resources object for how to load BokehJS verbose, # Whether to display verbose loading banner hide_banner, # Whether to hide the output banner entirely load_timeout # Time after which to report a load fail error )
show_doc (callable) –
A function for displaying Bokeh standalone documents in the notebook type. This function will be called with the following arguments:
show_doc( obj, # the Bokeh object to display state, # current bokeh.io "state" notebook_handle # whether a notebook handle was requested )
If the notebook platform is capable of supporting in-place updates to plots then this function may return an opaque notebook handle that can be used for that purpose. The handle will be returned by
show()
, and can be used by as appropriate to update plots, etc. by additional functions in the library that installed the hooks.show_app (callable) –
A function for displaying Bokeh applications in the notebook type. This function will be called with the following arguments:
show_app( app, # the Bokeh Application to display state, # current bokeh.io "state" notebook_url, # URL to the current active notebook page **kw # any backend-specific keywords passed as-is )
overwrite (bool, optional) – Whether to allow an existing hook to be overwritten by a new definition (default: False)
- Returns
None
- Raises
RuntimeError – If
notebook_type
is already installed andoverwrite=False
- load_notebook(resources: Resources | None = None, verbose: bool = False, hide_banner: bool = False, load_timeout: int = 5000) None [source]¶
Prepare the IPython notebook for displaying Bokeh plots.
- Parameters
resources (Resource, optional) – how and where to load BokehJS from (default: CDN)
verbose (bool, optional) – whether to report detailed settings (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)
Warning
Clearing the output cell containing the published BokehJS resources HTML code may cause Bokeh CSS styling to be removed.
- Returns
None
- publish_display_data(data: Dict[str, Any], metadata: Dict[Any, Any] | None = None, source: str | None = None, *, transient: Dict[str, Any] | None = None, **kwargs: Any) None [source]¶
- push_notebook(*, document: Document | None = None, state: State | None = None, handle: CommsHandle | None = None) None [source]¶
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 argumentnotebook_handle=True
, which will cause it to return a handle object that can be used to update the Bokeh output later. Whenpush_notebook
is called, any property updates (e.g. plot titles or data source values, etc.) since the last call topush_notebook
or the originalshow
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 usescurdoc()
. (default: None)state (State, optional) – A
State
object. If None, then the current default state (set byoutput_file()
, etc.) is used. (default: None)
- 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.text = "New Title" push_notebook(handle=handle)
- run_notebook_hook(notebook_type: typing_extensions.Literal[jupyter, zeppelin], action: typing_extensions.Literal[load, doc, app], *args: Any, **kwargs: Any) Any [source]¶
Run an installed notebook hook with supplied arguments.
- Parameters
All other arguments and keyword arguments are passed to the hook action exactly as supplied.
- Returns
Result of the hook action, as-is
- Raises
RuntimeError – If the hook or specific action is not installed
- show_app(app: Application, state: State, notebook_url: str | Callable[[int | None], str], port: int = 0, **kw: Any) None [source]¶
Embed a Bokeh server application in a Jupyter Notebook output cell.
- Parameters
app (Application or callable) – A Bokeh Application to embed inline in a Jupyter notebook.
state (State) – ** Unused **
notebook_url (str or callable) –
The URL of the notebook server that is running the embedded app.
If
notebook_url
is a string, the value string is parsed to construct the origin and full server URLs.If notebook_url is a callable, it must accept one parameter, which will be the server port, or None. If passed a port, the callable must generate the server URL, otherwise if passed None, it must generate the origin URL for the server.
port (int) –
A port for the embedded server will listen on.
By default the port is 0, which results in the server listening on a random dynamic port.
Any additional keyword arguments are passed to
Server
(added in version 1.1)- Returns
None
- show_doc(obj: Model, state: State) None [source]¶
- show_doc(obj: Model, state: State, notebook_handle: bokeh.io.notebook.CommsHandle) bokeh.io.notebook.CommsHandle
bokeh.io.output¶
- output_file(filename: PathLike, title: str = 'Bokeh Plot', mode: ResourcesMode | None = None, root_dir: PathLike | None = None) None [source]¶
Configure the default output state to generate output saved to a file when
show()
is called.Does not change the current
Document
fromcurdoc()
. File and notebook output may be active at the same time, so e.g., this does not clear the effects ofoutput_notebook()
.- Parameters
filename (str) – a filename for saving the HTML document
title (str, optional) – a title for the HTML document (default: “Bokeh Plot”)
mode (str, optional) – how to include BokehJS (default:
'cdn'
) One of:'inline'
,'cdn'
,'relative(-dev)'
or'absolute(-dev)'
. Seebokeh.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
orCDN
.
- Returns
None
Note
Generally, this should be called at the beginning of an interactive session or the top of a script.
- output_notebook(resources: Resources | None = None, verbose: bool = False, hide_banner: bool = False, load_timeout: int = 5000, notebook_type: NotebookType = 'jupyter') None [source]¶
Configure the default output state to generate output in notebook cells when
show()
is called. Note thatshow()
may be called multiple times in a single cell to display multiple objects in the output cell. The objects will be displayed in order.- 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)
notebook_type (string, optional) – Notebook type (default: jupyter)
- Returns
None
Note
Generally, this should be called at the beginning of an interactive session or the top of a script.
bokeh.io.saving¶
- save(obj: LayoutDOM, filename: PathLike | None = None, resources: ResourcesLike | None = None, title: str | None = None, template: Template | None = None, state: State | None = None) str [source]¶
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) forfilename
,resources
, ortitle
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 (LayoutDOM object) – a Layout (Row/Column), Plot or Widget object to display
filename (PathLike, e.g. str, Path, optional) – filename to save document under (default: None) If None, use the default state configuration.
resources (Resources or ResourcesMode, 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”
template (Template, optional) – HTML document template (default: FILE) A Jinja2 Template, see bokeh.core.templates.FILE for the required template parameters
state (State, optional) – A
State
object. If None, then the current default implicit state is used. (default: None).
- Returns
the filename where the HTML file is saved.
- Return type
bokeh.io.showing¶
- show(obj: LayoutDOM | Application | ModifyDoc, browser: str | None = None, new: BrowserTarget = 'tab', notebook_handle: bool = False, notebook_url: str = 'localhost:8888', **kwargs: Any) CommsHandle | None [source]¶
Immediately display a Bokeh object or application.
show()
may be called multiple times in a single Jupyter notebook cell to display multiple objects. The objects are displayed in order.- Parameters
obj (LayoutDOM or Application or callable) –
A Bokeh object to display.
Bokeh plots, widgets, layouts (i.e. rows and columns) may be passed to
show
in order to display them. Ifoutput_file()
has been called, the output will be to an HTML file, which is also opened in a new browser window or tab. Ifoutput_notebook()
has been called in a Jupyter notebook, the output will be inline in the associated notebook output cell.In a Jupyter notebook, a Bokeh application or callable may also be passed. A callable will be turned into an Application using a
FunctionHandler
. The application will be run and displayed inline in the associated notebook output cell.browser (str, optional) –
Specify the browser to use to open output files(default: None)
For file output, the browser argument allows for specifying which browser to display in, e.g. “safari”, “firefox”, “opera”, “windows-default”. Not all platforms may support this option, see the documentation for the standard library webbrowser module for more information
new (str, optional) –
Specify the browser mode to use for output files (default: “tab”)
For file 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) –
Whether to create a notebook interaction handle (default: False)
For notebook output, toggles whether a handle which can be used with
push_notebook
is returned. Note that notebook handles only apply to standalone plots, layouts, etc. They do not apply when showing Applications in the notebook.notebook_url (URL, optional) –
Location of the Jupyter notebook page (default: “localhost:8888”)
When showing Bokeh applications, the Bokeh server must be explicitly configured to allow connections originating from different URLs. This parameter defaults to the standard notebook host and port. If you are running on a different location, you will need to supply this value for the application to display properly. If no protocol is supplied in the URL, e.g. if it is of the form “localhost:8888”, then “http” will be used.
notebook_url
can also be a function that takes one int for the bound server port. If the port is provided, the function needs to generate the full public URL to the bokeh server. If None is passed, the function is to generate the origin URL.
Some parameters are only useful when certain output modes are active:
The
browser
andnew
parameters only apply whenoutput_file()
is active.The
notebook_handle
parameter only applies whenoutput_notebook()
is active, and non-Application objects are being shown. It is only supported in Jupyter notebook and raises an exception for other notebook types when it is True.The
notebook_url
parameter only applies when showing Bokeh Applications in a Jupyter notebook.Any additional keyword arguments are passed to
Server
when showing a Bokeh app (added in version 1.1)
- Returns
When in a Jupyter notebook (with
output_notebook()
enabled) andnotebook_handle=True
, returns a handle that can be used bypush_notebook
, None otherwise.
bokeh.io.state¶
Encapsulate implicit state that is useful for Bokeh plotting APIs.
Note
While State
objects can also be manipulated explicitly, they are
automatically configured when the output functions like output_file()
from bokeh.io are used. Therefore, manipulating State
objects is
usually not necessary.
Generating output for Bokeh plots requires coordinating several things:
Document
Groups together Bokeh models that may be shared between plots (e.g., range or data source objects) into one common structure.
Resources
Control how JavaScript and CSS for the client library BokehJS are included and used in the generated output.
It is possible to handle the configuration of these things manually, and some
examples of doing this can be found in examples/models
directory. When
developing sophisticated applications, it may be necessary or desirable to work
at this level. However, for general use this would quickly become burdensome.
This module provides a State
class that encapsulates these objects and
ensures their proper configuration in many common usage scenarios.
- class State[source]¶
Manage state related to controlling Bokeh output.
Public Data Attributes:
A default
Document
to use for all output operations.A structure with the default configuration for file output (READ ONLY)
Whether to generate notebook output on show operations.
Notebook type
Public Methods:
__init__
()output_file
(filename[, title, mode, root_dir])Configure output to a standalone HTML file.
output_notebook
([notebook_type])Generate output in notebook cells.
reset
()Deactivate all currently active output modes and set
curdoc()
to a fresh emptyDocument
.
- output_file(filename: PathLike, title: str = 'Bokeh Plot', mode: ResourcesMode | None = None, root_dir: PathLike | None = None) None [source]¶
Configure output to a standalone HTML file.
Calling
output_file
does not clear the effects of any other calls tooutput_notebook()
, etc. It adds an additional output destination (publishing to HTML files). Any other active output modes continue to be active.- Parameters
filename (PathLike, e.g. str, Path) – a filename for saving the HTML document
title (str, optional) – a title for the HTML document
mode (str, optional) –
how to include BokehJS (default:
'cdn'
)One of:
'inline'
,'cdn'
,'relative(-dev)'
or'absolute(-dev)'
. SeeResources
for more details.root_dir (str, optional) –
root dir to use for absolute resources (default: None)
This value is ignored for other resource types, e.g.
INLINE
orCDN
.
Warning
The specified output file will be overwritten on every save, e.g., every time
show()
orsave()
is called.
- output_notebook(notebook_type: NotebookType = 'jupyter') None [source]¶
Generate output in notebook cells.
Calling
output_notebook
does not clear the effects of any other calls tooutput_file()
, etc. It adds an additional output destination (publishing to notebook output cells). Any other active output modes continue to be active.- Returns
None
- reset() None [source]¶
Deactivate all currently active output modes and set
curdoc()
to a fresh emptyDocument
.Subsequent calls to
show()
will not render until a new output mode is activated.- Returns
None
- property document: bokeh.document.document.Document¶
A default
Document
to use for all output operations.
- curstate() bokeh.io.state.State [source]¶
Return the current State object
- Returns
the current default State object
- Return type
bokeh.io.util¶
- default_filename(ext: str) str [source]¶
Generate a default filename with a given extension, attempting to use the filename of the currently running process, if possible.
If the filename of the current process is not available (or would not be writable), then a temporary file with the given extension is returned.
- Parameters
ext (str) – the desired extension for the filename
- Returns
str
- Raises
RuntimeError – If the extensions requested is “.py”