bokeh.document.events

Provide events that represent various changes to Bokeh Documents.

These events are used internally to signal changes to Documents. For information about user-facing (e.g. UI or tool) events, see the reference for bokeh.events.

These events are employed for incoming and outgoing websocket messages and internally for triggering callbacks. For example, the sequence of events that happens when a user calls a Document API or sets a property resulting in a “patch event” to the Document:

user invokes Document API
    -> Document API triggers event objects
    -> registered callbacks are executed
    -> Sesssion callback generates JSON message from event object
    -> Session sends JSON message over websocket

But events may also be triggered from the client, and arrive as JSON messages over the transport layer, which is why the JSON handling and Document API must be separated. Consider the alternative sequence of events:

Session recieves JSON message over websocket
    -> Document calls event.handle_json
    -> handle_json invokes appropriate Document API
    -> Document API triggers event objects
    -> registered callbacks are executed
    -> Session callback suppresses outgoing event

As a final note, message “ping-pong” is avoided by recording a “setter” when events objects are created. If the session callback notes the event setter is itself, then no further action (e.g. sending an outgoing change event identical to the incoming event it just processed) is taken.

class ColumnDataChangedEvent(document: Document, column_source: ColumnarDataSource, cols: List[str] | None = None, setter: Setter | None = None, callback_invoker: Invoker | None = None)

A concrete event representing efficiently replacing all existing data for a ColumnDataSource

__init__(document: Document, column_source: ColumnarDataSource, cols: List[str] | None = None, setter: Setter | None = None, callback_invoker: Invoker | None = None)

Parameters

• document (Document) – A Bokeh document that is to be updated.

• column_source (ColumnDataSource) –

• cols (list[str]) – optional explicit list of column names to update. If None, all columns will be updated (default: None)

• setter (ClientSession or ServerSession or None, optional) –

  This is used to prevent “boomerang” updates to Bokeh apps. (default: None)

  See DocumentChangedEvent for more details.

• callback_invoker (callable, optional) – A callable that will invoke any Model callbacks that should be executed in response to the change that triggered this event. (default: None)

dispatch(receiver: Any) → None

Dispatch handling of this event to a receiver.

This method will invoke receiver._column_data_changed if it exists.

generate(references: Set[Model], buffers: Buffers) → ColumnDataChanged

Create a JSON representation of this event suitable for sending to clients.

{
    'kind'          : 'ColumnDataChanged'
    'column_source' : <reference to a CDS>
    'new'           : <new data to steam to column_source>
    'cols'          : <specific columns to update>
}

Parameters

• references (dict[str, Model]) –

  If the event requires references to certain models in order to function, they may be collected here.

  This is an “out” parameter. The values it contains will be modified in-place.

• buffers (set) –

  If the event needs to supply any additional Bokeh protocol buffers, they may be added to this set.

  This is an “out” parameter. The values it contains will be modified in-place.

class ColumnsPatchedEvent(document: Document, column_source: ColumnarDataSource, patches: Patches, setter: Setter | None = None, callback_invoker: Invoker | None = None)

A concrete event representing efficiently applying data patches to a ColumnDataSource

__init__(document: Document, column_source: ColumnarDataSource, patches: Patches, setter: Setter | None = None, callback_invoker: Invoker | None = None)

Parameters

• document (Document) – A Bokeh document that is to be updated.

• column_source (ColumnDataSource) – The data source to apply patches to.

• patches (list) –

• setter (ClientSession or ServerSession or None, optional) –

  This is used to prevent “boomerang” updates to Bokeh apps. (default: None)

  See DocumentChangedEvent for more details.

• callback_invoker (callable, optional) – A callable that will invoke any Model callbacks that should be executed in response to the change that triggered this event. (default: None)

dispatch(receiver: Any) → None

Dispatch handling of this event to a receiver.

This method will invoke receiver._columns_patched if it exists.

generate(references: Set[Model], buffers: Buffers) → ColumnsPatched

Create a JSON representation of this event suitable for sending to clients.

{
    'kind'          : 'ColumnsPatched'
    'column_source' : <reference to a CDS>
    'patches'       : <patches to apply to column_source>
}

Parameters

• references (dict[str, Model]) –

  If the event requires references to certain models in order to function, they may be collected here.

  This is an “out” parameter. The values it contains will be modified in-place.

• buffers (set) –

  If the event needs to supply any additional Bokeh protocol buffers, they may be added to this set.

  This is an “out” parameter. The values it contains will be modified in-place.

class ColumnsStreamedEvent(document: Document, column_source: ColumnarDataSource, data: DataDict | pd.DataFrame, rollover: int | None, setter: Setter | None = None, callback_invoker: Invoker | None = None)

A concrete event representing efficiently streaming new data to a ColumnDataSource

__init__(document: Document, column_source: ColumnarDataSource, data: DataDict | pd.DataFrame, rollover: int | None, setter: Setter | None = None, callback_invoker: Invoker | None = None)

Parameters

• document (Document) – A Bokeh document that is to be updated.

• column_source (ColumnDataSource) – The data source to stream new data to.

• data (dict or DataFrame) –

  New data to stream.

  If a DataFrame, will be stored as {c: df[c] for c in df.columns}

• rollover (int) – A rollover limit. If the data source columns exceed this limit, earlier values will be discarded to maintain the column length under the limit.

• setter (ClientSession or ServerSession or None, optional) –

  This is used to prevent “boomerang” updates to Bokeh apps. (default: None)

  See DocumentChangedEvent for more details.

• callback_invoker (callable, optional) – A callable that will invoke any Model callbacks that should be executed in response to the change that triggered this event. (default: None)

dispatch(receiver: Any) → None

Dispatch handling of this event to a receiver.

This method will invoke receiver._columns_streamed if it exists.

generate(references: Set[Model], buffers: Buffers) → ColumnsStreamed

Create a JSON representation of this event suitable for sending to clients.

{
    'kind'          : 'ColumnsStreamed'
    'column_source' : <reference to a CDS>
    'data'          : <new data to steam to column_source>
    'rollover'      : <rollover limit>
}

Parameters

• references (dict[str, Model]) –

  If the event requires references to certain models in order to function, they may be collected here.

  This is an “out” parameter. The values it contains will be modified in-place.

• buffers (set) –

  If the event needs to supply any additional Bokeh protocol buffers, they may be added to this set.

  This is an “out” parameter. The values it contains will be modified in-place.

class DocumentChangedEvent(document: Document, setter: Setter | None = None, callback_invoker: Invoker | None = None)

Base class for all internal events representing a change to a Bokeh Document.

__init__(document: Document, setter: Setter | None = None, callback_invoker: Invoker | None = None) → None

Parameters

• document (Document) – A Bokeh document that is to be updated.

• setter (ClientSession or ServerSession or None, optional) –

  This is used to prevent “boomerang” updates to Bokeh apps. (default: None)

  In the context of a Bokeh server application, incoming updates to properties will be annotated with the session that is doing the updating. This value is propagated through any subsequent change notifications that the update triggers. The session can compare the event setter to itself, and suppress any updates that originate from itself.

• callback_invoker (callable, optional) – A callable that will invoke any Model callbacks that should be executed in response to the change that triggered this event. (default: None)

combine(event: DocumentChangedEvent) → bool

dispatch(receiver: Any) → None

Dispatch handling of this event to a receiver.

This method will invoke receiver._document_changed if it exists.

class DocumentPatchedEvent(document: Document, setter: Setter | None = None, callback_invoker: Invoker | None = None)

A Base class for events that represent updating Bokeh Models and their properties.

dispatch(receiver: Any) → None

Dispatch handling of this event to a receiver.

This method will invoke receiver._document_patched if it exists.

generate(references: Set[Model], buffers: Buffers) → DocumentPatched

Create a JSON representation of this event suitable for sending to clients.

Sub-classes must implement this method.

Parameters

• references (dict[str, Model]) –

  If the event requires references to certain models in order to function, they may be collected here.

  This is an “out” parameter. The values it contains will be modified in-place.

• buffers (set) –

  If the event needs to supply any additional Bokeh protocol buffers, they may be added to this set.

  This is an “out” parameter. The values it contains will be modified in-place.

static handle_json(doc: Document, event_json: DocumentPatched, references: List[ReferenceJson], setter: Setter) → None

class MessageSentEvent(document: Document, msg_type: str, msg_data: Union[Any, bytes], setter: Setter | None = None, callback_invoker: Invoker | None = None)

dispatch(receiver: Any) → None

Dispatch handling of this event to a receiver.

This method will invoke receiver._document_patched if it exists.

generate(references: Set[Model], buffers: Buffers) → MessageSent

Create a JSON representation of this event suitable for sending to clients.

Sub-classes must implement this method.

Parameters

• references (dict[str, Model]) –

  If the event requires references to certain models in order to function, they may be collected here.

  This is an “out” parameter. The values it contains will be modified in-place.

• buffers (set) –

  If the event needs to supply any additional Bokeh protocol buffers, they may be added to this set.

  This is an “out” parameter. The values it contains will be modified in-place.

class ModelChangedEvent(document: Document, model: Model, attr: str, old: Unknown, new: Unknown, serializable_new: Unknown | None, hint: DocumentPatchedEvent | None = None, setter: Setter | None = None, callback_invoker: Invoker | None = None)

A concrete event representing updating an attribute and value of a specific Bokeh Model.

This is the “standard” way of updating most Bokeh model attributes. For special casing situations that can optimized (e.g. streaming, etc.), a hint may be supplied that overrides normal mechanisms.

__init__(document: Document, model: Model, attr: str, old: Unknown, new: Unknown, serializable_new: Unknown | None, hint: DocumentPatchedEvent | None = None, setter: Setter | None = None, callback_invoker: Invoker | None = None)

Parameters

• document (Document) – A Bokeh document that is to be updated.

• model (Model) – A Model to update

• attr (str) – The name of the attribute to update on the model.

• old (object) – The old value of the attribute

• new (object) – The new value of the attribute

• serializable_new (object) – A serialized (JSON) version of the new value. It may be None if a hint is supplied.

• hint (DocumentPatchedEvent, optional) – When appropriate, a secondary event may be supplied that modifies the normal update process. For example, in order to stream or patch data more efficiently than the standard update mechanism.

• setter (ClientSession or ServerSession or None, optional) –

  This is used to prevent “boomerang” updates to Bokeh apps. (default: None)

  See DocumentChangedEvent for more details.

• callback_invoker (callable, optional) – A callable that will invoke any Model callbacks that should be executed in response to the change that triggered this event. (default: None)

combine(event: DocumentChangedEvent) → bool

dispatch(receiver: Any) → None

Dispatch handling of this event to a receiver.

This method will invoke receiver._document_model_changed if it exists.

generate(references: Set[Model], buffers: Buffers) → ModelChanged

Create a JSON representation of this event suitable for sending to clients.

Parameters

• references (dict[str, Model]) –

  If the event requires references to certain models in order to function, they may be collected here.

  This is an “out” parameter. The values it contains will be modified in-place.

• buffers (set) –

  If the event needs to supply any additional Bokeh protocol buffers, they may be added to this set.

  This is an “out” parameter. The values it contains will be modified in-place.

class RootAddedEvent(document: Document, model: Model, setter: Setter | None = None, callback_invoker: Invoker | None = None)

A concrete event representing a change to add a new Model to a Document’s collection of “root” models.

__init__(document: Document, model: Model, setter: Setter | None = None, callback_invoker: Invoker | None = None) → None

Parameters

• document (Document) – A Bokeh document that is to be updated.

• model (Model) – The Bokeh Model to add as a Document root.

• setter (ClientSession or ServerSession or None, optional) –

  This is used to prevent “boomerang” updates to Bokeh apps. (default: None)

  See DocumentChangedEvent for more details.

• callback_invoker (callable, optional) – A callable that will invoke any Model callbacks that should be executed in response to the change that triggered this event. (default: None)

generate(references: Set[Model], buffers: Buffers) → RootAdded

Create a JSON representation of this event suitable for sending to clients.

{
    'kind'  : 'RootAdded'
    'title' : <reference to a Model>
}

Parameters

• references (dict[str, Model]) –

  If the event requires references to certain models in order to function, they may be collected here.

  This is an “out” parameter. The values it contains will be modified in-place.

• buffers (set) –

  If the event needs to supply any additional Bokeh protocol buffers, they may be added to this set.

  This is an “out” parameter. The values it contains will be modified in-place.

class RootRemovedEvent(document: Document, model: Model, setter: Setter | None = None, callback_invoker: Invoker | None = None)

A concrete event representing a change to remove an existing Model from a Document’s collection of “root” models.

__init__(document: Document, model: Model, setter: Setter | None = None, callback_invoker: Invoker | None = None) → None

Parameters

• document (Document) – A Bokeh document that is to be updated.

• model (Model) – The Bokeh Model to remove as a Document root.

• setter (ClientSession or ServerSession or None, optional) –

  This is used to prevent “boomerang” updates to Bokeh apps. (default: None)

  See DocumentChangedEvent for more details.

• callback_invoker (callable, optional) – A callable that will invoke any Model callbacks that should be executed in response to the change that triggered this event. (default: None)

generate(references: Set[Model], buffers: Buffers) → RootRemoved

Create a JSON representation of this event suitable for sending to clients.

{
    'kind'  : 'RootRemoved'
    'title' : <reference to a Model>
}

Parameters

• references (dict[str, Model]) –

  If the event requires references to certain models in order to function, they may be collected here.

  This is an “out” parameter. The values it contains will be modified in-place.

• buffers (set) –

  If the event needs to supply any additional Bokeh protocol buffers, they may be added to this set.

  This is an “out” parameter. The values it contains will be modified in-place.

class SessionCallbackAdded(document: Document, callback: SessionCallback)

A concrete event representing a change to add a new callback (e.g. periodic, timeout, or “next tick”) to a Document.

__init__(document: Document, callback: SessionCallback) → None

Parameters

• document (Document) – A Bokeh document that is to be updated.

• callback (SessionCallback) – The callback to add

dispatch(receiver: Any) → None

Dispatch handling of this event to a receiver.

This method will invoke receiver._session_callback_added if it exists.

class SessionCallbackRemoved(document: Document, callback: SessionCallback)

A concrete event representing a change to remove an existing callback (e.g. periodic, timeout, or “next tick”) from a Document.

__init__(document: Document, callback: SessionCallback) → None

Parameters

• document (Document) – A Bokeh document that is to be updated.

• callback (SessionCallback) – The callback to remove

dispatch(receiver: Any) → None

Dispatch handling of this event to a receiver.

This method will invoke receiver._session_callback_removed if it exists.

class TitleChangedEvent(document: Document, title: str, setter: Setter | None = None, callback_invoker: Invoker | None = None)

A concrete event representing a change to the title of a Bokeh Document.

__init__(document: Document, title: str, setter: Setter | None = None, callback_invoker: Invoker | None = None)

Parameters

• document (Document) – A Bokeh document that is to be updated.

• title (str) – The new title to set on the Document

• setter (ClientSession or ServerSession or None, optional) –

  This is used to prevent “boomerang” updates to Bokeh apps. (default: None)

  See DocumentChangedEvent for more details.

• callback_invoker (callable, optional) – A callable that will invoke any Model callbacks that should be executed in response to the change that triggered this event. (default: None)

combine(event: DocumentChangedEvent) → bool

generate(references: Set[Model], buffers: Buffers) → TitleChanged

Create a JSON representation of this event suitable for sending to clients.

{
    'kind'  : 'TitleChanged'
    'title' : <new title to set>
}

Parameters

• references (dict[str, Model]) –

  If the event requires references to certain models in order to function, they may be collected here.

  This is an “out” parameter. The values it contains will be modified in-place.

• buffers (set) –

  If the event needs to supply any additional Bokeh protocol buffers, they may be added to this set.

  This is an “out” parameter. The values it contains will be modified in-place.