bokeh.document.document

Note

This section documents the physical filesystem module that implements Document. However the intended public interface is in bokeh.document.

Provide the Document class, which is a container for Bokeh Models to be reflected to the client side BokehJS library.

As a concrete example, consider a column layout with Slider and Select widgets, and a plot with some tools, an axis and grid, and a glyph renderer for circles. A simplified representation of this document might look like the figure below:

A Bokeh Document is a collection of Bokeh Models (e.g. plots, tools, glyphs, etc.) that can be serialized as a single collection.

class Document(*, theme: ~bokeh.themes.theme.Theme = <bokeh.themes.theme.Theme object>, title: str = 'Bokeh Application')

The basic unit of serialization for Bokeh.

Document instances collect Bokeh models (e.g. plots, layouts, widgets, etc.) so that they may be reflected into the BokehJS client runtime. Because models may refer to other models (e.g., a plot has a list of renderers), it is not generally useful or meaningful to convert individual models to JSON. Accordingly, the Document is thus the smallest unit of serialization for Bokeh.

Public Data Attributes:

roots	A list of all the root models in this Document.
session_callbacks	A list of all the session callbacks for this document.
session_destroyed_callbacks	A list of all the on_session_destroyed callbacks for this document.
session_context	The SessionContext for this document.
template	A Jinja2 template to use for rendering this document.
template_variables	A dictionary of template variables to pass when rendering self.template.
theme	The current Theme instance affecting models in this Document.
title	A title for this document.

Public Methods:

__init__(*[, theme, title])
add_next_tick_callback(callback)	Add callback to be invoked once on the next tick of the event loop.
add_periodic_callback(callback, ...)	Add a callback to be invoked on a session periodically.
add_root(model[, setter])	Add a model as a root of this Document.
add_timeout_callback(callback, ...)	Add callback to be invoked once, after a specified timeout passes.
apply_json_patch(patch[, setter])	Apply a JSON patch object and process any resulting events.
apply_json_patch_string(patch)	Apply a JSON patch provided as a string.
clear()	Remove all content from the document but do not reset title.
delete_modules()
destroy(session)
from_json(json)	Load a document from JSON.
from_json_string(json)	Load a document from JSON.
get_model_by_id(model_id)	Find the model for the given ID in this document, or None if it is not found.
get_model_by_name(name)	Find the model for the given name in this document, or None if it is not found.
hold([policy])	Activate a document hold.
on_change(*callbacks)	Provide callbacks to invoke if the document or any Model reachable from its roots changes.
on_change_dispatch_to(receiver)
on_event(event, *callbacks)	Provide callbacks to invoke if a bokeh event is received.
on_message(msg_type, *callbacks)
on_session_destroyed(*callbacks)	Provide callbacks to invoke when the session serving the Document is destroyed
remove_next_tick_callback(callback_obj)	Remove a callback added earlier with add_next_tick_callback.
remove_on_change(*callbacks)	Remove a callback added earlier with on_change.
remove_on_message(msg_type, callback)
remove_periodic_callback(callback_obj)	Remove a callback added earlier with add_periodic_callback
remove_root(model[, setter])	Remove a model as root model from this Document.
remove_timeout_callback(callback_obj)	Remove a callback added earlier with add_timeout_callback.
replace_with_json(json)	Overwrite everything in this document with the JSON-encoded document.
select(selector)	Query this document for objects that match the given selector.
select_one(selector)	Query this document for objects that match the given selector.
set_select(selector, updates)	Update objects that match a given selector with the specified attribute/value updates.
set_title(title[, setter])
to_json()	Convert this document to a JSON object.
to_json_string([indent])	Convert the document to a JSON string.
unhold()	Turn off any active document hold and apply any collected events.
validate()	Perform integrity checks on the modes in this document.

---

add_next_tick_callback(callback: Callback) → NextTickCallback

Add callback to be invoked once on the next tick of the event loop.

Parameters

callback (callable) – A callback function to execute on the next tick.

Returns

can be used with remove_next_tick_callback

Return type

NextTickCallback

Note

Next tick callbacks only work within the context of a Bokeh server session. This function will no effect when Bokeh outputs to standalone HTML or Jupyter notebook cells.

add_periodic_callback(callback: Callback, period_milliseconds: int) → PeriodicCallback

Add a callback to be invoked on a session periodically.

Parameters

• callback (callable) – A callback function to execute periodically

• period_milliseconds (int) – Number of milliseconds between each callback execution.

Returns

can be used with remove_periodic_callback

Return type

PeriodicCallback

Note

Periodic callbacks only work within the context of a Bokeh server session. This function will no effect when Bokeh outputs to standalone HTML or Jupyter notebook cells.

add_root(model: Model, setter: Setter | None = None) → None

Add a model as a root of this Document.

Any changes to this model (including to other models referred to by it) will trigger on_change callbacks registered on this document.

Parameters

• model (Model) – The model to add as a root of this document.

• 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.

add_timeout_callback(callback: Callback, timeout_milliseconds: int) → TimeoutCallback

Add callback to be invoked once, after a specified timeout passes.

Parameters

• callback (callable) – A callback function to execute after timeout

• timeout_milliseconds (int) – Number of milliseconds before callback execution.

Returns

can be used with remove_timeout_callback

Return type

TimeoutCallback

Note

Timeout callbacks only work within the context of a Bokeh server session. This function will no effect when Bokeh outputs to standalone HTML or Jupyter notebook cells.

apply_json_patch(patch: PatchJson, setter: Setter | None = None) → None

Apply a JSON patch object and process any resulting events.

Parameters

• patch (JSON-data) – The JSON-object containing the patch to apply.

• 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.

Returns

None

apply_json_patch_string(patch: str) → None

Apply a JSON patch provided as a string.

Parameters

patch (str) –

Returns

None

clear() → None

Remove all content from the document but do not reset title.

Returns

None

classmethod from_json(json: DocJson) → Document

Load a document from JSON.

json (JSON-data) :

A JSON-encoded document to create a new Document from.

Return type

Document

classmethod from_json_string(json: str) → Document

Load a document from JSON.

json (str) :

A string with a JSON-encoded document to create a new Document from.

Return type

Document

get_model_by_id(model_id: ID) → Model | None

Find the model for the given ID in this document, or None if it is not found.

Parameters

model_id (str) – The ID of the model to search for

Returns

Model or None

get_model_by_name(name: str) → Model | None

Find the model for the given name in this document, or None if it is not found.

Parameters

name (str) – The name of the model to search for

Returns

Model or None

hold(policy: Literal['combine', 'collect'] = 'combine') → None

Activate a document hold.

While a hold is active, no model changes will be applied, or trigger callbacks. Once unhold is called, the events collected during the hold will be applied according to the hold policy.

Parameters

hold ('combine' or 'collect', optional) –

Whether events collected during a hold should attempt to be combined (default: ‘combine’)

When set to 'collect' all events will be collected and replayed in order as-is when unhold is called.

When set to 'combine' Bokeh will attempt to combine compatible events together. Typically, different events that change the same property on the same mode can be combined. For example, if the following sequence occurs:

doc.hold('combine')
slider.value = 10
slider.value = 11
slider.value = 12

Then only one callback, for the last slider.value = 12 will be triggered.

Returns

None

Note

hold only applies to document change events, i.e. setting properties on models. It does not apply to events such as ButtonClick, etc.

on_change(*callbacks: DocumentChangeCallback) → None

Provide callbacks to invoke if the document or any Model reachable from its roots changes.

on_change_dispatch_to(receiver: Any) → None

on_event(event: str | Type[Event], *callbacks: EventCallback) → None

Provide callbacks to invoke if a bokeh event is received.

on_message(msg_type: str, *callbacks: Callable[[Any], None]) → None

on_session_destroyed(*callbacks: SessionDestroyedCallback) → None

Provide callbacks to invoke when the session serving the Document is destroyed

remove_next_tick_callback(callback_obj: NextTickCallback) → None

Remove a callback added earlier with add_next_tick_callback.

Parameters

callback_obj – a value returned from add_next_tick_callback

Returns

None

Raises

ValueError, if the callback was never added or has already been run or removed –

remove_on_change(*callbacks: Any) → None

Remove a callback added earlier with on_change.

Raises

KeyError, if the callback was never added –

remove_on_message(msg_type: str, callback: Callable[[Any], None]) → None

remove_periodic_callback(callback_obj: PeriodicCallback) → None

Remove a callback added earlier with add_periodic_callback

Parameters

callback_obj – a value returned from add_periodic_callback

Returns

None

Raises

ValueError, if the callback was never added or has already been removed –

remove_root(model: Model, setter: Setter | None = None) → None

Remove a model as root model from this Document.

Changes to this model may still trigger on_change callbacks on this document, if the model is still referred to by other root models.

Parameters

• model (Model) – The model to add as a root of this document.

• 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.

remove_timeout_callback(callback_obj: TimeoutCallback) → None

Remove a callback added earlier with add_timeout_callback.

Parameters

callback_obj – a value returned from add_timeout_callback

Returns

None

Raises

ValueError, if the callback was never added or has already been run or removed –

replace_with_json(json: DocJson) → None

Overwrite everything in this document with the JSON-encoded document.

json (JSON-data) :

A JSON-encoded document to overwrite this one.

Returns

None

select(selector: SelectorType) → Iterable[Model]

Query this document for objects that match the given selector.

Parameters

selector (JSON-like query dictionary) – you can query by type or by name, e.g. {"type": HoverTool}, {"name": "mycircle"}

Returns

seq[Model]

select_one(selector: SelectorType) → Model | None

Query this document for objects that match the given selector. Raises an error if more than one object is found. Returns single matching object, or None if nothing is found

Parameters

selector (JSON-like query dictionary) – you can query by type or by name, e.g. {"type": HoverTool}, {"name": "mycircle"}

Returns

Model or None

set_select(selector: SelectorType | Type[Model], updates: Dict[str, Unknown]) → None

Update objects that match a given selector with the specified attribute/value updates.

Parameters

selector (JSON-like query dictionary) – you can query by type or by name,i e.g. {"type": HoverTool}, {"name": "mycircle"} updates (dict) :

Returns

None

set_title(title: str, setter: Setter | None = None) → None

to_json() → DocJson

Convert this document to a JSON object.

Returns

JSON-data

to_json_string(indent: int | None = None) → str

Convert the document to a JSON string.

Parameters

indent (int or None, optional) – number of spaces to indent, or None to suppress all newlines and indentation (default: None)

Returns

str

unhold() → None

Turn off any active document hold and apply any collected events.

Returns

None

validate() → None

Perform integrity checks on the modes in this document.

Returns

None

property roots: List[Model]

A list of all the root models in this Document.

property session_callbacks: List[SessionCallback]

A list of all the session callbacks for this document.

property session_context: SessionContext | None

The SessionContext for this document.

property session_destroyed_callbacks: Set[SessionDestroyedCallback]

A list of all the on_session_destroyed callbacks for this document.

property template: Template

A Jinja2 template to use for rendering this document.

property template_variables: Dict[str, Any]

A dictionary of template variables to pass when rendering self.template.

property theme: Theme

The current Theme instance affecting models in this Document.

Setting this to None sets the default theme. (i.e this property never returns None.)

Changing theme may trigger model change events on the models in the document if the theme modifies any model properties.

property title: str

A title for this document.

This title will be set on standalone HTML documents, but not e.g. when autoload_server is used.