bokeh.server.server#
Provide basic Bokeh server objects that use a Tornado HTTPServer
and
BokeTornado
Tornado Application to service Bokeh Server Applications.
There are two public classes in this module:
BaseServer
This is a lightweight class to explicitly coordinate the components needed to run a Bokeh server (A
BokehTornado
instance, and TornadoHTTPServer
and a TornadoIOLoop
)Server
This higher-level convenience class only needs to be configured with Bokeh
Application
instances, and will automatically create and coordinate the lower level Tornado components.
See Server introduction for general information on the Bokeh server.
- class BaseServer(io_loop: IOLoop, tornado_app: BokehTornado, http_server: HTTPServer)[source]#
Explicitly coordinate the level Tornado components required to run a Bokeh server:
A Tornado
IOLoop
to run the Bokeh server machinery.a
BokehTornado
Tornado application that defines the Bokeh server machinery.a Tornado
HTTPServer
to direct HTTP requests
All three of these components must be passed to
BaseServer
, which will initialize theBokehTornado
instance on theio_loop
. Thehttp_server
must have been previously created and initialized with theBokehTornado
instance.- __init__(io_loop: IOLoop, tornado_app: BokehTornado, http_server: HTTPServer) None [source]#
Create a
BaseServer
instance.- Parameters:
io_loop (IOLoop) – A Tornado
IOLoop
to run the Bokeh Tornado application on.tornado_app (BokehTornado) – An instance of the Bokeh Tornado application that generates Bokeh Documents and Sessions.
http_server (HTTPServer) – A Tornado
HTTPServer
to service HTTP requests for Bokeh applications. Should have already be configured with thetornado_app
when created.
- get_session(app_path: str, session_id: ID) ServerSession [source]#
Get an active a session by name application path and session ID.
- get_sessions(app_path: str | None = None) list[ServerSession] [source]#
Gets all currently active sessions for applications.
- Parameters:
app_path (str, optional) – The configured application path for the application to return sessions for. If None, return active sessions for all applications. (default: None)
- Returns:
list[ServerSession]
- run_until_shutdown() None [source]#
Run the Bokeh Server until shutdown is requested by the user, either via a Keyboard interrupt (Ctrl-C) or SIGTERM.
Calling this method will start the Tornado
IOLoop
and block all execution in the calling process.- Returns:
None
- show(app_path: str, browser: str | None = None, new: BrowserTarget = 'tab') None [source]#
Opens an app in a browser window or tab.
This method is useful for testing or running Bokeh server applications on a local machine but should not call when running Bokeh server for an actual deployment.
- Parameters:
app_path (str) – the app path to open The part of the URL after the hostname:port, with leading slash.
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) – window or tab (default: “tab”) If
new
is ‘tab’, then opens a new tab. Ifnew
is ‘window’, then opens a new window.
- Returns:
None
- start() None [source]#
Install the Bokeh Server and its background tasks on a Tornado
IOLoop
.This method does not block and does not affect the state of the Tornado
IOLoop
You must start and stop the loop yourself, i.e. this method is typically useful when you are already explicitly managing anIOLoop
yourself.To start a Bokeh server and immediately “run forever” in a blocking manner, see
run_until_shutdown()
.
- stop(wait: bool = True) None [source]#
Stop the Bokeh Server.
This stops and removes all Bokeh Server
IOLoop
callbacks, as well as stops theHTTPServer
that this instance was configured with.- Parameters:
fast (bool) – Whether to wait for orderly cleanup (default: True)
- Returns:
None
- unlisten() None [source]#
Stop listening on ports. The server will no longer be usable after calling this function.
Note
This function is mostly useful for tests
- Returns:
None
- property io_loop: IOLoop#
The Tornado
IOLoop
that this Bokeh Server is running on.
- class Server(applications: Mapping[str, Application | ModifyDoc] | Application | ModifyDoc, io_loop: IOLoop | None = None, http_server_kwargs: dict[str, Any] | None = None, **kwargs: Any)[source]#
A high level convenience class to run a Bokeh server.
This class can automatically coordinate the three the base level components required to run a Bokeh server:
A Tornado
IOLoop
to run the Bokeh server machinery.a
BokehTornado
Tornado application that defines the Bokeh server machinery.a Tornado
HTTPServer
to direct HTTP requests
This high level
Server
class has some limitations. In particular, it is not possible to set an explicitio_loop
andnum_procs
other than 1 at the same time. To do that, it is necessary to useBaseServer
and coordinate the three components above explicitly.- __init__(applications: Mapping[str, Application | ModifyDoc] | Application | ModifyDoc, io_loop: IOLoop | None = None, http_server_kwargs: dict[str, Any] | None = None, **kwargs: Any) None [source]#
Create a
Server
instance.- Parameters:
applications (dict[str, Application] or Application or callable) –
A mapping from URL paths to Application instances, or a single Application to put at the root URL.
The Application is a factory for Documents, with a new Document initialized for each Session. Each application is identified by a path that corresponds to a URL, like “/” or “/myapp”
If a single Application is provided, it is mapped to the URL path “/” automatically.
As a convenience, a callable may also be provided, in which an Application will be created for it using
FunctionHandler
.io_loop (IOLoop, optional) – An explicit Tornado
IOLoop
to run Bokeh Server code on. If None,IOLoop.current()
will be used (default: None)http_server_kwargs (dict, optional) –
Extra arguments passed to
tornado.httpserver.HTTPServer
.E.g.
max_buffer_size
to specify the maximum upload size. More details can be found at:http://www.tornadoweb.org/en/stable/httpserver.html#http-server
If None, no extra arguments are passed (default: None)
Additionally, the following options may be passed to configure the operation of
Server
:- Keyword Arguments:
- allow_websocket_origin (
Nullable
(List
)): A list of hosts that can connect to the websocket.
This is typically required when embedding a Bokeh server app in an external web site using
server_document()
or similar.If None, “localhost” is used. (default: None)
- allow_websocket_origin (
- num_procs (
Int
): The number of worker processes to start for the HTTP server. If an explicit
io_loop
is also configured, thennum_procs=1
is the only compatible value. UseBaseServer
to coordinate an explicitIOLoop
with a multi-process HTTP server.A value of 0 will auto detect number of cores.
Note that due to limitations inherent in Tornado, Windows does not support
num_procs
values greater than one! In this case consider running multiple Bokeh server instances behind a load balancer. (default: 1)
- num_procs (
- port (
Int
): The port number the server should listen on for HTTP requests. (default: 5006)
- port (
- prefix (
String
): A URL prefix to use for all Bokeh server paths. (default: ‘’)
- prefix (
- use_xheaders (
Bool
): Whether to have the Bokeh server override the remote IP and URI scheme and protocol for all requests with
X-Real-Ip
,X-Forwarded-For
,X-Scheme
,X-Forwarded-Proto
headers (if they are provided). (default: False)
- use_xheaders (
- websocket_max_message_size (
Int
): Set the Tornado
websocket_max_message_size
value. (default: 20971520)
- websocket_max_message_size (
Any remaining keyword arguments will be passed as-is to
BokehTornado
.