bokeh.client¶

bokeh.client.session¶

class 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.

force_roundtrip()¶

Used in unit testing to force a request/reply pair in order to avoid races

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.

document¶

Document which will be kept in sync with the server document

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

pull_session(session_id=None, url='default', app_path='/', 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 autoload_server() 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 base server URL to connect to (default: ‘default’) app_path (str, optional) – Relative path to the app on the server (default: ‘/’) io_loop (tornado.ioloop.IOLoop, optional) – The IOLoop to use for the websocket
Returns:	session – A new ClientSession connected to the server
Return type:	ClientSession

push_session(document, session_id=None, url='default', app_path='/', 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 base server URL to connect to (default: ‘default’) app_path – str, optional Relative path to the app on the server (defualt: ‘/’) io_loop – tornado.ioloop.IOLoop, optional The IOLoop to use for the websocket
Returns:	ClientSession A new ClientSession connected to the server
Return type:	session

show_session(session_id=None, url='default', app_path='/', 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 and app_path.

Parameters:

session_id (string, optional) – The name of the session, None to autogenerate a random one (default: None) url (str, optional) – The base server URL to connect to (default: ‘default’) app_path (str, optional) – Relative path to the app on the server (defualt: ‘/’) 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.