bokeh.client.session (original) (raw)

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:

class ClientSession(session_id: ID | None = None, websocket_url: str = 'ws://localhost:5006/ws', io_loop: IOLoop | None = None, arguments: dict[str, str] | None = None, max_message_size: int = 20971520)[source]#

Represents a websocket connection to a server-side session.

Each server session stores a Document, which is kept in sync with the corresponding Document for this ClientSession instance. Updates on either side of the connection will automatically propagate to the other side, as long as the connection is open.

ClientSession objects can (and usually should) be used as a context manager so that the session is properly closed:

with pull_session(url=app_url) as mysession: # customize session here script = server_session(session_id=mysession.id, url=app_url) return render_template("embed.html", script=script, template="Flask")

If you do not use ClientSession in this way, it is up to you to ensure that mysession.close() is called.

__init__(session_id: ID | None = None, websocket_url: str = 'ws://localhost:5006/ws', io_loop: IOLoop | None = None, arguments: dict[str, str] | None = None, max_message_size: int = 20971520)[source]#

A connection which attaches to a particular named session on the server.

Always call either pull() or push() immediately after creating the session (until these are called session.document will be None).

The push_session() andpull_session() functions will construct aClientSession and push or pull in one step, so they are a good way to obtain a ClientSession.

Parameters:

check_connection_errors() → None[source]#

Raises an error, when the connection could not have been established.

Should be used, after a call to connect.

Returns:

None

close(why: str = 'closed') → None[source]#

Close the connection to the server.

connect() → None[source]#

Connect to a Bokeh server at the configured URL.

force_roundtrip() → None[source]#

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

pull() → None[source]#

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: Document | None = None) → None[source]#

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 that will be kept in sync with the server document. None to use session.document or create a new document.

request_server_info() → ServerInfo[source]#

Ask for information about the server.

Returns:

A dictionary of server attributes.

show(obj: UIElement | None = None, browser: str | None = None, new: Literal['tab', 'window'] = 'tab') → None[source]#

Open a browser displaying this session.

Parameters:

property connected_: bool_#

Whether this session is currently connected.

property document_: Document_#

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

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

property id_: ID_#

A unique ID for this session.

property token_: str_#

A JWT token to authenticate the session.

pull_session(session_id: ID | None = None, url: str = 'default', io_loop: IOLoop | None = None, arguments: dict[str, str] | None = None, max_message_size: int = 20971520) → ClientSession[source]#

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 directlyshow_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_idcould be something human-readable such as "default" for convenience.

If you allow pull_session() to generate a uniquesession_id, you can obtain the generated ID with theid property on the returned ClientSession.

Parameters:

Returns:

A new ClientSession connected to the server

Return type:

ClientSession

push_session(document: Document, session_id: ID | None = None, url: str = 'default', io_loop: IOLoop | None = None, max_message_size: int = 20971520) → ClientSession[source]#

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

Parameters:

Returns:

ClientSession

A new ClientSession connected to the server

show_session(session_id: ID | None = None, url: str = 'default', session: ClientSession | None = None, browser: str | None = None, new: Literal['same', 'window', 'tab'] = 'tab', controller: BrowserLike | None = None) → None[source]#

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: