Provide a session object to service Bokeh documents in external Python
clients to a Bokeh server.
A client session has two primary uses:
Implementing automated testing infrastructure around Bokeh server
Creating and customizing specific sessions of a Bokeh server application
(running in the Bokeh server) before passing them on to a specific
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.
A connection which attaches to a particular named session on the
Always call either pull() or push() immediately after creating the
session (until these are called session.document will be None).
The push_session() and
pull_session() functions will construct a
ClientSession and push or pull in one step, so they are a good way to
obtain a ClientSession.
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 with session_id
already exists, these arguments will have no effect.
max_message_size (int, optional) – Configure the Tornado max websocket message size.
(default: 20 MB)
Raises an error, when the connection could not have been
Should be used, after a call to connect.
Close the connection to the server.
Connect to a Bokeh server at the configured URL.
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
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 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”).
Automatically calls connect() before pushing.
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.
Ask for information about the server.
A dictionary of server attributes.
Open a browser displaying this session.
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.
Whether this session is currently connected.
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.
A unique ID for this session.
A JWT token to authenticate the session.
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
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
For a notebook running on a single machine, session_id
could be something human-readable such as "default" for
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.
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
A dictionary of key/values to be passed as HTTP request arguments
to Bokeh application code (default: None)
A new ClientSession connected to the server
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
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)
io_loop – (tornado.ioloop.IOLoop, optional)
The IOLoop to use for the websocket
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.
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