Anaconda Enterprise: Documentation

# bokeh.io

Functions for configuring Bokeh output.

`bokeh.io.``curdoc`()

  Return the document for the current default state.

  Returns: | the current default document object.
  Return type: | Document

`bokeh.io.``curstate`()

  Return the current State object

  Returns: | the current default State object
  Return type: | State

`bokeh.io.``default_filename`(ext)

  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”

`bokeh.io.``export_png`(obj, filename=None, height=None, width=None, webdriver=None)

  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 (str, optional) – filename to save document under (default: None) If None, infer from the filename.
  - height (int) – the desired height of the exported layout obj only if it’s a Plot instance. Otherwise the height kwarg is ignored.
  - width (int) – the desired width of the exported layout obj only if it’s a Plot instance. Otherwise the width kwarg is ignored.
  - webdriver (selenium.webdriver) – a selenium webdriver instance to use to export the image.

  Returns: | the filename where the static file is saved.
  Return type: | filename (str)

  Warning

  Responsive sizing_modes may generate layouts with unexpected size and aspect ratios. It is recommended to use the default `fixed` sizing mode.

  Warning

  Glyphs that are rendered via webgl won’t be included in the generated PNG.

`bokeh.io.``export_svgs`(obj, filename=None, height=None, width=None, webdriver=None)

  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.
  - height (int) – the desired height of the exported layout obj only if it’s a Plot instance. Otherwise the height kwarg is ignored.
  - width (int) – the desired width of the exported layout obj only if it’s a Plot instance. Otherwise the width kwarg is ignored.
  - webdriver (selenium.webdriver) – a selenium webdriver instance to use to export the image.

  Returns:

  the list of filenames where the SVGs files

    are saved.

  Return type: | filenames (list(str))

  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.``install_notebook_hook`(notebook_type, load, show_doc, show_app, overwrite=False)

  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, unless `overwrite=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
        )

  - 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 and `overwrite=False`

`bokeh.io.``output_file`(filename, title='Bokeh Plot', 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 and notebook output may be active at the same time, so e.g., this does not clear the effects of `output_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)'`. 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.

`bokeh.io.``output_notebook`(resources=None, verbose=False, hide_banner=False, load_timeout=5000, notebook_type='jupyter')

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

  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.``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()`. (default: None)
  - state (State, optional) – A `State` object. If None, then the current default state (set by `output_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)

`bokeh.io.``reset_output`(state=None)

  Clear the default state of all output modes.

  Returns: | None

`bokeh.io.``save`(obj, filename=None, resources=None, title=None, state=None, **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 (LayoutDOM object) – a Layout (Row/Column), Plot or Widget object to display
  - filename (str, optional) – filename to save document under (default: None) If None, use the default state configuration.
  - 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”
    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: | str

`bokeh.io.``set_curdoc`(doc)

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

  Parameters: | doc (Document) – Document we will output.
  Returns: | None

  Warning

  Calling this function will replace any existing document.

`bokeh.io.``show`(obj, browser=None, new='tab', notebook_handle=False, notebook_url='localhost:8888')

  Immediately display a Bokeh object or application.

  Parameters:

  - obj (LayoutDOM or Application) –

    A Bokeh object to display.

    Bokeh plots, widgets, layouts (i.e. rows and columns) may be passed to `show` in order to display them. When `output_file` has been called, the output will be to an HTML file, which is also opened in a new browser window or tab. When `output_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 may also be passed. 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 differnet location, you will need to supply this value for the application to display properly.

    It is also possible to pass `notebook_url="*"` to disable the standard checks, so that applications will display regardless of the current notebook location, however a warning will appear.

  Some parameters are only useful when certain output modes are active:

  - The `browser` and `new` parameters only apply when `output_file` is active.
  - The `notebook_handle` parameter only applies when `output_notebook` is active, and non-Application objects are being shown. It is only supported to Jupyter notebook, raise exception for other notebook types when it is True.
  - The `notebook_url` parameter only applies when showing Bokeh Applications in a Jupyter notebook.

  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.