Anaconda Enterprise: Documentation

# bokeh.client.session

Provide a session object to service Bokeh documents in external Python clients to a Bokeh server.

## Use-Cases

A client session has two primary uses:

- Implementing automated testing infrastructure around Bokeh server applications.
- Creating and customizing specific sessions of a Bokeh server application (running in the Bokeh server) before passing them on to a specific viewer.

## Note About “External” Applications

The use of session.loop_until_closed and push_session to run Bokeh application code outside a Bokeh server is HIGHLY DISCOURAGED for any real use.

Running application code outside a Bokeh server with bokeh.client in this way has (and always will have) several intrinsic drawbacks:

- Fast binary array transport is NOT available! Base64 fallback is much slower
- All network traffic is DOUBLED due to extra hop between client and server
- Server and client process must be running at ALL TIMES for callbacks to work
- App code run outside the Bokeh server is NOT SCALABLE behind a load balancer

The bokeh.client API is recommended to use ONLY for testing, or for customizing individual sessions running in a full Bokeh server, before passing on to viewers.

For information about different ways of running apps in a Bokeh server, see:

> http://bokeh.pydata.org/en/latest/docs/user_guide/server.html

class `bokeh.client.session.``ClientSession`(session_id=None, websocket_url='ws://localhost:5006/ws', io_loop=None)

  Represents a websocket connection to a server-side session.

  Each server session stores a Document, which is kept in sync with the document in this ClientSession instance. Always call either pull() or push() immediately after creating the session, if you construct a session by hand.

  `close`(why='closed')

    Close the connection to the server.

  `connect`()

    Connect to a Bokeh server at the configured URL.

  `force_roundtrip`()

    Force a round-trip request/reply to the server, sometimes needed to avoid race conditions. Mostly useful for testing.

    Outside of test suites, this method hurts performance and should not be needed.

    Returns: | None

  `loop_until_closed`(suppress_warning=False)

    Execute a blocking loop that runs and exectutes event callbacks until the connection is closed (e.g. by hitting Ctrl-C).

    While this method can be used to run Bokeh application code “outside” the Bokeh server, this practice is HIGHLY DISCOURAGED for any real use case.

  `pull`()

    Pull the server’s state and set it as session.document.

    If this is called more than once, session.document will be the same object instance but its contents will be overwritten.

    Automatically calls `connect()` before pulling.

  `push`(document=None)

    Push the given document to the server and record it as session.document.

    If this is called more than once, the Document has to be the same (or None to mean “session.document”).

    Note

    Automatically calls `connect()` before pushing.

    Parameters: | document (`Document`, optional) – The document which will be kept in sync with the server document. None to use session.document or create a new document.

  `request_server_info`()

    Ask for information about the server.

    Returns: | A dictionary of server attributes.

  `show`(obj=None, browser=None, new='tab')

    Open a browser displaying this session.

    Parameters:

    - obj (LayoutDOM object, optional) – a Layout (Row/Column), Plot or Widget object to display. The object will be added to the session’s document.
    - 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.

  `connected`

    Whether this session is currently connected.

  `document`

    A `Document` that will be kept in sync with the corresponding Document on the server.

    This value is initialized when `pull()` or `push()` succeeds. It will be `None` until then.

  `id`

    A unique ID for this session.

`bokeh.client.session.``pull_session`(session_id=None, url='default', app_path=None, io_loop=None)

  Create a session by loading the current server-side document.

  `session.document` will be a fresh document loaded from the server. While the connection to the server is open, changes made on the server side will be applied to this document, and changes made on the client side will be synced to the server.

  If you don’t plan to modify `session.document` you probably don’t need to use this function; instead you can directly `show_session()` or `server_session()` without downloading the session’s document into your process first. It’s much more efficient to avoid downloading the session if you don’t need to.

  In a production scenario, the `session_id` should be unique for each browser tab, which keeps users from stomping on each other. It’s neither scalable nor secure to use predictable session IDs or to share session IDs across users.

  For a notebook running on a single machine, `session_id` could be something human-readable such as `"default"` for convenience.

  If you allow `pull_session()` to generate a unique `session_id`, you can obtain the generated ID with the `id` property on the returned `ClientSession`.

  Parameters:

  - session_id (string, optional) – The name of the session, None to autogenerate a random one (default: None)
  - url – (str, optional): The URL to a Bokeh application on a Bokeh server can also be “default” which will connect to the default app URL
  - io_loop (`tornado.ioloop.IOLoop`, optional) – The IOLoop to use for the websocket

  Returns: | A new ClientSession connected to the server
  Return type: | ClientSession

`bokeh.client.session.``push_session`(document, session_id=None, url='default', app_path=None, io_loop=None)

  Create a session by pushing the given document to the server, overwriting any existing server-side document.

  `session.document` in the returned session will be your supplied document. While the connection to the server is open, changes made on the server side will be applied to this document, and changes made on the client side will be synced to the server.

  In a production scenario, the `session_id` should be unique for each browser tab, which keeps users from stomping on each other. It’s neither scalable nor secure to use predictable session IDs or to share session IDs across users.

  For a notebook running on a single machine, `session_id` could be something human-readable such as `"default"` for convenience.

  If you allow `push_session()` to generate a unique `session_id`, you can obtain the generated ID with the `id` property on the returned `ClientSession`.

  Parameters:

  - document – (bokeh.document.Document) The document to be pushed and set as session.document
  - session_id – (string, optional) The name of the session, None to autogenerate a random one (default: None)
  - url – (str, optional): The URL to a Bokeh application on a Bokeh server can also be “default” which will connect to the default app URL
  - io_loop – (tornado.ioloop.IOLoop, optional) The IOLoop to use for the websocket

  Returns:

  ClientSession

    A new ClientSession connected to the server

`bokeh.client.session.``show_session`(session_id=None, url='default', app_path=None, session=None, browser=None, new='tab', controller=None)

  Open a browser displaying a session document.

  If you have a session from `pull_session()` or `push_session` you can `show_session(session=mysession)`. If you don’t need to open a connection to the server yourself, you can show a new session in a browser by providing just the `url`.

  Parameters:

  - session_id (string, optional) – The name of the session, None to autogenerate a random one (default: None)
  - url – (str, optional): The URL to a Bokeh application on a Bokeh server can also be “default” which will connect to the default app URL
  - session (ClientSession, optional) – session to get session ID and server URL from If you specify this, you don’t need to specify session_id and url
  - 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.