bokeh.document#
提供 Document
类,它是一个 Bokeh 模型的容器,用于反映到客户端 BokehJS 库。
作为一个具体的例子,考虑一个带有 Slider
和 Select
部件的列布局,以及一个带有某些工具、坐标轴和网格,以及圆形字形渲染器的绘图。这个文档的简化表示可能看起来像下图
Bokeh 文档是 Bokeh 模型(例如,绘图、工具、字形等)的集合,可以序列化为单个集合。#
- class Document(*, theme: ~bokeh.themes.theme.Theme = <bokeh.themes.theme.Theme object>, title: str = 'Bokeh Application')[source]#
Bokeh 序列化的基本单元。
Document 实例收集 Bokeh 模型(例如,绘图、布局、部件等),以便可以将它们反映到 BokehJS 客户端运行时中。由于模型可能引用其他模型(例如,一个绘图具有渲染器列表),因此通常将单个模型转换为 JSON 是没有用或没有意义的。因此,
Document
是 Bokeh 最小的序列化单元。- add_next_tick_callback(callback: Callback) NextTickCallback [source]#
添加回调,以便在事件循环的下一个刻度上调用一次。
- 参数:
callback (callable) – 在下一个刻度上执行的回调函数。
- 返回:
可以与
remove_next_tick_callback
一起使用- 返回类型:
注意
下一个刻度回调仅在 Bokeh 服务器会话的上下文中工作。当 Bokeh 输出到独立的 HTML 或 Jupyter notebook 单元格时,此函数将不起作用。
- add_periodic_callback(callback: Callback, period_milliseconds: int) PeriodicCallback [source]#
添加一个回调,以便在会话中定期调用。
- 参数:
callback (callable) – 定期执行的回调函数
period_milliseconds (int) – 每次回调执行之间的毫秒数。
- 返回:
可以与
remove_periodic_callback
一起使用- 返回类型:
注意
定期回调仅在 Bokeh 服务器会话的上下文中工作。当 Bokeh 输出到独立的 HTML 或 Jupyter notebook 单元格时,此函数将不起作用。
- add_root(model: Model, setter: Setter | None = None) None [source]#
将模型添加为此文档的根。
对此模型(包括对其引用的其他模型)的任何更改都将触发在此文档上注册的
on_change
回调。- 参数:
model (Model) – 要添加为此文档根的模型。
setter (ClientSession 或 ServerSession 或 None,可选) –
这用于防止对 Bokeh 应用程序的“回旋镖”更新。(默认值:None)
在 Bokeh 服务器应用程序的上下文中,对属性的传入更新将使用正在执行更新的会话进行注释。此值会通过更新触发的任何后续更改通知进行传播。会话可以将事件 setter 与自身进行比较,并禁止任何源自自身的更新。
- add_timeout_callback(callback: Callback, timeout_milliseconds: int) TimeoutCallback [source]#
添加回调,以便在指定的超时时间过后调用一次。
- 参数:
callback (callable) – 超时后执行的回调函数
timeout_milliseconds (int) – 回调执行前的毫秒数。
- 返回:
可以与
remove_timeout_callback
一起使用- 返回类型:
注意
超时回调仅在 Bokeh 服务器会话的上下文中工作。当 Bokeh 输出到独立的 HTML 或 Jupyter notebook 单元格时,此函数将不起作用。
- apply_json_patch(patch_json: PatchJson | Serialized[PatchJson], *, setter: Setter | None = None) None [source]#
应用 JSON 补丁对象并处理任何生成的事件。
- 参数:
patch_json (JSON-data) – 包含要应用的补丁的 JSON 对象。
setter (ClientSession 或 ServerSession 或 None,可选) –
这用于防止对 Bokeh 应用程序的“回旋镖”更新。(默认值:None)
在 Bokeh 服务器应用程序的上下文中,对属性的传入更新将使用正在执行更新的会话进行注释。此值会通过更新触发的任何后续更改通知进行传播。会话可以将事件 setter 与自身进行比较,并禁止任何源自自身的更新。
- 返回:
None
- classmethod from_json(doc_json: DocJson | Serialized[DocJson]) Document [source]#
从 JSON 加载文档。
- doc_json (JSON-data)
一个 JSON 编码的文档,用于从中创建一个新的 Document。
- 返回类型:
- classmethod from_json_string(json: str) Document [source]#
从 JSON 加载文档。
- json (str)
一个带有 JSON 编码文档的字符串,用于从中创建一个新的 Document。
- 返回类型:
- get_model_by_id(model_id: ID) Model | None [source]#
在此文档中查找给定 ID 的模型,如果未找到,则返回
None
。- 参数:
model_id (str) – 要搜索的模型的 ID
- 返回:
模型或 None
- get_model_by_name(name: str) Model | None [source]#
在此文档中查找给定名称的模型,如果未找到,则返回
None
。- 参数:
name (str) – 要搜索的模型的名称
- 返回:
模型或 None
- hold(policy: Literal['combine', 'collect'] = 'combine') None [source]#
激活文档保持。
在保持活动状态时,不会应用模型更改,也不会触发回调。一旦调用
unhold
,将在保持期间收集的事件将根据保持策略应用。- 参数:
policy ('combine' 或 'collect', 可选) –
在保持期间收集的事件是否应尝试组合在一起(默认值:'combine')
当设置为
'collect'
时,所有事件将被收集并在调用unhold
时按原样按顺序重放。当设置为
'combine'
时,Bokeh 将尝试将兼容的事件组合在一起。通常,更改同一模型上同一属性的不同事件可以组合在一起。例如,如果发生以下序列doc.hold('combine') slider.value = 10 slider.value = 11 slider.value = 12
那么只会触发一个回调,用于最后一个
slider.value = 12
。- 返回:
None
注意
hold
仅适用于文档更改事件,即设置模型上的属性。它不适用于诸如ButtonClick
等事件。
- js_on_event(event: str | type[Event], *callbacks: Callback) None [source]#
如果收到 bokeh 事件,则提供要调用的 JS 回调。
- on_event(event: str | type[Event], *callbacks: Callable[[Event], None]) None [source]#
如果收到 bokeh 事件,则提供要调用的回调。
- on_session_destroyed(*callbacks: SessionDestroyedCallback) None [source]#
提供在销毁服务 Document 的会话时调用的回调
- remove_next_tick_callback(callback_obj: NextTickCallback) None [source]#
删除先前使用
add_next_tick_callback
添加的回调。- 参数:
callback_obj – 从
add_next_tick_callback
返回的值- 返回:
None
- Raises:
ValueError, 如果回调从未添加或已运行或已移除 –
- remove_on_change(*callbacks: Any) None [source]#
移除先前使用
on_change
添加的回调。- Raises:
KeyError, 如果回调从未添加 –
- remove_periodic_callback(callback_obj: PeriodicCallback) None [source]#
移除先前使用
add_periodic_callback
添加的回调- 参数:
callback_obj – 从
add_periodic_callback
返回的值- 返回:
None
- Raises:
ValueError, 如果回调从未添加或已移除 –
- remove_root(model: Model, setter: Setter | None = None) None [source]#
从此文档中移除一个模型作为根模型。
如果模型仍然被其他根模型引用,则对此模型的更改仍可能触发此文档上的
on_change
回调。- 参数:
model (Model) – 要添加为此文档根的模型。
setter (ClientSession 或 ServerSession 或 None,可选) –
这用于防止对 Bokeh 应用程序的“回旋镖”更新。(默认值:None)
在 Bokeh 服务器应用程序的上下文中,对属性的传入更新将使用正在执行更新的会话进行注释。此值会通过更新触发的任何后续更改通知进行传播。会话可以将事件 setter 与自身进行比较,并禁止任何源自自身的更新。
- remove_timeout_callback(callback_obj: TimeoutCallback) None [source]#
移除先前使用
add_timeout_callback
添加的回调。- 参数:
callback_obj – 从
add_timeout_callback
返回的值- 返回:
None
- Raises:
ValueError, 如果回调从未添加或已运行或已移除 –
- replace_with_json(json: DocJson) None [source]#
使用 JSON 编码的文档覆盖此文档中的所有内容。
- json (JSON 数据)
一个 JSON 编码的文档,用于覆盖当前文档。
- 返回:
None
- select(selector: SelectorType) Iterable[Model] [source]#
在此文档中查询与给定选择器匹配的对象。
- 参数:
selector (类似 JSON 的查询字典) – 您可以按类型或名称查询,例如
{"type": HoverTool}
,{"name": "mycircle"}
- 返回:
seq[Model]
- select_one(selector: SelectorType) Model | None [source]#
在此文档中查询与给定选择器匹配的对象。如果找到多个对象,则引发错误。返回单个匹配对象,如果未找到任何对象,则返回 None
- 参数:
selector (类似 JSON 的查询字典) – 您可以按类型或名称查询,例如
{"type": HoverTool}
,{"name": "mycircle"}
- 返回:
模型或 None
- set_select(selector: SelectorType | type[Model], updates: dict[str, Any]) None [source]#
使用指定的属性/值更新来更新与给定选择器匹配的对象。
- 参数:
selector (类似 JSON 的查询字典) – 您可以按类型或名称查询,例如
{"type": HoverTool}
,{"name": "mycircle"}
updates (dict)
- 返回:
None
- property session_callbacks: list[SessionCallback]#
此文档的所有会话回调的列表。
- property session_context: SessionContext | None#
此文档的
SessionContext
。
- property session_destroyed_callbacks: set[SessionDestroyedCallback]#
此文档的所有 on_session_destroyed 回调的列表。
- property template: Template#
用于渲染此文档的 Jinja2 模板。
- without_document_lock(func: F) NoLockCallback[F] [source]#
包装一个回调函数,使其在不首先获取文档锁的情况下执行。
- 参数:
func (可调用对象) – 要包装的函数
- 返回:
一个被包装的函数,用于在没有
Document
锁的情况下执行。- 返回类型:
可调用对象
在未锁定的回调内部,修改
curdoc()
是完全不安全的。curdoc()
在回调内部的值将是Document
的特殊包装版本,该版本仅允许安全操作,即只有这些可以在不获取文档锁的情况下安全使用。要对文档进行其他更改,您必须添加下一个刻度回调,并从第二个回调中更改
curdoc()
。尝试以其他方式访问或更改文档将导致引发异常。
func
可以是同步函数、异步函数或使用asyncio.coroutine
修饰的函数。如果func
是后两者中的任何一个,则返回的函数将是异步函数。
- bokeh.document.document
- bokeh.document.events
- bokeh.document.locking