bokeh.document.document#

注意

本节介绍实现 Document 的物理文件系统模块。然而,预期的公共接口在 bokeh.document 中。

提供 Document 类,它是 Bokeh 模型的容器,用于反映到客户端 BokehJS 库。

作为一个具体的例子,考虑一个带有 SliderSelect 组件的列布局,以及一个带有工具、轴和网格以及圆形字形渲染器的绘图。此文档的简化表示可能如下图所示

../../../_images/document.svg

Bokeh 文档是 Bokeh 模型(例如,绘图、工具、字形等)的集合,可以序列化为单个集合。#

class Document(*, theme: ~bokeh.themes.theme.Theme = <bokeh.themes.theme.Theme object>, title: str = 'Bokeh 应用程序')[source]

Bokeh 序列化的基本单元。

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

add_next_tick_callback(callback: Callback) NextTickCallback[source]

添加回调以便在事件循环的下一个滴答时调用一次。

参数:

callback (callable) – 在下一个滴答时执行的回调函数。

返回值:

可以与 remove_next_tick_callback 一起使用

返回类型:

NextTickCallback

注意

下一个滴答回调仅在 Bokeh 服务器会话的上下文中工作。当 Bokeh 输出到独立 HTML 或 Jupyter notebook 单元格时,此函数将不起作用。

add_periodic_callback(callback: Callback, period_milliseconds: int) PeriodicCallback[source]

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

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

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

返回值:

可以与 remove_periodic_callback 一起使用

返回类型:

PeriodicCallback

注意

定期回调仅在 Bokeh 服务器会话的上下文中工作。当 Bokeh 输出到独立 HTML 或 Jupyter notebook 单元格时,此函数将不起作用。

add_root(model: Model, setter: Setter | None = None) None[source]

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

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

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

  • setter (ClientSessionServerSessionNone, 可选) –

    这用于防止对 Bokeh 应用程序的“回旋镖”更新。(默认值:None)

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

add_timeout_callback(callback: Callback, timeout_milliseconds: int) TimeoutCallback[source]

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

参数:
  • 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[source]

应用 JSON 补丁对象并处理任何结果事件。

参数:
  • patch_json (JSON-data) – 包含要应用的补丁的 JSON 对象。

  • setter (ClientSessionServerSessionNone, 可选) –

    这用于防止对 Bokeh 应用程序的“回旋镖”更新。(默认值:None)

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

返回值:

None

clear() None[source]

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

返回值:

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

返回值:

Model 或 None

get_model_by_name(name: str) Model | None[source]

在此文档中查找给定名称的模型,如果未找到,则返回 None

参数:

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

返回值:

Model 或 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]

提供 JS 回调,以便在收到 bokeh 事件时调用。

on_change(*callbacks: DocumentChangeCallback) None[source]

提供回调,以便在文档或从其根可访问的任何模型发生更改时调用。

on_change_dispatch_to(receiver: Any) None[source]
on_event(event: str | type[Event], *callbacks: Callable[[Event], None]) None[source]

提供回调,以便在收到 bokeh 事件时调用。

on_message(msg_type: str, *callbacks: Callable[[Any], None]) None[source]
on_session_destroyed(*callbacks: SessionDestroyedCallback) None[source]

提供回调,以便在服务文档的会话被销毁时调用

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_on_message(msg_type: str, callback: Callable[[Any], None]) None[source]
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 (ClientSessionServerSessionNone, 可选) –

    这用于防止对 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"}

返回值:

Model 或 None

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

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

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

  • updates (dict)

返回值:

None

set_title(title: str, setter: Setter | None = None) None[source]
to_json(*, deferred: bool = True) DocJson[source]

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

返回值:

DocJson

unhold() None[source]

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

返回值:

None

validate() None[source]

对此文档中的模型执行完整性检查。

返回值:

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 等情况时。