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.
- 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 thatmysession.close()
is called.Public Data Attributes:
Whether this session is currently connected.
error_reason
error_code
error_detail
url
A
Document
that will be kept in sync with the correspondingDocument
on the server.A unique ID for this session.
A JWT token to authenticate the session.
Public Methods:
__init__
([session_id, websocket_url, ...])A connection which attaches to a particular named session on the server.
__enter__
()__exit__
(exc_type, exc_value, exc_traceback)connect
()Connect to a Bokeh server at the configured URL.
close
([why])Close the connection to the server.
Force a round-trip request/reply to the server, sometimes needed to avoid race conditions.
Raises an error, when the connection could not have been established.
pull
()Pull the server's state and set it as session.document.
push
([document])Push the given document to the server and record it as
session.document
.Ask for information about the server.
show
([obj, browser, new])Open a browser displaying this session.
- __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 beNone
).The
push_session()
andpull_session()
functions will construct aClientSession
and push or pull in one step, so they are a good way to obtain aClientSession
.- Parameters
session_id (str) – The name of the session or None to generate one
websocket_url (str) – Websocket URL to connect to
io_loop (IOLoop, optional) – The IOLoop to use for the websocket
arguments (dict[str, str], optional) –
A dictionary of key/values to be passed as HTTP request arguments to Bokeh application code (default: None)
Note that should only be provided when pulling new sessions. If
session_id
is not None, or a session withsession_id
already exists, these arguments will have no effect.max_message_size (int, optional) – Configure the Tornado max websocket message size. (default: 20 MB)
- 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
- 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 usesession.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: LayoutDOM | None = None, browser: str | None = None, new: Literal['tab', 'window'] = 'tab') None [source]¶
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.
- property document: bokeh.document.document.Document¶
A
Document
that will be kept in sync with the correspondingDocument
on the server.This value is initialized when
pull()
orpush()
succeeds. It will beNone
until then.
- property id: ID¶
A unique ID for this 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()
orserver_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 uniquesession_id
, you can obtain the generated ID with theid
property on the returnedClientSession
.- 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) – TheIOLoop
to use for the websocketarguments (dict[str, str], optional) –
A dictionary of key/values to be passed as HTTP request arguments to Bokeh application code (default: None)
Note that should only be provided when pulling new sessions. If
session_id
is not None, or a session withsession_id
already exists, these arguments will have no effect.max_message_size (int, optional) – Configure the Tornado max websocket message size. (default: 20 MB)
- Returns
A new
ClientSession
connected to the server- Return type
- 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 uniquesession_id
, you can obtain the generated ID with theid
property on the returnedClientSession
.- 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
max_message_size (int, optional) – Configure the Tornado max websocket message size. (default: 20 MB)
- 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: BrowserTarget = 'tab', controller: BrowserLike | None = None) None [source]¶
Open a browser displaying a session document.
If you have a session from
pull_session()
orpush_session
you canshow_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 theurl
.- 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.