bokeh.document.document

注意

本节记录实现 Document 的物理文件系统模块。但是，预期的公共接口位于 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')

Bokeh 的基本序列化单元。

Document 实例收集 Bokeh 模型（例如绘图、布局、部件等），以便它们可以反映到 BokehJS 客户端运行时中。因为模型可能引用其他模型（例如，绘图具有渲染器列表），所以将单个模型转换为 JSON 通常没有用或没有意义。因此，Document 因此是 Bokeh 的最小序列化单元。

add_next_tick_callback(callback: Callback) → NextTickCallback

添加将在事件循环的下一次刻度时调用的回调。

参数：

callback (callable) – 下一次刻度时要执行的回调函数。

返回值：

可与 remove_next_tick_callback 一起使用

返回类型：

NextTickCallback

注意

下一刻度回调仅在 Bokeh 服务器会话的上下文中有效。当 Bokeh 输出到独立 HTML 或 Jupyter 笔记本单元格时，此函数将不起作用。

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

添加一个回调，以便定期在会话中调用。

参数：

• callback (callable) – 定期执行的回调函数

• period_milliseconds (int) – 每次回调执行之间的时间（毫秒）。

返回值：

可与 remove_periodic_callback 一起使用

返回类型：

PeriodicCallback

注意

周期性回调仅在 Bokeh 服务器会话的上下文中有效。当 Bokeh 输出到独立 HTML 或 Jupyter 笔记本单元格时，此函数将不起作用。

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

将模型添加为此文档的根。

对该模型的任何更改（包括对它引用的其他模型的更改）都将触发在此文档上注册的 on_change 回调。

参数：

• model (Model) – 要添加为此文档根的模型。

• setter (ClientSession 或 ServerSession 或 None, 可选) –

  这用于防止 Bokeh 应用程序的“回旋镖”更新。（默认值：None）

  在 Bokeh 服务器应用程序的上下文中，传入属性的更新将使用正在执行更新的会话进行注释。此值会通过更新触发的任何后续更改通知进行传播。会话可以将其自身与事件设置程序进行比较，并抑制任何源自自身的更新。

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

添加将在指定超时时间过后一次调用的回调。

参数：

• callback (callable) – 超时后要执行的回调函数

• timeout_milliseconds (int) – 回调执行前的时间（毫秒）。

返回值：

可与 remove_timeout_callback 一起使用

返回类型：

TimeoutCallback

注意

超时回调仅在 Bokeh 服务器会话的上下文中有效。当 Bokeh 输出到独立 HTML 或 Jupyter Notebook 单元格时，此函数将不起作用。

apply_json_patch(patch_json: PatchJson | Serialized[PatchJson], *, setter: Setter | None = None) → None

应用 JSON 修补对象并处理任何产生的事件。

参数：

• patch_json (JSON 数据) – 包含要应用的修补程序的 JSON 对象。

• setter (ClientSession 或 ServerSession 或 None, 可选) –

  这用于防止 Bokeh 应用程序的“回旋镖”更新。（默认值：None）

  在 Bokeh 服务器应用程序的上下文中，传入属性的更新将使用正在执行更新的会话进行注释。此值会通过更新触发的任何后续更改通知进行传播。会话可以将其自身与事件设置程序进行比较，并抑制任何源自自身的更新。

返回值：

无

clear() → None

从文档中删除所有内容，但不重置标题。

返回值：

无

classmethod from_json(doc_json: DocJson | Serialized[DocJson]) → Document

从 JSON 加载文档。

doc_json (JSON 数据)

一个 JSON 编码的文档，用于创建一个新的 Document。

返回类型：

Document

classmethod from_json_string(json: str) → Document

从 JSON 加载文档。

json (str)

一个包含 JSON 编码文档的字符串，用于创建一个新的 Document。

返回类型：

Document

get_model_by_id(model_id: ID) → Model | None

在当前文档中查找给定 ID 的模型，如果未找到则返回 None。

参数：

model_id (str) – 要搜索的模型的 ID

返回值：

Model 或 None

get_model_by_name(name: str) → Model | None

在当前文档中查找给定名称的模型，如果未找到则返回 None。

参数：

name (str) – 要搜索的模型的名称

返回值：

Model 或 None

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

激活文档保持。

在保持激活期间，不会应用任何模型更改或触发回调。一旦调用 unhold，在保持期间收集的事件将根据保持策略应用。

参数：

policy ('combine' 或 'collect', 可选) –

在保持期间收集的事件是否应尝试组合（默认值：'combine'）

设置为 'collect' 时，所有事件都将被收集并在调用 unhold 时按原样按顺序重放。

设置为 'combine' 时，Bokeh 将尝试将兼容的事件组合在一起。通常，更改同一模型上同一属性的不同事件可以组合在一起。例如，如果发生以下序列

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

则只会触发一个回调，用于最后一个 slider.value = 12。

返回值：

无

注意

hold 仅适用于文档更改事件，即设置模型上的属性。它不适用于 ButtonClick 等事件。

js_on_event(event: str | type[Event], *callbacks: Callback) → None

如果收到 bokeh 事件，则提供要调用的 JS 回调。

on_change(*callbacks: DocumentChangeCallback) → None

如果文档或其根目录可访问的任何模型发生更改，则提供要调用的回调。

on_change_dispatch_to(receiver: Any) → None

on_event(event: str | type[Event], *callbacks: Callable[[Event], None]) → None

如果收到 bokeh 事件，则提供要调用的回调。

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

on_session_destroyed(*callbacks: SessionDestroyedCallback) → None

当服务于文档的会话销毁时，提供要调用的回调函数。

remove_next_tick_callback(callback_obj: NextTickCallback) → None

移除之前使用add_next_tick_callback添加的回调函数。

参数：

callback_obj – add_next_tick_callback返回的值

返回值：

无

引发异常:

ValueError, 如果回调函数从未添加或已运行或已移除 –

remove_on_change(*callbacks: Any) → None

移除之前使用on_change添加的回调函数。

引发异常:

KeyError, 如果回调函数从未添加 –

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

remove_periodic_callback(callback_obj: PeriodicCallback) → None

移除之前使用add_periodic_callback添加的回调函数。

参数：

callback_obj – add_periodic_callback返回的值

返回值：

无

引发异常:

ValueError, 如果回调函数从未添加或已移除 –

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

从该文档中移除模型作为根模型。

如果模型仍被其他根模型引用，则对该模型的更改仍可能触发该文档上的on_change回调函数。

参数：

• model (Model) – 要添加为此文档根的模型。

• setter (ClientSession 或 ServerSession 或 None, 可选) –

  这用于防止 Bokeh 应用程序的“回旋镖”更新。（默认值：None）

  在 Bokeh 服务器应用程序的上下文中，传入属性的更新将使用正在执行更新的会话进行注释。此值会通过更新触发的任何后续更改通知进行传播。会话可以将其自身与事件设置程序进行比较，并抑制任何源自自身的更新。

remove_timeout_callback(callback_obj: TimeoutCallback) → None

移除之前使用add_timeout_callback添加的回调函数。

参数：

callback_obj – add_timeout_callback返回的值

返回值：

无

引发异常:

ValueError, 如果回调函数从未添加或已运行或已移除 –

replace_with_json(json: DocJson) → None

用JSON编码的文档覆盖此文档中的所有内容。

json (JSON 数据)

用于覆盖此文档的JSON编码文档。

返回值：

无

select(selector: SelectorType) → Iterable[Model]

查询此文档中与给定选择器匹配的对象。

参数：

selector (类似JSON的查询字典) – 可以按类型或名称查询，例如 {"type": HoverTool}, {"name": "mycircle"}

返回值：

Model 序列

select_one(selector: SelectorType) → Model | None

查询此文档中与给定选择器匹配的对象。如果找到多个对象，则引发错误。返回单个匹配对象，如果未找到任何对象则返回 None。

参数：

selector (类似JSON的查询字典) – 可以按类型或名称查询，例如 {"type": HoverTool}, {"name": "mycircle"}

返回值：

Model 或 None

set_select(selector: SelectorType | type[Model], updates: dict[str, Any]) → None

使用指定的属性/值更新来更新与给定选择器匹配的对象。

参数：

• selector (类似 JSON 的查询字典) – 可以按类型或名称查询，例如 {"type": HoverTool}，{"name": "mycircle"}

• updates (dict)

返回值：

无

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

to_json(*, deferred: bool = True) → DocJson

将此文档转换为可 JSON 序列化的对象。

返回值：

DocJson

unhold() → None

关闭任何活动的文档保持并应用任何收集到的事件。

返回值：

无

validate() → None

对本文档中的模式执行完整性检查。

返回值：

无

property roots: list[Model]

此文档中所有根模型的列表。

property session_callbacks: list[SessionCallback]

此文档的所有会话回调的列表。

property session_context: SessionContext | None

此文档的SessionContext。

property session_destroyed_callbacks: set[SessionDestroyedCallback]

此文档的所有 on_session_destroyed 回调的列表。

property template: Template

用于渲染此文档的 Jinja2 模板。

property template_variables: dict[str, Any]

渲染 self.template 时传递的模板变量字典。

property theme: Theme

当前影响此文档中模型的Theme 实例。

将其设置为None 将设置默认主题。（即此属性永远不会返回None。）

如果主题修改任何模型属性，则更改主题可能会触发文档中模型上的模型更改事件。

property title: str

此文档的标题。

此标题将设置在独立的 HTML 文档上，但例如在使用autoload_server 时不会设置。