bokeh.application.application

Provide the Application class.

Application instances are factories for creating new Bokeh Documents.

When a Bokeh server session is initiated, the Bokeh server asks the Application for a new Document to service the session. To do this, the Application first creates a new empty Document, then it passes this new Document to the modify_document method of each of its handlers. When all handlers have updated the Document, it is used to service the user session.

class Application(*handlers, **kwargs)

An Application is a factory for Document instances.

__init__(*handlers, **kwargs)

Application factory.

Parameters

handlers (seq[Handler]) – List of handlers to call. The URL is taken from the first one only.

Keyword Arguments

metadata (dict) –

arbitrary user-supplied JSON data to make available with the application.

The server will provide a URL http://applicationurl/metadata which returns a JSON blob of the form:

{
    "data": {
        "hi": "hi",
        "there": "there"
    },
    "url": "/myapp"
}

The user-supplied metadata is returned as-is under the "data" key in the blob.

add(handler)

Add a handler to the pipeline used to initialize new documents.

Parameters

handler (Handler) – a handler for this Application to use to process Documents

create_document()

Creates and initializes a document using the Application’s handlers.

initialize_document(doc)

Fills in a new document using the Application’s handlers.

on_server_loaded(server_context)

Invoked to execute code when a new session is created.

This method calls on_server_loaded on each handler, in order, with the server context passed as the only argument.

on_server_unloaded(server_context)

Invoked to execute code when the server cleanly exits. (Before stopping the server’s IOLoop.)

This method calls on_server_unloaded on each handler, in order, with the server context passed as the only argument.

Warning

In practice this code may not run, since servers are often killed by a signal.

async on_session_created(session_context)

Invoked to execute code when a new session is created.

This method calls on_session_created on each handler, in order, with the session context passed as the only argument.

May return a Future which will delay session creation until the Future completes.

async on_session_destroyed(session_context)

Invoked to execute code when a session is destroyed.

This method calls on_session_destroyed on each handler, in order, with the session context passed as the only argument.

Afterwards, session_context.destroyed will be True.

process_request(request)

Processes incoming HTTP request returning a dictionary of additional data to add to the session_context.

Parameters

request – HTTP request

Returns

A dictionary of JSON serializable data to be included on the session context.

property handlers

The ordered list of handlers this Application is configured with.

property metadata

Arbitrary user-supplied metadata to associate with this application.

property safe_to_fork

property static_path

Path to any (optional) static resources specified by handlers.

class ServerContext

A harness for server-specific information and tasks related to collections of Bokeh sessions.

This base class is probably not of interest to general users.

abstract add_next_tick_callback(callback)

Add a callback to be run on the next tick of the event loop.

Subclasses must implement this method.

Parameters

callback (callable) –

a callback to add

The callback will execute on the next tick of the event loop, and should have the form def callback() (i.e. it should not accept any arguments)

Returns

an ID that can be used with remove_next_tick_callback.

abstract add_periodic_callback(callback, period_milliseconds)

Add a callback to be run periodically until it is removed.

Subclasses must implement this method.

Parameters

• callback (callable) –

  a callback to add

  The callback will execute periodically on the event loop as specified, and should have the form def callback() (i.e. it should not accept any arguments)

• period_milliseconds (int) – number of milliseconds to wait between executing the callback.

Returns

an ID that can be used with remove_periodic_callback.

abstract add_timeout_callback(callback, timeout_milliseconds)

Add a callback to be run once after timeout_milliseconds.

Subclasses must implement this method.

Parameters

• callback (callable) –

  a callback to add

  The callback will execute once on the event loop after the timeout has passed, and should have the form def callback() (i.e. it should not accept any arguments)

• timeout_milliseconds (int) – number of milliseconds to wait before executing the callback.

Returns

an ID that can be used with remove_timeout_callback.

abstract remove_next_tick_callback(callback_id)

Remove a callback added with add_next_tick_callback, before it runs.

Subclasses must implement this method.

Parameters

callback_id – the ID returned from add_next_tick_callback

abstract remove_periodic_callback(callback_id)

Removes a callback added with add_periodic_callback.

Subclasses must implement this method.

Parameters

callback_id – the ID returned from add_periodic_callback

abstract remove_timeout_callback(callback_id)

Remove a callback added with add_timeout_callback, before it runs.

Subclasses must implement this method.

Parameters

callback_id – the ID returned from add_timeout_callback

abstract property sessions

SessionContext instances belonging to this application.

Subclasses must implement this method.

class SessionContext(server_context, session_id)

A harness for server-specific information and tasks related to Bokeh sessions.

This base class is probably not of interest to general users.

__init__(server_context, session_id)

abstract with_locked_document(func)

Runs a function with the document lock held, passing the document to the function.

Subclasses must implement this method.

Parameters

func (callable) – function that takes a single parameter (the Document) and returns None or a Future

Returns

a Future containing the result of the function

abstract property destroyed

If True, the session has been discarded and cannot be used.

A new session with the same ID could be created later but this instance will not come back to life.

property id

The unique ID for the session associated with this context.

property server_context

The server context for this session context