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 序列化的基本单位。

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

add_next_tick_callback(callback: Callback) → NextTickCallback

添加回调以在事件循环的下一个刻度上调用一次。

Parameters:

callback (callable) – 一个回调函数，在下一个时间点执行。

Returns:

可以与remove_next_tick_callback一起使用

Return type:

NextTickCallback

注意

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

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

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

Parameters:

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

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

Returns:

可以与remove_periodic_callback一起使用

Return type:

PeriodicCallback

注意

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

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

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

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

Parameters:

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

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

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

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

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

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

Parameters:

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

• timeout_milliseconds (int) – 回调执行前的毫秒数。

Returns:

可以与remove_timeout_callback一起使用

Return type:

TimeoutCallback

注意

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

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

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

Parameters:

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

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

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

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

Returns:

无

clear() → None

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

Returns:

无

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

从JSON加载文档。

doc_json (JSON-data) :

用于创建新文档的JSON编码文档。

Return type:

Document

classmethod from_json_string(json: str) → Document

从JSON加载文档。

json (str) :

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

Return type:

Document

get_model_by_id(model_id: ID) → Model | None

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

Parameters:

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

Returns:

模型或无

get_model_by_name(name: str) → Model | None

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

Parameters:

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

Returns:

模型或无

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

激活文档保留。

当保持处于活动状态时，不会应用任何模型更改或触发回调。一旦调用unhold，在保持期间收集的事件将根据保持策略进行应用。

Parameters:

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

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

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

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

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

然后只会触发一个回调，即最后一个 slider.value = 12。

Returns:

无

注意

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 添加的回调函数。

Parameters:

callback_obj – 从 add_next_tick_callback 返回的值

Returns:

无

Raises:

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

remove_on_change(*callbacks: Any) → None

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

Raises:

KeyError, 如果回调从未被添加 –

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

remove_periodic_callback(callback_obj: PeriodicCallback) → None

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

Parameters:

callback_obj – 从 add_periodic_callback 返回的值

Returns:

无

Raises:

ValueError, 如果回调从未被添加或已经被移除 –

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

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

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

Parameters:

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

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

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

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

remove_timeout_callback(callback_obj: TimeoutCallback) → None

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

Parameters:

callback_obj – 从 add_timeout_callback 返回的值

Returns:

无

Raises:

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

replace_with_json(json: DocJson) → None

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

json (JSON-data) :

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

Returns:

无

select(selector: SelectorType) → Iterable[Model]

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

Parameters:

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

Returns:

序列[模型]

select_one(selector: SelectorType) → Model | None

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

Parameters:

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

Returns:

模型或无

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

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

Parameters:

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

• 更新 (dict)

Returns:

无

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

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

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

Returns:

文档JSON

unhold() → None

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

Returns:

无

validate() → None

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

Returns:

无

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实例。

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

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

property title: str

本文档的标题。

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

without_document_lock(func: F) → NoLockCallback[F]

包装一个回调函数，使其无需首先获取文档锁即可执行。

Parameters:

func (callable) – 要包装的函数

Returns:

一个被包装的函数，可以在没有Document锁的情况下执行。

Return type:

可调用的

在解锁的回调函数内部，修改curdoc()是完全不安全的。回调函数内部的curdoc()值将是Document的一个特别包装版本，该版本只允许安全操作，这些操作包括：

• add_next_tick_callback()

• remove_next_tick_callback()

只有这些可以在不获取文档锁的情况下安全使用。要对文档进行其他更改，您必须添加一个下一个tick回调，并从该第二个回调中对curdoc()进行更改。

尝试以其他方式访问或更改文档将导致引发异常。

func 可以是一个同步函数、一个异步函数，或者一个用 asyncio.coroutine 装饰的函数。如果 func 是后两者中的任何一种，返回的函数将是一个异步函数。

• bokeh.document.document
• bokeh.document.events
  • ColumnDataChangedEvent
    • ColumnDataChangedEvent.__init__()
    • ColumnDataChangedEvent.dispatch()
    • ColumnDataChangedEvent.to_serializable()
  • ColumnsPatchedEvent
    • ColumnsPatchedEvent.__init__()
    • ColumnsPatchedEvent.dispatch()
    • ColumnsPatchedEvent.to_serializable()
  • ColumnsStreamedEvent
    • ColumnsStreamedEvent.__init__()
    • ColumnsStreamedEvent.dispatch()
    • ColumnsStreamedEvent.to_serializable()
  • DocumentChangedEvent
    • DocumentChangedEvent.__init__()
    • DocumentChangedEvent.combine()
    • DocumentChangedEvent.dispatch()
  • DocumentPatchedEvent
    • DocumentPatchedEvent.dispatch()
    • DocumentPatchedEvent.handle_event()
    • DocumentPatchedEvent.to_serializable()
  • MessageSentEvent
    • MessageSentEvent.dispatch()
    • MessageSentEvent.to_serializable()
  • ModelChangedEvent
    • ModelChangedEvent.__init__()
    • ModelChangedEvent.combine()
    • ModelChangedEvent.dispatch()
    • ModelChangedEvent.to_serializable()
  • RootAddedEvent
    • RootAddedEvent.__init__()
    • RootAddedEvent.to_serializable()
  • RootRemovedEvent
    • RootRemovedEvent.__init__()
    • RootRemovedEvent.to_serializable()
  • SessionCallbackAdded
    • SessionCallbackAdded.__init__()
    • SessionCallbackAdded.dispatch()
  • SessionCallbackRemoved
    • SessionCallbackRemoved.__init__()
    • SessionCallbackRemoved.dispatch()
  • TitleChangedEvent
    • TitleChangedEvent.__init__()
    • TitleChangedEvent.combine()
    • TitleChangedEvent.to_serializable()
• bokeh.document.locking
  • UnlockedDocumentProxy
    • UnlockedDocumentProxy.__init__()
    • UnlockedDocumentProxy.add_next_tick_callback()
    • UnlockedDocumentProxy.remove_next_tick_callback()
  • without_document_lock()