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:
-
class
Document
(**kwargs)[source]¶ 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.-
add_next_tick_callback
(callback)[source]¶ 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
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, period_milliseconds)[source]¶ 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
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, setter=None)[source]¶ 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, timeout_milliseconds)[source]¶ 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
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, setter=None)[source]¶ 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)[source]¶ Apply a JSON patch provided as a string.
- Parameters
patch (str) –
- Returns
None
-
delete_modules
()[source]¶ Clean up after any modules created by this Document when its session is destroyed.
-
classmethod
from_json
(json)[source]¶ Load a document from JSON.
- json (JSON-data) :
A JSON-encoded document to create a new Document from.
- Returns
- Return type
-
classmethod
from_json_string
(json)[source]¶ Load a document from JSON.
- json (str) :
A string with a JSON-encoded document to create a new Document from.
- Returns
- Return type
-
get_model_by_id
(model_id)[source]¶ 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)[source]¶ 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='combine')[source]¶ 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 whenunhold
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 asButtonClick
, etc.
-
on_change
(*callbacks)[source]¶ Provide callbacks to invoke if the document or any Model reachable from its roots changes.
-
on_session_destroyed
(*callbacks)[source]¶ Provide callbacks to invoke when the session serving the Document is destroyed
-
remove_next_tick_callback
(callback_obj)[source]¶ 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)[source]¶ Remove a callback added earlier with
on_change
.- Raises
KeyError, if the callback was never added –
-
remove_periodic_callback
(callback_obj)[source]¶ 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, setter=None)[source]¶ 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)[source]¶ 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 alraedy been run or removed –
-
replace_with_json
(json)[source]¶ 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)[source]¶ 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)[source]¶ 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, updates)[source]¶ 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
-
property
roots
¶ A list of all the root models in this Document.
-
property
session_callbacks
¶ A list of all the session callbacks on this document.
-
property
session_context
¶ The
SessionContext
for this document.
-
property
session_destroyed_callbacks
¶ A list of all the on_session_destroyed callbacks on this document.
-
property
template
¶ A Jinja2 template to use for rendering this document.
-
property
template_variables
¶ A dictionary of template variables to pass when rendering
self.template
.
-
property
theme
¶ The current
Theme
instance affecting models in this Document.Setting this to
None
sets the default theme. (i.e this property never returnsNone
.)Changing theme may trigger model change events on the models in the document if the theme modifies any model properties.
-
property
title
¶ A title for this document.
This title will be set on standalone HTML documents, but not e.g. when
autoload_server
is used.
-
Navigate the tree on the left for information about each subcommand.